Skip to content

Commit 46b0f92

Browse files
author
DavidQ
committed
Document restart for Palette-first Tool v2 migration with session-backed data - PR 11.187
1 parent 0f6ed6a commit 46b0f92

5 files changed

Lines changed: 263 additions & 24 deletions

File tree

‎docs/dev/NEXT_RESTART.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# NEXT RESTART - TOOL V2 MIGRATION
2+
3+
## Open repo
4+
5+
```powershell
6+
cd C:\Users\davidq\Documents\GitHub\HTML-JavaScript-Gaming
7+
code .
8+
```
9+
10+
## Sync
11+
12+
```powershell
13+
git status
14+
git pull
15+
```
16+
17+
## Current Decision
18+
19+
Stop patching legacy Workspace Manager/tool shell code.
20+
21+
Start clean Tool v2 lane:
22+
23+
```text
24+
Palette first
25+
Session-backed shared data
26+
One tool at a time
27+
Reverse engineer, do not copy
28+
Move old tools to <tool>-v1
29+
No schema/sample/game changes
30+
```
31+
32+
## Supported load paths
33+
34+
```text
35+
1. Workspace from URL -> load data -> session -> tool
36+
2. Tool from URL -> load data -> session -> tool
37+
3. Tool from session loaded by Workspace
38+
```
39+
40+
## Next PR
41+
42+
```text
43+
PR_11_188_PALETTE_V2_REVERSE_ENGINEER_AND_REBUILD
44+
```
45+
46+
## Next PR must do
47+
48+
```text
49+
Reverse engineer Palette Browser
50+
Move tools/Palette Browser -> tools/Palette Browser-v1
51+
Create clean tools/Palette Browser
52+
Add/use shared CSS
53+
Use session context only
54+
No platformShell
55+
No assetUsageIntegration
56+
No shared handoff
57+
No fallback data
58+
No schema/sample/game changes
59+
```

‎docs/dev/codex_commands.md‎

Lines changed: 21 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,31 @@
1-
# Codex Commands — PR 11.184
1+
# Codex Commands - PR 11.187
22

33
Model: GPT-5 high
44
Reasoning: high
55

6-
Remove cross-tool aliasing.
6+
Commit/restart documentation only.
77

8-
Primary file:
9-
- `tools/toolRegistry.js`
8+
Do not modify:
9+
- schemas
10+
- samples
11+
- games
12+
- runtime tool code
1013

11-
Steps:
12-
1. Remove `TOOL_ID_ALIASES`.
13-
2. Update `resolveToolIdAlias(toolId)` so it only trims and returns exact input.
14-
3. Ensure `getToolById("vector-asset-studio")` does not resolve to SVG.
15-
4. Do not add fallback aliases.
16-
5. Create report:
17-
- `docs/dev/reports/pr_11_184_validation.md`
14+
Create/keep docs that define the restart lane:
1815

19-
Validation:
20-
- `node --check tools/toolRegistry.js`
21-
- `node --check "tools/Workspace Manager/main.js"`
22-
23-
Manual:
24-
- Open Workspace Manager sample 1902.
25-
- Confirm SVG tile still renders as `svg-asset-studio`.
26-
- Confirm no tool id aliases are used to launch SVG.
16+
- Tool v2 migration
17+
- Palette first
18+
- session-backed shared data
19+
- reverse engineer tools, do not copy old code
20+
- move old tools to `<tool>-v1`
21+
- support data load paths:
22+
1. workspace from URL -> session -> tool
23+
2. tool from URL -> session -> tool
24+
3. tool from workspace session
2725

28-
Full samples smoke:
29-
- Skip.
30-
- Reason: targeted registry alias cleanup.
26+
Validation:
27+
- docs only; no runtime validation required
28+
- full samples smoke skipped because this is commit/restart documentation
3129

3230
Return ZIP artifact at:
33-
`<project folder>/tmp/PR_11_184_20260430_01.zip`
31+
`<project folder>/tmp/PR_11_187_20260430_01.zip`

‎docs/dev/commit_comment.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
Remove cross-tool registry alias and require exact tool ids - PR 11.184
1+
Document restart for Palette-first Tool v2 migration with session-backed data - PR 11.187

‎docs/dev/reports/pr_11_187_restart_notes.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# PR 11.187 Restart Notes
2+
3+
## Current State
4+
The old Workspace Manager/SVG fix lane consumed too much time with little progress because legacy code paths are tangled:
5+
6+
- platformShell
7+
- assetUsageIntegration
8+
- shared handoff
9+
- old click dispatch
10+
- tool aliases
11+
- inconsistent tool entry behavior
12+
13+
Manual testing proved that direct tool/session loading can work, so the remaining issue is orchestration and legacy tool consistency.
14+
15+
## New Direction
16+
Do not keep fighting the old path.
17+
18+
Start Tool v2 migration:
19+
20+
1. Palette Browser / Manager first
21+
2. SVG Asset Studio second
22+
3. Vector Map Editor third
23+
4. Tilemap Studio fourth
24+
5. Continue one tool at a time
25+
26+
## Non-Negotiables
27+
- no schema changes
28+
- no sample changes
29+
- no game changes
30+
- no copied legacy implementation
31+
- old tool folder moves to `-v1`
32+
- new tool folder is clean
33+
- session context is the only shared data source
34+
- common CSS as much as possible
35+
36+
## Supported Data Load Paths
37+
1. Workspace from URL -> session -> tool
38+
2. Tool from URL -> session -> tool
39+
3. Tool from workspace session
40+
41+
## Restart Command Block
42+
43+
```powershell
44+
cd C:\Users\davidq\Documents\GitHub\HTML-JavaScript-Gaming
45+
code .
46+
git status
47+
git pull
48+
```
49+
50+
## Review Today's State
51+
52+
```powershell
53+
git status
54+
git diff --stat
55+
```
56+
57+
## Commit Suggested Current Lane
58+
59+
Use this only after reviewing/accepting the generated PR docs:
60+
61+
```powershell
62+
git add docs/pr docs/dev
63+
git commit -m "Start Palette-first Tool v2 migration lane with session-backed contracts - PR 11.187"
64+
```
65+
66+
## Next Codex Execution
67+
Run the next PR from this baseline:
68+
69+
```text
70+
PR_11_188_PALETTE_V2_REVERSE_ENGINEER_AND_REBUILD
71+
```
72+
73+
## Next PR Constraints
74+
- no schemas
75+
- no samples
76+
- no games
77+
- reverse engineer first
78+
- move Palette Browser to Palette Browser-v1
79+
- create clean Palette Browser v2
80+
- session-backed palette data
81+
- shared CSS foundation
82+
83+
## Validation
84+
- Runtime validation: not run.
85+
- Full samples smoke: skipped.
86+
- Reason: commit/restart documentation only; no schemas, samples, games, or runtime tool code were modified.

‎docs/pr/BUILD_PR_LEVEL_11_187_COMMIT_AND_RESTART_TOOL_V2_LANE.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# BUILD_PR_LEVEL_11_187_COMMIT_AND_RESTART_TOOL_V2_LANE
2+
3+
## Purpose
4+
Create commit-ready restart instructions for the new Tool v2 migration lane after the failed legacy Workspace Manager/SVG debugging loop.
5+
6+
## Decision
7+
Stop patching the old Workspace Manager/tool shell spaghetti.
8+
9+
Start a clean Tool v2 lane:
10+
11+
- Palette first
12+
- session-backed shared data
13+
- one tool at a time
14+
- reverse engineer behavior
15+
- do not copy old tool implementation code
16+
- move legacy tools to `<tool>-v1`
17+
- rebuild clean tools with consistent layout and shared CSS
18+
19+
## Hard Scope Rules
20+
No changes to:
21+
22+
- schemas
23+
- samples
24+
- games
25+
- runtime tool code
26+
27+
This PR is commit/restart documentation only. The lane it defines is architecture/tool cleanup only.
28+
29+
## Data Loading Rules
30+
There are three supported data-load paths:
31+
32+
### 1. Workspace from URL
33+
```text
34+
Workspace Manager v2 URL
35+
-> loads manifest/data
36+
-> stores session context
37+
-> passes session/context id to tool
38+
```
39+
40+
### 2. Tool from URL
41+
```text
42+
Tool URL
43+
-> loads explicit tool data from URL/preset path
44+
-> stores session context
45+
-> tool reads from session
46+
```
47+
48+
### 3. Tool from session loaded by workspace
49+
```text
50+
Workspace Manager v2
51+
-> writes session context
52+
-> launches tool with hostContextId/session id
53+
-> tool reads session context
54+
```
55+
56+
## Forbidden Data Paths
57+
Do not use:
58+
59+
- platformShell for v2 hosted data
60+
- assetUsageIntegration
61+
- shared asset handoff
62+
- shared palette handoff
63+
- fallback/default samples
64+
- guessed paths
65+
- tool id aliases
66+
- hidden data loading
67+
68+
## Reverse Engineering Rule
69+
For every tool:
70+
71+
1. Inspect old tool.
72+
2. Document behavior.
73+
3. Document inputs/outputs.
74+
4. Document UI sections.
75+
5. Document what to keep conceptually.
76+
6. Document what to discard.
77+
7. Move old folder to `<tool>-v1`.
78+
8. Build clean v2 folder from the documented behavior only.
79+
80+
Do not copy old implementation code.
81+
82+
## Next Execution Lane
83+
Continue from PR 11.186 / 11.187 into:
84+
85+
```text
86+
PR_11_188_PALETTE_V2_REVERSE_ENGINEER_AND_REBUILD
87+
```
88+
89+
Expected next PR:
90+
- inspect Palette Browser
91+
- create reverse engineering report
92+
- move `tools/Palette Browser/` to `tools/Palette Browser-v1/`
93+
- create clean `tools/Palette Browser/`
94+
- use session-backed data
95+
- use common shared CSS
96+
- no schema/sample/game changes

0 commit comments

Comments
 (0)