Align Achievements with project data and clarify Colors disabled swatches - PR_26159_030-achievements-project-data-alignment & Restore Colors picker viewer and explain unavailable swatches - PR_26159_031-colors-picker-viewer-restore

Author: ToolboxAid

docs_build/dev/admin-notes/project-journey/index.txt

@@ -25,6 +25,10 @@ Project Workspace uses the `project-workspace` server repository source, seeded
 
 Because the Account page did not read from the Project Workspace repository/API boundary, the two surfaces drifted. This PR moves the Build rows into `assets/theme-v2/js/account-achievements.js` and reads them through `createServerRepositoryClient("project-workspace")`.
 
+## Scope Cleanup
+
+The current working tree also removes `docs_build/dev/admin-notes/project-journey/index.txt` because it was accidentally included in the prior PR_26159_030 commit even though Admin Notes and Project Journey notes are unrelated to this PR. No Admin Notes runtime behavior is changed.
+
 ## Colors Disabled / Grayed Swatch Explanation
 
 The meaningful disabled subset is picker swatches that are already pinned into Project Swatches. Those swatches are not invalid colors; they are already selected. They are dimmed/disabled by default in Picker Preview so clicking the picker grid adds new swatches instead of toggling already selected ones.
@@ -58,6 +62,7 @@ The checkbox is now labeled `Include already selected swatches`, which describes
 | Playwright impacted | PASS | Account Achievements, Project Workspace render, and Palette lanes run. |
 | Do not run full samples validation | PASS | Full samples skipped with reason. |
 | Produce repo-structured ZIP | PASS | Created under `tmp/PR_26159_030-achievements-project-data-alignment_delta.zip`. |
+| Keep PR scope clean | PASS | Removed the out-of-scope `docs_build/dev/admin-notes/project-journey/index.txt` file that was accidentally included in the prior PR_26159_030 commit. |
 
 ## Validation Evidence
 
@@ -72,7 +77,7 @@ Commands run:
 - `npx playwright test tests/playwright/tools/PaletteToolMockRepository.spec.mjs` - PASS, 6 passed
 - `npx playwright test tests/playwright/account/AchievementsPage.spec.mjs tests/playwright/tools/PaletteToolMockRepository.spec.mjs --workers=1` - PASS, 8 passed and final V8 coverage
 - `git diff --check` - PASS
-- Active scans for old Achievements mock names, Colors Symbol validation, and old global picker checkbox naming - PASS
+- Active scans for old Achievements mock names, Colors Symbol validation, and old global picker checkbox naming - PASS. The text `Picker Preview` remains only as the accordion title, not as the checkbox label.
 
 ## Skipped Lanes
 

docs_build/dev/reports/achievements-project-data-alignment-report.md

@@ -0,0 +1,69 @@
+# PR_26159_031 Colors Picker Viewer Restore Report
+
+## Executive Summary
+
+Status: PASS
+Playwright impacted: Yes
+Full samples validation: Skipped, not impacted.
+
+Colors Picker Preview now renders available picker swatches first and already-in-project picker swatches in a separate bottom section. ROYGBIV was added as a curated Defined Swatch Selector source, and active Colors Symbol validation remains removed.
+
+## Root Cause: Unavailable Picker Swatches
+
+Some picker swatches are unavailable because their normalized RGB value already exists in Project Swatches. The exact rule is `pinnedSwatchForHex(hex)`: compare the generated picker swatch hex against Project Swatches using the first seven normalized hex characters, ignoring alpha.
+
+Unavailable swatches are not unavailable because of contrast/filter rules, missing metadata, or generic disabled picker state. They are RGB duplicates of an existing Project Swatches color.
+
+This PR places available swatches in the top `Available Picker Swatches` section and places duplicates in the bottom `Already in Project` section. The unavailable section preserves the real color, does not use disabled buttons, does not change opacity, and click attempts do not add duplicates. The override checkbox is now named `Include already in Project swatches` and only affects that already-in-project subset.
+
+## Root Cause: Symbol Regression
+
+The returned `Symbol: Enter a symbol for this swatch.` error came from older/stale Colors validation paths where swatches required a one-character symbol. The current active Colors flow is key/hex/name based. Active Colors source no longer has Symbol fields, Symbol validation, or `data-palette-symbol` controls.
+
+This PR also corrected the browser API helper for `validatePaletteSwatchInput` so it forwards the same input, existing-swatches, and options contract used by the server-side palette validation. Add, Update, picker selection, Project Swatches, and `tools.palette-browser.swatches` all operate without Symbol input.
+
+## Requirement Checklist
+
+| Requirement | Status | Evidence |
+| --- | --- | --- |
+| Read `PROJECT_INSTRUCTIONS.md` first | PASS | Read before implementation. |
+| Inspect PR_26159_025 behavior/history | PASS | Inspected commit `1ad83b4c2` and current picker render code. |
+| Available picker swatches grouped at top | PASS | Playwright validates `Available Picker Swatches` top group and counts. |
+| Unavailable picker swatches grouped at bottom | PASS | Playwright validates `Already in Project` bottom group and counts. |
+| Preserve subset unavailable behavior | PASS | Unavailable subset is only RGB duplicates already in Project Swatches. |
+| Keep newer Defined Swatch Selector controls/options | PASS | Existing Theme Collection, Palette Type, Variant controls and curated options remain; Playwright iterates all expected collections/types. |
+| Add ROYGBIV curated selector option | PASS | Added ROYGBIV collection/type with Red, Orange, Yellow, Green, Blue, Indigo, Violet base swatches; Playwright validates generated names. |
+| Report why swatches are unavailable | PASS | Root-cause section above. |
+| Report exact bottom-section rule | PASS | `pinnedSwatchForHex(hex)` normalized RGB match against Project Swatches. |
+| Do not gray out unavailable swatches | PASS | Unavailable swatches do not use disabled button opacity; Playwright validates opacity remains `1`. |
+| Remove red not-allowed cursor behavior | PASS | Unavailable swatches are not disabled and Playwright validates cursor is not `not-allowed`. |
+| Unavailable swatches preserve true color | PASS | Playwright validates unavailable color input value matches the generated hex. |
+| Unavailable swatches do not add on click | PASS | Playwright clicks unavailable swatch and verifies Project Swatches count stays unchanged. |
+| Available swatches add on click | PASS | Playwright clicks available picker swatches and verifies Project Swatches count increases. |
+| Remove global enable/disable checkbox behavior | PASS | Old global picker checkbox strings are absent; remaining checkbox only affects already-in-project swatches. |
+| Fix Symbol validation error | PASS | Active Symbol validation scan is clean; Add/Update Playwright passes without Symbol field. |
+| `tools.palette-browser.swatches` accepts swatches without Symbol | PASS | Repository and UI tests add swatches using key/hex/name payloads with no Symbol input. |
+| Validate no console errors | PASS | Palette Playwright captures page errors/console errors and passed. |
+| Do not run full samples validation | PASS | Full samples skipped; no sample JSON or shared sample loader changed. |
+
+## Validation Evidence
+
+- `node --check toolbox/colors/colors.js` - PASS
+- `node --check toolbox/colors/palette-api-client.js` - PASS
+- `node --check tests/playwright/tools/PaletteToolMockRepository.spec.mjs` - PASS
+- `npx playwright test tests/playwright/tools/PaletteToolMockRepository.spec.mjs` - PASS, 6 passed
+- `git diff --check` - PASS with line-ending warnings only
+- Active `rg` scan for Symbol validation/control strings - PASS, no matches
+- Active `rg` scan for old global picker checkbox strings - PASS, no matches
+
+## Skipped Lanes
+
+- Full samples validation: skipped because this PR only changes the Colors tool runtime/test path and does not change sample JSON, sample launcher code, or shared sample framework behavior.
+- Broad Playwright suite: skipped because targeted Palette Playwright validates the affected picker viewer, Add/Update, validation, and console-error behavior.
+
+## Artifacts
+
+- `docs_build/dev/reports/codex_review.diff`
+- `docs_build/dev/reports/codex_changed_files.txt`
+- `docs_build/dev/reports/playwright_v8_coverage_report.txt`
+- `tmp/PR_26159_031-colors-picker-viewer-restore_delta.zip`

docs_build/dev/reports/colors-picker-viewer-restore-report.md

@@ -6,12 +6,8 @@ Missing changed runtime JS files are WARN, not FAIL.
 Source: Playwright/Chromium built-in V8 coverage from the active Playwright run.
 
 Changed runtime JS files considered:
-(0%) src/dev-runtime/guest-seeds/tool-state-samples.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(0%) src/dev-runtime/persistence/mock-db-store.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(0%) src/dev-runtime/persistence/tool-repositories/palette-workspace-repository.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(84%) toolbox/colors/colors.js - executed lines 1872/1872; executed functions 157/186
+(85%) toolbox/colors/colors.js - executed lines 1938/1938; executed functions 165/194
+(100%) toolbox/colors/palette-api-client.js - executed lines 19/19; executed functions 4/4
 
 Guardrail warnings:
-(0%) src/dev-runtime/guest-seeds/tool-state-samples.js - WARNING: changed runtime JS file missing from coverage; advisory only
-(0%) src/dev-runtime/persistence/mock-db-store.js - WARNING: changed runtime JS file missing from coverage; advisory only
-(0%) src/dev-runtime/persistence/tool-repositories/palette-workspace-repository.js - WARNING: changed runtime JS file missing from coverage; advisory only
+(100%) none - no changed runtime JS coverage warnings

docs_build/dev/reports/coverage_changed_js_guardrail.txt

@@ -14,37 +14,26 @@ Note: coverage entries are aggregated across every page/tool where coverageRepor
 Exercised tool entry points detected:
 (84%) Toolbox Index - exercised 3 runtime JS files
 (0%) Tool Template V2 - not exercised by this Playwright run
-(71%) Theme V2 Shared JS - exercised 3 runtime JS files
+(64%) Theme V2 Shared JS - exercised 2 runtime JS files
 
 Changed runtime JS files covered:
-(0%) src/dev-runtime/guest-seeds/tool-state-samples.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(0%) src/dev-runtime/persistence/mock-db-store.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(0%) src/dev-runtime/persistence/tool-repositories/palette-workspace-repository.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(84%) toolbox/colors/colors.js - executed lines 1872/1872; executed functions 157/186
+(85%) toolbox/colors/colors.js - executed lines 1938/1938; executed functions 165/194
+(100%) toolbox/colors/palette-api-client.js - executed lines 19/19; executed functions 4/4
 
 Files with executed line/function counts where available:
 (58%) src/engine/api/server-api-client.js - executed lines 159/159; executed functions 11/19
+(64%) assets/theme-v2/js/gamefoundry-partials.js - executed lines 525/525; executed functions 28/44
 (64%) assets/theme-v2/js/tool-display-mode.js - executed lines 201/201; executed functions 9/14
-(66%) assets/theme-v2/js/gamefoundry-partials.js - executed lines 525/525; executed functions 29/44
 (78%) toolbox/tool-registry-api-client.js - executed lines 148/148; executed functions 21/27
-(84%) toolbox/colors/colors.js - executed lines 1872/1872; executed functions 157/186
-(93%) assets/theme-v2/js/account-achievements.js - executed lines 106/106; executed functions 13/14
+(85%) toolbox/colors/colors.js - executed lines 1938/1938; executed functions 165/194
 (100%) toolbox/colors/palette-api-client.js - executed lines 19/19; executed functions 4/4
 
 Uncovered or low-coverage changed JS files:
-(0%) src/dev-runtime/guest-seeds/tool-state-samples.js - WARNING: uncovered changed runtime JS file; advisory only
-(0%) src/dev-runtime/persistence/mock-db-store.js - WARNING: uncovered changed runtime JS file; advisory only
-(0%) src/dev-runtime/persistence/tool-repositories/palette-workspace-repository.js - WARNING: uncovered changed runtime JS file; advisory only
+(100%) none - no low-coverage changed runtime JS files
 
 Changed JS files considered:
-(0%) src/dev-runtime/guest-seeds/tool-state-samples.js - changed JS file not collected as browser runtime coverage
-(0%) src/dev-runtime/persistence/mock-db-store.js - changed JS file not collected as browser runtime coverage
-(0%) src/dev-runtime/persistence/tool-repositories/palette-workspace-repository.js - changed JS file not collected as browser runtime coverage
+(0%) assets/theme-v2/js/account-achievements.js - changed JS file not collected as browser runtime coverage
 (0%) tests/playwright/account/AchievementsPage.spec.mjs - changed JS file not collected as browser runtime coverage
-(0%) tests/playwright/tools/AdminDbViewer.spec.mjs - changed JS file not collected as browser runtime coverage
-(0%) tests/playwright/tools/LoginSessionMode.spec.mjs - changed JS file not collected as browser runtime coverage
 (0%) tests/playwright/tools/PaletteToolMockRepository.spec.mjs - changed JS file not collected as browser runtime coverage
-(0%) tests/playwright/tools/ProjectJourneyTool.spec.mjs - changed JS file not collected as browser runtime coverage
-(66%) assets/theme-v2/js/gamefoundry-partials.js - changed JS file with browser V8 coverage
-(84%) toolbox/colors/colors.js - changed JS file with browser V8 coverage
-(93%) assets/theme-v2/js/account-achievements.js - changed JS file with browser V8 coverage
+(85%) toolbox/colors/colors.js - changed JS file with browser V8 coverage
+(100%) toolbox/colors/palette-api-client.js - changed JS file with browser V8 coverage

docs_build/dev/reports/playwright_v8_coverage_report.txt

@@ -1,38 +1,37 @@
 # Testing Lane Execution Report
 
-PR: PR_26159_030-achievements-project-data-alignment
+PR: PR_26159_031-colors-picker-viewer-restore
 Generated: 2026-06-08
 Full samples validation: SKIPPED
 
 ## Summary
 
 PASS: 7
-WARN: 1
+WARN: 0
 FAIL: 0
-SKIP: 1
+SKIP: 2
 
 ## Executed Lanes
 
 | Lane | Status | Command | Evidence |
 | --- | --- | --- | --- |
-| Changed JS syntax | PASS | `node --check assets/theme-v2/js/account-achievements.js` | Account Achievements module parses. |
-| Colors runtime syntax | PASS | `node --check toolbox/colors/colors.js` | Colors picker subset changes parse. |
-| Achievements Playwright syntax | PASS | `node --check tests/playwright/account/AchievementsPage.spec.mjs` | Updated account test parses. |
-| Palette Playwright syntax | PASS | `node --check tests/playwright/tools/PaletteToolMockRepository.spec.mjs` | Updated palette test parses. |
-| Account Achievements Playwright | PASS | `npx playwright test tests/playwright/account/AchievementsPage.spec.mjs` | 2 passed. Validates Project Workspace project names/statuses, placeholders, old mock names absent, and no console errors. |
-| Project Workspace render validation | PASS | `npx playwright test tests/playwright/tools/ProjectWorkspaceMockRepository.spec.mjs -g "Project Workspace creates, opens, and deletes mock projects"` | 1 passed. Validates Project Workspace still renders its project cards/list. |
-| Palette / Colors Playwright | PASS | `npx playwright test tests/playwright/tools/PaletteToolMockRepository.spec.mjs` | 6 passed. Validates Add/Update without Symbol, renamed picker checkbox, subset-only disabled behavior, and no console errors. |
-| Combined V8 coverage run | PASS | `npx playwright test tests/playwright/account/AchievementsPage.spec.mjs tests/playwright/tools/PaletteToolMockRepository.spec.mjs --workers=1` | 8 passed. Final V8 coverage includes `assets/theme-v2/js/account-achievements.js` and `toolbox/colors/colors.js`. |
-| Full Project Workspace spec | WARN | `npx playwright test tests/playwright/tools/ProjectWorkspaceMockRepository.spec.mjs` | 6 passed, 1 unrelated existing Toolbox member-role count expectation failed: expected `Tool Count: 5/38`, current page shows `6/38`. The requested Project Workspace render/list test passed and was rerun directly. |
-| Static validation | PASS | `git diff --check`; active `rg` scans for Symbol validation, old Achievements mock names, and picker checkbox labels | No whitespace errors; no active Colors Symbol validation hits; old Achievements mock names are absent from active Achievements source; global picker enable label removed. |
+| Colors runtime syntax | PASS | `node --check toolbox/colors/colors.js` | Colors picker grouping, ROYGBIV data, and unavailable handling parse. |
+| Colors API helper syntax | PASS | `node --check toolbox/colors/palette-api-client.js` | Validation API contract forwarding parses. |
+| Palette Playwright syntax | PASS | `node --check tests/playwright/tools/PaletteToolMockRepository.spec.mjs` | Updated Palette tests parse. |
+| Palette / Colors Playwright | PASS | `npx playwright test tests/playwright/tools/PaletteToolMockRepository.spec.mjs` | 6 passed. Validates available/unavailable picker groups, unavailable click blocking, no graying/not-allowed cursor, ROYGBIV, Add/Update without Symbol validation, and no console errors. |
+| Runtime V8 coverage | PASS | Palette Playwright afterAll coverage reporter | `docs_build/dev/reports/playwright_v8_coverage_report.txt` includes `toolbox/colors/colors.js` and `toolbox/colors/palette-api-client.js`. |
+| Static whitespace validation | PASS | `git diff --check` | No whitespace errors; line-ending warnings only. |
+| Targeted string scans | PASS | Active `rg` scans for Symbol validation/control strings and old global picker checkbox strings | No active Colors Symbol validation/control hits and no old global picker checkbox strings. |
 
 ## Skipped Lanes
 
 | Lane | Status | Reason |
 | --- | --- | --- |
-| Full samples validation | SKIP | This PR did not change sample JSON contracts or the shared sample loader/framework. Targeted account, Project Workspace render, Colors, syntax, and static checks covered the impacted surfaces. |
+| Full samples validation | SKIP | This PR does not touch sample JSON, sample launcher code, or shared sample framework behavior. |
+| Broad Playwright suite | SKIP | Targeted Palette Playwright covers the changed Colors runtime/UI behavior and console-error assertions. |
 
 ## Notes
 
-- The unrelated untracked folder `docs_build/dev/admin-notes/project-journey/` was present before this PR work and was not touched or packaged.
-- Playwright V8 coverage was generated at `docs_build/dev/reports/playwright_v8_coverage_report.txt`.
+- The unavailable picker swatch rule is normalized RGB duplicate detection against Project Swatches via `pinnedSwatchForHex(hex)`.
+- Unavailable picker swatches are not disabled buttons, so their color and cursor remain normal while click handling prevents duplicate adds.
+- Existing local test-server output still prints SQLite experimental warnings and seed-only audit fallback diagnostics; targeted Playwright assertions passed.