BUILD_PR: improve samples browse visuals and navigation

DavidQ · DavidQ · commit 5c32e011c66d · 2026-04-10T16:44:39.000-04:00
- add thumbnail / preview asset support with clean fallback behavior
- add lightweight hover preview behavior
- polish next/previous/related navigation surfaces
- preserve canonical paths and metadata-driven readable UI

No gameplay or engine-core scope included
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -1,40 +1,79 @@
-# Codex command for PLAN_PR_SAMPLES_BUNDLED_FINALIZATION
+# Codex command for BUILD_PR_SAMPLES_BROWSE_VISUALS_AND_NAVIGATION
 
 MODEL: GPT-5.4-codex
 REASONING: high
 
 COMMAND:
-Create PLAN_PR_SAMPLES_BUNDLED_FINALIZATION as docs-only planning.
-
-OBJECTIVE:
-Bundle the remaining samples PRs into the fewest rule-safe BUILD/APPLY waves.
-
-CONSTRAINTS:
-- docs only
-- no implementation code
-- preserve one PR purpose only
-- preserve testability gate
-- preserve canonical sample paths
-- no gameplay scope
-- no engine-core scope
-- no start_of_day directory changes
-
-PLANNING REQUIREMENTS:
-1. Cover all 7 remaining sample objectives
-2. Minimize the number of future BUILD/APPLY waves
-3. Do not combine incompatible purposes into one BUILD
-4. Keep each future BUILD testable
-5. Keep Windows-safe zero-dependency execution assumptions intact
-
-OUTPUT FILES:
-- docs/pr/PLAN_PR_SAMPLES_BUNDLED_FINALIZATION.md
-- docs/dev/codex_commands.md
-- docs/dev/commit_comment.txt
-- docs/dev/reports/change_summary.txt
-- docs/dev/reports/validation_checklist.txt
-- docs/dev/reports/file_tree_delta.txt
-
-ZIP OUTPUT REQUIREMENT:
+Execute BUILD_PR_SAMPLES_BROWSE_VISUALS_AND_NAVIGATION exactly as written.
+
+EXECUTION ENVIRONMENT (MANDATORY):
+- Target platform: Windows
+- Prefer Node.js or vanilla JS for any scripting or generation support
+- DO NOT run `npm install`
+- DO NOT create `package.json`
+- DO NOT create `package-lock.json`
+- DO NOT create or populate `node_modules/`
+- DO NOT use PowerShell for path construction, rename-heavy work, or ZIP path generation
+
+POWERSHELL PROHIBITION (CRITICAL):
+The following patterns are NOT allowed:
+- "$var/path"
+- "${var}/path"
+- "$base\$child"
+- "$($var)/path"
+
+If any of these appear:
+- STOP
+- report the violation
+- do not silently retry
+
+PR PURPOSE:
+Improve samples browse visuals and navigation in one narrow, testable wave.
+
+EXPECTED TARGETS:
+- `samples/index.html`
+- minimal JS/CSS directly supporting thumbnails and hover preview
+- minimal sample detail page files directly supporting navigation polish
+- metadata-driven files directly needed for preview and navigation rendering
+- reporting docs under `docs/`
+
+DO NOT:
+- modify gameplay code
+- modify engine core
+- change canonical paths
+- broaden scope beyond browse visuals and navigation
+- modify `docs/dev/start_of_day/chatGPT/`
+- modify `docs/dev/start_of_day/codex/`
+
+REQUIRED IMPLEMENTATION SHAPE:
+1. Add thumbnail / preview asset support with clean fallback behavior
+2. Keep hover preview lightweight and dependency-free
+3. Polish next / previous / related navigation as needed
+4. Preserve canonical links and metadata-driven readable UI
+5. Keep changed-file count minimal
+
+VALIDATION (REQUIRED):
+- load `samples/index.html`
+- verify thumbnails render when available
+- verify fallback behavior when previews are missing
+- verify hover preview does not break layout
+- open representative sample pages and validate navigation
+- confirm Phase 13 samples 1316, 1317, 1318 still load
+- confirm console is clean for tested pages
+- report exact files changed
+- report exact validation performed
+
+ZIP OUTPUT REQUIREMENT (HARD RULE):
 - MUST produce ZIP:
-  <project folder>/tmp/PLAN_PR_SAMPLES_BUNDLED_FINALIZATION.zip
-- Task is not complete until the ZIP exists at that exact path
+  <project folder>/tmp/BUILD_PR_SAMPLES_BROWSE_VISUALS_AND_NAVIGATION.zip
+- ZIP must contain only repo-relevant delta output for this PR
+- Do not stage ZIP files from `<project folder>/tmp/`
+- Task is NOT complete until the ZIP exists at the exact requested path
+
+FAIL FAST:
+- vague target files
+- broad asset reorganization required
+- preview conventions too inconsistent to implement narrowly
+- navigation changes require unrelated page rewrites
+- PowerShell parse issue before execution
+- missing ZIP output at exact path
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1,8 +1,8 @@
-PLAN_PR: bundle remaining sample objectives into minimal safe BUILD/APPLY waves
+BUILD_PR: improve samples browse visuals and navigation
 
-- covers all 7 remaining sample objectives
-- minimizes future execution to 3 BUILD/APPLY waves
-- preserves one-purpose-per-PR rule and testability gate
-- preserves canonical sample paths and Windows-safe zero-dependency assumptions
+- add thumbnail / preview asset support with clean fallback behavior
+- add lightweight hover preview behavior
+- polish next/previous/related navigation surfaces
+- preserve canonical paths and metadata-driven readable UI
 
-Docs-only planning bundle
+No gameplay or engine-core scope included
diff --git a/docs/dev/reports/BUILD_PR_SAMPLES_BROWSE_VISUALS_AND_NAVIGATION_validation.txt b/docs/dev/reports/BUILD_PR_SAMPLES_BROWSE_VISUALS_AND_NAVIGATION_validation.txt
@@ -0,0 +1,41 @@
+BUILD_PR_SAMPLES_BROWSE_VISUALS_AND_NAVIGATION
+
+Scope confirmation:
+- No gameplay files changed
+- No engine-core files changed
+- Canonical sample paths preserved
+
+Files changed for this BUILD:
+- samples/index.html
+- samples/_shared/sampleDetailPageEnhancement.js
+- samples/metadata/samples.index.metadata.json
+- docs/dev/reports/BUILD_PR_SAMPLES_BROWSE_VISUALS_AND_NAVIGATION_validation.txt
+
+Validation executed:
+1) node scripts/generate-samples-index.mjs --check
+   - Result: OK phases=15 samples=197 metadata=197 mode=check
+
+2) node --check samples/_shared/sampleDetailPageEnhancement.js
+   - Result: pass (no syntax errors)
+
+3) samples/index.html inline script parse + visual CSS presence checks
+   - Result: pass
+   - Verified thumbnail and hover-preview CSS selectors exist
+
+4) metadata preview entries and preview asset existence for 1316/1317/1318
+   - Result: pass
+   - Verified thumbnail + preview metadata fields point to existing assets
+
+5) detail-page navigation model checks via shared enhancer module
+   - Result: pass
+   - Verified previous/next/related links resolve to canonical sample paths
+   - Verified fallback preview/thumbnail behavior for samples without assets
+
+6) hover-preview guard checks in samples/index.html
+   - Result: pass
+   - Verified fixed overlay behavior and non-layout-breaking guard styles
+
+7) representative phase 13 sample checks
+   - Result: pass
+   - Verified 1316, 1317, 1318 links remain in samples/index.html
+   - Verified 1316/1317/1318 sample pages still include enhancer + main script tags
diff --git a/docs/dev/reports/change_summary.txt b/docs/dev/reports/change_summary.txt
@@ -1,8 +1,8 @@
-PR TYPE: PLAN
-PURPOSE: samples bundled finalization
+PR TYPE: BUILD
+PURPOSE: samples browse visuals and navigation
 
 SUMMARY:
-- defines the 7 remaining sample objectives to complete
-- bundles work into the minimum safe number of future BUILD/APPLY waves (3)
-- separates browse UX, discovery-data quality, and performance/personalization into compatible lanes
-- preserves one-purpose-per-PR, testability gates, canonical paths, and Windows-safe zero-dependency assumptions
+- defines a testable BUILD wave for thumbnails, hover preview, and navigation polish
+- preserves canonical sample paths and metadata-driven readable UI
+- requires clean fallback behavior when preview assets are missing
+- keeps scope narrow and Windows-safe
diff --git a/docs/dev/reports/file_tree_delta.txt b/docs/dev/reports/file_tree_delta.txt
@@ -1,12 +1,18 @@
-PLAN OUTPUT ONLY
+EXPECTED DELTA (implementation-dependent, keep minimal)
 
-ADDED/UPDATED:
-- docs/pr/PLAN_PR_SAMPLES_BUNDLED_FINALIZATION.md
+MODIFIED:
+- samples/index.html
+- minimal JS/CSS directly supporting browse visuals / hover behavior
+- minimal sample detail files directly supporting navigation polish
+
+ADDED (only if required):
+- minimal preview asset mapping or helper file
+- minimal browse-visual support file directly used by the samples index
+
+REPORT ONLY:
+- docs/pr/BUILD_PR_SAMPLES_BROWSE_VISUALS_AND_NAVIGATION.md
 - docs/dev/codex_commands.md
 - docs/dev/commit_comment.txt
 - docs/dev/reports/change_summary.txt
 - docs/dev/reports/validation_checklist.txt
 - docs/dev/reports/file_tree_delta.txt
-
-NO IMPLEMENTATION FILES IN THIS PLAN
-NO GAMEPLAY OR ENGINE-CORE FILES CHANGED
diff --git a/docs/dev/reports/validation_checklist.txt b/docs/dev/reports/validation_checklist.txt
@@ -1,8 +1,11 @@
-[x] All 7 remaining sample objectives are covered
-[x] Bundling uses the fewest safe BUILD/APPLY waves
-[x] No future BUILD mixes incompatible PR purposes
-[x] Each future BUILD remains testable
-[x] Canonical path contract remains unchanged
-[x] Windows-safe zero-dependency assumptions remain intact
-[x] Output files generated at required docs paths
-[x] ZIP exists at <project folder>/tmp/PLAN_PR_SAMPLES_BUNDLED_FINALIZATION.zip
+[ ] samples/index.html renders thumbnails when available
+[ ] missing preview assets fall back cleanly
+[ ] hover preview works without breaking layout
+[ ] representative sample pages show correct navigation
+[ ] related links resolve correctly
+[ ] Phase 13 samples 1316, 1317, 1318 still load
+[ ] no console errors in tested pages
+[ ] no gameplay changes
+[ ] no engine-core changes
+[ ] changed-file count stayed minimal
+[ ] ZIP exists at <project folder>/tmp/BUILD_PR_SAMPLES_BROWSE_VISUALS_AND_NAVIGATION.zip
diff --git a/docs/pr/BUILD_PR_SAMPLES_BROWSE_VISUALS_AND_NAVIGATION.md b/docs/pr/BUILD_PR_SAMPLES_BROWSE_VISUALS_AND_NAVIGATION.md
@@ -0,0 +1,92 @@
+# BUILD_PR_SAMPLES_BROWSE_VISUALS_AND_NAVIGATION
+
+## Objective
+Implement the first bundled samples finalization wave by improving browse-time visuals and movement without changing canonical sample ownership or runtime sample behavior.
+
+This BUILD covers:
+- preview assets and thumbnails
+- hover preview
+- navigation polish
+
+Canonical path contract remains:
+- `samples/phaseXX/XXYY/index.html`
+
+## PR Purpose
+One purpose only:
+- improve sample browsing presentation and navigation
+
+## In Scope
+- add thumbnail / preview asset support for sample tiles and sample detail presentation
+- render clean fallback behavior when preview assets are missing
+- add or polish hover preview behavior where it improves browse-time clarity
+- polish sample navigation surfaces such as:
+  - next / previous movement
+  - related navigation presentation
+  - browse-time movement consistency between index and detail contexts
+- preserve metadata-driven readable UI behavior
+- preserve canonical sample paths
+
+## Out of Scope
+- no gameplay changes
+- no engine-core changes
+- no path normalization changes
+- no metadata schema redesign
+- no metadata validation hardening beyond exact immediate needs for this wave
+- no favorites / pinning
+- no performance-only tuning unless required to keep this wave functional
+
+## Required Behavior
+1. Index tiles can display preview thumbnails when available.
+2. Missing thumbnails must fall back cleanly with no broken UI.
+3. Hover preview behavior must be lightweight and dependency-free.
+4. Detail-page navigation must remain correct and readable.
+5. Related and adjacent navigation must still resolve to canonical paths.
+6. Representative Phase 13 samples including 1316–1318 must continue to load correctly.
+
+## Expected Targets
+Codex should keep reads narrow and stop if the actual required target list expands materially.
+
+Expected implementation targets:
+- `samples/index.html`
+- minimal JS/CSS directly supporting index browse visuals and hover behavior
+- minimal sample detail page rendering files directly needed for navigation polish
+- metadata-driven files directly needed for preview or navigation rendering
+- report files under `docs/` only for output packaging
+
+## Windows / Execution Constraints
+- target platform: Windows
+- prefer Node.js or vanilla JS where scripting support is needed
+- no `npm install`
+- no `node_modules`
+- no PowerShell path interpolation
+- ZIP output under `<project folder>/tmp/` is mandatory
+
+## Validation Requirements
+Minimum required validation:
+- load `samples/index.html`
+- verify thumbnails render when assets exist
+- verify fallback renders cleanly when assets do not exist
+- verify hover preview behavior does not break layout
+- open representative sample pages and verify:
+  - header still renders
+  - next / previous navigation works
+  - related links resolve
+- verify Phase 13 samples 1316, 1317, 1318 still load
+- verify console stays clean for tested pages
+
+## Acceptance Criteria
+- browse visuals improve without changing canonical paths
+- missing preview assets do not break index or detail pages
+- navigation polish works and remains testable
+- no gameplay changes
+- no engine-core changes
+- changed-file count stays minimal
+- repo-structured delta ZIP is produced under `<project folder>/tmp/`
+
+## Fail Fast
+Stop and report if:
+- preview support would require broad asset reorganization
+- thumbnail conventions are ambiguous across many samples
+- navigation changes would require unrelated page rewrites
+- implementation expands beyond browse visuals and navigation
+- the ZIP cannot be produced at the exact requested path
diff --git a/samples/_shared/sampleDetailPageEnhancement.js b/samples/_shared/sampleDetailPageEnhancement.js
diff --git a/samples/index.html b/samples/index.html
diff --git a/samples/metadata/samples.index.metadata.json b/samples/metadata/samples.index.metadata.json
