BUILD_PR: add filtering and search to samples index

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -2,41 +2,23 @@ MODEL: GPT-5.4-codex
 REASONING: high
 
 COMMAND:
-Create PLAN_PR_SAMPLES_FILTER_AND_SEARCH as docs-only planning.
+Execute BUILD_PR_SAMPLES_FILTER_AND_SEARCH
 
-OBJECTIVE:
-Define a narrow, testable filter-and-search layer for the samples index using canonical sample paths and metadata-driven readable content.
+ENVIRONMENT:
+- Windows
+- Use Node.js or vanilla JS only
+- No npm install
+- No node_modules
 
-CONSTRAINTS:
-- docs only
-- no implementation code changes
-- no gameplay scope
-- no engine-core scope
-- no path normalization changes
-- no start_of_day directory changes
+RULES:
+- Do not change canonical paths
+- Do not modify gameplay
+- Keep changes minimal
 
-PLANNING REQUIREMENTS:
-1. Define minimal UX for:
-   - phase filtering
-   - tag filtering
-   - search
-2. Define combined state behavior
-3. Define source-of-truth boundaries among:
-   - canonical folder structure
-   - metadata
-   - index UI behavior
-4. Define validation and fail-fast expectations
-5. Keep the future BUILD testable and narrowly scoped
+VALIDATION:
+- filters work
+- search works
+- 1316–1318 load correctly
 
-OUTPUT FILES:
-- docs/pr/PLAN_PR_SAMPLES_FILTER_AND_SEARCH.md
-- docs/dev/codex_commands.md
-- docs/dev/commit_comment.txt
-- docs/dev/reports/change_summary.txt
-- docs/dev/reports/validation_checklist.txt
-- docs/dev/reports/file_tree_delta.txt
-
-ZIP OUTPUT REQUIREMENT:
-- MUST produce ZIP:
-  <project folder>/tmp/PLAN_PR_SAMPLES_FILTER_AND_SEARCH.zip
-- Task is not complete until the ZIP exists at that exact path
+ZIP:
+<project folder>/tmp/BUILD_PR_SAMPLES_FILTER_AND_SEARCH.zip

docs/dev/COMMIT_COMMENT.txt

@@ -1,7 +1 @@
-PLAN_PR_SAMPLES_FILTER_AND_SEARCH
-
-- Define docs-only plan for samples index phase/tag/search UX
-- Define combined-state filtering behavior and deterministic ordering
-- Define source-of-truth boundaries (canonical paths, metadata, UI)
-- Define validation + fail-fast expectations for future BUILD
-- Keep future BUILD narrowly scoped and testable
+BUILD_PR: add filtering and search to samples index

docs/dev/reports/change_summary.txt

@@ -1,12 +1 @@
-TYPE: PLANNING ONLY
-
-Created planning artifacts for samples index filter-and-search.
-
-Defined:
-- minimal UX contract for phase filtering, tag filtering, and search
-- combined-state behavior and deterministic result ordering
-- source-of-truth boundaries across canonical folders, metadata, and UI behavior
-- fail-fast expectations for duplicates, mismatches, and missing required fields
-- narrow, testable future BUILD scope
-
-No implementation/runtime/gameplay/engine-core changes.
+Add phase filter, tag filter, and search to samples index

docs/dev/reports/file_tree_delta.txt

@@ -1,13 +1,5 @@
-PLAN_PR_SAMPLES_FILTER_AND_SEARCH DELTA
+MODIFIED:
+- samples/index.html
 
-Modified:
-- docs/pr/PLAN_PR_SAMPLES_FILTER_AND_SEARCH.md
-- docs/dev/codex_commands.md
-- docs/dev/commit_comment.txt
-- docs/dev/reports/change_summary.txt
-- docs/dev/reports/validation_checklist.txt
-- docs/dev/reports/file_tree_delta.txt
-
-Scope:
-- docs-only planning
-- no implementation/runtime code changes
+ADDED:
+- minimal filter/search JS

docs/dev/reports/validation_checklist.txt

@@ -1,11 +1,7 @@
-[x] Docs-only scope preserved
-[x] No implementation code changes
-[x] No gameplay scope introduced
-[x] No engine-core scope introduced
-[x] No path normalization scope introduced
-[x] No start_of_day directory changes
-[x] Minimal UX contract defined (phase, tag, search)
-[x] Combined-state behavior defined
-[x] Source-of-truth boundaries defined
-[x] Validation + fail-fast expectations documented
-[x] Future BUILD scope kept narrow and testable
+[ ] phase filter works
+[ ] tag filter works
+[ ] search works
+[ ] combined filtering works
+[ ] links resolve (1316–1318)
+[ ] no console errors
+[ ] zip exists

samples/index.html

@@ -10,6 +10,34 @@
   <meta charset="UTF-8" />
   <title>ToolboxAid - Sample Launcher</title>
   <link rel="stylesheet" href="../src/engine/ui/hubCommon.css" />
+  <style>
+    .samples-filters {
+      display: grid;
+      gap: 0.75rem;
+      margin: 1rem 0 1.5rem;
+      grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
+      align-items: end;
+    }
+    .samples-filters label {
+      display: block;
+      margin-bottom: 0.25rem;
+      font-weight: 600;
+    }
+    .samples-filters select,
+    .samples-filters input {
+      width: 100%;
+      padding: 0.45rem 0.55rem;
+      border: 1px solid #9ca3af;
+      border-radius: 6px;
+      font: inherit;
+      box-sizing: border-box;
+    }
+    .samples-filters .status {
+      margin: 0;
+      font-size: 0.95rem;
+      align-self: center;
+    }
+  </style>
 </head>
 <body class="hub-page-samples">
   <div class="wrap">
@@ -22,6 +50,26 @@
       <h1>ToolboxAid - Sample Launcher</h1>
       <p class="subtitle">Samples are regrouped into phase folders and renumbered as LLSS (Level + Sample).</p>
     </section>
+    <section class="samples-filters" aria-label="Sample filters">
+      <div>
+        <label for="sample-phase-filter">Phase</label>
+        <select id="sample-phase-filter">
+          <option value="">All phases</option>
+        </select>
+      </div>
+      <div>
+        <label for="sample-tag-filter">Tag</label>
+        <select id="sample-tag-filter">
+          <option value="">All tags</option>
+          <option value="__untagged">Untagged</option>
+        </select>
+      </div>
+      <div>
+        <label for="sample-search">Search</label>
+        <input id="sample-search" type="search" placeholder="Sample ID, title, description, or tag" />
+      </div>
+      <p class="status" id="samples-filter-status" role="status" aria-live="polite"></p>
+    </section>
     <!-- AUTO-GENERATED SAMPLE SECTIONS START -->
     <section>
       <h2>Phase 01 - Core Engine (0101-0124)</h2>
@@ -326,6 +374,96 @@ <h2>Phase 16 - 3D Games (160x-160x)</h2>
       </div>
     </section>    
   </div>
+  <script>
+    (function () {
+      const phaseFilter = document.getElementById('sample-phase-filter');
+      const tagFilter = document.getElementById('sample-tag-filter');
+      const searchInput = document.getElementById('sample-search');
+      const statusNode = document.getElementById('samples-filter-status');
+      const linkNodes = Array.from(document.querySelectorAll('section .grid a.live'));
+
+      if (!phaseFilter || !tagFilter || !searchInput || !statusNode || linkNodes.length === 0) {
+        return;
+      }
+
+      const linkModels = linkNodes.map((link) => {
+        const href = String(link.getAttribute('href') || '');
+        const match = href.match(/^\.\/phase(\d{2})\/(\d{4})\/index\.html$/);
+        const phase = match ? match[1] : '';
+        const sampleId = match ? match[2] : '';
+        const tags = String(link.getAttribute('data-tags') || '')
+          .split(',')
+          .map((tag) => tag.trim().toLowerCase())
+          .filter(Boolean);
+        const titleText = String(link.textContent || '').trim().toLowerCase();
+        const descriptionText = String(link.getAttribute('title') || '').trim().toLowerCase();
+        const searchText = [sampleId, titleText, descriptionText, tags.join(' ')].join(' ');
+
+        return { link, phase, tags, searchText };
+      });
+
+      const phaseValues = Array.from(
+        new Set(linkModels.map((model) => model.phase).filter(Boolean))
+      ).sort();
+      for (const phase of phaseValues) {
+        const option = document.createElement('option');
+        option.value = phase;
+        option.textContent = 'Phase ' + phase;
+        phaseFilter.appendChild(option);
+      }
+
+      const tagValues = Array.from(
+        new Set(linkModels.flatMap((model) => model.tags).filter(Boolean))
+      ).sort();
+      for (const tag of tagValues) {
+        const option = document.createElement('option');
+        option.value = tag;
+        option.textContent = tag;
+        tagFilter.appendChild(option);
+      }
+
+      const sections = Array.from(document.querySelectorAll('.wrap > section')).map((section) => ({
+        section,
+        links: Array.from(section.querySelectorAll('.grid a.live'))
+      }));
+
+      function applyFilters() {
+        const selectedPhase = String(phaseFilter.value || '');
+        const selectedTag = String(tagFilter.value || '').toLowerCase();
+        const query = String(searchInput.value || '').trim().toLowerCase();
+        let visibleCount = 0;
+
+        for (const model of linkModels) {
+          const phaseMatch = !selectedPhase || model.phase === selectedPhase;
+          const tagMatch =
+            !selectedTag ||
+            (selectedTag === '__untagged' ? model.tags.length === 0 : model.tags.includes(selectedTag));
+          const searchMatch = !query || model.searchText.includes(query);
+          const isVisible = phaseMatch && tagMatch && searchMatch;
+
+          model.link.style.display = isVisible ? '' : 'none';
+          if (isVisible) {
+            visibleCount += 1;
+          }
+        }
+
+        for (const sectionModel of sections) {
+          if (sectionModel.links.length === 0) {
+            continue;
+          }
+          const hasVisibleLink = sectionModel.links.some((link) => link.style.display !== 'none');
+          sectionModel.section.style.display = hasVisibleLink ? '' : 'none';
+        }
+
+        statusNode.textContent = String(visibleCount) + ' of ' + String(linkModels.length) + ' samples shown';
+      }
+
+      phaseFilter.addEventListener('change', applyFilters);
+      tagFilter.addEventListener('change', applyFilters);
+      searchInput.addEventListener('input', applyFilters);
+      applyFilters();
+    })();
+  </script>
 </body>
 </html>