Skip to content

Commit 98095f9

Browse files
ToolboxAidToolboxAid
committed
Audit tool-linked samples for JSON SSoT including colors and visual config - PR 11.8. Ensure standalone sample tools load direct JSON SSoT including color and style data - PR 11.9
1 parent 0895eae commit 98095f9

37 files changed

Lines changed: 10757 additions & 333 deletions

‎docs/dev/codex_commands.md‎

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,20 @@
1-
Apply PR_11_7_NAV_LABEL_CLEANUP: remove [ ] from PREV/NEXT labels.
1+
# CODEX COMMANDS
2+
3+
model: gpt-5.3-codex
4+
reasoning: medium
5+
6+
Apply PR_11_9_STANDALONE_SAMPLE_TOOL_JSON_DIRECT_LOAD_AUDIT.
7+
8+
Required:
9+
- Treat samples as standalone tool launch users, not workspace launch users.
10+
- Review sample 1208 first and fix duplicated JS-vs-JSON ownership.
11+
- Ensure standalone tools load sample JSON payloads directly.
12+
- Remove/demote JS data modules that mirror JSON and create duplicate SSoT.
13+
- Scan all samples for standalone tool JSON payloads and verify all tool-visible data is JSON-owned.
14+
- Include colors, palettes, fill, stroke, style, preview/render config in the audit.
15+
- Do not use workspace-only validation as primary proof.
16+
- Do not add fallback/default/hidden sample data.
17+
- Do not scrape JS source.
18+
- Do not modify start_of_day folders.
19+
- Add validation report at docs/dev/reports/PR_11_9_STANDALONE_SAMPLE_TOOL_JSON_DIRECT_LOAD_AUDIT_report.md.
20+
- Return ZIP artifact at tmp/PR_11_9_STANDALONE_SAMPLE_TOOL_JSON_DIRECT_LOAD_AUDIT_delta.zip.

‎docs/dev/commit_comment.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
Remove brackets from PREV/NEXT labels - PR 11.7
1+
Ensure standalone sample tools load direct JSON SSoT including color and style data - PR 11.9

‎docs/dev/reports/PR_11_8_TOOL_LINKED_SAMPLE_JSON_SSOT_AUDIT_report.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# PR_11_8_TOOL_LINKED_SAMPLE_JSON_SSOT_AUDIT Report
2+
3+
## PASS/FAIL
4+
PASS (with scoped fixes applied and execution-backed validation passing)
5+
6+
## Scope Executed
7+
- Audited sample/tool linkage across tool JSON, sample launch metadata, and sample runtime JSON handoff paths.
8+
- Enforced JSON-path SSOT handoff where direct violations were found.
9+
- Kept scope to sample/tool JSON ownership and launch handoff only.
10+
11+
## Tool-Linked Samples Found
12+
- 0204, 0207, 0213, 0214, 0219, 0221, 0224
13+
- 0301, 0302, 0305, 0306
14+
- 0510
15+
- 0901, 0905
16+
- 1204, 1205, 1208, 1209, 1210, 1211
17+
- 1413, 1414, 1417
18+
- 1505
19+
20+
## JSON Files Inspected
21+
- Pattern families inspected:
22+
- `sample.*.asset-browser.json`
23+
- `sample.*.sprite-editor.json`
24+
- `sample.*.tile-map-editor.json`
25+
- `sample.*.vector-asset-studio.json`
26+
- `sample.*.vector-map-editor.json`
27+
- `sample.*.3d-asset-viewer.json`
28+
- `sample.*.parallax-editor.json`
29+
- `sample.*.asset-pipeline-tool.json`
30+
- `sample.*.tile-model-converter.json`
31+
- `sample.*.3d-json-payload-normalizer.json`
32+
- Launch metadata checked in sample `index.html` files for `samplePresetPath` validity.
33+
34+
## Violations Found and Fixed
35+
1. Legacy preset filename mismatch in runtime sample JS (`sample-####-tool.json` vs `sample.####.tool.json`) caused JSON load failures and fallback paths.
36+
- Fixed across sprite/tilemap-linked runtime scene files by switching to canonical `sample.####.tool.json` paths.
37+
38+
2. JS-owned canonical fallback tilemaps in tool-linked samples 0221 and 0305.
39+
- Removed canonical in-scene fallback ownership.
40+
- Replaced with explicit empty-state boot document and actionable load-failure status.
41+
- Runtime now depends on explicit sample JSON for real tilemap content.
42+
43+
3. Sample 1208 canonical tile/parallax ownership was JS-first.
44+
- Added `samples/phase-12/1208/data/toolFormattedTileMap.json` as explicit JSON artifact.
45+
- Updated tool presets to reference JSON tilemap document path.
46+
- Rewired sample runtime to load tile/parallax documents from tool preset JSON (no JS canonical imports/fallback documents).
47+
48+
4. Broken tool launch links in 1208/1209/1210/1211 sample pages.
49+
- Updated `samplePresetPath` links to existing canonical preset files.
50+
51+
## Color/Palette Ownership Result Per Sample
52+
- PASS: 0204, 0207, 0213, 0214, 0219, 0221, 0224, 0301, 0302, 0305, 0306, 0510, 0901, 0905, 1204, 1205, 1208, 1209, 1210, 1211, 1413, 1414, 1417, 1505.
53+
- Notes:
54+
- Sprite samples now resolve canonical sprite preset JSON paths consistently.
55+
- Tilemap-linked samples 0221/0305 now avoid JS-owned canonical fallback maps.
56+
- 1208 tile/parallax preview config now resolves through explicit JSON documents.
57+
58+
## Samples Intentionally Unchanged (and Why)
59+
- Samples with already-valid tool JSON contract and load diagnostics were left unchanged to preserve smallest-scope implementation.
60+
- Existing defensive UI/runtime fallback messaging was not broadened; this PR focused on canonical JSON handoff/path correctness and JS canonical-data demotion where directly violated.
61+
62+
## Confirmation: No Fallback/Hidden Sample Data Added
63+
- Confirmed. This PR removes/demotes direct JS-owned canonical fallback ownership in the fixed targets and does not introduce new fallback sample payloads.
64+
65+
## Validation Performed
66+
1. Syntax validation (changed JS only)
67+
- Command: `node --check <changed-js-files>`
68+
- Result: PASS
69+
70+
2. Sample standalone data-flow validation
71+
- Command: `npm run test:sample-standalone:data-flow`
72+
- Result: PASS
73+
- Key output:
74+
- `schemaFailures: []`
75+
- `contractFailures: []`
76+
- `roundtripPathFailures: []`
77+
- `genericFailures: []`
78+
- `totalSampleToolPayloadFiles: 64`
79+
80+
3. Launch preset target existence sanity check
81+
- Verified all sample `samplePresetPath` targets referenced in sample HTML resolve to existing files after updates.
82+
- Result: PASS
83+
84+
## Confirmation: No start_of_day Changes
85+
- Confirmed. No `start_of_day` paths were modified.

‎docs/dev/reports/PR_11_9_STANDALONE_SAMPLE_TOOL_JSON_DIRECT_LOAD_AUDIT_report.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# PR_11_9_STANDALONE_SAMPLE_TOOL_JSON_DIRECT_LOAD_AUDIT Report
2+
3+
## PASS/FAIL
4+
PASS
5+
6+
## Standalone Validation Path Used (Primary)
7+
- Primary proof used standalone sample/tool validation, not workspace launch validation:
8+
- `npm run test:sample-standalone:data-flow`
9+
- `node ./tests/runtime/SampleStandaloneToolDataFlow.test.mjs` (captured to `tmp/PR_11_9_sample_standalone_data_flow_output.json`)
10+
- Supplemental audit artifacts:
11+
- `tmp/PR_11_9_sample_tool_json_audit.json`
12+
- `tmp/PR_11_9_standalone_tool_load_summary.json`
13+
14+
## Sample 1208 Findings and Fixes (Reviewed First)
15+
Findings:
16+
- Duplicate JS-vs-JSON ownership existed for tool-visible tile/parallax data via mirrored files:
17+
- `samples/phase-12/1208/data/toolFormattedParallax.js`
18+
- `samples/phase-12/1208/data/toolFormattedParallax.json`
19+
- `samples/phase-12/1208/data/toolFormattedTileMap.js`
20+
- `samples/phase-12/1208/data/toolFormattedTileMap.json`
21+
- Standalone sample/tool preset shape relied on document-path references where direct JSON document payload was preferred.
22+
23+
Fixes:
24+
- Removed JS mirror canonical files:
25+
- deleted `samples/phase-12/1208/data/toolFormattedParallax.js`
26+
- deleted `samples/phase-12/1208/data/toolFormattedTileMap.js`
27+
- Kept JSON canonical files:
28+
- `samples/phase-12/1208/data/toolFormattedParallax.json`
29+
- `samples/phase-12/1208/data/toolFormattedTileMap.json`
30+
- Normalized sample tool payloads to direct JSON document ownership for standalone load.
31+
32+
## JS Mirror Files Removed/Demoted
33+
Removed:
34+
- `samples/phase-12/1208/data/toolFormattedParallax.js`
35+
- `samples/phase-12/1208/data/toolFormattedTileMap.js`
36+
37+
Demotion outcome:
38+
- JSON files remain the canonical source.
39+
- No sample tool payload now references JS data module files as source payloads.
40+
41+
## All Tool-Linked Samples Found
42+
Sample IDs with standalone sample tool payloads audited:
43+
- 0201, 0202, 0204, 0205, 0207, 0208, 0210, 0213, 0214, 0217, 0219, 0220, 0221, 0224, 0226, 0227
44+
- 0301, 0302, 0303, 0305, 0306, 0308, 0313
45+
- 0510, 0512
46+
- 0708
47+
- 0901, 0905
48+
- 1204, 1205, 1208, 1209, 1210, 1211
49+
- 1315, 1319
50+
- 1406, 1407, 1413, 1414, 1417
51+
- 1505
52+
- 1606
53+
54+
## Direct JSON Load Result Per Standalone Tool
55+
From `tmp/PR_11_9_standalone_tool_load_summary.json` and standalone data-flow output:
56+
- `3d-asset-viewer`: load signals present, no failure signals.
57+
- `3d-camera-path-editor`: load signals present, no failure signals.
58+
- `3d-json-payload-normalizer`: load signals present, no failure signals.
59+
- `asset-browser`: load signals present, no failure signals.
60+
- `asset-pipeline-tool`: load signals present, no failure signals.
61+
- `palette-browser`: load signals present, no failure signals.
62+
- `parallax-editor`: load signals present, no failure signals.
63+
- `performance-profiler`: load signals present, no failure signals.
64+
- `physics-sandbox`: load signals present, no failure signals.
65+
- `replay-visualizer`: load signals present, no failure signals.
66+
- `tile-map-editor`: load signals present, no failure signals.
67+
- `tile-model-converter`: load signals present, no failure signals.
68+
- `vector-asset-studio`: load signals present, no failure signals.
69+
- `vector-map-editor`: load signals present, no failure signals.
70+
- `sprite-editor`, `state-inspector`, `skin-editor`: no generic load-signal requirement in this harness; no failure signals reported.
71+
72+
## Color/Palette/Style Ownership Result
73+
- Audited sample payloads include JSON-owned color/palette/style fields where applicable (`palette`, `color`, `fill`, `stroke`, `style`, selection/style-related fields).
74+
- No sample tool payload JSON used JS file references as canonical tool-visible data source.
75+
- Tile-map editor payloads that were path-only are now direct JSON documents in payload config.
76+
77+
## Fixes Applied Beyond 1208 (Direct Document Normalization)
78+
Updated to direct `config.tileMapDocument` (removed `tileMapDocumentPath` / `tilemapDocumentPath`):
79+
- `samples/phase-02/0221/sample.0221.tile-map-editor.json`
80+
- `samples/phase-02/0224/sample.0224.tile-map-editor.json`
81+
- `samples/phase-03/0305/sample.0305.tile-map-editor.json`
82+
- `samples/phase-12/1208/sample.1208.tile-map-editor.json`
83+
- `samples/phase-12/1209/sample.1209.tile-map-editor.json`
84+
- `samples/phase-12/1210/sample.1210.tile-map-editor.json`
85+
- `samples/phase-12/1211/sample.1211.tile-map-editor.json`
86+
- `samples/phase-12/1208/sample.1208.parallax-editor.json` (removed tilemap path reference; parallax document remains direct)
87+
88+
## Constraint Confirmations
89+
- No workspace-only validation used as primary proof.
90+
- No fallback/default/hidden sample data added.
91+
- No `start_of_day` folder changes.

‎docs/dev/reports/REPORT_PR_11_8.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# REPORT_PR_11_8_TOOL_LINKED_SAMPLE_JSON_SSOT_AUDIT
2+
3+
## Summary
4+
Final pre-closeout audit to ensure every tool-linked sample is fully JSON-source-of-truth.
5+
6+
## Target
7+
- Tool-visible data comes from JSON.
8+
- Color/palette/style data comes from JSON.
9+
- No hidden fallback or JS-owned canonical data remains for tool-linked samples.

‎docs/dev/reports/REPORT_PR_11_9.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# REPORT_PR_11_9_STANDALONE_SAMPLE_TOOL_JSON_DIRECT_LOAD_AUDIT
2+
3+
## Summary
4+
Final SSoT audit focused on sample standalone tool launches.
5+
6+
## Target
7+
- Standalone tools load direct sample JSON.
8+
- Sample 1208 no longer has duplicate JS mirror data as canonical source.
9+
- Tool-visible colors/styles/config are JSON-owned.

‎docs/pr/PR_11_8_TOOL_LINKED_SAMPLE_JSON_SSOT_AUDIT/BUILD.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# BUILD_PR_11_8_TOOL_LINKED_SAMPLE_JSON_SSOT_AUDIT
2+
3+
## Required Codex Work
4+
5+
### 1. Identify tool-linked samples
6+
Scan samples for links to tool payloads / tool JSON files / workspace launches. Include every sample with any of:
7+
- sample.*.asset-browser.json
8+
- sample.*.sprite-editor.json
9+
- sample.*.tilemap-studio.json
10+
- sample.*.vector-asset-studio.json
11+
- sample.*.vector-map-editor.json
12+
- sample.*.3d-asset-viewer.json
13+
- tool/workspace launch metadata
14+
15+
### 2. Verify JSON ownership
16+
For each tool-linked sample, verify the following are in JSON, not canonical JS constants/classes:
17+
- assets
18+
- tilemaps/tilesets
19+
- sprites/frames/palettes
20+
- vector shapes
21+
- vector maps
22+
- colors
23+
- fill/stroke/line width
24+
- selected item/tool state
25+
- preview config
26+
- import/export destinations
27+
28+
### 3. Fix violations
29+
If a sample contains canonical tool-visible data in JS:
30+
- move/normalize the data into the sample tool JSON
31+
- update runtime/tool code to consume JSON
32+
- do not add fallback/default/hidden sample data
33+
- do not scrape JS source
34+
35+
### 4. Color requirement
36+
Specifically check that all color-related tool-visible data is JSON-owned:
37+
- palette arrays
38+
- selected color
39+
- fill color
40+
- stroke color
41+
- background/grid colors if tool-visible
42+
- sprite palette colors
43+
- vector style colors
44+
45+
### 5. Validation report
46+
Create:
47+
docs/dev/reports/PR_11_8_TOOL_LINKED_SAMPLE_JSON_SSOT_AUDIT_report.md
48+
49+
Report must include:
50+
- all tool-linked samples found
51+
- JSON files inspected
52+
- violations found/fixed
53+
- color/palette ownership result per sample
54+
- samples intentionally unchanged with reason
55+
- confirmation no fallback data
56+
- confirmation no start_of_day changes
57+
58+
## Constraints
59+
- One PR purpose only: tool-linked sample JSON SSoT.
60+
- No broad UI polish.
61+
- No schema rewrite unless minimal compatible field addition is required.
62+
- No unrelated sample changes.

‎docs/pr/PR_11_8_TOOL_LINKED_SAMPLE_JSON_SSOT_AUDIT/PLAN.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# PLAN_PR_11_8_TOOL_LINKED_SAMPLE_JSON_SSOT_AUDIT
2+
3+
## Purpose
4+
Audit and enforce JSON source-of-truth for every sample that is tied to a tool, including visual/color data.
5+
6+
## Scope
7+
- All samples that launch, reference, preview, or provide data to tools.
8+
- Tool-linked sample JSON only.
9+
- Verify 100% of tool/sample data comes from JSON:
10+
- asset entries
11+
- selected asset/tool state
12+
- colors
13+
- palettes
14+
- stroke/fill values
15+
- tile/vector/sprite config
16+
- import/export destination hints
17+
- preview/render config
18+
- Remove or demote code-local canonical data where it duplicates JSON.
19+
- Preserve no fallback/hidden/default-data rule.
20+
- Do not modify start_of_day folders.
21+
22+
## Acceptance
23+
- Every tool-linked sample has explicit JSON data for tool-visible state/data.
24+
- No tool-linked sample depends on JS hardcoded canonical data for colors or other tool data.
25+
- Color/palette/stroke/fill config is JSON-owned where visible to tools.
26+
- Tools and sample previews consume the same JSON source.
27+
- Empty states still work when explicit JSON is absent.

‎docs/pr/PR_11_9_STANDALONE_SAMPLE_TOOL_JSON_DIRECT_LOAD_AUDIT/BUILD.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# BUILD_PR_11_9_STANDALONE_SAMPLE_TOOL_JSON_DIRECT_LOAD_AUDIT
2+
3+
## Required Codex Work
4+
5+
### 1. Correct validation target
6+
Treat samples as standalone tool launch users.
7+
Do not validate this PR using samples-to-workspace as the primary path.
8+
9+
Validate by opening/running standalone tools launched from samples.
10+
11+
### 2. Review sample 1208 first
12+
Inspect sample 1208:
13+
- `data/toolFormattedParallax.js`
14+
- `data/toolFormattedParallax.json`
15+
- `data/toolFormattedTileMap.js`
16+
- `data/toolFormattedTileMap.json`
17+
- `sample.1208.*.json`
18+
- `ToolFormattedTilesParallaxScene.js`
19+
- `main.js`
20+
21+
Expected issue:
22+
- JS files mirror JSON data and create duplicate source-of-truth risk.
23+
- Scene references JSON files and extracts nested payloads instead of treating JSON payload as the direct canonical input.
24+
25+
Fix so:
26+
- JSON is the only canonical data.
27+
- Standalone tools load the JSON directly.
28+
- Runtime/sample preview consumes the same JSON.
29+
- JS mirror data modules are removed or made non-canonical only if needed.
30+
31+
### 3. Scan all sample tool payloads
32+
Find all sample-owned tool JSON files:
33+
- `samples/**/sample.*.asset-browser.json`
34+
- `samples/**/sample.*.sprite-editor.json`
35+
- `samples/**/sample.*.tile-map-editor.json`
36+
- `samples/**/sample.*.tilemap-studio.json`
37+
- `samples/**/sample.*.vector-asset-studio.json`
38+
- `samples/**/sample.*.vector-map-editor.json`
39+
- `samples/**/sample.*.parallax-editor.json`
40+
- `samples/**/sample.*.palette.json`
41+
- `samples/**/sample.*.3d-asset-viewer.json`
42+
- any other `sample.*.<tool>.json`
43+
44+
For each:
45+
- verify the standalone tool can directly load the JSON file
46+
- verify tool-visible data is not supplied by JS mirror files
47+
- verify color/palette/style data is JSON-owned
48+
49+
### 4. Fix JSON payload shape where needed
50+
If a standalone tool currently receives only references to JSON:
51+
- normalize the sample payload so it contains the direct document/config the tool needs
52+
- keep source paths only as asset references, not as substitute data ownership
53+
- do not create fallback data
54+
55+
### 5. Validation report
56+
Create:
57+
docs/dev/reports/PR_11_9_STANDALONE_SAMPLE_TOOL_JSON_DIRECT_LOAD_AUDIT_report.md
58+
59+
Report must include:
60+
- standalone tool validation path used
61+
- all tool-linked samples found
62+
- sample 1208 findings and fixes
63+
- JS mirror files removed/demoted
64+
- color/palette/style ownership result
65+
- direct JSON load result per standalone tool
66+
- confirmation no workspace-only validation was used as primary proof
67+
- confirmation no fallback/hidden data and no start_of_day changes
68+
69+
## Constraints
70+
- One PR purpose only: standalone sample tools load direct JSON SSoT.
71+
- No broad UI polish.
72+
- No unrelated runtime refactor.
73+
- No schema rewrite unless minimal compatible payload normalization is required.

0 commit comments

Comments
 (0)