Repair preview path contract after sample structure change.

BUILD_PR_PREVIEW_PATH_CONTRACT_REALIGNMENT
- update tools/preview path resolution to current sample contract
- validate and remove/update any stale samples/shared preview dependency
- keep scope limited to preview-path repair

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -1,3 +1,6 @@
-Engine usage enforcement completion (Level 18 Track A)
+Repair preview path contract after sample structure change.
 
-BUILD_PR_LEVEL_18_1_ENGINE_USAGE_ENFORCEMENT_COMPLETION
+BUILD_PR_PREVIEW_PATH_CONTRACT_REALIGNMENT
+- update tools/preview path resolution to current sample contract
+- validate and remove/update any stale samples/shared preview dependency
+- keep scope limited to preview-path repair

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1,35 @@
-Docs-only enforcement PR
+BUILD_PR_PREVIEW_PATH_CONTRACT_REALIGNMENT
+Date: 2026-04-17
+Scope: Preview path contract repair only (tools/preview + preview generation script).
+
+Summary of changes
+1) Preview sample-path contract stays aligned to canonical sample paths:
+   - samples/phase-XX/XXXX/index.html
+
+2) Updated preview HTML executors to default preview output folder to images path:
+   - tools/preview/generate-list-previews_updated.html
+   - tools/preview/preview_svg_executor_1600x900.html
+   - tools/preview/preview_svg_executor_games_enter.html
+
+   Exact output-folder changes applied in each:
+   - input default: "assets" -> "assets/images"
+   - fallback display path: "assets" -> "assets/images"
+   - displayed sample write target now resolves as:
+     samples\\phase-XX\\XXXX\\assets\\images
+
+3) Updated runtime sample preview writer path:
+   - scripts/generate-runtime-sample-previews.mjs
+   - output path changed:
+     path.join(sample.sampleDir, 'assets', 'preview.svg')
+     -> path.join(sample.sampleDir, 'assets', 'images', 'preview.svg')
+
+4) Preview capture dependency remains aligned to preview tooling location:
+   - /tools/preview/runtimePreviewCapture.html
+   - local capture page: tools/preview/runtimePreviewCapture.html
+
+Notes
+- No engine/runtime feature behavior changed beyond preview output path contract.
+- No roadmap edits.
+- No start_of_day edits.
+- No unrelated cleanup.
+

docs/dev/reports/change_summary.txt

@@ -1 +1,19 @@
-generated
+BUILD_PR_PREVIEW_PATH_CONTRACT_REALIGNMENT file tree
+
+scripts/
+  generate-runtime-sample-previews.mjs  (modified)
+
+tools/
+  preview/
+    generate-list-previews_updated.html      (modified)
+    preview_svg_executor_1600x900.html       (modified)
+    preview_svg_executor_games_enter.html    (modified)
+    runtimePreviewCapture.html               (added)
+
+docs/
+  dev/
+    reports/
+      change_summary.txt         (updated)
+      validation_checklist.txt   (updated)
+      file_tree.txt              (updated)
+

docs/dev/reports/file_tree.txt

@@ -1,3 +1,36 @@
-[ ] games use engine
-[ ] no local logic
-[ ] validation pass
+BUILD_PR_PREVIEW_PATH_CONTRACT_REALIGNMENT - Validation Checklist
+Date: 2026-04-17
+
+[PASS] Syntax validation
+Command:
+- node --check scripts/generate-runtime-sample-previews.mjs
+Result:
+- Exit 0
+
+[PASS] Output-path contract verification (targeted file assertions)
+Command:
+- python inline assertion across:
+  - tools/preview/generate-list-previews_updated.html
+  - tools/preview/preview_svg_executor_1600x900.html
+  - tools/preview/preview_svg_executor_games_enter.html
+  - scripts/generate-runtime-sample-previews.mjs
+Result:
+- html default value="assets/images": expected 3, actual 3
+- html fallback || "assets/images": expected 3, actual 3
+- html stale default value="assets": expected 0, actual 0
+- html stale fallback || "assets": expected 0, actual 0
+- script path includes 'assets', 'images', 'preview.svg': expected 1, actual 1
+- script stale path 'assets', 'preview.svg': expected 0, actual 0
+- OVERALL PASS
+
+[PASS] Canonical phase-hyphen sample directory contract check
+Command:
+- Python scan over samples/ for phase directories matching ^phase-\d{2}$ and per-sample index.html presence
+Result:
+- PHASE_DIR_COUNT=19
+- MISSING_INDEX_COUNT=0
+
+Validation conclusion
+- Preview tooling now targets image output under assets/images/preview.svg.
+- Preview sample path resolution remains aligned to phase-hyphen contract.
+

docs/dev/reports/validation_checklist.txt

@@ -595,6 +595,7 @@ <h2>Phase 19 - Next Phase Bootstrap</h2>
         const parsed = parseSampleLink(href);
         const phase = parsed.phase;
         const sampleId = parsed.sampleId;
+        const defaultPreviewPath = buildDefaultSamplePreviewPath(phase, sampleId);
         const tags = parseTagTokens({ link });
         const titleText = labelText.toLowerCase();
         const descriptionText = String(link.getAttribute('title') || '').trim().toLowerCase();
@@ -609,8 +610,8 @@ <h2>Phase 19 - Next Phase Bootstrap</h2>
           href,
           section: link.closest('section'),
           searchText,
-          thumbnail: '',
-          preview: '',
+          thumbnail: defaultPreviewPath,
+          preview: defaultPreviewPath,
           itemNode: link,
           isVisible: true,
           favoriteButton: null,
@@ -696,6 +697,13 @@ <h2>Phase 19 - Next Phase Bootstrap</h2>
         };
       }
 
+      function buildDefaultSamplePreviewPath(phase, sampleId) {
+        if (!/^\d{2}$/.test(String(phase || '')) || !/^\d{4}$/.test(String(sampleId || ''))) {
+          return '';
+        }
+        return '/samples/phase-' + phase + '/' + sampleId + '/assets/images/preview.svg';
+      }
+
       function parseTagTokens(model) {
         const tags = String(model.link.getAttribute('data-tags') || '')
           .split(',')