Skip to content

Commit 8b58002

Browse files
author
DavidQ
committed
PR_PRODUCTIZATION_DISTRIBUTION_STARTER_FULL as a docs-first bundle.
1 parent b2824cd commit 8b58002

10 files changed

+249
-65
lines changed

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 17 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -2,27 +2,27 @@ MODEL: GPT-5.3-codex
22
REASONING: medium
33

44
COMMAND:
5-
Execute PLAN + BUILD + APPLY for DEBUG_UX_FINAL_POLISH.
5+
Create PR_PRODUCTIZATION_DISTRIBUTION_STARTER_FULL
6+
7+
PURPOSE:
8+
Define how showcase samples (Asteroids, Breakout) are packaged, presented, and shared as a product.
69

710
IN SCOPE:
8-
- finalize debug ON/OFF badge behavior
9-
- finalize default preset auto-load behavior
10-
- finalize `Open Debug Panel` consistency
11-
- finalize inline mini help consistency
12-
- evaluate remembered debug state
13-
- evaluate one-click demo mode
11+
- showcase landing page structure
12+
- sample discovery (games/index.html improvements)
13+
- packaging strategy (standalone vs repo)
14+
- asset bundling rules
15+
- entry points for users (play vs debug)
1416

15-
TARGET SAMPLES:
16-
- Asteroids
17-
- Breakout
17+
OUT OF SCOPE:
18+
- engine changes
19+
- Track G
20+
- Track H
1821

1922
RULES:
20-
- sample-level integration only
21-
- preserve production-safe defaults
22-
- do not modify BIG_PICTURE_ROADMAP.md
23-
- if PRODUCTIZATION_ROADMAP.md is updated, use bracket-only edits only
24-
- no Track G or Track H work
23+
- docs-first
24+
- no BIG_PICTURE_ROADMAP edits
25+
- PRODUCTIZATION_ROADMAP updates are bracket-only
2526

2627
OUTPUT:
27-
Create:
28-
<project folder>/tmp/PR_DEBUG_UX_FINAL_POLISH_FULL_bundle.zip
28+
<project folder>/tmp/PR_PRODUCTIZATION_DISTRIBUTION_STARTER_FULL_bundle.zip

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,2 @@
1-
PR_DEBUG_UX_FINAL_POLISH_FULL
2-
polish(debug-ux): finalize Asteroids and Breakout debug badge/preset/panel/help flows with optional remember and demo modes
1+
PR_PRODUCTIZATION_DISTRIBUTION_STARTER_FULL
2+
docs: define productization distribution starter contracts for showcase packaging and entry flows

‎docs/dev/NEXT_COMMAND.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
PLAN_PR_DEBUG_UX_CROSS_SAMPLE_SHARED_BOOT_HELPER
1+
PLAN_PR_PRODUCTIZATION_DISTRIBUTION_IMPLEMENTATION_PASS_1

‎docs/dev/PRODUCTIZATION_ROADMAP.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -37,9 +37,9 @@ Do NOT change structure or wording.
3737

3838
# TRACK R - DISTRIBUTION AND PACKAGING
3939

40-
- [ ] Showcase landing page
41-
- [ ] Build packaging strategy
42-
- [ ] Asset bundling rules
40+
- [.] Showcase landing page
41+
- [.] Build packaging strategy
42+
- [.] Asset bundling rules
4343

4444
---
4545

‎docs/dev/reports/change_summary.txt‎

Lines changed: 19 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -3,23 +3,25 @@ David Quesenberry
33
04/05/2026
44
change_summary.txt
55

6-
Executed PLAN + BUILD + APPLY for DEBUG_UX_FINAL_POLISH.
6+
Executed PR_PRODUCTIZATION_DISTRIBUTION_STARTER_FULL as docs-only PLAN/BUILD/APPLY.
77

8-
Sample updates:
9-
- Asteroids:
10-
- added debug badge/button/help UI
11-
- finalized default preset auto-load with fallbacks
12-
- added optional `rememberDebug=1`
13-
- added optional `debugDemo=1`
14-
- Breakout:
15-
- finalized optional `rememberDebug=1`
16-
- finalized optional `debugDemo=1`
17-
- aligned mini-help and preset-status messaging
8+
Added:
9+
- `docs/pr/PLAN_PR_PRODUCTIZATION_DISTRIBUTION_STARTER.md`
10+
- `docs/pr/BUILD_PR_PRODUCTIZATION_DISTRIBUTION_STARTER.md`
11+
- `docs/pr/APPLY_PR_PRODUCTIZATION_DISTRIBUTION_STARTER.md`
1812

19-
Roadmap updates:
20-
- Updated `docs/dev/PRODUCTIZATION_ROADMAP.md` with bracket-only state changes for completed UX polish items.
13+
Defined:
14+
- showcase landing page structure
15+
- discovery guidance for `games/index.html`
16+
- standalone vs repo-linked packaging strategy
17+
- asset bundling include/exclude rules
18+
- user entry points for play, debug, and demo
2119

22-
Safety:
23-
- No engine core changes.
24-
- No BIG_PICTURE roadmap edits.
25-
- No Track G/H work.
20+
Roadmap update:
21+
- `docs/dev/PRODUCTIZATION_ROADMAP.md` Track R states moved to in-progress via bracket-only edits.
22+
23+
Scope guard:
24+
- Docs-first only
25+
- No engine changes
26+
- No Track G/H work
27+
- No BIG_PICTURE roadmap edits

‎docs/dev/reports/file_tree.txt‎

Lines changed: 4 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,16 +3,13 @@ David Quesenberry
33
04/05/2026
44
file_tree.txt
55

6-
docs/pr/PLAN_PR_DEBUG_UX_FINAL_POLISH.md
7-
docs/pr/BUILD_PR_DEBUG_UX_FINAL_POLISH.md
8-
docs/pr/APPLY_PR_DEBUG_UX_FINAL_POLISH.md
6+
docs/pr/PLAN_PR_PRODUCTIZATION_DISTRIBUTION_STARTER.md
7+
docs/pr/BUILD_PR_PRODUCTIZATION_DISTRIBUTION_STARTER.md
8+
docs/pr/APPLY_PR_PRODUCTIZATION_DISTRIBUTION_STARTER.md
99
docs/dev/PRODUCTIZATION_ROADMAP.md
1010
docs/dev/codex_commands.md
1111
docs/dev/commit_comment.txt
1212
docs/dev/next_command.txt
1313
docs/dev/reports/change_summary.txt
1414
docs/dev/reports/validation_checklist.txt
15-
docs/dev/reports/file_tree.txt
16-
games/Asteroids/index.html
17-
games/Asteroids/main.js
18-
games/Breakout/main.js
15+
docs/dev/reports/file_tree.txt

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 17 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -3,22 +3,21 @@ David Quesenberry
33
04/05/2026
44
validation_checklist.txt
55

6-
[x] PLAN/BUILD/APPLY docs updated
7-
[x] Asteroids debug badge behavior finalized
8-
[x] Breakout debug badge behavior finalized
9-
[x] Default preset auto-load finalized for both samples
10-
[x] `Open Debug Panel` behavior consistent
11-
[x] Inline mini help consistency finalized
12-
[x] Remembered debug state evaluated and implemented as optional (`rememberDebug=1`)
13-
[x] One-click demo mode evaluated and implemented as optional (`debugDemo=1`)
14-
[x] Production-safe defaults preserved
15-
[x] No BIG_PICTURE_ROADMAP.md changes
16-
[x] PRODUCTIZATION_ROADMAP.md edits are bracket-only
17-
[x] No Track G or Track H work
6+
[x] PLAN doc created
7+
[x] BUILD doc created
8+
[x] APPLY doc created
9+
[x] Landing page structure defined
10+
[x] Discovery improvements contract defined
11+
[x] Standalone vs repo-linked packaging strategy defined
12+
[x] Asset bundling rules defined
13+
[x] User entry points defined
14+
[x] Docs-only scope preserved
15+
[x] No BIG_PICTURE_ROADMAP edits
16+
[x] PRODUCTIZATION_ROADMAP updates are bracket-only
17+
[x] No Track G/H work
18+
[x] Repo-structured bundle zip created
1819

19-
Validation commands:
20-
- `node --check games/Asteroids/main.js`
21-
- `node --check games/Breakout/main.js`
22-
- `node --check games/Breakout/game/BreakoutScene.js`
23-
- `node -e "import('./tests/games/AsteroidsValidation.test.mjs').then(async (m)=>{await m.run(); console.log('AsteroidsValidation:PASS');})"`
24-
- `node -e "import('./tests/games/BreakoutValidation.test.mjs').then(async (m)=>{await m.run(); console.log('BreakoutValidation:PASS');})"`
20+
Validation checks:
21+
- `git diff --name-only`
22+
- `git diff -- docs/dev/PRODUCTIZATION_ROADMAP.md`
23+
- `tar -tf tmp/PR_PRODUCTIZATION_DISTRIBUTION_STARTER_FULL_bundle.zip`

‎docs/pr/APPLY_PR_PRODUCTIZATION_DISTRIBUTION_STARTER.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
Toolbox Aid
2+
David Quesenberry
3+
04/05/2026
4+
APPLY_PR_PRODUCTIZATION_DISTRIBUTION_STARTER.md
5+
6+
# APPLY_PR_PRODUCTIZATION_DISTRIBUTION_STARTER
7+
8+
## Apply Decision
9+
Apply BUILD_PR_PRODUCTIZATION_DISTRIBUTION_STARTER exactly as scoped.
10+
11+
## Applied Scope
12+
- Added productization distribution starter PLAN/BUILD/APPLY docs.
13+
- Defined landing page, discovery, packaging, bundling, and entry-point contracts for Asteroids and Breakout.
14+
- Updated `PRODUCTIZATION_ROADMAP.md` with bracket-only Track R state transitions.
15+
16+
## Validation Summary
17+
- Docs-only changes.
18+
- No engine/runtime changes.
19+
- No BIG_PICTURE roadmap edits.
20+
- Productization roadmap updated via bracket states only.
21+
22+
## Output
23+
`<project folder>/tmp/PR_PRODUCTIZATION_DISTRIBUTION_STARTER_FULL_bundle.zip`

‎docs/pr/BUILD_PR_PRODUCTIZATION_DISTRIBUTION_STARTER.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
Toolbox Aid
2+
David Quesenberry
3+
04/05/2026
4+
BUILD_PR_PRODUCTIZATION_DISTRIBUTION_STARTER.md
5+
6+
# BUILD_PR_PRODUCTIZATION_DISTRIBUTION_STARTER
7+
8+
## Build Summary
9+
Created a docs-only productization distribution starter bundle defining how Asteroids and Breakout are packaged, discovered, and shared.
10+
11+
## Defined Contracts
12+
13+
### 1. Showcase Landing Page Structure
14+
Recommended structure for a dedicated distribution landing page:
15+
1. Hero block:
16+
- Productized showcase intent.
17+
- Supported browser baseline.
18+
- Quick start call-to-action.
19+
20+
2. Showcase sample cards:
21+
- Asteroids card.
22+
- Breakout card.
23+
- Badge row: `Playable` and `Debug Showcase`.
24+
- Buttons:
25+
- `Play` -> default path.
26+
- `Play (Debug)` -> explicit debug query entry.
27+
- `Demo` -> one-click demo mode query entry.
28+
29+
3. Help and support block:
30+
- Debug key combos.
31+
- Troubleshooting basics.
32+
- Production-safe default note.
33+
34+
4. Build/package metadata block:
35+
- Package version.
36+
- Build date.
37+
- Included sample list.
38+
39+
### 2. Sample Discovery Contract (`games/index.html`)
40+
Starter discovery improvements contract:
41+
- Keep showcase badge visible and unique.
42+
- Ensure Asteroids and Breakout both display debug showcase intent.
43+
- Keep links predictable and documented:
44+
- Play: `index.html`
45+
- Debug: `index.html?debug=1`
46+
- Demo: `index.html?debugDemo=1`
47+
48+
### 3. Packaging Strategy (Standalone vs Repo-linked)
49+
Two packaging modes are defined:
50+
51+
A. Repo-linked package:
52+
- Intended for contributors and local development.
53+
- Uses existing repo-relative paths.
54+
- Includes docs and source for iterative updates.
55+
56+
B. Standalone showcase package:
57+
- Intended for external sharing/demo distribution.
58+
- Includes only runtime-required files for Asteroids and Breakout.
59+
- Excludes tests, temp artifacts, and unrelated game/sample trees.
60+
61+
### 4. Asset Bundling Rules
62+
Include:
63+
- `games/Asteroids/**` runtime-required files.
64+
- `games/Breakout/**` runtime-required files.
65+
- Required engine runtime/UI assets referenced by those samples.
66+
- Required shared debug tooling files used by those samples.
67+
68+
Exclude:
69+
- `tests/**`
70+
- `tmp/**`
71+
- unrelated game/sample folders
72+
- planning/report artifacts not needed for runtime demo package
73+
74+
Path rules:
75+
- Preserve browser-resolvable relative paths.
76+
- Avoid rewriting paths during packaging unless explicitly versioned by a later PR.
77+
78+
### 5. User Entry Points (Play vs Debug)
79+
Asteroids and Breakout entry contract:
80+
- Play: `/games/<Sample>/index.html`
81+
- Debug: `/games/<Sample>/index.html?debug=1`
82+
- Demo: `/games/<Sample>/index.html?debugDemo=1`
83+
84+
Behavior expectations:
85+
- Play remains production-safe default.
86+
- Debug and Demo remain explicit opt-in.
87+
- Debug UI messaging is consistent across both samples.
88+
89+
## Roadmap State Updates
90+
`docs/dev/PRODUCTIZATION_ROADMAP.md` bracket-only updates:
91+
- Track R / Showcase landing page: `[ ]` -> `[.]`
92+
- Track R / Build packaging strategy: `[ ]` -> `[.]`
93+
- Track R / Asset bundling rules: `[ ]` -> `[.]`
94+
95+
## Validation
96+
- Docs-only scope preserved.
97+
- No engine files changed.
98+
- No BIG_PICTURE roadmap edits.
99+
- Productization roadmap edits are bracket-only.

‎docs/pr/PLAN_PR_PRODUCTIZATION_DISTRIBUTION_STARTER.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
Toolbox Aid
2+
David Quesenberry
3+
04/05/2026
4+
PLAN_PR_PRODUCTIZATION_DISTRIBUTION_STARTER.md
5+
6+
# PLAN_PR_PRODUCTIZATION_DISTRIBUTION_STARTER
7+
8+
## Goal
9+
Define a productization distribution starter contract for the showcase samples (Asteroids and Breakout) covering packaging, presentation, discoverability, and user entry flows.
10+
11+
## Workflow
12+
PLAN_PR -> BUILD_PR -> APPLY_PR
13+
14+
## In Scope
15+
- Showcase landing page structure definition.
16+
- Sample discovery improvements definition for `games/index.html`.
17+
- Packaging strategy definition (standalone package vs repo-linked package).
18+
- Asset bundling rule definition.
19+
- User entry point definition (play flow vs debug flow).
20+
21+
## Out of Scope
22+
- Engine core changes.
23+
- Runtime refactors.
24+
- Track G work.
25+
- Track H work.
26+
27+
## Constraints
28+
- Docs-first only.
29+
- No `BIG_PICTURE_ROADMAP.md` edits.
30+
- If `PRODUCTIZATION_ROADMAP.md` is updated, bracket-only state edits only.
31+
- Preserve production-safe defaults for debug access.
32+
33+
## Distribution Starter Decisions To Define
34+
1. Landing page information architecture:
35+
- Hero summary.
36+
- Sample cards for Asteroids/Breakout.
37+
- Entry actions for Play and Debug.
38+
- Compatibility and known limitations block.
39+
40+
2. Discovery contract for `games/index.html`:
41+
- Consistent debug showcase labeling.
42+
- Clear visual distinction between playable vs debug showcase context.
43+
- Link path conventions for play and debug entry.
44+
45+
3. Packaging contract:
46+
- `repo-linked` mode for contributors.
47+
- `standalone` mode for product demo distribution.
48+
- Explicit list of required files and excluded files.
49+
50+
4. Asset bundling rules:
51+
- Include sample-local assets, required engine UI, and required shared debug assets.
52+
- Exclude tests, temporary artifacts, and unrelated samples.
53+
- Preserve relative paths and browser-loadable structure.
54+
55+
5. Entry points:
56+
- Play entry: default production-safe mode.
57+
- Debug entry: explicit query-param entry (`?debug=1`).
58+
- Optional demo entry: explicit one-click mode (`?debugDemo=1`).
59+
60+
## Acceptance Criteria
61+
- Distribution contract is explicit and actionable.
62+
- Asteroids and Breakout are both covered.
63+
- Packaging and asset rules are deterministic.
64+
- Entry point behavior is clear for users and maintainers.

0 commit comments

Comments
 (0)