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

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -15,56 +15,45 @@ EXECUTION ENVIRONMENT (MANDATORY):
 - 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:
-Normalize sample presentation, preview assets, metadata tags, and engine-class reporting consistently across the samples system.
+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 asset generation path or preview mapping files directly needed for normalization
+- 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 sample paths
-- broaden scope beyond presentation / preview / metadata display normalization
+- 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 using a consistent convention
-2. Remove preview image from sample detail pages
-3. Ensure sample page layout is:
+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
-4. Normalize tags to classes used while excluding:
+5. Normalize tags to classes used while excluding:
    - engine
    - theme
    - phase labels
    - sample numbers
    - sample names
-5. Normalize Engine Classes Used references consistently to the engine folder/class format
-6. Update `samples/index.html` labels for 1316 / 1317 / 1318 to exactly match the sample page titles
-7. Keep changed-file count minimal for the approved scope
+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
@@ -74,7 +63,7 @@ VALIDATION (REQUIRED):
 - 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 are wired consistently
+- 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
@@ -89,8 +78,7 @@ ZIP OUTPUT REQUIREMENT (HARD RULE):
 - Task is NOT complete until the ZIP exists at the exact requested path
 
 FAIL FAST:
-- preview SVG generation requires broad asset pipeline redesign
+- runtime preview SVG generation requires broad asset pipeline redesign
 - engine-class normalization requires engine-core changes
 - layout normalization requires unrelated page architecture rewrites
-- PowerShell parse issue before execution
 - missing ZIP output at exact path

docs/dev/COMMIT_COMMENT.txt

@@ -1,6 +1,6 @@
-BUILD_PR: normalize sample presentation, previews, tags, and engine-class reporting
+BUILD_PR: normalize sample presentation, runtime-derived previews, tags, and engine-class reporting
 
-- create preview SVG assets for all samples
+- 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

docs/dev/reports/change_summary.txt

@@ -1,9 +1,9 @@
 PR TYPE: BUILD
-PURPOSE: sample presentation / preview / metadata normalization
+PURPOSE: sample presentation / runtime-preview / metadata normalization
 
 SUMMARY:
-- defines a final normalization BUILD for sample page layout, preview assets, tags, and engine-class reporting
+- corrects the preview requirement so SVGs reflect the running sample canvas appearance
 - preserves canonical sample paths and runtime behavior
-- removes preview image blocks from sample pages while adding preview SVG assets for all samples
+- removes preview image blocks from sample pages while adding runtime-representative preview SVGs for all samples
 - aligns index labels for 1316 / 1317 / 1318 with sample page titles
 - keeps scope narrow, dependency-free, and Windows-safe

docs/dev/reports/file_tree_delta.txt

@@ -6,7 +6,7 @@ MODIFIED:
 - minimal sample detail rendering files/templates/helpers controlling page layout
 
 ADDED:
-- preview SVG assets for samples or the minimal generator/mapping path directly required to produce them
+- runtime-derived preview SVG assets for samples or the minimal generator/mapping path directly required to produce them
 
 REPORT ONLY:
 - docs/pr/BUILD_PR_SAMPLES_PRESENTATION_PREVIEW_AND_METADATA_NORMALIZATION.md

docs/dev/reports/validation_checklist.txt

@@ -1,4 +1,4 @@
-[ ] preview SVG assets exist for all samples or follow the approved generated convention
+[ ] preview SVG assets reflect the running canvas appearance for representative samples
 [ ] preview image block is removed from sample pages
 [ ] H1 is at the top of representative sample pages
 [ ] description is directly below H1 on representative sample pages

docs/pr/BUILD_PR_SAMPLES_PRESENTATION_PREVIEW_AND_METADATA_NORMALIZATION.md

@@ -1,13 +1,13 @@
 # BUILD_PR_SAMPLES_PRESENTATION_PREVIEW_AND_METADATA_NORMALIZATION
 
 ## Objective
-Implement a final, testable normalization wave for sample presentation, preview assets, tag semantics, and engine-class reporting across the samples system.
+Implement a final, testable normalization wave for sample presentation, runtime-derived preview assets, tag semantics, and engine-class reporting across the samples system.
 
 This BUILD must apply the following user-approved adjustments:
 
-1. create preview SVG for all samples
+1. create preview SVG for all samples based on what the sample canvas looks like when the sample is running
 2. remove tags that are the sample number, phase, or sample name
-3. correct all "Engine classes used" entries so they reference `engine/<class>` consistently
+3. correct all "Engine Classes Used" entries so they reference `engine/<class>` consistently
 4. set tags to classes used, excluding `engine` and `theme`
 5. remove preview image from the sample page
 6. keep tags at the top
@@ -21,11 +21,12 @@ Canonical path contract remains:
 
 ## PR Purpose
 One purpose only:
-- normalize sample presentation and sample metadata display consistency
+- normalize sample presentation and sample metadata display consistency using runtime-representative previews
 
 ## In Scope
-- generate or define preview SVG assets for all samples using a consistent convention
-- ensure sample detail pages no longer show a preview image block above or within the page body where it conflicts with the desired layout
+- create or generate preview SVG assets for all samples using the actual running canvas output as the visual source
+- ensure preview assets visually represent the rendered sample scene rather than generic placeholders
+- ensure sample detail pages no longer show a preview image block in the page body
 - normalize sample page structure so:
   - H1 is at the top
   - description is directly below the H1
@@ -50,16 +51,21 @@ One purpose only:
 - no unrelated performance work
 - no favorites/pinning changes unless directly required to preserve current behavior
 
-## Required Behavior
-1. Every sample has a preview SVG asset or a clearly generated preview placeholder under the agreed samples preview convention.
-2. Sample detail pages do not show the preview image block in the final page layout.
-3. H1 and description are the first visible content at the top of the sample page.
-4. Tags remain at the top section of the sample page.
-5. Back to Samples and Prev / Next navigation remain intact.
-6. Related Samples appears below the canvas and before Engine Classes Used.
-7. Engine Classes Used entries are normalized to the `engine/<ClassName>` style or the exact repo-appropriate engine folder/class reference format used consistently across all samples.
-8. Tags reflect classes used and exclude engine/theme/system-noise labels.
-9. `samples/index.html` labels for 1316 / 1317 / 1318 exactly match their sample page titles.
+## Required Preview Behavior
+1. Every sample has a preview SVG asset or a clearly generated preview SVG based on the sample's actual running canvas appearance.
+2. The preview generation path must use the live or representative rendered scene as the source of truth.
+3. The preview SVG should capture the look of the sample canvas, not a generic text-only or placeholder card.
+4. If exact runtime capture cannot be fully automated for a subset of samples, fail fast and report which samples block automation rather than silently substituting generic placeholders.
+
+## Required Page Behavior
+1. Sample detail pages do not show the preview image block in the final page layout.
+2. H1 and description are the first visible content at the top of the sample page.
+3. Tags remain at the top section of the sample page.
+4. Back to Samples and Prev / Next navigation remain intact.
+5. Related Samples appears below the canvas and before Engine Classes Used.
+6. Engine Classes Used entries are normalized to the `engine/<ClassName>` style or the exact repo-appropriate engine folder/class reference format used consistently across all samples.
+7. Tags reflect classes used and exclude engine/theme/system-noise labels.
+8. `samples/index.html` labels for 1316 / 1317 / 1318 exactly match their sample page titles.
 
 ## Expected Targets
 Codex should keep reads narrow and stop if the actual required target list expands materially.
@@ -68,7 +74,7 @@ Expected implementation 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 sample page layout
-- preview SVG asset generation path or preview asset mapping files directly needed for this normalization
+- preview SVG generation path or preview asset mapping files directly needed to produce runtime-representative previews
 - report files under `docs/` only for output packaging
 
 ## Windows / Execution Constraints
@@ -94,13 +100,14 @@ Minimum required validation:
 - verify Engine Classes Used formatting is normalized on representative samples
 - verify tags exclude sample-number / phase / sample-name noise
 - verify tags reflect classes used while excluding `engine` and `theme`
-- verify preview SVG assets exist for representative samples and are wired consistently
+- verify preview SVG assets exist for representative samples and visually match the running canvas appearance
 - verify `samples/index.html` names for 1316 / 1317 / 1318 match their sample pages exactly
 - verify Phase 13 samples 1316, 1317, 1318 still load correctly
 - verify console stays clean for tested pages
 
 ## Acceptance Criteria
 - all 10 approved adjustments are implemented
+- preview SVGs are derived from what the sample canvas looks like when running
 - no gameplay changes
 - no engine-core changes
 - canonical sample paths remain unchanged
@@ -109,7 +116,7 @@ Minimum required validation:
 
 ## Fail Fast
 Stop and report if:
-- preview SVG generation would require a broad asset pipeline redesign
+- runtime-representative preview SVG generation would require a broad asset pipeline redesign
 - engine-class normalization would require engine-core changes
 - layout normalization requires unrelated page architecture rewrites
 - implementation expands beyond sample presentation and metadata display normalization

samples/_shared/runtimePreviewCapture.html

@@ -0,0 +1,147 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <title>Runtime Preview Capture</title>
+  <style>
+    html, body {
+      margin: 0;
+      width: 100%;
+      height: 100%;
+      overflow: hidden;
+      background: #000;
+    }
+    #frame {
+      position: fixed;
+      width: 1px;
+      height: 1px;
+      left: -10000px;
+      top: -10000px;
+      border: 0;
+      visibility: hidden;
+    }
+    #surface {
+      display: block;
+      width: 100vw;
+      height: 100vh;
+      background: #000;
+    }
+  </style>
+</head>
+<body>
+  <iframe id="frame" title="sample frame" sandbox="allow-scripts allow-same-origin"></iframe>
+  <canvas id="surface"></canvas>
+  <script>
+    (function () {
+      const params = new URLSearchParams(window.location.search);
+      const samplePath = params.get('sample') || '';
+      const width = Number(params.get('w') || 640);
+      const height = Number(params.get('h') || 360);
+      const settleMs = Number(params.get('settle') || 1800);
+      const timeoutMs = Number(params.get('timeout') || 12000);
+      const outputCanvas = document.getElementById('surface');
+      const frame = document.getElementById('frame');
+
+      outputCanvas.width = width;
+      outputCanvas.height = height;
+      const ctx = outputCanvas.getContext('2d');
+
+      function writeLabel(text, color) {
+        ctx.fillStyle = '#0b1020';
+        ctx.fillRect(0, 0, width, height);
+        ctx.strokeStyle = '#334e7a';
+        ctx.lineWidth = 2;
+        ctx.strokeRect(10, 10, width - 20, height - 20);
+        ctx.fillStyle = color;
+        ctx.font = '600 18px monospace';
+        ctx.fillText(text, 20, 40);
+      }
+
+      function drawSourceCanvas(sourceCanvas) {
+        const sw = sourceCanvas.width || sourceCanvas.clientWidth || width;
+        const sh = sourceCanvas.height || sourceCanvas.clientHeight || height;
+        if (!sw || !sh) {
+          throw new Error('Canvas has invalid size.');
+        }
+
+        const scale = Math.max(width / sw, height / sh);
+        const dw = sw * scale;
+        const dh = sh * scale;
+        const dx = (width - dw) * 0.5;
+        const dy = (height - dh) * 0.5;
+
+        ctx.fillStyle = '#000';
+        ctx.fillRect(0, 0, width, height);
+        ctx.drawImage(sourceCanvas, dx, dy, dw, dh);
+      }
+
+      function setStatus(status) {
+        document.body.setAttribute('data-capture-status', status);
+        document.title = 'capture:' + status;
+      }
+
+      function fail(message) {
+        writeLabel(message, '#ff9ca8');
+        setStatus('error');
+      }
+
+      if (!samplePath) {
+        fail('Missing sample parameter');
+        return;
+      }
+
+      writeLabel('Loading sample...', '#a5c0e6');
+      setStatus('loading');
+
+      const startTime = Date.now();
+      let settled = false;
+
+      frame.src = samplePath;
+
+      function attemptCapture() {
+        try {
+          const frameDoc = frame.contentDocument;
+          if (!frameDoc) {
+            throw new Error('Frame document unavailable.');
+          }
+
+          const sourceCanvas = frameDoc.querySelector('canvas');
+          if (!sourceCanvas) {
+            if (Date.now() - startTime > timeoutMs) {
+              fail('Canvas not found');
+              return;
+            }
+            requestAnimationFrame(attemptCapture);
+            return;
+          }
+
+          if (!settled) {
+            settled = true;
+            setTimeout(attemptCapture, settleMs);
+            return;
+          }
+
+          drawSourceCanvas(sourceCanvas);
+          setStatus('ready');
+        } catch (error) {
+          if (Date.now() - startTime > timeoutMs) {
+            fail('Capture timeout');
+            return;
+          }
+          requestAnimationFrame(attemptCapture);
+        }
+      }
+
+      frame.addEventListener('load', function () {
+        requestAnimationFrame(attemptCapture);
+      });
+
+      setTimeout(function () {
+        if (document.body.getAttribute('data-capture-status') !== 'ready') {
+          fail('Capture timeout');
+        }
+      }, timeoutMs + settleMs + 800);
+    })();
+  </script>
+</body>
+</html>

samples/_shared/sampleDetailPageEnhancement.js

@@ -177,9 +177,10 @@ function ensureStyles() {
     '  color: #e7edf8;',
     '  font: 600 12px/1.2 monospace;',
     '}',
+    '.sample-detail-row a { color: #ffffff; }',
     '.sample-detail-nav { display: flex; flex-wrap: wrap; gap: 12px; margin: 10px 0; }',
-    '.sample-detail-nav a { color: #9bd1ff; }',
-    '.sample-detail-muted { color: #c7d5ea; margin: 6px 0 0; }'
+    '.sample-detail-nav a { color: #ffffff; }',
+    '.sample-detail-muted { color: #ffffff; margin: 6px 0 0; }'
   ].join('\n');
   document.head.appendChild(style);
 }

samples/metadata/samples.index.metadata.json

@@ -5007,7 +5007,7 @@
         "engine/theme/index/ThemeTokens",
         "engine/utils/math/clamp"
       ],
-      "indexLabel": "Sample 1318 - Divergence / Trace Validation"
+      "indexLabel": "Network Sample C - Divergence / Trace Validation"
     },
     {
       "id": "1401",