BUILD_PR_SAMPLES_RUNTIME_PREVIEW_SVG_CAPTURE: add 3-second runtime-derived preview SVG generation for samples, keep scope limited to preview capture.

&
BUILD_PR_SAMPLES_INDEX_FIXES_AND_TARGETED_PREVIEW_RETRY: narrow samples-system BUILD for index label cleanup, Sample 1303 local asteroid speed cap, and targeted preview SVG retry only where current SVG contains "Capture timeout".

Author: DavidQ

build_bundle_samples_runtime_preview/docs/dev/codex_commands.md

@@ -0,0 +1,39 @@
+# Codex Command
+
+MODEL: GPT-5.4-codex  
+REASONING: high
+
+## COMMAND
+Execute `BUILD_PR_SAMPLES_RUNTIME_PREVIEW_SVG_CAPTURE` 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 depend on external screenshot tools or browser extensions
+
+## HARD CONSTRAINTS
+- Do not modify gameplay logic except for minimal non-behavioral hooks strictly required for automated preview capture
+- Do not modify engine core unless absolutely required for capture orchestration
+- Do not change sample page layout
+- Do not change tags, titles, related samples, or engine-classes-used presentation
+- Do not modify `samples/index.html` except if strictly required to consume existing preview asset paths already used by the system
+- Do not modify `docs/dev/start_of_day/chatGPT/`
+- Do not modify `docs/dev/start_of_day/codex/`
+- Do not perform more work on `1316`, `1317`, or `1318`; preserve them exactly as they are now
+
+## RUNTIME CAPTURE REQUIREMENT
+For each targeted sample:
+1. Load the actual runnable sample page
+2. Let the game/sample run for 3 seconds
+3. Capture the live canvas appearance at 3000 ms
+4. Generate/update the preview SVG asset from that runtime-derived canvas state
+
+## ZIP OUTPUT REQUIREMENT
+Must produce:
+`<project folder>/tmp/BUILD_PR_SAMPLES_RUNTIME_PREVIEW_SVG_CAPTURE.zip`
+
+Task is not complete until that ZIP exists at the exact requested path.

build_bundle_samples_runtime_preview/docs/dev/commit_comment.txt

@@ -0,0 +1 @@
+BUILD_PR_SAMPLES_RUNTIME_PREVIEW_SVG_CAPTURE: add 3-second runtime-derived preview SVG generation for samples, keep scope limited to preview capture, and leave 1316/1317/1318 untouched

build_bundle_samples_runtime_preview/docs/dev/next_command.txt

@@ -0,0 +1,3 @@
+Next suggested command after this BUILD succeeds:
+
+Create APPLY_PR_SAMPLES_RUNTIME_PREVIEW_SVG_CAPTURE docs-only acceptance bundle with exact files changed, exact validation performed, and explicit confirmation that 1316/1317/1318 were not modified.

build_bundle_samples_runtime_preview/docs/dev/reports/change_summary.txt

@@ -0,0 +1,13 @@
+Bundle type: BUILD
+PR purpose: Runtime-derived sample preview SVG capture after 3 seconds of gameplay/runtime
+
+What this bundle changes:
+- Replaces the earlier broader direction with a narrowed runtime-preview-only BUILD
+- Explicitly freezes samples 1316, 1317, and 1318 from further changes
+- Preserves layout/metadata normalization for a separate future PR if needed
+
+Non-goals:
+- No sample page layout work
+- No metadata/tag/title normalization
+- No Engine Classes Used formatting work
+- No further 1316/1317/1318 work

build_bundle_samples_runtime_preview/docs/dev/reports/file_tree.txt

@@ -0,0 +1,11 @@
+docs/
+  dev/
+    codex_commands.md
+    commit_comment.txt
+    next_command.txt
+    reports/
+      change_summary.txt
+      file_tree.txt
+      validation_checklist.txt
+  pr/
+    BUILD_PR_SAMPLES_RUNTIME_PREVIEW_SVG_CAPTURE.md

build_bundle_samples_runtime_preview/docs/dev/reports/validation_checklist.txt

@@ -0,0 +1,18 @@
+Session validation gate applied:
+- Single PR purpose: yes
+- BUILD specific enough for Codex: yes
+- Scope minimized: yes
+- No vague repo-wide refactor language: yes
+- No fake claim of code already written: yes
+- No start_of_day directories touched: yes
+- 1316/1317/1318 explicitly protected: yes
+- ZIP-required output specified: yes
+
+Codex validation to report:
+- representative runtime capture at 3000 ms confirmed
+- preview SVG assets created/updated for targeted samples
+- console clean for representative tested samples
+- exact changed files listed
+- exact validation listed
+- any uncaptured samples listed with exact reason
+- 1316/1317/1318 confirmed untouched

build_bundle_samples_runtime_preview/docs/pr/BUILD_PR_SAMPLES_RUNTIME_PREVIEW_SVG_CAPTURE.md

@@ -0,0 +1,89 @@
+# BUILD_PR_SAMPLES_RUNTIME_PREVIEW_SVG_CAPTURE
+
+## PR Purpose
+Generate runtime-derived preview SVG assets for samples by loading each runnable sample, allowing runtime/gameplay to proceed for 3 seconds, then capturing the live canvas appearance and producing the preview SVG from that runtime state.
+
+## Scope
+In scope only:
+- sample preview generation script(s) or helper(s) directly responsible for preview creation
+- preview SVG output location used by the samples system
+- minimal automation hooks strictly required for capture orchestration
+- minimal docs/reporting for this PR
+
+Out of scope:
+- gameplay changes
+- engine-core refactors
+- sample detail page layout changes
+- tag/title/related/engine-classes-used normalization
+- changes to `samples/index.html` except if strictly required to consume the existing preview asset path already used by the system
+- any additional work on Phase 13 samples `1316`, `1317`, or `1318`
+- any modification inside:
+  - `docs/dev/start_of_day/chatGPT/`
+  - `docs/dev/start_of_day/codex/`
+
+## Frozen Samples
+Do not perform more work on:
+- `1316`
+- `1317`
+- `1318`
+
+These samples are explicitly accepted visually as they are now and must not be restyled, relabeled, relaid out, or otherwise normalized in this PR.
+
+## Required Implementation Shape
+1. Load each target sample's actual runnable sample page.
+2. Let the sample run for exactly 3000 ms before capture.
+3. Capture the live canvas appearance after that runtime window.
+4. Generate or update the preview SVG asset from that runtime-derived canvas state.
+5. Ensure the final preview asset is based on real runtime output, not a placeholder or manually drawn card.
+6. Keep changed-file count minimal and tightly scoped to runtime preview generation.
+
+## Capture Rules
+- Use the sample's real canvas output.
+- Wait 3000 ms after runtime start before capture.
+- Prefer deterministic capture where feasible.
+- If a sample does not animate meaningfully, still capture its real canvas state at 3 seconds.
+- Do not hand-draw preview art.
+- Do not replace runtime-derived previews with generic cards.
+- Preserve existing approved appearance for `1316`, `1317`, and `1318`.
+
+## Target Files
+Expected likely targets only if directly needed:
+- preview generation scripts/helpers
+- preview asset output folders/files used by the samples system
+- minimal automation support files directly required for runtime capture
+- docs under `docs/` for changed-file/validation reporting
+
+## Validation Required
+- confirm preview SVG assets exist for all samples targeted by the generation path
+- confirm representative previews were captured from live runtime after 3 seconds
+- confirm no placeholder preview cards remain as final generated assets for targeted samples
+- confirm representative samples still load normally after any automation hooks
+- confirm console is clean for tested representative samples
+- report exact files changed
+- report exact validation performed
+- report any samples that could not be captured and the exact reason
+- confirm `1316`, `1317`, and `1318` were not modified in this PR
+
+## Acceptance Criteria
+- Runtime preview generation works from actual sample canvas output.
+- Capture timing is 3 seconds from runtime start.
+- Preview assets are SVG outputs derived from runtime state.
+- Scope remains limited to preview generation.
+- `1316`, `1317`, and `1318` remain untouched.
+- ZIP output exists at the requested path.
+
+## ZIP Output Requirement
+Must produce:
+- `<project folder>/tmp/BUILD_PR_SAMPLES_RUNTIME_PREVIEW_SVG_CAPTURE.zip`
+
+ZIP must:
+- contain only repo-relevant delta output for this PR
+- exclude staged ZIPs from `<project folder>/tmp/`
+
+## Fail Fast
+Stop and report failure immediately if:
+- preview generation requires unrelated metadata/layout normalization
+- runtime capture requires broad engine-core redesign
+- capture cannot be performed from the actual sample canvas
+- implementation would require changing `1316`, `1317`, or `1318`
+- ZIP output is missing at the exact requested path

docs/dev/CODEX_COMMANDS.md

@@ -1,84 +1,39 @@
-# Codex command for BUILD_PR_SAMPLES_PRESENTATION_PREVIEW_AND_METADATA_NORMALIZATION
+# Codex Command
 
-MODEL: GPT-5.4-codex
+MODEL: GPT-5.4-codex  
 REASONING: high
 
-COMMAND:
-Execute BUILD_PR_SAMPLES_PRESENTATION_PREVIEW_AND_METADATA_NORMALIZATION exactly as written.
+## COMMAND
+Execute `BUILD_PR_SAMPLES_RUNTIME_PREVIEW_SVG_CAPTURE` exactly as written.
 
-EXECUTION ENVIRONMENT (MANDATORY):
+## 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
-
-PR PURPOSE:
-Normalize sample presentation, runtime-derived preview assets, metadata tags, and engine-class reporting consistently across the samples system.
-
-EXPECTED TARGETS:
-- `samples/index.html`
-- sample metadata source(s) directly used for titles, tags, related items, and engine-classes-used presentation
-- minimal sample detail rendering files/templates/helpers directly controlling page layout
-- preview SVG generation path or preview mapping files directly needed for producing previews from the running sample canvas appearance
-- reporting docs under `docs/`
-
-DO NOT:
-- modify gameplay code
-- modify engine core
-- change canonical paths
-- broaden scope beyond presentation / runtime-preview / metadata display normalization
-- modify `docs/dev/start_of_day/chatGPT/`
-- modify `docs/dev/start_of_day/codex/`
-
-REQUIRED IMPLEMENTATION SHAPE:
-1. Create preview SVG assets for all samples based on the sample canvas appearance when running
-2. Do not use generic placeholder cards as the final preview source
-3. Remove preview image from sample detail pages
-4. Ensure sample page layout is:
-   - H1
-   - description
-   - tags
-   - canvas
-   - related samples
-   - engine classes used
-   - navigation retained
-5. Normalize tags to classes used while excluding:
-   - engine
-   - theme
-   - phase labels
-   - sample numbers
-   - sample names
-6. Normalize Engine Classes Used references consistently to the engine folder/class format
-7. Update `samples/index.html` labels for 1316 / 1317 / 1318 to exactly match the sample page titles
-8. Keep changed-file count minimal for the approved scope
-
-VALIDATION (REQUIRED):
-- open representative sample pages and validate top-of-page structure
-- confirm preview image block is removed from sample pages
-- confirm tags remain at the top
-- confirm Related Samples is below the canvas and before Engine Classes Used
-- confirm Back to Samples and Prev / Next remain present and functional
-- confirm Engine Classes Used formatting is normalized
-- confirm tags exclude sample-number / phase / sample-name noise
-- confirm preview SVG assets exist and visually match the running canvas appearance for representative samples
-- confirm `samples/index.html` names for 1316 / 1317 / 1318 match sample page titles exactly
-- 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/BUILD_PR_SAMPLES_PRESENTATION_PREVIEW_AND_METADATA_NORMALIZATION.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:
-- runtime preview SVG generation requires broad asset pipeline redesign
-- engine-class normalization requires engine-core changes
-- layout normalization requires unrelated page architecture rewrites
-- missing ZIP output at exact path
+- Do not depend on external screenshot tools or browser extensions
+
+## HARD CONSTRAINTS
+- Do not modify gameplay logic except for minimal non-behavioral hooks strictly required for automated preview capture
+- Do not modify engine core unless absolutely required for capture orchestration
+- Do not change sample page layout
+- Do not change tags, titles, related samples, or engine-classes-used presentation
+- Do not modify `samples/index.html` except if strictly required to consume existing preview asset paths already used by the system
+- Do not modify `docs/dev/start_of_day/chatGPT/`
+- Do not modify `docs/dev/start_of_day/codex/`
+- Do not perform more work on `1316`, `1317`, or `1318`; preserve them exactly as they are now
+
+## RUNTIME CAPTURE REQUIREMENT
+For each targeted sample:
+1. Load the actual runnable sample page
+2. Let the game/sample run for 3 seconds
+3. Capture the live canvas appearance at 3000 ms
+4. Generate/update the preview SVG asset from that runtime-derived canvas state
+
+## ZIP OUTPUT REQUIREMENT
+Must produce:
+`<project folder>/tmp/BUILD_PR_SAMPLES_RUNTIME_PREVIEW_SVG_CAPTURE.zip`
+
+Task is not complete until that ZIP exists at the exact requested path.

docs/dev/COMMIT_COMMENT.txt

@@ -1,12 +1 @@
-BUILD_PR: normalize sample presentation, runtime-derived previews, tags, and engine-class reporting
-
-- create preview SVG assets for all samples from the running sample canvas appearance
-- remove preview image blocks from sample pages
-- keep H1, description, and tags at the top
-- keep Back to Samples and Prev / Next navigation
-- move Related Samples below canvas and before Engine Classes Used
-- normalize Engine Classes Used references
-- normalize tags to classes used excluding engine/theme/system-noise labels
-- sync samples/index.html names for 1316/1317/1318 with sample page titles
-
-No gameplay or engine-core scope included
+BUILD_PR_SAMPLES_RUNTIME_PREVIEW_SVG_CAPTURE: add 3-second runtime-derived preview SVG generation for samples, keep scope limited to preview capture, and leave 1316/1317/1318 untouched

docs/dev/NEXT_COMMAND.txt

@@ -1 +1,3 @@
-Create APPLY_PR_NETWORK_SAMPLES_RELOCATION_FROM_GAMES_TO_SAMPLES
+Next suggested command after this BUILD succeeds:
+
+Create APPLY_PR_SAMPLES_RUNTIME_PREVIEW_SVG_CAPTURE docs-only acceptance bundle with exact files changed, exact validation performed, and explicit confirmation that 1316/1317/1318 were not modified.