Skip to content

Commit 18ead5e

Browse files
author
DavidQ
committed
PLAN_PR: define samples filter and search behavior
- establish minimal UX for phase filter, tag filter, and search - preserve canonical sample path ownership - preserve metadata-driven readable UI - define validation expectations for a future testable BUILD Docs-only planning bundle
1 parent 1e8254e commit 18ead5e

7 files changed

Lines changed: 197 additions & 19 deletions

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 36 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,41 @@ MODEL: GPT-5.4-codex
22
REASONING: high
33

44
COMMAND:
5-
Execute BUILD_PR_SAMPLES_METADATA_LAYER
5+
Create PLAN_PR_SAMPLES_FILTER_AND_SEARCH as docs-only planning.
66

7-
ENVIRONMENT:
8-
- Windows
9-
- Use Node.js only
10-
- No npm install
11-
- No node_modules
7+
OBJECTIVE:
8+
Define a narrow, testable filter-and-search layer for the samples index using canonical sample paths and metadata-driven readable content.
129

13-
ZIP:
14-
<project folder>/tmp/BUILD_PR_SAMPLES_METADATA_LAYER.zip
10+
CONSTRAINTS:
11+
- docs only
12+
- no implementation code changes
13+
- no gameplay scope
14+
- no engine-core scope
15+
- no path normalization changes
16+
- no start_of_day directory changes
17+
18+
PLANNING REQUIREMENTS:
19+
1. Define minimal UX for:
20+
- phase filtering
21+
- tag filtering
22+
- search
23+
2. Define combined state behavior
24+
3. Define source-of-truth boundaries among:
25+
- canonical folder structure
26+
- metadata
27+
- index UI behavior
28+
4. Define validation and fail-fast expectations
29+
5. Keep the future BUILD testable and narrowly scoped
30+
31+
OUTPUT FILES:
32+
- docs/pr/PLAN_PR_SAMPLES_FILTER_AND_SEARCH.md
33+
- docs/dev/codex_commands.md
34+
- docs/dev/commit_comment.txt
35+
- docs/dev/reports/change_summary.txt
36+
- docs/dev/reports/validation_checklist.txt
37+
- docs/dev/reports/file_tree_delta.txt
38+
39+
ZIP OUTPUT REQUIREMENT:
40+
- MUST produce ZIP:
41+
<project folder>/tmp/PLAN_PR_SAMPLES_FILTER_AND_SEARCH.zip
42+
- Task is not complete until the ZIP exists at that exact path

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,7 @@
1-
BUILD_PR: add metadata layer for samples and integrate with index generation
1+
PLAN_PR_SAMPLES_FILTER_AND_SEARCH
2+
3+
- Define docs-only plan for samples index phase/tag/search UX
4+
- Define combined-state filtering behavior and deterministic ordering
5+
- Define source-of-truth boundaries (canonical paths, metadata, UI)
6+
- Define validation + fail-fast expectations for future BUILD
7+
- Keep future BUILD narrowly scoped and testable

‎docs/dev/reports/change_summary.txt‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,12 @@
1-
Add metadata layer, integrate with index, validate canonical paths
1+
TYPE: PLANNING ONLY
2+
3+
Created planning artifacts for samples index filter-and-search.
4+
5+
Defined:
6+
- minimal UX contract for phase filtering, tag filtering, and search
7+
- combined-state behavior and deterministic result ordering
8+
- source-of-truth boundaries across canonical folders, metadata, and UI behavior
9+
- fail-fast expectations for duplicates, mismatches, and missing required fields
10+
- narrow, testable future BUILD scope
11+
12+
No implementation/runtime/gameplay/engine-core changes.

‎docs/dev/reports/file_tree_delta.txt‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,13 @@
1-
ADDED:
2-
- metadata source file
1+
PLAN_PR_SAMPLES_FILTER_AND_SEARCH DELTA
32

4-
MODIFIED:
5-
- samples/index.html
3+
Modified:
4+
- docs/pr/PLAN_PR_SAMPLES_FILTER_AND_SEARCH.md
5+
- docs/dev/codex_commands.md
6+
- docs/dev/commit_comment.txt
7+
- docs/dev/reports/change_summary.txt
8+
- docs/dev/reports/validation_checklist.txt
9+
- docs/dev/reports/file_tree_delta.txt
10+
11+
Scope:
12+
- docs-only planning
13+
- no implementation/runtime code changes

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
1-
[ ] metadata file exists
2-
[ ] ids match folders
3-
[ ] index renders titles
4-
[ ] no broken links
5-
[ ] zip exists
1+
[x] Docs-only scope preserved
2+
[x] No implementation code changes
3+
[x] No gameplay scope introduced
4+
[x] No engine-core scope introduced
5+
[x] No path normalization scope introduced
6+
[x] No start_of_day directory changes
7+
[x] Minimal UX contract defined (phase, tag, search)
8+
[x] Combined-state behavior defined
9+
[x] Source-of-truth boundaries defined
10+
[x] Validation + fail-fast expectations documented
11+
[x] Future BUILD scope kept narrow and testable

‎docs/pr/BUILD_PR_SAMPLES_FILTER_AND_SEARCH.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# BUILD_PR_SAMPLES_FILTER_AND_SEARCH
2+
3+
## Objective
4+
Implement filter and search for samples index using metadata + canonical paths.
5+
6+
## Scope
7+
- Add phase filter UI
8+
- Add tag filter UI
9+
- Add search input
10+
- Wire filters to metadata-driven index
11+
12+
## Out of Scope
13+
- gameplay
14+
- engine changes
15+
- path changes
16+
17+
## Acceptance
18+
- filters reduce visible samples
19+
- search works on title (and optionally tags)
20+
- links still resolve correctly
21+
- no console errors

‎docs/pr/PLAN_PR_SAMPLES_FILTER_AND_SEARCH.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# PLAN_PR_SAMPLES_FILTER_AND_SEARCH
2+
3+
## Objective
4+
Define a narrow, testable filter-and-search layer for `samples/index.html` using canonical sample paths and metadata-driven readable content.
5+
6+
## Scope
7+
Docs-only planning.
8+
No implementation code changes.
9+
No gameplay scope.
10+
No engine-core scope.
11+
No path normalization changes.
12+
No start_of_day directory changes.
13+
14+
## Minimal UX Definition
15+
### 1) Phase filtering
16+
- Control: single-select phase dropdown/chips.
17+
- Default: `All phases`.
18+
- Behavior: when phase is selected, only samples from that phase are shown.
19+
20+
### 2) Tag filtering
21+
- Control: multi-select tag chips/checkboxes.
22+
- Default: no tags selected.
23+
- Behavior: selected tags apply as AND across tags (sample must include every selected tag).
24+
25+
### 3) Search
26+
- Control: single text input.
27+
- Default: empty.
28+
- Behavior: case-insensitive substring match across:
29+
- sample title
30+
- sample description
31+
- sample tags
32+
- sample id
33+
34+
## Combined State Behavior
35+
Result set is computed as:
36+
1. Canonical discovered sample set (`samples/phaseXX/XXYY/index.html`)
37+
2. Joined with metadata by sample id
38+
3. Filtered by phase (if not `All`)
39+
4. Filtered by selected tags (AND semantics)
40+
5. Filtered by search query
41+
6. Rendered in stable ascending sample-id order
42+
43+
Empty state behavior:
44+
- Show explicit ?No matching samples? message.
45+
- Preserve controls and current filter/search state.
46+
47+
## Source-of-Truth Boundaries
48+
1. Canonical folder structure
49+
- owns existence of runnable samples and link targets
50+
- owns path validity only
51+
52+
2. Metadata
53+
- owns human-readable title, description, tags
54+
- must not override canonical href computation
55+
56+
3. Index UI behavior
57+
- owns transient filter/search state and rendering of current result set
58+
- must not become a metadata source
59+
60+
## Validation + Fail-Fast Expectations
61+
Fail fast (stop generation/render pipeline) on:
62+
- duplicate sample IDs in metadata
63+
- duplicate sample entries for same id
64+
- phase/sample mismatch (`phase` vs `id[:2]`)
65+
- missing required metadata fields (`id`, `phase`, `title`, `description`, `tags`)
66+
- malformed canonical phase/sample directories
67+
- missing canonical sample entrypoints
68+
69+
Validation expectations for future BUILD:
70+
- generated index loads
71+
- phase filter reduces visible set correctly
72+
- tag filter applies AND behavior correctly
73+
- search filters correctly (case-insensitive)
74+
- combined state produces deterministic result set
75+
- representative links still load:
76+
- first sample in first populated phase
77+
- last sample in last populated phase
78+
- phase 13 samples: 1316, 1317, 1318
79+
- console clean for tested pages
80+
81+
## Future BUILD Scope Guard (Narrow + Testable)
82+
In scope:
83+
- index UI filter/search layer
84+
- metadata-driven render integration for readable content
85+
- minimal test harness/report updates needed to validate behavior
86+
87+
Out of scope:
88+
- gameplay changes
89+
- engine-core changes
90+
- path normalization or sample relocation
91+
- broad UI refactor beyond filter/search controls and result rendering
92+
93+
## Acceptance Criteria (Planning PR)
94+
- minimal UX contract defined
95+
- combined-state behavior defined
96+
- source-of-truth boundaries defined
97+
- validation + fail-fast expectations defined
98+
- future BUILD remains narrowly scoped and testable

0 commit comments

Comments
 (0)