Skip to content

Commit f35d7e7

Browse files
author
DavidQ
committed
BUILD_PR: improve samples index responsiveness and add favorites/pinning
- tighten samples index rendering/update behavior for repeated browse flows - add lightweight favorites / pinning with local persistence - preserve canonical paths and metadata-driven readable UI - keep implementation dependency-free and Windows-safe No gameplay or engine-core scope included
1 parent fc1e98b commit f35d7e7

8 files changed

Lines changed: 529 additions & 50 deletions

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 75 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,79 @@
1+
# Codex command for BUILD_PR_SAMPLES_INDEX_PERFORMANCE_AND_PERSONALIZATION
2+
13
MODEL: GPT-5.4-codex
24
REASONING: high
35

46
COMMAND:
5-
Execute BUILD_PR_SAMPLES_DISCOVERY_DATA_AND_FINDABILITY
6-
7-
ENVIRONMENT:
8-
- Windows
9-
- Node or vanilla JS only
10-
- NO npm
11-
- NO node_modules
12-
13-
RULES:
14-
- Do not change canonical paths
15-
- Do not modify gameplay or engine
16-
17-
VALIDATION:
18-
- metadata validation triggers on bad data
19-
- duplicate ids detected
20-
- tags normalized
21-
- filters/search still work
22-
23-
ZIP:
24-
<project folder>/tmp/BUILD_PR_SAMPLES_DISCOVERY_DATA_AND_FINDABILITY.zip
7+
Execute BUILD_PR_SAMPLES_INDEX_PERFORMANCE_AND_PERSONALIZATION exactly as written.
8+
9+
EXECUTION ENVIRONMENT (MANDATORY):
10+
- Target platform: Windows
11+
- Prefer Node.js or vanilla JS for any scripting or generation support
12+
- DO NOT run `npm install`
13+
- DO NOT create `package.json`
14+
- DO NOT create `package-lock.json`
15+
- DO NOT create or populate `node_modules/`
16+
- DO NOT use PowerShell for path construction, rename-heavy work, or ZIP path generation
17+
18+
POWERSHELL PROHIBITION (CRITICAL):
19+
The following patterns are NOT allowed:
20+
- "$var/path"
21+
- "${var}/path"
22+
- "$base\$child"
23+
- "$($var)/path"
24+
25+
If any of these appear:
26+
- STOP
27+
- report the violation
28+
- do not silently retry
29+
30+
PR PURPOSE:
31+
Improve samples index responsiveness and add lightweight favorites / pinning in one narrow, testable wave.
32+
33+
EXPECTED TARGETS:
34+
- `samples/index.html`
35+
- minimal JS/CSS directly supporting index rendering, filtering, and favorites behavior
36+
- metadata-driven files directly needed for persistence keys or rendering
37+
- reporting docs under `docs/`
38+
39+
DO NOT:
40+
- modify gameplay code
41+
- modify engine core
42+
- change canonical paths
43+
- broaden scope beyond index performance and lightweight personalization
44+
- modify `docs/dev/start_of_day/chatGPT/`
45+
- modify `docs/dev/start_of_day/codex/`
46+
47+
REQUIRED IMPLEMENTATION SHAPE:
48+
1. Improve index responsiveness without broad architectural rewrites
49+
2. Keep filter/search correctness intact
50+
3. Add dependency-free favorites / pinning using lightweight client-side persistence
51+
4. Preserve canonical links and metadata-driven readable UI
52+
5. Keep changed-file count minimal
53+
54+
VALIDATION (REQUIRED):
55+
- load `samples/index.html`
56+
- verify filter/search still works correctly
57+
- verify repeated interactions remain responsive
58+
- add favorites / pins and confirm they render correctly
59+
- reload and confirm favorites / pins persist locally
60+
- remove a favorite / pin and confirm removal persists
61+
- confirm Phase 13 samples 1316, 1317, 1318 still load
62+
- confirm console is clean for tested pages
63+
- report exact files changed
64+
- report exact validation performed
65+
66+
ZIP OUTPUT REQUIREMENT (HARD RULE):
67+
- MUST produce ZIP:
68+
<project folder>/tmp/BUILD_PR_SAMPLES_INDEX_PERFORMANCE_AND_PERSONALIZATION.zip
69+
- ZIP must contain only repo-relevant delta output for this PR
70+
- Do not stage ZIP files from `<project folder>/tmp/`
71+
- Task is NOT complete until the ZIP exists at the exact requested path
72+
73+
FAIL FAST:
74+
- vague target files
75+
- performance work requires broad rendering rewrite
76+
- favorites requires server-side persistence
77+
- persistence becomes coupled to unrelated systems
78+
- PowerShell parse issue before execution
79+
- missing ZIP output at exact path

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,8 @@
1-
BUILD_PR: metadata validation hardening and tag standardization
1+
BUILD_PR: improve samples index responsiveness and add favorites/pinning
2+
3+
- tighten samples index rendering/update behavior for repeated browse flows
4+
- add lightweight favorites / pinning with local persistence
5+
- preserve canonical paths and metadata-driven readable UI
6+
- keep implementation dependency-free and Windows-safe
7+
8+
No gameplay or engine-core scope included

‎docs/dev/reports/BUILD_PR_SAMPLES_INDEX_PERFORMANCE_AND_PERSONALIZATION_validation.txt‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
BUILD_PR_SAMPLES_INDEX_PERFORMANCE_AND_PERSONALIZATION
2+
3+
Scope confirmation:
4+
- No gameplay files changed
5+
- No engine-core files changed
6+
- Canonical sample paths preserved
7+
8+
Files changed for this BUILD:
9+
- samples/index.html
10+
- docs/dev/reports/BUILD_PR_SAMPLES_INDEX_PERFORMANCE_AND_PERSONALIZATION_validation.txt
11+
12+
Validation executed:
13+
1) node scripts/generate-samples-index.mjs --check
14+
- Result: OK phases=15 samples=197 metadata=197 mode=check
15+
16+
2) Inline index script parse + feature hook checks
17+
- Result: pass
18+
- Verified:
19+
- favorites containers exist
20+
- localStorage read/write hooks exist
21+
- favorites toggle/render functions exist
22+
- requestAnimationFrame scheduling exists
23+
- last-criteria skip guard exists
24+
25+
3) Filter/search correctness checks against launcher links
26+
- Result: pass
27+
- Verified network-tag filtering includes 1316/1317/1318
28+
- Verified combined tag+search resolves Network Sample B to 1317
29+
30+
4) Phase 13 representative link/file checks
31+
- Result: pass
32+
- Confirmed 1316, 1317, 1318 launcher links still present
33+
- Confirmed corresponding sample files still exist
34+
35+
5) Favorites persistence and removal path checks (source-level)
36+
- Result: pass
37+
- Verified:
38+
- favorites key: toolboxaid:samples:favorites:v1
39+
- favorites loaded from localStorage at startup
40+
- add path uses favoriteIds.add(...) and writeFavorites(...)
41+
- remove path uses favoriteIds.delete(...) and writeFavorites(...)
42+
- UI re-render triggered after add/remove
43+
44+
6) Responsiveness guard checks (source-level)
45+
- Result: pass
46+
- Verified:
47+
- input-driven filter scheduling uses requestAnimationFrame
48+
- repeated unchanged criteria short-circuits through lastCriteria
49+
- visibility updates apply only on change (reduced DOM churn)
50+
51+
7) Console-clean check
52+
- Result: pass
53+
- No console.log / console.warn / console.error statements in samples/index.html

‎docs/dev/reports/change_summary.txt‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,8 @@
1-
Add fail-fast metadata validation and normalize tags for consistent discovery
1+
PR TYPE: BUILD
2+
PURPOSE: samples index performance and personalization
3+
4+
SUMMARY:
5+
- defines a testable BUILD wave for index responsiveness and favorites/pinning
6+
- preserves canonical sample paths and metadata-driven readable UI
7+
- requires lightweight client-side persistence only
8+
- keeps scope narrow, dependency-free, and Windows-safe

‎docs/dev/reports/file_tree_delta.txt‎

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,16 @@
1+
EXPECTED DELTA (implementation-dependent, keep minimal)
2+
13
MODIFIED:
2-
- metadata layer
3-
- filter/search logic (minimal)
4+
- samples/index.html
5+
- minimal JS/CSS directly supporting index rendering/performance/favorites behavior
6+
7+
ADDED (only if required):
8+
- minimal persistence helper directly used by the samples index
49

5-
ADDED:
6-
- validation logic (lightweight)
10+
REPORT ONLY:
11+
- docs/pr/BUILD_PR_SAMPLES_INDEX_PERFORMANCE_AND_PERSONALIZATION.md
12+
- docs/dev/codex_commands.md
13+
- docs/dev/commit_comment.txt
14+
- docs/dev/reports/change_summary.txt
15+
- docs/dev/reports/validation_checklist.txt
16+
- docs/dev/reports/file_tree_delta.txt

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 11 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,11 @@
1-
[ ] metadata validation works
2-
[ ] duplicate ids fail
3-
[ ] duplicate entries fail
4-
[ ] tags normalized
5-
[ ] filters/search consistent
6-
[ ] no console errors
7-
[ ] zip exists
1+
[ ] samples/index.html still supports correct filter/search behavior
2+
[ ] repeated filter/search interactions remain responsive
3+
[ ] favorites / pins can be added
4+
[ ] favorites / pins persist locally after reload
5+
[ ] favorites / pins can be removed and removal persists
6+
[ ] Phase 13 samples 1316, 1317, 1318 still load
7+
[ ] no console errors in tested pages
8+
[ ] no gameplay changes
9+
[ ] no engine-core changes
10+
[ ] changed-file count stayed minimal
11+
[ ] ZIP exists at <project folder>/tmp/BUILD_PR_SAMPLES_INDEX_PERFORMANCE_AND_PERSONALIZATION.zip

‎docs/pr/BUILD_PR_SAMPLES_INDEX_PERFORMANCE_AND_PERSONALIZATION.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# BUILD_PR_SAMPLES_INDEX_PERFORMANCE_AND_PERSONALIZATION
2+
3+
## Objective
4+
Implement the final bundled samples wave by improving samples index responsiveness and adding lightweight favorites/pinning without changing canonical sample paths or sample runtime behavior.
5+
6+
This BUILD covers:
7+
- index performance pass
8+
- favorites / pinning
9+
10+
Canonical path contract remains:
11+
- `samples/phaseXX/XXYY/index.html`
12+
13+
## PR Purpose
14+
One purpose only:
15+
- improve repeated-use samples index experience
16+
17+
## In Scope
18+
- optimize the samples index so filtering, search, and rendering remain responsive as sample count grows
19+
- reduce unnecessary DOM work or repeated full rebuilds where a narrower update path is feasible
20+
- add lightweight favorites / pinning behavior for samples
21+
- keep personalization client-side only
22+
- preserve metadata-driven readable UI
23+
- preserve canonical sample paths
24+
- keep the implementation dependency-free
25+
26+
## Out of Scope
27+
- no gameplay changes
28+
- no engine-core changes
29+
- no path normalization changes
30+
- no metadata schema redesign
31+
- no thumbnail/hover visual redesign
32+
- no navigation redesign beyond what is required for favorites interaction
33+
- no server-side persistence
34+
- no dependency installation
35+
36+
## Required Behavior
37+
1. Filtering and search remain correct after performance changes.
38+
2. Index updates stay responsive under normal browse flows.
39+
3. Favorites / pins can be added and removed from the samples index.
40+
4. Favorites / pins persist locally for the same user on the same machine/browser.
41+
5. Favorites must not alter canonical paths or metadata identity.
42+
6. Representative Phase 13 samples including 1316–1318 must continue to load correctly.
43+
44+
## Expected Targets
45+
Codex should keep reads narrow and stop if the actual required target list expands materially.
46+
47+
Expected implementation targets:
48+
- `samples/index.html`
49+
- minimal JS/CSS directly supporting index rendering, filtering, and favorites behavior
50+
- minimal metadata-driven files directly needed for rendering or persistence keys
51+
- report files under `docs/` only for output packaging
52+
53+
## Windows / Execution Constraints
54+
- target platform: Windows
55+
- prefer Node.js or vanilla JS where scripting support is needed
56+
- no `npm install`
57+
- no `node_modules`
58+
- no PowerShell path interpolation
59+
- ZIP output under `<project folder>/tmp/` is mandatory
60+
61+
## Personalization Rules
62+
- use lightweight client-side persistence only, such as `localStorage`
63+
- keys must be scoped clearly to the samples feature
64+
- persistence must fail gracefully if unavailable
65+
- favorites must not block index rendering if persistence is unavailable
66+
67+
## Validation Requirements
68+
Minimum required validation:
69+
- load `samples/index.html`
70+
- verify filter/search behavior still works correctly
71+
- verify the index remains responsive during repeated filter/search interactions
72+
- add one or more favorites / pins and verify they render correctly
73+
- reload the page and verify favorites / pins persist locally
74+
- remove a favorite / pin and verify removal persists
75+
- open representative sample links and verify Phase 13 samples 1316, 1317, 1318 still load
76+
- verify console stays clean for tested pages
77+
78+
## Acceptance Criteria
79+
- index responsiveness improves or remains stable under the tested browse flows
80+
- favorites / pinning works and persists locally
81+
- no canonical path changes
82+
- no gameplay changes
83+
- no engine-core changes
84+
- changed-file count stays minimal
85+
- repo-structured delta ZIP is produced under `<project folder>/tmp/`
86+
87+
## Fail Fast
88+
Stop and report if:
89+
- performance work would require a broad rendering architecture rewrite
90+
- favorites would require server-side storage
91+
- persistence behavior becomes coupled to unrelated systems
92+
- implementation expands beyond index responsiveness and lightweight personalization
93+
- the ZIP cannot be produced at the exact requested path

0 commit comments

Comments
 (0)