Skip to content

Commit 3fac22c

Browse files
author
DavidQ
committed
BUILD_PR: normalize sample presentation, previews, tags, and engine-class reporting
- create preview SVG assets for all samples - 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
1 parent 959e5cb commit 3fac22c

209 files changed

Lines changed: 8283 additions & 879 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 90 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,96 @@
1+
# Codex command for BUILD_PR_SAMPLES_PRESENTATION_PREVIEW_AND_METADATA_NORMALIZATION
2+
13
MODEL: GPT-5.4-codex
24
REASONING: high
35

46
COMMAND:
5-
Execute APPLY_PR_SAMPLES_DISCOVERY_DATA_AND_FINDABILITY
7+
Execute BUILD_PR_SAMPLES_PRESENTATION_PREVIEW_AND_METADATA_NORMALIZATION exactly as written.
8+
9+
EXECUTION ENVIRONMENT (MANDATORY):
10+
- Target platform: Windows
11+
- Prefer Node.js or vanilla JS for any scripting or generation support
12+
- DO NOT run `npm install`
13+
- DO NOT create `package.json`
14+
- DO NOT create `package-lock.json`
15+
- DO NOT create or populate `node_modules/`
16+
- DO NOT use PowerShell for path construction, rename-heavy work, or ZIP path generation
17+
18+
POWERSHELL PROHIBITION (CRITICAL):
19+
The following patterns are NOT allowed:
20+
- "$var/path"
21+
- "${var}/path"
22+
- "$base\$child"
23+
- "$($var)/path"
24+
25+
If any of these appear:
26+
- STOP
27+
- report the violation
28+
- do not silently retry
29+
30+
PR PURPOSE:
31+
Normalize sample presentation, preview assets, metadata tags, and engine-class reporting consistently across the samples system.
32+
33+
EXPECTED TARGETS:
34+
- `samples/index.html`
35+
- sample metadata source(s) directly used for titles, tags, related items, and engine-classes-used presentation
36+
- minimal sample detail rendering files/templates/helpers directly controlling page layout
37+
- preview SVG asset generation path or preview mapping files directly needed for normalization
38+
- reporting docs under `docs/`
39+
40+
DO NOT:
41+
- modify gameplay code
42+
- modify engine core
43+
- change canonical sample paths
44+
- broaden scope beyond presentation / preview / metadata display normalization
45+
- modify `docs/dev/start_of_day/chatGPT/`
46+
- modify `docs/dev/start_of_day/codex/`
47+
48+
REQUIRED IMPLEMENTATION SHAPE:
49+
1. Create preview SVG assets for all samples using a consistent convention
50+
2. Remove preview image from sample detail pages
51+
3. Ensure sample page layout is:
52+
- H1
53+
- description
54+
- tags
55+
- canvas
56+
- related samples
57+
- engine classes used
58+
- navigation retained
59+
4. Normalize tags to classes used while excluding:
60+
- engine
61+
- theme
62+
- phase labels
63+
- sample numbers
64+
- sample names
65+
5. Normalize Engine Classes Used references consistently to the engine folder/class format
66+
6. Update `samples/index.html` labels for 1316 / 1317 / 1318 to exactly match the sample page titles
67+
7. Keep changed-file count minimal for the approved scope
68+
69+
VALIDATION (REQUIRED):
70+
- open representative sample pages and validate top-of-page structure
71+
- confirm preview image block is removed from sample pages
72+
- confirm tags remain at the top
73+
- confirm Related Samples is below the canvas and before Engine Classes Used
74+
- confirm Back to Samples and Prev / Next remain present and functional
75+
- confirm Engine Classes Used formatting is normalized
76+
- confirm tags exclude sample-number / phase / sample-name noise
77+
- confirm preview SVG assets exist and are wired consistently
78+
- confirm `samples/index.html` names for 1316 / 1317 / 1318 match sample page titles exactly
79+
- confirm Phase 13 samples 1316, 1317, 1318 still load
80+
- confirm console is clean for tested pages
81+
- report exact files changed
82+
- report exact validation performed
683

7-
ENVIRONMENT:
8-
- Windows
9-
- No npm
10-
- No node_modules
84+
ZIP OUTPUT REQUIREMENT (HARD RULE):
85+
- MUST produce ZIP:
86+
<project folder>/tmp/BUILD_PR_SAMPLES_PRESENTATION_PREVIEW_AND_METADATA_NORMALIZATION.zip
87+
- ZIP must contain only repo-relevant delta output for this PR
88+
- Do not stage ZIP files from `<project folder>/tmp/`
89+
- Task is NOT complete until the ZIP exists at the exact requested path
1190

12-
ZIP:
13-
<project folder>/tmp/APPLY_PR_SAMPLES_DISCOVERY_DATA_AND_FINDABILITY.zip
91+
FAIL FAST:
92+
- preview SVG generation requires broad asset pipeline redesign
93+
- engine-class normalization requires engine-core changes
94+
- layout normalization requires unrelated page architecture rewrites
95+
- PowerShell parse issue before execution
96+
- missing ZIP output at exact path

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,12 @@
1-
APPLY_PR: apply metadata validation and tag normalization
1+
BUILD_PR: normalize sample presentation, previews, tags, and engine-class reporting
2+
3+
- create preview SVG assets for all samples
4+
- remove preview image blocks from sample pages
5+
- keep H1, description, and tags at the top
6+
- keep Back to Samples and Prev / Next navigation
7+
- move Related Samples below canvas and before Engine Classes Used
8+
- normalize Engine Classes Used references
9+
- normalize tags to classes used excluding engine/theme/system-noise labels
10+
- sync samples/index.html names for 1316/1317/1318 with sample page titles
11+
12+
No gameplay or engine-core scope included

‎docs/dev/reports/BUILD_PR_SAMPLES_PRESENTATION_PREVIEW_AND_METADATA_NORMALIZATION_validation.txt‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
BUILD_PR_SAMPLES_PRESENTATION_PREVIEW_AND_METADATA_NORMALIZATION
2+
3+
Scope confirmation:
4+
- No gameplay files changed
5+
- No engine-core files changed
6+
- Canonical sample paths preserved
7+
8+
Files changed for this BUILD:
9+
- scripts/normalize-samples-presentation.mjs
10+
- scripts/generate-samples-index.mjs
11+
- samples/_shared/sampleDetailPageEnhancement.js
12+
- samples/metadata/samples.index.metadata.json
13+
- samples/index.html
14+
- samples/phaseXX/XXYY/assets/preview.svg (generated for all canonical samples; count=197)
15+
- docs/dev/reports/BUILD_PR_SAMPLES_PRESENTATION_PREVIEW_AND_METADATA_NORMALIZATION_validation.txt
16+
17+
Validation executed:
18+
1) node scripts/normalize-samples-presentation.mjs
19+
- Result: OK normalized samples=197 metadata=197 previews=197
20+
21+
2) node scripts/generate-samples-index.mjs
22+
- Result: OK phases=15 samples=197 metadata=197 mode=write
23+
24+
3) node scripts/generate-samples-index.mjs --check
25+
- Result: OK phases=15 samples=197 metadata=197 mode=check
26+
27+
4) node scripts/generate-samples-index.mjs --self-test
28+
- Result: OK self-test metadata validation and tag normalization
29+
30+
5) Syntax validation
31+
- node --check scripts/normalize-samples-presentation.mjs => pass
32+
- node --check scripts/generate-samples-index.mjs => pass
33+
- node --check samples/_shared/sampleDetailPageEnhancement.js => pass
34+
35+
6) Metadata + preview + label normalization checks (all canonical samples)
36+
- Preview file presence and wiring: pass (197/197)
37+
- Engine Classes Used format `engine/...`: pass
38+
- Tag noise exclusion (engine/theme/phase/sample/name/id): pass
39+
- 1316/1317/1318 index labels exactly match sample H1 titles: pass
40+
41+
7) Console-clean guard checks for tested UI files
42+
- No console.log / console.warn / console.error in:
43+
- samples/index.html
44+
- samples/_shared/sampleDetailPageEnhancement.js
45+
46+
Representative checks:
47+
- Sample 0101: H1="Sample 0101 - Basic Loop" | index label="Sample 0101 - Basic Loop"
48+
- Sample 1316: H1="Network Sample A - Local Loopback / Fake Network" | index label="Network Sample A - Local Loopback / Fake Network"
49+
- Sample 1317: H1="Network Sample B - Host / Client Diagnostics" | index label="Network Sample B - Host / Client Diagnostics"
50+
- Sample 1318: H1="Network Sample C - Divergence / Trace Validation" | index label="Network Sample C - Divergence / Trace Validation"
51+
- Sample 1506: H1="Sample 1506 - Scene Graph / Entity Hierarchy Viewer" | index label="Sample 1506 - Scene Graph Entity Hierarchy Viewer"
52+
53+
Layout enforcement note:
54+
- sampleDetailPageEnhancement enforces DOM order to: H1, description, tags, navigation, canvas, related samples, engine classes used.
55+
- Preview image block creation removed from sample detail enhancement.

‎docs/dev/reports/change_summary.txt‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,9 @@
1-
Apply validation + tag normalization
1+
PR TYPE: BUILD
2+
PURPOSE: sample presentation / preview / metadata normalization
3+
4+
SUMMARY:
5+
- defines a final normalization BUILD for sample page layout, preview assets, tags, and engine-class reporting
6+
- preserves canonical sample paths and runtime behavior
7+
- removes preview image blocks from sample pages while adding preview SVG assets for all samples
8+
- aligns index labels for 1316 / 1317 / 1318 with sample page titles
9+
- keeps scope narrow, dependency-free, and Windows-safe

‎docs/dev/reports/file_tree_delta.txt‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,17 @@
1-
APPLY only
1+
EXPECTED DELTA (implementation-dependent, keep minimal)
2+
3+
MODIFIED:
4+
- samples/index.html
5+
- sample metadata source(s) directly controlling titles, tags, related items, and engine-classes-used presentation
6+
- minimal sample detail rendering files/templates/helpers controlling page layout
7+
8+
ADDED:
9+
- preview SVG assets for samples or the minimal generator/mapping path directly required to produce them
10+
11+
REPORT ONLY:
12+
- docs/pr/BUILD_PR_SAMPLES_PRESENTATION_PREVIEW_AND_METADATA_NORMALIZATION.md
13+
- docs/dev/codex_commands.md
14+
- docs/dev/commit_comment.txt
15+
- docs/dev/reports/change_summary.txt
16+
- docs/dev/reports/validation_checklist.txt
17+
- docs/dev/reports/file_tree_delta.txt

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 16 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,16 @@
1-
[ ] validation enforced
2-
[ ] duplicates rejected
3-
[ ] tags normalized
4-
[ ] filters/search ok
5-
[ ] no console errors
6-
[ ] zip exists
1+
[ ] preview SVG assets exist for all samples or follow the approved generated convention
2+
[ ] preview image block is removed from sample pages
3+
[ ] H1 is at the top of representative sample pages
4+
[ ] description is directly below H1 on representative sample pages
5+
[ ] tags remain at the top
6+
[ ] Back to Samples and Prev / Next remain present and functional
7+
[ ] Related Samples appears below the canvas and before Engine Classes Used
8+
[ ] Engine Classes Used formatting is normalized
9+
[ ] tags exclude phase/sample/name noise and exclude engine/theme
10+
[ ] tags reflect classes used
11+
[ ] samples/index.html names for 1316 / 1317 / 1318 match sample page titles exactly
12+
[ ] Phase 13 samples 1316, 1317, 1318 still load
13+
[ ] no console errors in tested pages
14+
[ ] no gameplay changes
15+
[ ] no engine-core changes
16+
[ ] ZIP exists at <project folder>/tmp/BUILD_PR_SAMPLES_PRESENTATION_PREVIEW_AND_METADATA_NORMALIZATION.zip

‎docs/pr/BUILD_PR_SAMPLES_PRESENTATION_PREVIEW_AND_METADATA_NORMALIZATION.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# BUILD_PR_SAMPLES_PRESENTATION_PREVIEW_AND_METADATA_NORMALIZATION
2+
3+
## Objective
4+
Implement a final, testable normalization wave for sample presentation, preview assets, tag semantics, and engine-class reporting across the samples system.
5+
6+
This BUILD must apply the following user-approved adjustments:
7+
8+
1. create preview SVG for all samples
9+
2. remove tags that are the sample number, phase, or sample name
10+
3. correct all "Engine classes used" entries so they reference `engine/<class>` consistently
11+
4. set tags to classes used, excluding `engine` and `theme`
12+
5. remove preview image from the sample page
13+
6. keep tags at the top
14+
7. keep Back to Samples and Prev / Next navigation
15+
8. move Related Samples under the canvas and before Engine Classes Used
16+
9. ensure H1 and description are at the top of the page
17+
10. correct the names on `samples/index.html` for 1316, 1317, 1318 so they exactly match the sample page names
18+
19+
Canonical path contract remains:
20+
- `samples/phaseXX/XXYY/index.html`
21+
22+
## PR Purpose
23+
One purpose only:
24+
- normalize sample presentation and sample metadata display consistency
25+
26+
## In Scope
27+
- generate or define preview SVG assets for all samples using a consistent convention
28+
- ensure sample detail pages no longer show a preview image block above or within the page body where it conflicts with the desired layout
29+
- normalize sample page structure so:
30+
- H1 is at the top
31+
- description is directly below the H1
32+
- tags remain near the top
33+
- Back to Samples and Prev / Next remain present
34+
- Related Samples appears below the canvas and before Engine Classes Used
35+
- normalize tags so tags represent classes used only, excluding:
36+
- engine
37+
- theme
38+
- phase number
39+
- sample number
40+
- sample name
41+
- normalize Engine Classes Used so entries consistently reference the engine folder/class relationship
42+
- update `samples/index.html` names for 1316 / 1317 / 1318 to match the corresponding sample pages exactly
43+
44+
## Out of Scope
45+
- no gameplay changes
46+
- no engine-core changes
47+
- no canonical path changes
48+
- no new dependency installation
49+
- no broad metadata schema redesign beyond what is directly needed to normalize tags and presentation
50+
- no unrelated performance work
51+
- no favorites/pinning changes unless directly required to preserve current behavior
52+
53+
## Required Behavior
54+
1. Every sample has a preview SVG asset or a clearly generated preview placeholder under the agreed samples preview convention.
55+
2. Sample detail pages do not show the preview image block in the final page layout.
56+
3. H1 and description are the first visible content at the top of the sample page.
57+
4. Tags remain at the top section of the sample page.
58+
5. Back to Samples and Prev / Next navigation remain intact.
59+
6. Related Samples appears below the canvas and before Engine Classes Used.
60+
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.
61+
8. Tags reflect classes used and exclude engine/theme/system-noise labels.
62+
9. `samples/index.html` labels for 1316 / 1317 / 1318 exactly match their sample page titles.
63+
64+
## Expected Targets
65+
Codex should keep reads narrow and stop if the actual required target list expands materially.
66+
67+
Expected implementation targets:
68+
- `samples/index.html`
69+
- sample metadata source(s) directly used for titles, tags, related items, and engine-classes-used presentation
70+
- minimal sample detail rendering files/templates/helpers directly controlling sample page layout
71+
- preview SVG asset generation path or preview asset mapping files directly needed for this normalization
72+
- report files under `docs/` only for output packaging
73+
74+
## Windows / Execution Constraints
75+
- target platform: Windows
76+
- prefer Node.js or vanilla JS where scripting support is needed
77+
- DO NOT run `npm install`
78+
- DO NOT create `package.json`
79+
- DO NOT create `package-lock.json`
80+
- DO NOT create or populate `node_modules/`
81+
- no PowerShell path interpolation
82+
- ZIP output under `<project folder>/tmp/` is mandatory
83+
84+
## Validation Requirements
85+
Minimum required validation:
86+
- open representative sample pages and verify:
87+
- H1 is at the top
88+
- description is directly below H1
89+
- tags are near the top
90+
- preview image block is removed
91+
- canvas renders in normal position
92+
- Related Samples appears below the canvas and before Engine Classes Used
93+
- Back to Samples and Prev / Next remain present and functional
94+
- verify Engine Classes Used formatting is normalized on representative samples
95+
- verify tags exclude sample-number / phase / sample-name noise
96+
- verify tags reflect classes used while excluding `engine` and `theme`
97+
- verify preview SVG assets exist for representative samples and are wired consistently
98+
- verify `samples/index.html` names for 1316 / 1317 / 1318 match their sample pages exactly
99+
- verify Phase 13 samples 1316, 1317, 1318 still load correctly
100+
- verify console stays clean for tested pages
101+
102+
## Acceptance Criteria
103+
- all 10 approved adjustments are implemented
104+
- no gameplay changes
105+
- no engine-core changes
106+
- canonical sample paths remain unchanged
107+
- changed-file count stays minimal for the scope
108+
- repo-structured delta ZIP is produced under `<project folder>/tmp/`
109+
110+
## Fail Fast
111+
Stop and report if:
112+
- preview SVG generation would require a broad asset pipeline redesign
113+
- engine-class normalization would require engine-core changes
114+
- layout normalization requires unrelated page architecture rewrites
115+
- implementation expands beyond sample presentation and metadata display normalization
116+
- the ZIP cannot be produced at the exact requested path

0 commit comments

Comments
 (0)