Skip to content

Commit f36d9bd

Browse files
ToolboxAidToolboxAid
committed
Implement tool launch SSoT routing with exact launch labels
PR Details: - Routes sample-launched tools through explicit tools/<tool>/index.html targets using Open <tool>. - Routes game workspace flows through tools/Workspace Manager/index.html using Open with Workspace Manager. - Clears launch memory for external sample/game launches. - Removes default/fallback behavior from touched launch flow. - Adds validation report for SSoT routing and launch labels.
1 parent 49af3ae commit f36d9bd

6 files changed

Lines changed: 195 additions & 84 deletions

File tree

‎docs/dev/codex_rules.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,16 @@ Read and obey:
1010

1111
- docs/dev/specs/TOOL_LAUNCH_SSOT.md
1212

13+
## Required UI Labels
14+
15+
Samples:
16+
- use `Open <tool>` for sample-to-tool launch actions
17+
- do NOT use `Open with Workspace Manager`
18+
19+
Games:
20+
- use `Open with Workspace Manager` for game-to-workspace launch actions
21+
- do NOT use `Open <tool>`
22+
1323
## This PR
1424

1525
Allowed:
@@ -25,6 +35,7 @@ Forbidden:
2535
- implementation outside touched launch path
2636
- start_of_day changes
2737
- roadmap text rewrite
38+
- changing required UI label semantics
2839

2940
## Anti-Patterns Forbidden
3041

‎docs/dev/reports/tool_launch_ssot_routing_validation.md‎

Lines changed: 56 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -2,28 +2,31 @@
22

33
## Changed Files
44

5-
- `tools/shared/toolLaunchSSoT.js`
65
- `games/index.render.js`
76
- `docs/dev/reports/tool_launch_ssot_routing_validation.md`
87

98
## Tested UAT Paths
109

11-
1. Samples hub roundtrip launch href resolution via `resolveSampleToolLaunchHref(...)`.
12-
2. Games hub workspace launch href resolution via `resolveGameWorkspaceLaunchHref(...)`.
13-
3. External launch memory clearing via `clearExternalToolWorkspaceMemory()` and `launchWithExternalToolWorkspaceReset(...)`.
14-
4. Missing launch context handling for:
15-
- sample launch missing `sampleId`
16-
- games metadata entries missing valid `href`
10+
1. Samples hub: sample-to-tool action label and launch href generation.
11+
2. Games hub: game-to-workspace action label and launch href generation.
12+
3. External launch flow: storage reset before navigation.
13+
4. Missing launch context behavior: sample missing `sampleId`; game entries missing valid `href`.
1714

18-
## Proof: Samples Route To `tools/<tool>/index.html`
15+
## Proof Sample Actions Are Labeled `Open <tool>`
1916

20-
Command run:
17+
Code proof:
2118

22-
```bash
23-
node --input-type=module -
19+
- `samples/index.render.js:102`
20+
21+
```text
22+
const label = `Open ${normalize(tool.displayName) || normalize(tool.name) || toolId}`;
2423
```
2524

26-
Script output:
25+
This preserves required sample launch semantics and does not use `Open with Workspace Manager` for sample-to-tool actions.
26+
27+
## Proof Samples Route To `tools/<tool>/index.html`
28+
29+
Command output:
2730

2831
```text
2932
sampleLaunch {
@@ -32,21 +35,30 @@ sampleLaunch {
3235
}
3336
```
3437

35-
Implementation references:
38+
Code proof:
3639

3740
- `tools/shared/toolLaunchSSoT.js:75`
38-
- `tools/shared/toolLaunchSSoT.js:91`
41+
- `tools/shared/toolLaunchSSoT.js:86`
3942
- `samples/index.render.js:92`
43+
- `samples/index.render.js:345`
4044

41-
## Proof: Games Route To `tools/Workspace Manager/index.html`
45+
## Proof Game Actions Are Labeled `Open with Workspace Manager`
4246

43-
Command run:
47+
Code proof:
4448

45-
```bash
46-
node --input-type=module -
49+
- `games/index.render.js:260`
50+
51+
```text
52+
Open with Workspace Manager
4753
```
4854

49-
Script output:
55+
Additional V2 hardening:
56+
57+
- Removed unlabeled game launch triggers (`game-title-link`, card-click launch) so workspace launch is exposed through the required labeled action path.
58+
59+
## Proof Games Route To `tools/Workspace Manager/index.html`
60+
61+
Command output:
5062

5163
```text
5264
gameLaunch {
@@ -55,59 +67,58 @@ gameLaunch {
5567
}
5668
```
5769

58-
Implementation references:
70+
Code proof:
5971

6072
- `tools/shared/toolLaunchSSoT.js:105`
6173
- `tools/shared/toolLaunchSSoT.js:117`
6274
- `tools/shared/toolLaunchSSoT.js:118`
6375
- `games/index.render.js:147`
76+
- `games/index.render.js:407`
6477

65-
## Proof: External Launch Memory Is Cleared
78+
## Proof External Launch Memory Is Cleared
6679

67-
Command run:
68-
69-
```bash
70-
node --input-type=module -
71-
```
72-
73-
Script output:
80+
Command output:
7481

7582
```text
7683
clearResult true
7784
localAfterClear [ [ 'keep.one', 'x' ] ]
7885
sessionAfterClear [ [ 'keep.two', 'y' ] ]
7986
launchResult true
80-
assignCalls [ '/tools/Sprite%20Editor/index.html?sampleId=1208' ]
87+
assignCalls [ '/tools/Workspace%20Manager/index.html?gameId=2001&mount=game' ]
8188
localAfterLaunch [ [ 'keep.one', 'x' ] ]
8289
sessionAfterLaunch [ [ 'keep.two', 'y' ] ]
8390
```
8491

85-
Implementation references:
92+
Code proof:
8693

8794
- `tools/shared/toolLaunchSSoT.js:123`
8895
- `tools/shared/toolLaunchSSoT.js:140`
8996
- `samples/index.render.js:537`
90-
- `games/index.render.js:424`
91-
- `games/index.render.js:444`
97+
- `games/index.render.js:416`
9298

93-
## Proof: Missing Context Does Not Fallback
99+
## Proof Missing Context Does Not Fallback
94100

95-
1. Sample launch now requires `sampleId`; missing context returns explicit error and empty href:
101+
1. Missing sample launch context is explicit and non-routable:
96102

97103
```text
98104
missingSampleContext { href: '', error: 'Tool "sprite-editor" launch is missing sampleId.' }
99105
```
100106

101-
2. Games rows missing valid game `href` now emit explicit visible launch errors instead of silent empty launch state:
107+
2. Missing game launch context is visible in games UI (`Workspace launch error`) instead of silently falling back:
102108

103109
- `games/index.render.js:147`
104-
- `games/index.render.js:271`
105-
- `games/index.render.js:336`
110+
- `games/index.render.js:264`
111+
- `games/index.render.js:330`
106112

107-
3. Workspace launch links are only bound when explicit `workspaceHref` exists, so missing context cannot route through a fallback launcher:
113+
Metadata scan used during validation:
108114

109-
- `games/index.render.js:266`
110-
- `games/index.render.js:416`
115+
```text
116+
{ totalGames: 29, missingValidHref: 18 }
117+
```
118+
119+
3. No hidden alternate game workspace launch action remains in touched flow:
120+
121+
- `games/index.render.js` contains no `game-title-link`, `handleCardLaunch`, or `data-workspace-href` launch path.
111122

112123
## Static Validation
113124

@@ -123,8 +134,8 @@ All commands exited successfully.
123134

124135
## Anti-Pattern Self-Check
125136

126-
- No new duplicate launch state introduced.
127-
- No new hidden/default/fallback launch route added in touched flow.
128-
- No duplicate event listeners added.
129-
- No new globals/managers/factories introduced.
130-
- No unrelated files changed for behavior.
137+
- No duplicate launch state introduced.
138+
- No hidden/default/fallback route/tool/workspace behavior added in touched flow.
139+
- No duplicate event listeners introduced.
140+
- No globals/managers/factories/service layers added.
141+
- No unrelated cleanup or scope expansion.

‎docs/operations/dev/codex_commands.md‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Codex Commands — BUILD_PR_LEVEL_20_8_IMPLEMENT_TOOL_LAUNCH_SSOT_ROUTING
1+
# Codex Commands — BUILD_PR_LEVEL_20_8_IMPLEMENT_TOOL_LAUNCH_SSOT_ROUTING_V2
22

33
## Model
44
GPT-5.4 or GPT-5.3-codex
@@ -12,14 +12,16 @@ High
1212
Read docs/dev/codex_rules.md first.
1313
Read docs/dev/specs/TOOL_LAUNCH_SSOT.md second.
1414
15-
Execute BUILD_PR_LEVEL_20_8_IMPLEMENT_TOOL_LAUNCH_SSOT_ROUTING.
15+
Execute BUILD_PR_LEVEL_20_8_IMPLEMENT_TOOL_LAUNCH_SSOT_ROUTING_V2.
1616
1717
Goal:
18-
Implement the first runtime slice of TOOL_LAUNCH_SSOT.
18+
Implement the first runtime slice of TOOL_LAUNCH_SSOT with exact UI launch wording.
1919
2020
Required behavior:
2121
- samples launch tools through tools/<tool>/index.html
22+
- sample launch actions must be labeled: Open <tool>
2223
- games launch workspace flows through tools/Workspace Manager/index.html
24+
- game launch actions must be labeled: Open with Workspace Manager
2325
- external launches from samples/games clear launch memory before loading
2426
- launch data comes from the existing single source of truth
2527
- no default/fallback route/tool/workspace behavior in touched launch flow
@@ -32,17 +34,20 @@ Hard constraints:
3234
- no start_of_day changes
3335
- no roadmap text rewrite except status markers
3436
- no anti-patterns listed in docs/dev/codex_rules.md
37+
- do not alter the required label meanings
3538
3639
Validation:
3740
Create docs/dev/reports/tool_launch_ssot_routing_validation.md with:
3841
- changed files
3942
- tested UAT paths
43+
- proof sample actions are labeled Open <tool>
4044
- proof samples route to tools/<tool>/index.html
45+
- proof game actions are labeled Open with Workspace Manager
4146
- proof games route to tools/Workspace Manager/index.html
4247
- proof external launch memory is cleared
4348
- proof missing context does not fallback
4449
- anti-pattern self-check
4550
4651
Return ZIP at:
47-
tmp/BUILD_PR_LEVEL_20_8_IMPLEMENT_TOOL_LAUNCH_SSOT_ROUTING.zip
52+
tmp/BUILD_PR_LEVEL_20_8_IMPLEMENT_TOOL_LAUNCH_SSOT_ROUTING_V2.zip
4853
```

‎docs/operations/dev/commit_comment.txt‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
1-
Implement tool launch SSoT routing
1+
Implement tool launch SSoT routing with exact launch labels
22

33
PR Details:
4-
- Routes sample-launched tools through explicit tools/<tool>/index.html targets.
5-
- Routes game workspace flows through tools/Workspace Manager/index.html.
4+
- Routes sample-launched tools through explicit tools/<tool>/index.html targets using Open <tool>.
5+
- Routes game workspace flows through tools/Workspace Manager/index.html using Open with Workspace Manager.
66
- Clears launch memory for external sample/game launches.
77
- Removes default/fallback behavior from touched launch flow.
8-
- Adds validation report for SSoT routing.
8+
- Adds validation report for SSoT routing and launch labels.

‎docs/pr/BUILD_PR_LEVEL_20_8_IMPLEMENT_TOOL_LAUNCH_SSOT_ROUTING_V2.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# BUILD_PR_LEVEL_20_8_IMPLEMENT_TOOL_LAUNCH_SSOT_ROUTING_V2
2+
3+
## Purpose
4+
5+
Implement the first runtime slice of the launch SSoT contract with exact UI launch wording:
6+
7+
- sample-launched tools use `Open <tool>`
8+
- game-launched Workspace Manager flows use `Open with Workspace Manager`
9+
10+
## Scope
11+
12+
One PR purpose only:
13+
14+
- route sample-launched tools through explicit `tools/<tool>/index.html` targets via `Open <tool>`
15+
- route game-launched workspace flows through `tools/Workspace Manager/index.html` via `Open with Workspace Manager`
16+
- clear launch memory for external launches from samples or games
17+
- remove default/fallback launch behavior only where touched by this launch path
18+
19+
## Required Source of Truth
20+
21+
Codex must use:
22+
23+
- `docs/dev/specs/TOOL_LAUNCH_SSOT.md`
24+
- existing launch metadata/config files already present in the repo
25+
26+
Codex must not invent a second source of truth.
27+
28+
## Required UI Contract
29+
30+
### Samples UI
31+
32+
Samples must expose tool launch actions as:
33+
34+
```text
35+
Open <tool>
36+
```
37+
38+
Examples:
39+
40+
```text
41+
Open Vector Map Editor
42+
Open Vector Asset Studio
43+
Open Tilemap Studio
44+
```
45+
46+
Samples must not use `Open with Workspace Manager` for sample-to-tool launch actions.
47+
48+
### Games UI
49+
50+
Games must expose Workspace Manager launch actions as:
51+
52+
```text
53+
Open with Workspace Manager
54+
```
55+
56+
Games must not use `Open <tool>` for game-to-workspace launch actions.
57+
58+
## Hard Constraints
59+
60+
Codex must NOT:
61+
62+
- rewrite unrelated tools
63+
- rewrite unrelated games
64+
- rewrite unrelated samples
65+
- change route names unless required by the SSoT
66+
- change the required launch labels
67+
- introduce default tool fallback
68+
- introduce default workspace fallback
69+
- silently redirect missing launch context
70+
- preserve stale memory on external launches
71+
- add managers/factories/service layers unless already part of the existing pattern
72+
- modify `start_of_day`
73+
- rewrite roadmap text except status markers
74+
75+
## Anti-Pattern Guards
76+
77+
Do not introduce:
78+
79+
- alias variables
80+
- pass-through variables
81+
- duplicate state
82+
- stored derived state
83+
- vague names
84+
- magic route strings outside the SSoT path
85+
- duplicate event listeners
86+
- broad truthy/falsy checks that change behavior
87+
- hidden fallback behavior
88+
89+
## Required Validation
90+
91+
Codex must document validation in:
92+
93+
- `docs/dev/reports/tool_launch_ssot_routing_validation.md`
94+
95+
Validation must include:
96+
97+
- sample tile/action labels use `Open <tool>`
98+
- sample tile/action launches resolve to explicit `tools/<tool>/index.html`
99+
- game tile/action labels use `Open with Workspace Manager`
100+
- game tile/action launches resolve to `tools/Workspace Manager/index.html`
101+
- external launch memory is cleared before loading
102+
- missing launch data fails visibly
103+
- no default/fallback path remains in touched launch flow
104+
- no anti-patterns introduced in touched files
105+
106+
## Acceptance
107+
108+
- Runtime launch behavior follows `TOOL_LAUNCH_SSOT.md`.
109+
- Sample launch UI uses `Open <tool>`.
110+
- Game launch UI uses `Open with Workspace Manager`.
111+
- SSoT remains the authority.
112+
- UAT path from `games/index.html` to Workspace Manager works.
113+
- UAT path from `samples/index.html` to tool index works.
114+
- No unrelated implementation changes.

0 commit comments

Comments
 (0)