Skip to content

Commit c0f5d45

Browse files
ToolboxAidToolboxAid
committed
Use the individual commit comment generated for each PR. Do not squash PR_26152_149 through PR_26152_153 into a single commit.
1 parent fcd56a2 commit c0f5d45

5 files changed

Lines changed: 450 additions & 0 deletions

‎docs/dev/reports/sample_rebuild_authoritative_surfaces.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# Sample Rebuild Authoritative Surfaces
2+
3+
PR: PR_26152_152-sample-rebuild-authoritative-surfaces
4+
Date: 2026-06-02
5+
6+
## Scope
7+
8+
- Defined authoritative validation surfaces.
9+
- Identified which schemas govern rebuilt samples.
10+
- Eliminated assumptions about `workspace.schema.json`.
11+
- Made no sample JSON changes.
12+
13+
## Authoritative Surfaces
14+
15+
| Surface | Authority | Use For Rebuilt Samples |
16+
| --- | --- | --- |
17+
| `tools/schemas/game.manifest.schema.json` | Active manifest schema | Game/sample manifest ownership, launch path, tool map, and asset/tool references where game manifest direction is used. |
18+
| `tools/schemas/tools/*.schema.json` | Active tool payload schemas | Tool-specific payload validation. |
19+
| `tools/schemas/samples/sample.tool-payload.schema.json` | Existing sample wrapper schema | Legacy wrapper validation only, unless future rebuild keeps wrapper format intentionally. |
20+
| `src/shared/contracts/projectWorkspaceRuntimeContract.js` | ProjectWorkspace runtime-only contract | ProjectWorkspace handoff and runtime coordination boundaries. |
21+
| `src/shared/contracts/toolStateContract.js` | Tool State contract | Saved tool payload ownership, version, status, visibility, and portability. |
22+
| `src/shared/contracts/gameManifestContract.js` | Contract-level manifest planning surface | Portable manifest ownership rules for future DB/export alignment. |
23+
24+
## Non-Authoritative Or Missing Surfaces
25+
26+
| Surface | Status | Decision |
27+
| --- | --- | --- |
28+
| `tools/schemas/workspace.schema.json` | Missing | Do not assume it exists. |
29+
| `tools/schemas/workspace.manifest.schema.json` | Missing | Do not use as authoritative for rebuilt samples in this lane. |
30+
| Historical references under `docs/dev/reports/` | Historical | Do not treat as active schema ownership. |
31+
| Historical snapshots under `tools/schemas/docs/` | Historical | Do not treat as active schema ownership. |
32+
| Sample launch behavior | Future | Not an authoritative validation surface until rebuilt sample execution PRs scope it. |
33+
34+
## Active Game Manifest Tool Keys
35+
36+
Current `game.manifest.schema.json` governs these tool keys under `tools`:
37+
38+
- `asset-manager-v2`
39+
- `audio-sfx-playground-v2`
40+
- `input-mapping-v2`
41+
- `midi-studio-v2`
42+
- `object-vector-studio-v2`
43+
- `palette-manager-v2`
44+
- `text2speech-V2`
45+
46+
Other rebuilt sample tools may need either:
47+
48+
- direct Tool State payload validation against `tools/schemas/tools/<toolId>.schema.json`, or
49+
- an explicit future schema update before they become manifest-owned sample launch targets.
50+
51+
## Validation
52+
53+
Static validation surface review only:
54+
55+
```powershell
56+
rg --files tools/schemas
57+
Get-ChildItem tools/schemas -Recurse -Filter '*workspace*'
58+
node -e "<static active schema surface inventory>"
59+
```
60+
61+
Result: PASS.
62+
63+
## Lanes Executed
64+
65+
- docs/report authoritative surface review only.
66+
67+
## Lanes Skipped
68+
69+
- samples - no sample JSON changes and no sample launch validation.
70+
- runtime - no runtime behavior changed.
71+
- tool runtime validation - not run.
72+
- engine - no engine code changed.
73+
- Playwright - not impacted.
74+
75+
## Samples Decision
76+
77+
SKIP / pending rebuild. Rebuilt samples remain future work.
78+
79+
## Playwright
80+
81+
Playwright impacted: No.
82+
83+
## Blocker Scope
84+
85+
No blocker for static surface review. Missing workspace schema assumptions are eliminated from the active validation plan.

‎docs/dev/reports/sample_rebuild_execution_readiness.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# Sample Rebuild Execution Readiness
2+
3+
PR: PR_26152_153-sample-rebuild-execution-readiness
4+
Date: 2026-06-02
5+
6+
## Scope
7+
8+
- Confirmed rebuild execution readiness.
9+
- Confirmed Wave 1 sample selection.
10+
- Confirmed validation path.
11+
- Confirmed unrebuilt samples remain SKIP.
12+
- Made no sample JSON changes.
13+
14+
## Readiness Summary
15+
16+
| Area | Status | Notes |
17+
| --- | --- | --- |
18+
| Schema discovery | PASS | Active schema ownership surfaces are identified. |
19+
| Dependency map | PASS | Sample types are mapped to manifest, tool payload, Tool State, and ProjectWorkspace surfaces. |
20+
| Wave 1 targets | PASS | Exact sample directories and JSON files are named. |
21+
| Authoritative surfaces | PASS | Active surfaces are defined and workspace schema assumptions are eliminated. |
22+
| Sample JSON changes | SKIP | No sample JSON was modified. |
23+
| Sample launch validation | SKIP | Not run; future rebuilt sample PRs only. |
24+
| Unrebuilt samples | SKIP | Remain pending rebuild and are not failures. |
25+
26+
## Confirmed Wave 1 Selection
27+
28+
Execution can start with:
29+
30+
1. `samples/phase-19/1903`
31+
2. `samples/phase-14/1413`
32+
3. `samples/phase-14/1414`
33+
4. `samples/phase-12/1208`
34+
5. `samples/phase-19/1902`, after removing or replacing the missing workspace schema assumption
35+
36+
## Confirmed Validation Path
37+
38+
Future rebuild execution PRs should validate only rebuilt samples:
39+
40+
1. Static JSON parse.
41+
2. Active schema or approved target schema validation.
42+
3. Tool payload ownership validation.
43+
4. Tool State boundary validation.
44+
5. ProjectWorkspace manifest/toolState handoff validation.
45+
6. Targeted sample launch validation only when explicitly requested for rebuilt samples.
46+
47+
## Unrebuilt Sample Decision
48+
49+
- Unrebuilt samples remain SKIP / pending rebuild.
50+
- Unrebuilt samples must not be classified as FAIL.
51+
- Full sample tree validation remains out of scope until a future explicit full-lane PR.
52+
53+
## Validation
54+
55+
Readiness review only:
56+
57+
```powershell
58+
git diff --check
59+
```
60+
61+
Result: PASS.
62+
63+
## Lanes Executed
64+
65+
- docs/report readiness review only.
66+
67+
## Lanes Skipped
68+
69+
- samples - no sample JSON changes and no sample launch validation.
70+
- runtime - no runtime behavior changed.
71+
- tool runtime validation - not run.
72+
- engine - no engine code changed.
73+
- Playwright - not impacted.
74+
75+
## Samples Decision
76+
77+
SKIP / pending rebuild. Rebuilt samples remain future work until execution PRs modify exact sample targets.
78+
79+
## Playwright
80+
81+
Playwright impacted: No.
82+
83+
## Remaining Blockers
84+
85+
None for execution readiness planning. `samples/phase-19/1902` requires a schema surface decision before it can be rebuilt as a validation target.

‎docs/dev/reports/sample_rebuild_wave_1_targets.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Sample Rebuild Wave 1 Targets
2+
3+
PR: PR_26152_151-sample-rebuild-wave-1-targets
4+
Date: 2026-06-02
5+
6+
## Scope
7+
8+
- Refined Wave 1 sample rebuild targets.
9+
- Grouped targets by schema compatibility requirements.
10+
- Grouped targets by rebuild complexity.
11+
- Made no sample JSON changes.
12+
13+
## Refined Wave 1 Target Groups
14+
15+
| Group | Samples | Complexity | Reason |
16+
| --- | --- | --- | --- |
17+
| A - Low schema friction | `samples/phase-19/1903` | Low | Text to Speech V2 already has an active root-array payload schema. |
18+
| B - Single-tool wrapper rebuild | `samples/phase-14/1413` | Medium | Asset Pipeline payload needs wrapper-to-tool-payload mapping. |
19+
| C - Paired payload rebuild | `samples/phase-14/1414` | Medium | Sprite Editor and palette payloads need explicit relationship and ownership boundaries. |
20+
| D - Multi-tool payload rebuild | `samples/phase-12/1208` | High | Tilemap, parallax, palette, and SVG asset payloads need coordinated manifest/toolState mapping. |
21+
| E - Workspace dependency resolution | `samples/phase-19/1902` | Highest | Current sample references missing `workspace.manifest.schema.json`; must resolve authoritative surface before rebuild. |
22+
23+
## Exact Wave 1 JSON Targets
24+
25+
| Target | Group | Current Schema State |
26+
| --- | --- | --- |
27+
| `samples/phase-19/1903/sample.1903.text2speech-V2.json` | A | No `$schema`; payload matches active Text to Speech V2 root-array direction. |
28+
| `samples/phase-14/1413/sample.1413.asset-pipeline.json` | B | Legacy wrapper with no `$schema`. |
29+
| `samples/phase-14/1414/sample.1414.sprite-editor.json` | C | Legacy wrapper with no `$schema`. |
30+
| `samples/phase-14/1414/sample.1414.palette.json` | C | Existing `palette-browser.schema.json` reference. |
31+
| `samples/phase-12/1208/sample.1208.tile-map-editor.json` | D | Legacy wrapper with no `$schema`. |
32+
| `samples/phase-12/1208/sample.1208.parallax-editor.json` | D | Legacy wrapper with no `$schema`. |
33+
| `samples/phase-12/1208/sample.1208.palette.json` | D | Existing `palette-browser.schema.json` reference. |
34+
| `samples/phase-12/1208/sample.1208.svg-asset-studio.json` | D | Legacy wrapper with no `$schema`. |
35+
| `samples/phase-19/1902/sample.1902.workspace-all-tools.json` | E | References missing `workspace.manifest.schema.json`. |
36+
37+
## Recommended Execution Order
38+
39+
1. Rebuild `samples/phase-19/1903` first to prove root-array payload handoff.
40+
2. Rebuild `samples/phase-14/1413` to prove single-tool wrapper conversion.
41+
3. Rebuild `samples/phase-14/1414` to prove sprite plus palette relationship.
42+
4. Rebuild `samples/phase-12/1208` to prove coordinated multi-tool sample payloads.
43+
5. Rebuild or split `samples/phase-19/1902` only after the missing workspace schema assumption is removed or replaced.
44+
45+
## Validation
46+
47+
Static planning validation only:
48+
49+
```powershell
50+
node -e "<static Wave 1 target inventory>"
51+
```
52+
53+
Result: PASS.
54+
55+
## Lanes Executed
56+
57+
- docs/report Wave 1 target planning only.
58+
59+
## Lanes Skipped
60+
61+
- samples - no sample JSON changes and no sample launch validation.
62+
- runtime - no runtime behavior changed.
63+
- tool runtime validation - not run.
64+
- engine - no engine code changed.
65+
- Playwright - not impacted.
66+
67+
## Samples Decision
68+
69+
SKIP / pending rebuild. Wave 1 targets become validation targets only in future rebuild execution PRs.
70+
71+
## Playwright
72+
73+
Playwright impacted: No.
74+
75+
## Blocker Scope
76+
77+
No blocker for static target planning. `samples/phase-19/1902` remains the highest dependency risk.

‎docs/dev/reports/sample_schema_dependency_map.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Sample Schema Dependency Map
2+
3+
PR: PR_26152_150-sample-schema-dependency-map
4+
Date: 2026-06-02
5+
6+
## Scope
7+
8+
- Created schema dependency map.
9+
- Mapped sample types to authoritative schema sources.
10+
- Mapped ProjectWorkspace interactions.
11+
- Made no sample JSON changes.
12+
13+
## Dependency Map
14+
15+
| Sample Type | Current Shape | Authoritative Surface | ProjectWorkspace Interaction |
16+
| --- | --- | --- | --- |
17+
| Game/sample manifest | Manifest-like object with game/sample launch metadata | `tools/schemas/game.manifest.schema.json` or a future explicitly approved sample manifest schema | Provides `manifestInput`; does not persist ProjectWorkspace runtime state. |
18+
| Tool payload wrapper | `tool`, `version`, `payload` | `tools/schemas/samples/sample.tool-payload.schema.json` for legacy wrapper validation; active tool payload schema for payload content | Converted into explicit `toolStateInput` for rebuilt samples. |
19+
| Tool payload content | Tool-specific payload object or array | `tools/schemas/tools/<toolId>.schema.json` when active | Saved payload belongs to Tool State, not ProjectWorkspace. |
20+
| Palette data | Standalone `html-js-gaming.palette` document | `tools/schemas/tools/palette-browser.schema.json` currently; future rebuild may map to palette-manager/palette browser ownership | ProjectWorkspace may reference active palette context only. |
21+
| Tilemap document | `toolbox.tilemap/1` document | `tools/schemas/tools/tile-map-editor.schema.json` for rebuilt tool payload boundary | Tool State owns tilemap payload; manifest references assets/paths. |
22+
| Workspace all-tools sample | `html-js-gaming.project` with missing workspace schema reference | No active workspace schema; must map to game manifest plus explicit ProjectWorkspace handoff, or define an approved replacement first | ProjectWorkspace remains runtime-only coordination. |
23+
| Text to Speech V2 root array | Root array payload | `tools/schemas/tools/text2speech-V2.schema.json` | Tool State owns speech queue payload. |
24+
25+
## Wave 1 Dependency Requirements
26+
27+
| Sample JSON | Required Surface | Compatibility Requirement |
28+
| --- | --- | --- |
29+
| `samples/phase-19/1902/sample.1902.workspace-all-tools.json` | No active workspace schema; must resolve to game manifest/tool payload handoff or future schema | Highest dependency risk. |
30+
| `samples/phase-19/1903/sample.1903.text2speech-V2.json` | `tools/schemas/tools/text2speech-V2.schema.json` | Low schema risk; add explicit manifest and Tool State handoff in future rebuild. |
31+
| `samples/phase-14/1413/sample.1413.asset-pipeline.json` | `tools/schemas/tools/asset-pipeline.schema.json` | Legacy wrapper must map payload to active tool schema. |
32+
| `samples/phase-14/1414/sample.1414.sprite-editor.json` | `tools/schemas/tools/sprite-editor.schema.json` | Legacy wrapper must map payload to `spriteProject`. |
33+
| `samples/phase-14/1414/sample.1414.palette.json` | `tools/schemas/tools/palette-browser.schema.json` | Palette ownership must be explicit. |
34+
| `samples/phase-12/1208/sample.1208.tile-map-editor.json` | `tools/schemas/tools/tile-map-editor.schema.json` | Legacy wrapper must map tilemap fields to active payload boundary. |
35+
| `samples/phase-12/1208/sample.1208.parallax-editor.json` | `tools/schemas/tools/parallax-editor.schema.json` | Legacy wrapper must map parallax fields to active payload boundary. |
36+
| `samples/phase-12/1208/sample.1208.palette.json` | `tools/schemas/tools/palette-browser.schema.json` | Palette ownership must be explicit. |
37+
| `samples/phase-12/1208/sample.1208.svg-asset-studio.json` | `tools/schemas/tools/svg-asset-studio.schema.json` | Map legacy SVG asset sample to current asset/vector ownership decision. |
38+
39+
## ProjectWorkspace Interaction Rules
40+
41+
- ProjectWorkspace consumes explicit manifest and Tool State references.
42+
- ProjectWorkspace does not own sample payload data.
43+
- ProjectWorkspace does not own saved Tool State records.
44+
- Rebuilt samples must not use hidden fallback data, `localStorage`, `sessionStorage`, or runtime render state as source of truth.
45+
- Rebuilt sample image data must use file/path fields, not persisted `imageDataUrl`.
46+
47+
## Validation
48+
49+
Static dependency validation only:
50+
51+
```powershell
52+
node -e "<static schema/sample dependency inventory>"
53+
```
54+
55+
Result: PASS.
56+
57+
## Lanes Executed
58+
59+
- docs/report dependency mapping only.
60+
61+
## Lanes Skipped
62+
63+
- samples - no sample JSON changes and no sample launch validation.
64+
- runtime - no runtime behavior changed.
65+
- tool runtime validation - not run.
66+
- engine - no engine code changed.
67+
- Playwright - not impacted.
68+
69+
## Samples Decision
70+
71+
SKIP / pending rebuild. Rebuilt samples remain future work.
72+
73+
## Playwright
74+
75+
Playwright impacted: No.
76+
77+
## Blocker Scope
78+
79+
No blocker for static dependency mapping. Wave 1 execution must resolve the `1902` workspace-schema dependency before making it a PASS/FAIL launch target.

0 commit comments

Comments
 (0)