Skip to content

Commit 32d3e33

Browse files
author
DavidQ
committed
Migrate Samples2Tools naming to sample-xxxx-toolID.json across docs, sample links, preset filenames, and loader references; remove old preset filenames and add Batch 3 validation reports.
1 parent 7b11fb6 commit 32d3e33

25 files changed

Lines changed: 249 additions & 129 deletions

‎docs/dev/reports/samples2tools_batch_2_validation.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ Generated: 2026-04-23T23:17:40.888Z
1010
[x] Non-Phase-20 metadata tool mappings available
1111

1212
Execution evidence:
13-
- Canonical sample preset exists for 1208: samples/phase-12/1208/sample-1208.json
13+
- Canonical sample preset exists for 1208: samples/phase-12/1208/sample-1208-parallax-editor.json
1414
- Sample 1208 runtime loads shared sample JSON: samples/phase-12/1208/main.js
1515
- Sample 1208 roundtrip links pass sampleId + samplePresetPath: samples/phase-12/1208/index.html
1616
- Parallax tool query preload flow is implemented: tools/Parallax Scene Studio/main.js

‎docs/dev/reports/samples2tools_batch_3_summary.txt‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
Samples2Tools Batch 3 Summary
2+
Generated: 2026-04-23T23:35:45.186Z
3+
Scope: phase-01 through phase-19 sample->tool mappings with sample-xxxx-toolID preset naming
4+
5+
Mapped tools: 3
6+
Mapped sample links: 9
7+
8+
parallax-editor: 4 sample(s)
9+
tile-map-editor: 4 sample(s)
10+
vector-asset-studio: 1 sample(s)
11+
12+
Mapped links:
13+
- parallax-editor <= Phase 03 Sample 0306 | Nes Style Zones Parallax | ./phase-03/0306/index.html | preset: /samples/phase-03/0306/sample-0306-parallax-editor.json
14+
- parallax-editor <= Phase 12 Sample 1204 | Tilemap Parallax Hero | ./phase-12/1204/index.html | preset: /samples/phase-12/1204/sample-1204-parallax-editor.json
15+
- parallax-editor <= Phase 12 Sample 1205 | Multi-System Demo | ./phase-12/1205/index.html | preset: /samples/phase-12/1205/sample-1205-parallax-editor.json
16+
- parallax-editor <= Phase 12 Sample 1208 | Tool Formatted Tiles Parallax | ./phase-12/1208/index.html | preset: /samples/phase-12/1208/sample-1208-parallax-editor.json
17+
- tile-map-editor <= Phase 12 Sample 1208 | Tool Formatted Tiles Parallax | ./phase-12/1208/index.html | preset: /samples/phase-12/1208/sample-1208-tile-map-editor.json
18+
- tile-map-editor <= Phase 12 Sample 1209 | Tilemap Basic Layout Preset | ./phase-12/1209/index.html | preset: /samples/phase-12/1209/sample-1209-tile-map-editor.json
19+
- tile-map-editor <= Phase 12 Sample 1210 | Tilemap Objective Layout Preset | ./phase-12/1210/index.html | preset: /samples/phase-12/1210/sample-1210-tile-map-editor.json
20+
- tile-map-editor <= Phase 12 Sample 1211 | Tilemap Mario Learning Layout Preset | ./phase-12/1211/index.html | preset: /samples/phase-12/1211/sample-1211-tile-map-editor.json
21+
- vector-asset-studio <= Phase 12 Sample 1208 | Tool Formatted Tiles Parallax | ./phase-12/1208/index.html | preset: /samples/phase-12/1208/sample-1208-vector-asset-studio.json

‎docs/dev/reports/samples2tools_batch_3_validation.txt‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
Samples2Tools Batch 3 Validation
2+
Generated: 2026-04-23T23:35:45.186Z
3+
4+
[x] Roundtrip naming uses sample-xxxx-toolID.json
5+
[x] Expected tool preset files exist for mapped roundtrip samples
6+
[x] 1208 sample roundtrip links use sample-xxxx-toolID naming
7+
[x] 1209-1211 redirects use sample-xxxx-toolID naming
8+
[x] phase-01 through phase-19 scope excludes phase-20 mappings
9+
10+
Execution evidence:
11+
- Roundtrip naming uses sample-xxxx-toolID.json: samples/index.render.js:getRoundtripPresetPath
12+
- Expected tool preset files exist for mapped roundtrip samples: 9 preset files present
13+
- 1208 sample roundtrip links use sample-xxxx-toolID naming: samples/phase-12/1208/index.html
14+
- 1209-1211 redirects use sample-xxxx-toolID naming: samples/phase-12/1209-1211/index.html
15+
- phase-01 through phase-19 scope excludes phase-20 mappings: 9 links within phases 01-19
16+
- overall: pass

‎docs/dev/reports/samples2tools_link_map_3.json‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
{
2+
"generatedAt": "2026-04-23T23:35:45.186Z",
3+
"scope": "phase-01-phase-19",
4+
"naming": "sample-xxxx-toolID.json",
5+
"totalLinks": 9,
6+
"tools": [
7+
{
8+
"toolId": "parallax-editor",
9+
"count": 4
10+
},
11+
{
12+
"toolId": "tile-map-editor",
13+
"count": 4
14+
},
15+
{
16+
"toolId": "vector-asset-studio",
17+
"count": 1
18+
}
19+
],
20+
"links": [
21+
{
22+
"toolId": "parallax-editor",
23+
"sampleId": "0306",
24+
"phase": "03",
25+
"title": "Nes Style Zones Parallax",
26+
"href": "./phase-03/0306/index.html",
27+
"presetPath": "/samples/phase-03/0306/sample-0306-parallax-editor.json"
28+
},
29+
{
30+
"toolId": "parallax-editor",
31+
"sampleId": "1204",
32+
"phase": "12",
33+
"title": "Tilemap Parallax Hero",
34+
"href": "./phase-12/1204/index.html",
35+
"presetPath": "/samples/phase-12/1204/sample-1204-parallax-editor.json"
36+
},
37+
{
38+
"toolId": "parallax-editor",
39+
"sampleId": "1205",
40+
"phase": "12",
41+
"title": "Multi-System Demo",
42+
"href": "./phase-12/1205/index.html",
43+
"presetPath": "/samples/phase-12/1205/sample-1205-parallax-editor.json"
44+
},
45+
{
46+
"toolId": "parallax-editor",
47+
"sampleId": "1208",
48+
"phase": "12",
49+
"title": "Tool Formatted Tiles Parallax",
50+
"href": "./phase-12/1208/index.html",
51+
"presetPath": "/samples/phase-12/1208/sample-1208-parallax-editor.json"
52+
},
53+
{
54+
"toolId": "tile-map-editor",
55+
"sampleId": "1208",
56+
"phase": "12",
57+
"title": "Tool Formatted Tiles Parallax",
58+
"href": "./phase-12/1208/index.html",
59+
"presetPath": "/samples/phase-12/1208/sample-1208-tile-map-editor.json"
60+
},
61+
{
62+
"toolId": "tile-map-editor",
63+
"sampleId": "1209",
64+
"phase": "12",
65+
"title": "Tilemap Basic Layout Preset",
66+
"href": "./phase-12/1209/index.html",
67+
"presetPath": "/samples/phase-12/1209/sample-1209-tile-map-editor.json"
68+
},
69+
{
70+
"toolId": "tile-map-editor",
71+
"sampleId": "1210",
72+
"phase": "12",
73+
"title": "Tilemap Objective Layout Preset",
74+
"href": "./phase-12/1210/index.html",
75+
"presetPath": "/samples/phase-12/1210/sample-1210-tile-map-editor.json"
76+
},
77+
{
78+
"toolId": "tile-map-editor",
79+
"sampleId": "1211",
80+
"phase": "12",
81+
"title": "Tilemap Mario Learning Layout Preset",
82+
"href": "./phase-12/1211/index.html",
83+
"presetPath": "/samples/phase-12/1211/sample-1211-tile-map-editor.json"
84+
},
85+
{
86+
"toolId": "vector-asset-studio",
87+
"sampleId": "1208",
88+
"phase": "12",
89+
"title": "Tool Formatted Tiles Parallax",
90+
"href": "./phase-12/1208/index.html",
91+
"presetPath": "/samples/phase-12/1208/sample-1208-vector-asset-studio.json"
92+
}
93+
]
94+
}

‎docs/dev/roadmaps/MASTER_ROADMAP_SAMPLES2TOOLS.md‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@
3535
- [x] Validate that older payloads in active lanes are migrated and no active launcher depends on `imageDataUrl`.
3636

3737
## Canonical Data Contract
38-
- [.] File naming standard: `samples/phase-xx/xxxx/sample-xxxx.json`
38+
- [.] File naming standard: `samples/phase-xx/xxxx/sample-xxxx-toolID.json`
3939
- [ ] Required fields:
4040
- `sampleId` (string)
4141
- `phase` (string)
@@ -51,7 +51,7 @@
5151
## Launch Contract (Shared)
5252
- [x] Standard query parameters for tool launch:
5353
- `sampleId=<id>`
54-
- `samplePresetPath=/samples/phase-xx/xxxx/sample-xxxx.json`
54+
- `samplePresetPath=/samples/phase-xx/xxxx/sample-xxxx-toolID.json`
5555
- [ ] Tool boot behavior:
5656
- detect contract params
5757
- fetch JSON from `samplePresetPath`
@@ -69,17 +69,17 @@
6969
## Rollout Plan
7070

7171
### Batch 1 - Active Work (Phase 1 Slice)
72-
- [x] Add `samples/phase-12/1208/sample-1208.json` as shared sample/tool preset source.
72+
- [x] Add `samples/phase-12/1208/sample-1208-parallax-editor.json` as shared sample/tool preset source.
7373
- [x] Wire Sample 1208 page/tool link to pass:
7474
- `sampleId=1208`
75-
- `samplePresetPath=/samples/phase-12/1208/sample-1208.json`
75+
- `samplePresetPath=/samples/phase-12/1208/sample-1208-parallax-editor.json`
7676
- [x] Wire `Parallax Scene Studio` launch path to load and hydrate from `samplePresetPath` when provided.
7777
- [ ] Validate end-to-end parity for the slice (sample load + tool preload + visible content match).
7878

7979
### Phase 1 - Foundation + One Vertical Slice
8080
- [x] Add shared adapter guidance document for sample-to-tool loading.
8181
- [x] Implement one full reference flow:
82-
- sample page loads `sample-xxxx.json`
82+
- sample page loads `sample-xxxx-toolID.json`
8383
- same file is passed to tool launch
8484
- tool hydrates from same file
8585
- [x] Suggested first slice: `Parallax Scene Studio` (clear, low candidate count).
@@ -96,7 +96,7 @@
9696
- [ ] Vector Asset Studio (1 candidate sample)
9797
- [ ] Vector Map Editor (1 candidate sample)
9898
- [ ] For each:
99-
- create/link `sample-xxxx.json` in selected sample folders
99+
- create/link `sample-xxxx-toolID.json` in selected sample folders
100100
- add/open tool link with shared launch contract
101101
- verify tool state visibly matches sample payload intent
102102

@@ -138,10 +138,10 @@
138138
- [ ] Prefer semantically exact sample-tool matches over high volume.
139139
- [ ] Limit initial additions per tool card to 2-5 links.
140140
- [ ] Use non-Phase-20 samples only in this lane.
141-
- [ ] Maintain stable sample identity (`sample-xxxx.json`) for reproducibility.
141+
- [ ] Maintain stable sample identity (`sample-xxxx-toolID.json`) for reproducibility.
142142

143143
## Validation Checklist
144-
- [ ] Every linked sample has `sample-xxxx.json`.
144+
- [x] Every linked sample has `sample-xxxx-toolID.json`.
145145
- [ ] Sample page consumes same JSON it passes to tool.
146146
- [ ] Tool launch with `samplePresetPath` succeeds without manual edits.
147147
- [ ] Tool status includes loaded sample id/path.
@@ -154,6 +154,6 @@
154154
- [x] `docs/dev/reports/samples2tools_link_map_<n>.json`
155155

156156
## Current Snapshot (from tools_used.txt)
157-
- [x] Current tagged samples across active tools: `4` (excluding Phase 20)
157+
- [x] Current tagged samples across active tools: `9` (phase-01 through phase-19)
158158
- [x] Candidate coverage inventory exists for all active tools
159159
- [.] Convert candidates into curated, validated sample-to-tool links

‎docs/dev/samples2tools_adapter_guidance.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
## Shared Launch Contract
88
- Query params:
99
- `sampleId=<id>`
10-
- `samplePresetPath=/samples/phase-xx/xxxx/<tool-or-sample-name>.json`
10+
- `samplePresetPath=/samples/phase-xx/xxxx/sample-xxxx-toolID.json`
1111
- Rules:
1212
- Reject empty/invalid paths.
1313
- Normalize path separators to `/`.
@@ -66,6 +66,6 @@
6666

6767
## Current Verified Vertical Slice
6868
- Sample `1208`:
69-
- shared preset file exists
69+
- tool-specific preset files exist (`sample-1208-tile-map-editor.json`, `sample-1208-parallax-editor.json`, `sample-1208-vector-asset-studio.json`)
7070
- roundtrip links pass `sampleId` + `samplePresetPath`
7171
- Parallax, Tilemap, and Vector Asset Studio implement query preload adapters

‎samples/index.render.js‎

Lines changed: 18 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -43,17 +43,28 @@ function shouldUsePresetRoundtrip(sample, toolId) {
4343
if (!sampleId || !samplePhase) {
4444
return false;
4545
}
46-
if (sampleId === "1208" && samplePhase === "12") {
46+
if (samplePhase === "12" && sampleId === "1208") {
4747
return toolId === "tile-map-editor"
4848
|| toolId === "parallax-editor"
4949
|| toolId === "vector-asset-studio";
5050
}
51-
if (toolId !== "parallax-editor") {
52-
return false;
51+
if (toolId === "parallax-editor") {
52+
return (sampleId === "0306" && samplePhase === "03")
53+
|| (sampleId === "1204" && samplePhase === "12")
54+
|| (sampleId === "1205" && samplePhase === "12");
55+
}
56+
if (toolId === "tile-map-editor") {
57+
return (sampleId === "1209" && samplePhase === "12")
58+
|| (sampleId === "1210" && samplePhase === "12")
59+
|| (sampleId === "1211" && samplePhase === "12");
5360
}
54-
return (sampleId === "0306" && samplePhase === "03")
55-
|| (sampleId === "1204" && samplePhase === "12")
56-
|| (sampleId === "1205" && samplePhase === "12");
61+
return false;
62+
}
63+
64+
function getRoundtripPresetPath(sample, toolId) {
65+
const sampleId = normalize(sample?.id);
66+
const samplePhase = normalize(sample?.phase);
67+
return `/samples/phase-${samplePhase}/${sampleId}/sample-${sampleId}-${toolId}.json`;
5768
}
5869

5970
function buildRoundtripLinks(sample, toolRegistryMap) {
@@ -77,7 +88,7 @@ function buildRoundtripLinks(sample, toolRegistryMap) {
7788
let href = baseHref;
7889
let label = `Open ${normalize(tool.displayName) || normalize(tool.name) || toolId}`;
7990
if (shouldUsePresetRoundtrip(sample, toolId)) {
80-
const presetPath = `/samples/phase-${sample.phase}/${sample.id}/${toolId}-sample-${sample.id}.json`;
91+
const presetPath = getRoundtripPresetPath(sample, toolId);
8192
href = `${baseHref}?sampleId=${encodeURIComponent(sample.id)}&samplePresetPath=${encodeURIComponent(presetPath)}`;
8293
}
8394

samples/phase-03/0306/parallax-editor-sample-0306.json renamed to samples/phase-03/0306/sample-0306-parallax-editor.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@
6565
"preferredToolId": "parallax-editor"
6666
},
6767
"provenance": {
68-
"path": "/samples/phase-03/0306/parallax-editor-sample-0306.json",
68+
"path": "/samples/phase-03/0306/sample-0306-parallax-editor.json",
6969
"createdAt": "2026-04-23T00:00:00.000Z",
7070
"version": 1
7171
}

samples/phase-12/1204/parallax-editor-sample-1204.json renamed to samples/phase-12/1204/sample-1204-parallax-editor.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,7 @@
8080
"preferredToolId": "parallax-editor"
8181
},
8282
"provenance": {
83-
"path": "/samples/phase-12/1204/parallax-editor-sample-1204.json",
83+
"path": "/samples/phase-12/1204/sample-1204-parallax-editor.json",
8484
"createdAt": "2026-04-23T00:00:00.000Z",
8585
"version": 1
8686
}

samples/phase-12/1205/parallax-editor-sample-1205.json renamed to samples/phase-12/1205/sample-1205-parallax-editor.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,7 @@
8080
"preferredToolId": "parallax-editor"
8181
},
8282
"provenance": {
83-
"path": "/samples/phase-12/1205/parallax-editor-sample-1205.json",
83+
"path": "/samples/phase-12/1205/sample-1205-parallax-editor.json",
8484
"createdAt": "2026-04-23T00:00:00.000Z",
8585
"version": 1
8686
}

0 commit comments

Comments
 (0)