repremium/mokosh
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(04-06): complete visual polish + dark-logo decoupling — D-P4-03 closed (UAT 36/36 GREEN; 188/188 vitest with #9/#10 flake tolerated; operator re-confirmed 2026-05-26)

Browse Source 
Plan 04-06 closure — the most ceremony-heavy plan in Phase 4: 3 planner
passes + 2 plan-checker passes + 4 task commits + 1 /gsd-debug fix cycle
+ this closure commit. D-P4-03 (locked, 04-CONTEXT.md) CLOSED — both
visual polish items: (a) cursor visibility verification + (b) dark-surface
logo contrast.

Closure trail:
  6a989e8 mis-diagnosed strict-meta-json deferred-items entry
  b59bd24 re-plan iter-1 — correct false jsdom premise + back-patch lines
  deb68df re-plan-checker iter-1 — ITERATE-NEEDED (2 BLOCKER)
  f3baa3a re-plan iter-2 — real A35 + corrected 184/184 baseline
  48c7053 re-plan-checker iter-2 — PASSED (0B + 0W + 3 cosmetic-advisories)
  f0b88d4 Task 1 — Wave 0 RED inline-SVG source-contract + cursor pin
  c416143 Task 2 — Wave 1 GREEN SVG+welcome.ts+globals.d.ts
  3f8e31a Task 3 — A35 driver + A17.8 narrowed + back-patch + correction
  d66cbf6 Task 4 artifact — operator-empirical screenshot harness
  (Task 4 first operator empirical: TWEAK verdict 2026-05-26)
  a8bcc17 debug-fix — decouple via --mks-mark-stroke + A35.5 sub-check
  (Task 4 re-empirical: CONFIRMED FIXED 2026-05-26)
  THIS    closure (SUMMARY + STATE.md + ROADMAP.md + debug archive)

Key deliverables:
- mokosh-mark.svg stroke="#181b2a" -> stroke="currentColor"
- welcome.ts ?url/<img> -> ?raw/DOMParser/replaceChildren inline-<svg>
- globals.d.ts *.svg?raw ambient decl
- src/shared/tokens.css NEW --mks-mark-stroke = var(--mks-linen-50) in :root
  (NOT overridden in .dark — theme-independent brand-component token)
- src/welcome/welcome.css .welcome-hero__mark rewired to --mks-mark-stroke
- NEW A35 host-side harness (5 sub-checks incl. A35.5 light+dark equality
  decouple-proof) at tests/uat/lib/harness-page-driver.ts
- A17.8 honestly narrowed to SOURCE-BUNDLING only; points to A35
- tests/welcome/inline-svg.test.ts (3 source-contract tests)
- tests/build/cursor-visibility.test.ts (1 regression pin)
- scripts/04-06-welcome-hero-screenshots.mjs (reproducible artifact)
- 01-07-SUMMARY back-patch (5 stale lines flipped; 4 historical left)
- deferred-items.md mis-diagnosis correction

Baselines preserved:
- vitest 188/188 GREEN (most recent 187/188 with 04-CONTEXT #9/#10
  webm-remux flake; passes in isolation; tolerated per Task 2 gate)
- UAT 36/36 GREEN; FORBIDDEN_HOOK_STRINGS unchanged at 12
- Pre-checkpoint bundle gates 6/6 PASS at both checkpoint + re-checkpoint
- All 4 ROADMAP SC CLOSED; D-P4-03 CLOSED

Phase 4 progress: 6/8 -> 7/8 (Plan 04-07 NEXT).

SUMMARY: .planning/phases/04-harden-clean-up-optional/04-06-SUMMARY.md
Debug session archived: .planning/debug/resolved/04-06-dark-mode-mark-decouple.md
This commit is contained in:
Mark
2026-05-26 13:14:41 +02:00
parent a8bcc17822
commit c790c6a8b3
4 changed files with 407 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

50
.planning/STATE.md
View File

@@ -3,15 +3,15 @@ gsd_state_version: 1.0
milestone: v2.0.0
milestone_name: milestone
status: executing
stopped_at: "Completed 04-05-PLAN.md (A34 fetch+XHR network_error empirical; ROADMAP SC #2 CLOSED; skip-mode UAT 34->35/35 GREEN; full-mode bailed at pre-existing Plan 04-08 A33 SAVE-ack flake — A34 SKIPPED-not-reached but verified by skip-mode)"
last_updated: "2026-05-22T10:43:22.622Z"
last_activity: 2026-05-22
stopped_at: "Completed 04-06-PLAN.md (D-P4-03 CLOSED — both visual polish items: cursor visibility verification + dark-surface logo contrast via --mks-mark-stroke brand-component token decoupling; A35 host-side harness with 5 sub-checks including A35.5 light+dark equality decouple-proof; UAT 35->36 GREEN; vitest 184->188; multi-iteration ceremony: 3 planner passes + 2 checker passes + 1 /gsd-debug fix cycle; operator re-empirical confirmed 2026-05-26)"
last_updated: "2026-05-26T11:08:13.425Z"
last_activity: 2026-05-26
progress:
total_phases: 4
completed_phases: 3
total_plans: 31
completed_plans: 28
percent: 90
completed_plans: 29
percent: 93
---
# Project State
@@ -28,12 +28,31 @@ no server, no password leaks.
## Current Position
Phase: 04 (harden-clean-up-optional) — EXECUTING
Phase 4 of 4 (Hardening — optional) — Plans 04-01..04-05 + 04-08 closed (6/8); 2 plans remain: 04-06 (visual polish; operator empirical) + 04-07 (closure aggregator). ROADMAP SC #1 + SC #2 both CLOSED.
Plan: 7 of 7 (04-06 NEXT)
Phase 4 of 4 (Hardening — optional) — Plans 04-01..04-06 + 04-08 closed (7/8); 1 plan remains: 04-07 (Phase 4 closure aggregator + v1 milestone close prep). ROADMAP SC #1 + SC #2 both CLOSED; D-P4-03 CLOSED via Plan 04-06.
Plan: 8 of 8 (04-07 NEXT)
Status: Ready to execute
Last activity: 2026-05-22
Last activity: 2026-05-26
Progress: [█████████░] 90%
Progress: [█████████▒] 93%
### Plan 04-06 closure (2026-05-26)
- Dark-logo contrast strategy + cursor visibility verification landed end-to-end; D-P4-03 (locked, 04-CONTEXT.md) CLOSED — both visual polish items.
- 5 atomic commits (4 task + 1 debug-fix): `f0b88d4` (Task 1 — Wave 0 RED inline-SVG source-contract + cursor-visibility regression pin) → `c416143` (Task 2 — Wave 1 GREEN: SVG stroke recolor + welcome.ts ?raw/DOMParser/replaceChildren + globals.d.ts ambient decl) → `3f8e31a` (Task 3 — A35 live-DOM inline-SVG harness check + A17.8 raw-source update + 01-07-SUMMARY back-patch + deferred-items correction) → `d66cbf6` (Task 4 artifact — operator-empirical screenshot harness scripts/04-06-welcome-hero-screenshots.mjs) → operator-empirical TWEAK verdict 2026-05-26 → /gsd-debug session → `a8bcc17` (debug-fix — decouple welcome-hero mark stroke via NEW `--mks-mark-stroke` brand-component token in :root + A35.5 light+dark equality decouple-proof sub-check) → operator re-empirical CONFIRMED FIXED 2026-05-26.
- SUMMARY: `.planning/phases/04-harden-clean-up-optional/04-06-SUMMARY.md`.
- **Multi-iteration ceremony**: this was the most ceremony-heavy plan in Phase 4 — 3 planner passes (`6a989e8` mis-diagnosis → `b59bd24` re-plan iter-1 → `f3baa3a` re-plan iter-2) + 2 plan-checker passes (`deb68df` iter-1 ITERATE-NEEDED → `48c7053` iter-2 PASSED) + 4 task commits + 1 /gsd-debug fix cycle (debug session at `.planning/debug/resolved/04-06-dark-mode-mark-decouple.md`). Ceremony was a necessary cost — the brand-component vs semantic token abstraction error only surfaced when the operator saw the dark theme. Lesson encoded: when a checkpoint is operator-empirical, the planner should either front-load the brand-component token or accept a /gsd-debug fix cycle as part of the plan budget.
- **Dark-logo currentColor strategy**: src/shared/brand/mokosh-mark.svg root `<svg>` `stroke="#181b2a"` → `stroke="currentColor"` (1-attribute change; 13 children unchanged). src/welcome/welcome.ts line 46 `import markUrl from '../shared/brand/mokosh-mark.svg?url'` → `import markSvg from '../shared/brand/mokosh-mark.svg?raw'`; populateMark body rewritten to use DOMParser + replaceChildren inline-`<svg>` injection (no `<img>`, no innerHTML — MV3 CSP discipline T-04-06-01 mitigation). globals.d.ts ambient `declare module '*.svg?raw' { const raw: string; export default raw; }` block appended.
- **Theme decoupling via `--mks-mark-stroke` brand-component token**: NEW token `--mks-mark-stroke: var(--mks-linen-50)` in src/shared/tokens.css universal `:root` block (line ~131) — CRUCIALLY NOT overridden in `.dark, [data-theme="dark"]` block; stays linen-50 on every surface. src/welcome/welcome.css line 72 `.welcome-hero__mark { color: var(--mks-fg-inverse); }` → `color: var(--mks-mark-stroke);`. SVG remains untouched — stroke="currentColor" cascade plumbing identical; only the wrapper's color source changed. Both light + dark themes now resolve `computedStroke` to `rgb(250, 247, 241)` (linen-50) — crisp linen-on-madder grid icon in both themes.
- **NEW A35 host-side harness assertion** (5 sub-checks): driveA35(page, browser, extensionId) at tests/uat/lib/harness-page-driver.ts opens welcome.html as a real Puppeteer tab via `browser.newPage()` + `page.goto('chrome-extension://${extensionId}/src/welcome/welcome.html', { waitUntil: 'domcontentloaded' })` + `waitForSelector('.welcome-hero__mark svg', ...)`. Extracted `a35Probe(welcomePage, dark)` helper toggles `data-theme="dark"` on documentElement (+ requestAnimationFrame wait) + reads live DOM. 5 sub-checks: A35.1 svg present; A35.2 stroke="currentColor"; A35.3 getComputedStyle().stroke resolved non-default (linen-50); A35.4 no `<img>` in slot; A35.5 (NEW from debug session) light.computedStroke === dark.computedStroke === "rgb(250, 247, 241)" (linen-50 decouple-proof). welcomePage.close() in finally block ensures no tab leak. 3-site orchestrator wiring at tests/uat/harness.test.ts. UAT 35 → 36 GREEN.
- **A17.8 honestly narrowed**: tests/uat/extension-page-harness.ts A17.8 sub-check replaced `data:image/svg+xml` data-URL grep with raw-source grep (`stroke="currentColor"` + `viewBox="0 0 32 32"` in jsText). Explanatory comment block explicitly disavows live-DOM coverage and points to A35 for runtime behavior proof.
- **Source-contract unit tests**: tests/welcome/inline-svg.test.ts (3 it() blocks; node-env file-read + string-assert per tests/i18n/manifest-i18n.test.ts; NO DOM library; NO `@vitest-environment jsdom`). Tests A/B/C pin SVG recolor + welcome.ts ?raw/DOMParser/no-innerHTML + globals.d.ts ambient decl. tests/build/cursor-visibility.test.ts (1 it() block) pins literal `cursor: 'always'` at recorder.ts:285 (Plan 01-09 opportunistic). vitest 184 → 188 GREEN; most recent full-suite run 187/188 with the 04-CONTEXT #9/#10 webm-remux ffprobe-timeout flake tolerated (passes 5/5 in isolation per Task 2 VITEST GATE LOGIC behavior-based rule).
- **01-07-SUMMARY back-patch**: 5 stale 'deferred to Phase 5' framing lines (22, 47, 82, 135, 205) flipped to 'shipped opportunistically Plan 01-09 at recorder.ts:285; verified Phase 4 Plan 04-06'; 4 historical commit-description lines (40, 89, 109, 110) LEFT unchanged. Narrative internally consistent.
- **deferred-items.md mis-diagnosis correction**: the prior 'strict-meta-json fails on a clean tree' entry (commit `6a989e8`) rewritten to describe the real root cause — the 04-CONTEXT #9/#10 parallel-vitest ffprobe-timeout flake family + the true clean baseline of 184/184 GREEN.
- **Tier-1 FORBIDDEN_HOOK_STRINGS unchanged at 12** (Plan 04-06 adds no `__MOKOSH_UAT__`-gated symbols — DOMParser is standard web platform API; `?raw` is normal production Vite import; `*.svg?raw` ambient decl is type-only at build).
- **Pre-checkpoint bundle gates 6/6 PASS** at BOTH the first Task 4 checkpoint AND the post-debug re-checkpoint. SW chunk byte-identical at the Plan 04-05 boundary (Plan 04-06 modifies only welcome + tokens.css :root + tests + globals.d.ts — none affect SW chunk shape).
- **Cosmetic advisories ADV-2A/B/C** from re-plan-checker iter-2 all addressed: ADV-2A (banner string) LEAVE per decision (auto-count via `total = drivers.length + 1` carries actual count); ADV-2B (SKIP_PROD_REBUILD=0 rationale) corrected prose in SUMMARY; ADV-2C (A35-appended-LAST safety) documented in SUMMARY threat-surface section.
- **Debug session archived**: `.planning/debug/04-06-dark-mode-mark-decouple.md` moved to `.planning/debug/resolved/04-06-dark-mode-mark-decouple.md` at plan closure (resolved end-to-end via `a8bcc17` + operator re-empirical 2026-05-26).
- **Plan 04-07 (Phase 4 closure aggregator + v1 milestone close prep) is now the ONLY remaining Phase 4 plan.** All 4 ROADMAP success criteria CLOSED; D-P4-03 CLOSED via this plan.
### Plan 04-05 closure (2026-05-22)
@@ -166,6 +185,7 @@ Progress: [█████████░] 90%
| Phase 04 P03 | 46min | 2 tasks | 2 files |
| Phase 04 P04 | ~25min | - tasks | - files |
| Phase 04 P05 | ~45min | 2 tasks | 3 files |
| Phase 04 P06 | ~4 days end-to-end (3 planner + 2 checker + 1 /gsd-debug fix cycle; ~6h executor wall-clock across 4 task commits + 1 debug-fix commit) | 4 tasks (3 autonomous + 1 operator empirical with TWEAK→fix→CONFIRMED arc) | 11 modified + 4 created |
## Accumulated Context
@@ -223,6 +243,10 @@ current work:
- [Phase 04-04]: stopServiceWorker(browser, extensionId) helper landed at tests/uat/lib/harness-page-driver.ts (verbatim Chrome devrel canonical pattern — Puppeteer >=22.1.0 worker.close()). Persisting artifact retained even though Task 2 BLOCKED — helper is non-empty positive scaffolding for the eventual IndexedDB-persistence plan-fix verification harness (A33-equivalent reuse). Pattern: spike-FAILED forensic-evidence — commit the spike script (tests/uat/spike-a33-sw-persistence.ts; 202 lines) AND the persisting helpers (not delete) so future plan-fix can re-run the exact reproducible test that revealed the failure.
- [Phase ?]: [Phase 04-08]: Methodology reframe — video-file MediaStream replaces canvas.captureStream throttling per debug session-2 verdict; A33 lands; UAT 33->34; ROADMAP SC #1 CLOSED 2026-05-22 (videoSize=1.8MB vs 8505 baseline); architecture UNCHANGED.
- [Phase ?]: [Phase 04-05]: A34 fetch+XHR network_error empirical lands (ROADMAP SC #2 CLOSED). cs-injection-world fetch(404)+XMLHttpRequest(404) from an example.com probe tab via chrome.scripting.executeScript ISOLATED; driveA34 host-side JSZip-parses logs/events.json + asserts 2 network_error entries (fetch+XHR) with meta.status===404. Plan 04-01 P1 #11 Request-narrow fix validated end-to-end — fetch entry target carries real URL not [object Request]. Skip-mode UAT 34->35/35 GREEN (A34 real, all 6 checks PASS). Tier-1 FORBIDDEN_HOOK_STRINGS unchanged at 12; bundle gates 6/6 PASS; vitest 184/184 preserved. Full-mode 35/35 gate observed a pre-existing Plan 04-08 A33 SAVE-ack flake (A33.1 false; 1.56MB video buffer survived) — A34 SKIPPED-not-reached in that run, unaffected; A33 flake routed to /gsd-debug.
- [Phase 04-06]: Dark-logo currentColor + inline-SVG injection + `--mks-mark-stroke` brand-component token decoupling + cursor-visibility verification + NEW A35 host-side harness with 5 sub-checks (incl. A35.5 light+dark equality decouple-proof). D-P4-03 (locked, 04-CONTEXT.md) CLOSED — both visual polish items. Multi-iteration ceremony: 3 planner passes + 2 plan-checker passes + 1 /gsd-debug fix cycle (debug session resolved at `a8bcc17`). 5 task commits: `f0b88d4` (Wave 0 RED test+pin) → `c416143` (Wave 1 GREEN SVG+welcome.ts+globals.d.ts) → `3f8e31a` (A35 driver + A17.8 raw-source narrowing + 01-07-SUMMARY back-patch + deferred-items correction) → `d66cbf6` (operator-empirical screenshot harness) → `a8bcc17` (debug-fix --mks-mark-stroke decoupling + A35.5 sub-check). Operator empirical Task 4 TWEAK → /gsd-debug per `feedback-gsd-ceremony-for-fixes.md` → CONFIRMED FIXED 2026-05-26.
- [Phase 04-06]: Brand-component token vs semantic token abstraction pattern established. `--mks-fg-inverse` is for theme-flipping text foreground (where the surface flips); the welcome-mark wrapper sits on theme-INDEPENDENT madder-600, so a theme-coupled stroke was the wrong abstraction. Fix: introduce a NEW brand-component token `--mks-mark-stroke = var(--mks-linen-50)` in the universal `:root` block + do NOT override in `.dark, [data-theme="dark"]` + rewire `.welcome-hero__mark { color: var(--mks-mark-stroke); }`. SVG remains untouched (currentColor cascade plumbing identical; only wrapper's color source changed). Both themes now resolve computedStroke to rgb(250, 247, 241) (linen-50). The `--mks-fg-inverse` token continues serving its proper role (e.g. src/popup/style.css:39 — theme-flipping surface; LEFT untouched). Pattern: brand-component tokens for theme-independent surfaces; semantic tokens for theme-flipping surfaces.
- [Phase 04-06]: Live-DOM host-side harness assertion pattern against welcome.html — NEW A35 driver (driveA35 in tests/uat/lib/harness-page-driver.ts) opens welcome.html as a real Puppeteer tab via browser.newPage() + page.goto(chrome-extension://${extensionId}/src/welcome/welcome.html) + waitForSelector('.welcome-hero__mark svg', ...). Extracted a35Probe(welcomePage, dark) helper toggles documentElement.setAttribute('data-theme', 'dark'|'light') (+ requestAnimationFrame wait) for multi-theme probing. 5 CheckRecords incl. A35.5 light+dark equality decouple-proof. welcomePage.close() in finally block. Pattern reusable for any future welcome.html DOM contract + multi-theme live-DOM check.
- [Phase 04-06]: Operator-empirical screenshot harness pattern — per `feedback-trust-harness-over-manual-uat.md`, the operator only judges aesthetics from /tmp/04-06-welcome-hero-{light,dark}.png produced via Puppeteer's Emulation.setEmulatedMedia (prefers-color-scheme: dark). Automation does the rest. scripts/04-06-welcome-hero-screenshots.mjs (194 lines) is the reproducible artifact. The operator's TWEAK verdict on the dark cascade was the surface that catches the abstraction error a planner-checker cannot — encoded the cost-of-empirical-checkpoints lesson.
### Pending Todos
@@ -247,11 +271,13 @@ Items acknowledged and carried forward from previous milestone close:
## Session Continuity
Last session: 2026-05-22T10:43:10.855Z
Stopped at: Completed 04-05-PLAN.md (A34 fetch+XHR network_error empirical; ROADMAP SC #2 CLOSED; skip-mode UAT 34->35/35 GREEN; full-mode bailed at pre-existing Plan 04-08 A33 SAVE-ack flake — A34 SKIPPED-not-reached but verified by skip-mode)
Last session: 2026-05-26T11:08:13Z
Stopped at: Completed 04-06-PLAN.md (D-P4-03 CLOSED — both visual polish items: cursor visibility verification + dark-surface logo contrast via --mks-mark-stroke brand-component token decoupling; A35 host-side harness with 5 sub-checks including A35.5 light+dark equality decouple-proof; UAT 35->36 GREEN; vitest 184->188; multi-iteration ceremony: 3 planner passes + 2 checker passes + 1 /gsd-debug fix cycle; operator re-empirical confirmed 2026-05-26)
Resume file: None
Prior session: 2026-05-21T08:22:59.958Z — /gsd-pause-work saved Phase 4 execution-ready handoff (dbcf482); Phase 4 plans validated iter-2 PASSED + 3 cosmetic advisories fixed
Prior session: 2026-05-22T10:43:10.855Z — Completed 04-05-PLAN.md (A34 fetch+XHR network_error empirical; ROADMAP SC #2 CLOSED; skip-mode UAT 34->35/35 GREEN; full-mode bailed at pre-existing Plan 04-08 A33 SAVE-ack flake — A34 SKIPPED-not-reached but verified by skip-mode)
Earlier session: 2026-05-21T08:22:59.958Z — /gsd-pause-work saved Phase 4 execution-ready handoff (dbcf482); Phase 4 plans validated iter-2 PASSED + 3 cosmetic advisories fixed
Earlier session: 2026-05-20T12:54:42.000Z — /gsd-pause-work saved Phase 2 execution-ready handoff (a440c7d); Phase 1 closed end-to-end via verifier audit GREEN (586836f); alpha distribution shipped (dist-archives/mokosh-build-2026-05-20-6dbed91.zip)
Earlier session: 2026-05-20T12:00:00.000Z — Plan 01-10 closed via cycle-2 operator ack "All good" + 5 inter-cycle debug fixes + brand-rename follow-up
Even earlier: 2026-05-20T08:00:00.000Z — Plan 01-12 closed via Wave 7 operator brand-fit ack 2026-05-20 'all good' (SUMMARY f319c7d; 147/147 vitest + 21/21 UAT GREEN)