TheLastGarden/.planning/phases/02-season-1-vertical-slice-soil/02-06-uat-gap-closure-SUMMARY.md

---

phase: 02-season-1-vertical-slice-soil plan: 06 subsystem: uat-gap-closure tags: [gap-closure, uat, css, first-run-hint, tile-contrast, gate-context, mvp, wave-0]

Dependency graph

requires:

• phase: 02-01 provides: Zustand store + V1Payload + session slice (extended in this plan with firstRunHintDismissed)
• phase: 02-02 provides: BeginScreen (analog component for FirstRunHint shape) + tile-renderer (G3 modifies its constants) + ui-strings.yaml shape
• phase: 02-03 provides: JournalIcon (analog corner-affordance pattern) + Journal modal
• phase: 02-04 provides: gate-renderer (G4 adds wall band primitive) + Lura gate location at canvas (880, 384)
• phase: 02-05 provides: tests/e2e/season1-loop.spec.ts (Playwright PIPE-07 full-loop smoke — Task 5 threads 3 new gap-closure assertions into it) + App.tsx render tree (FirstRunHint mounts alongside Letter / Settings / etc.) provides:
• src/index.css — global page styles (body bg #1a1a1a, color #e8e0d0, zero margin, 100vh, serif, #game-container flex centering). Imported once from src/main.tsx so Vite bundles it into the entry chunk; body styles apply before React mounts.
• src/ui/first-run/FirstRunHint.tsx — single-line bible-voice hint surfaced after BeginScreen dismisses, auto-dismisses on first plant !== null transition. Reads externalized line from uiStrings[1]?.first_run_hint per STRY-09.
• src/store/session-slice.ts extended — firstRunHintDismissed: boolean + dismissFirstRunHint() action. Session state ONLY; NEVER added to V1Payload (no migrations[2]).
• src/content/schemas/ui-strings.ts extended — UiStringsSchema gains first_run_hint: z.string().min(1) so Zod's default strip mode does NOT silently drop the YAML key from parsed.data at runtime.
• content/seasons/01-soil/ui-strings.yaml — first_run_hint key added with bible-voice copy "Begin where the soil is bare." (the plan's #1 ranked candidate; rationale documented in §Decisions Made).
• src/render/garden/tile-renderer.ts — OUTLINE_COLOR brightened 0x4d4d52 → 0x5a5a60 + OUTLINE_HOVER 0x6e6e75 → 0x7a7a82 + HOVER_FILL_ALPHA=0.06 fill bump on the hit rectangle. Constants exported for testability.
• src/render/garden/gate-renderer.ts — adds 4th Phaser primitive (wall band) at GATE_X column spanning the full 768px canvas height with alpha=0.18 (mid of 0.15-0.20 fix_shape range). GateGameObjects interface gains a wall field — additive, Garden.ts unchanged.
• tests/e2e/season1-loop.spec.ts — extended with 3 new assertions covering G1 + G2 end-to-end (body bg = rgb(26, 26, 26), FirstRunHint visible after Begin dismiss, FirstRunHint gone after first plant).
• 21 new Vitest cases across 4 test files (G1: 6 file-read smoke, G2: 6 behavioral, G3: 5 phaser-mocked, G4: 4 phaser-mocked).
• 4 first-impression UX gaps from 2026-05-09 live UAT structurally closed (G1 BLOCKING, G2 BLOCKING, G3 HIGH, G4 MEDIUM). affects: [/gsd-verify-work (re-verifier consumes this SUMMARY to flip 02-VERIFICATION.md status from gaps_found → verified), Phase 3 (Watercolor & Cello — paints over the structural primitives without changing the layout intent)]

Tech tracking

tech-stack: added: [] patterns: - "Single CSS file imported from main.tsx as the global-style anchor: Vite bundles plain CSS imports natively, no build-config change needed. body bg + color + font-family all match the BeginScreen overlay so there is no tonal break at any frame." - "Session-state-only first-run gate: firstRunHintDismissed lives in src/store/session-slice.ts (NOT V1Payload). The hint reappears on hard reload until the first plantSeed commits — that is the correct A-Dark-Room first-run UX (re-prompt on a fresh tab, dismiss on first action)." - "Schema extension MANDATORY when adding YAML keys: Zod's default z.object() strip mode silently drops unknown keys from parsed.data. Without extending UiStringsSchema, the runtime would have rendered first_run_hint as undefined and FirstRunHint would have rendered null — production-only failure that unit tests mocking the store directly would not catch." - "Phaser-mock pattern for renderer unit tests: vi.mock('phaser', ...) short-circuits the Phaser bundle import so the renderer module loads under happy-dom (Phaser 4's checkInverseAlpha boot probe crashes on canvas.getContext returning null). Combined with a mocked Phaser.Scene surface (add.graphics + add.rectangle returning vi.fn() spies), the test pins constants and call args without needing a real Chromium canvas. Reusable for plant-renderer and ready-pulse coverage in future phases." - "Tile hover as steady-state outline + fill swap (NOT animation): pointerover swaps OUTLINE_COLOR → OUTLINE_HOVER and bumps the hit rectangle's fill alpha from 0 → 0.06; pointerout reverses. No tweens, no setInterval. Reduced-motion-safe by construction; Phase 8's global motion-preference owner has no work to do here." - "Gate wall band as structural primitive (Phase 3 deferral preserved): a single Phaser Rectangle at GATE_X with alpha=0.18 spans the canvas height to give the gate visual context (the bible's 'walled garden' framing). Phase 3 paints the watercolor wall over this primitive without changing the geometry or interaction surface."

key-files: created: - src/index.css (G1 — global page styles, ~25 lines) - src/index.css.test.ts (G1 — 6 file-read smoke cases pinning the load-bearing CSS rules) - src/ui/first-run/FirstRunHint.tsx (G2 — single-line hint component, externalized copy, auto-dismiss subscription) - src/ui/first-run/FirstRunHint.test.tsx (G2 — 6 behavioral cases: hidden when Begin still up, hidden when dismissed, renders externalized line, reads uiStrings, auto-dismisses on first plant, stays dismissed) - src/ui/first-run/index.ts (G2 — barrel) - src/render/garden/tile-renderer.test.ts (G3 — 5 cases via Phaser-Scene-mock pattern: constants pinned, 16 tile groups, initial draw uses OUTLINE_COLOR, pointerover swaps to OUTLINE_HOVER + fill bump) - src/render/garden/gate-renderer.test.ts (G4 — 4 cases via Phaser-Scene-mock pattern: constants in fix_shape range, wall is first rectangle with full canvas height, 4 total rectangles, GateGameObjects exposes wall handle) - .planning/phases/02-season-1-vertical-slice-soil/02-06-uat-gap-closure-SUMMARY.md (this file) modified: - src/main.tsx (G1 — single import './index.css'; line added) - src/store/session-slice.ts (G2 — firstRunHintDismissed + dismissFirstRunHint added; session state only, NOT in V1Payload) - src/content/schemas/ui-strings.ts (G2 — UiStringsSchema gains first_run_hint: z.string().min(1) so Zod strip mode does not drop the YAML key) - content/seasons/01-soil/ui-strings.yaml (G2 — first_run_hint key with bible-voice copy) - src/ui/index.ts (G2 — re-exports ./first-run) - src/App.tsx (G2 — mounted between BeginScreen and SeedPicker) - src/render/garden/tile-renderer.ts (G3 — OUTLINE_COLOR + OUTLINE_HOVER brightened, HOVER_FILL_ALPHA=0.06 added; constants exported) - src/render/garden/gate-renderer.ts (G4 — wall band primitive added; WALL_BAND_X / WALL_BAND_WIDTH / WALL_BAND_HEIGHT / WALL_BAND_ALPHA / WALL_BAND_COLOR exported; GateGameObjects gains wall field) - tests/e2e/season1-loop.spec.ts (Task 5 — 3 new assertions threaded into PIPE-07 happy path: body bg, FirstRunHint visible after Begin, FirstRunHint gone after first plant)

decisions:

• id: 02-06-D1 decision: "First-run hint copy: 'Begin where the soil is bare.' (plan's #1 ranked candidate)" rationale: "CLAUDE.md tone constraint says player-visible copy must match the bible's voice — warm, specific, intermittent, sometimes funny, sometimes devastating. Of the three ranked candidates, #1 has all four bible markers — soil + bare are specific and contemplative; the imperative 'Begin' echoes the BeginScreen CTA without redundancy; the construction is intermittent (one beat, no follow-on). #2 ('The soil is waiting.') is quieter but more elliptical for a brand-new player on frame one. #3 ('Click a tile to plant.') is the functional fallback and would only be chosen if HUMAN-UAT review surfaced #1 as too elliptical. The plan's recommended choice was #1 and there was no reason to deviate."
• id: 02-06-D2 decision: "Session-state for firstRunHintDismissed (NOT V1Payload — no migrations[2])" rationale: "Plan scope_constraint #3 (also CLAUDE.md hard constraint). The hint is a first-run-of-this-tab affordance, like A Dark Room's '...the room is empty' or '...the fire is dead' surfaces. The player should see it again if they hard-reload before planting; once they plant it stays down for the session. Persisting to save would (1) require migrations[2] which Phase 1 has shipped zero v1 saves to migrate forward and is structurally premature; (2) force a one-time 'permanent dismissal' UX that loses the cozy re-onboarding signal across reloads. Session state is the cleaner shape."
• id: 02-06-D3 decision: "UiStringsSchema extended with first_run_hint: z.string().min(1) — schema edit was MANDATORY, not optional" rationale: "Zod's default object mode is 'strip' — unknown keys parse SUCCESSFULLY but are SILENTLY DROPPED from parsed.data. Without the schema edit, content/seasons/01-soil/ui-strings.yaml could carry the first_run_hint key but uiStrings[1].first_run_hint would be undefined at runtime, FirstRunHint would render null in production, and only the unit tests that mock the store directly would catch it. The plan's Step 2 calls this out explicitly. The edit is one line in src/content/schemas/ui-strings.ts; the cost of skipping it is a production-only failure mode that unit tests cannot detect. .min(1) defends against an accidental empty-string in YAML."
• id: 02-06-D4 decision: "Phaser-mock pattern via vi.mock('phaser') for tile-renderer + gate-renderer tests" rationale: "First attempt at tile-renderer test imported the source file directly; Phaser 4's checkInverseAlpha boot probe (canvas.getContext('2d') returning null under happy-dom) crashed the test setup. The plan acknowledged this risk via the SeedPicker mock pattern reference. vi.mock('phaser', () => ({ default: {} })) at module top short-circuits the bundle load entirely; the test then mocks the Scene's add.graphics + add.rectangle surface to capture call args. For gate-renderer, BlendModes.ADD is mocked as the sentinel value 1 so setBlendMode receives a non-undefined argument. The pattern is reusable for plant-renderer + ready-pulse coverage in future phases."
• id: 02-06-D5 decision: "WALL_BAND_ALPHA = 0.18 (mid of the 0.15-0.20 fix_shape range)" rationale: "The plan's fix_shape says alpha 0.15-0.20. 0.18 is the mid of that range — low enough that the gate body remains the visual focal point (the load-bearing element), high enough that the wall actually reads against the #1a1a1a canvas. Lower (0.15) would be invisible at the edge of the gate; higher (0.20) would compete with the body. Phase 3 paints over without changing this geometry."

metrics: duration: ~30 min (5 tasks: ~6 min/task average; G1 fastest at ~3 min; G2 longest at ~10 min due to 7-step shape) completed: 2026-05-09 tests-added: 21 (was 312 → 333) tests-green: 333/333 e2e-assertions-added: 3 (was 16 → 19) e2e-runtime: 1.7s (was 1.6s — 0.1s growth from 3 cheap evaluations + 1 visibility + 1 negation) ci-runtime: ~30s (lint + compile:ink + 333 vitest + validate:assets + build + check:bundle-split) bundle-size: 1.9MB (unchanged — no new dependencies, no new image assets) commits: 5 (one per task; conventional-commit format with fix(02-06,GN): / test(02-06): scopes)

requirements-completed: [GARD-01, AEST-07, UX-01]

Phase 2 Plan 06: UAT Gap Closure (G1–G4) Summary

Closed the 4 first-impression UX gaps that the 2026-05-09 live UAT walkthrough surfaced — the dark canvas no longer floats in a white viewport (G1), a first-time player sees a single bible-voice instructional line after Begin dismisses (G2), the 4×4 tile grid reads as legible interactive surfaces (G3), and the gate has structural wall context instead of floating as a stray gray rectangle (G4). All fixes use Phaser primitives or one CSS file; Phase 3 watercolor deferral preserved.

Tasks Executed

#	Gap	Severity	Files	Commit	Tests
1	G1 — white halo	BLOCKING	src/index.css, src/main.tsx, src/index.css.test.ts	f52de0b	6 file-read smoke
2	G2 — no first-run prompt	BLOCKING	content/seasons/01-soil/ui-strings.yaml, src/content/schemas/ui-strings.ts, src/store/session-slice.ts, src/ui/first-run/{FirstRunHint.tsx, FirstRunHint.test.tsx, index.ts}, src/ui/index.ts, src/App.tsx	c46fc75	6 behavioral
3	G3 — dim tile grid	HIGH	src/render/garden/tile-renderer.ts, src/render/garden/tile-renderer.test.ts	ab48c7e	5 phaser-mocked
4	G4 — floating gate	MEDIUM	src/render/garden/gate-renderer.ts, src/render/garden/gate-renderer.test.ts	88adc4f	4 phaser-mocked
5	Integration	—	tests/e2e/season1-loop.spec.ts	47b5b8d	3 e2e assertions

Hint Copy Chosen

Begin where the soil is bare.

This is the plan's #1 ranked candidate (recommended). Rationale documented in decision 02-06-D1: bible voice (warm + specific + contemplative), echoes the BeginScreen CTA without redundancy, intermittent construction (one beat, no follow-on). The candidate was committed unchanged; no deviation from the plan's recommendation.

Test & Gate Results

• Vitest: 312 → 333 (+21 new cases) — 333/333 green.
• Playwright e2e: 16 → 19 assertions (+3 gap-closure) — 1.6s → 1.7s runtime; 1 passed in 4.7s end-to-end.
• npm run ci: Exit 0 (lint + compile:ink + 333 vitest + validate:assets + build + check:bundle-split).
• npm run test:e2e: Exit 0 (Playwright PIPE-07 with all 3 new assertions green).
• Bundle size: 1.9MB unchanged — no new dependencies, no new image assets.
• V1Payload: Unchanged — firstRunHintDismissed is session-state only; migrations[2] does NOT exist; no migrations.ts edits.

Constraint Compliance Confirmation

Constraint	Verification	Status
No painted assets (Phase 3 watercolor deferral)	git diff main~5 HEAD -- '*.png' '*.jpg' '*.webp' is empty	✓
No new npm dependencies	git diff main~5 HEAD -- package.json package-lock.json is empty	✓
firstRunHintDismissed is session-state, not save-state	grep -c firstRunHintDismissed src/save/migrations.ts = 0	✓
No migrations[2] entry	grep -E 'migrations\[2\]\s*=' src/save/migrations.ts returns no match	✓
Hint copy externalized (not hardcoded)	grep -L "Begin where the soil is bare|The soil is waiting|Click a tile to plant" src/ui/first-run/FirstRunHint.tsx matches the file (i.e. the candidate strings do NOT appear in the component)	✓
UiStringsSchema extended for first_run_hint	grep -E 'first_run_hint:\s*z\.string\(\)' src/content/schemas/ui-strings.ts matches	✓
Tile outline brightened to 0x5a5a60 / 0x7a7a82	tile-renderer.ts exports OUTLINE_COLOR=0x5a5a60 + OUTLINE_HOVER=0x7a7a82 (old hex literals appear ONLY in comment annotations documenting the change, not in active code paths)	✓
Wall band alpha in 0.15-0.20 range	gate-renderer.ts exports WALL_BAND_ALPHA=0.18	✓
Wall band height = canvas height	gate-renderer.ts exports WALL_BAND_HEIGHT=768	✓
Sim purity preserved (no edits in src/sim/**)	git diff main~5 HEAD -- 'src/sim/**' is empty	✓
No motion-only affordances	Tile hover is pointer-driven steady-state (color + alpha swap, no tweens); wall band is steady-state alpha, no pulse	✓

Gap Closure Evidence (vs 02-VERIFICATION.md frontmatter gaps: block)

Gap	Fix verification
G1 white halo	src/index.css exists with the 6 required rules (body bg #1a1a1a, color #e8e0d0, margin 0, min-height 100vh, serif, #game-container flex). src/main.tsx imports it (line 4). Playwright Assertion A confirms document.body.backgroundColor === 'rgb(26, 26, 26)' from frame one in real Chromium.
G2 no first-run prompt	src/ui/first-run/FirstRunHint.tsx exists; mounted in App.tsx between BeginScreen and SeedPicker. content/seasons/01-soil/ui-strings.yaml carries first_run_hint: "Begin where the soil is bare.". src/store/session-slice.ts carries firstRunHintDismissed + dismissFirstRunHint. src/content/schemas/ui-strings.ts extended with first_run_hint: z.string().min(1). Playwright Assertion B confirms the hint is visible after Begin click; Assertion C confirms it auto-dismisses after the first plantSeed lands. 6 unit tests pin behavior.
G3 dim tile grid	src/render/garden/tile-renderer.ts exports OUTLINE_COLOR=0x5a5a60 (was 0x4d4d52) + OUTLINE_HOVER=0x7a7a82 (was 0x6e6e75) + HOVER_FILL_ALPHA=0.06 (new). 5 unit tests pin the constants and the pointerover behavior via Phaser-Scene-mock.
G4 floating gate	src/render/garden/gate-renderer.ts exports WALL_BAND_X=880 + WALL_BAND_HEIGHT=768 + WALL_BAND_ALPHA=0.18 + WALL_BAND_COLOR=0x6e6e75 + WALL_BAND_WIDTH=44. drawGate adds the wall as the first rectangle (z-order: behind body / glow / hit). GateGameObjects exposes the new wall handle. 4 unit tests pin constants in fix_shape range + first-rectangle geometry + 4-rectangle count + wall handle exposure.

Deviations from Plan

None — plan executed exactly as written.

The plan's 5 tasks landed in order with no Rule 1-4 deviations triggered. The plan's anticipated risks were all addressed by the plan's own structure:

• Phaser 4 / happy-dom incompatibility (G3 + G4 tests) — plan called out via SeedPicker analog reference; Phaser-mock pattern (vi.mock('phaser', () => ({ default: {} }))) landed cleanly first try.
• Schema-strip mode silently dropping unknown keys (G2 plan Step 2) — plan called out as MANDATORY; schema edit landed first try, content/loader.test.ts continued green.
• Garden.ts integration breakage from additive GateGameObjects.wall field — plan called out as risk; verified by reading Garden.ts line 110 (this.gate = drawGate(this)) which stores the whole returned object so the additive field is structurally safe; npm run ci confirmed end-to-end.

Auth Gates

None — the plan introduces no auth surfaces; all 5 tasks ran fully autonomously.

Decisions Made

(Captured in frontmatter decisions: block above — 02-06-D1 through 02-06-D5.)

Handoff to Verifier

The 4 gap entries in .planning/phases/02-season-1-vertical-slice-soil/02-VERIFICATION.md frontmatter gaps: block are structurally closed. The verifier (gsd-verifier) consumes this SUMMARY + re-runs verification to flip status from gaps_found → verified.

Out of scope for this plan (carried forward):

• 6 HUMAN-UAT.md tone items (Lura voice in the .ink files, letter cadence, Begin tonal feel, ≥5min absence flow, gate visual indicator + LuraDialogue overlay flow). These are inherently subjective and remain pending. They are addressed by the user's tone-review workflow at the next merge / playtest, not by code.
• 3 INEFFECTIVE_DYNAMIC_IMPORT build warnings (inherited from Plan 02-02's eager-corpus + lazy-glob co-existence). Phase 4+ resolves these when consumers move to lazy-only.
• gray-matter package.json cleanup (tracked in .planning/phases/02-season-1-vertical-slice-soil/deferred-items.md).

REQ-IDs reinforced (not flipped — those were already structurally PASS in 02-VERIFICATION.md):

• GARD-01 (supplemental — first-frame legibility of the planting affordance)
• AEST-07 (supplemental — tonal coherence between body and canvas; Begin dismissal lands on a guided rather than empty surface)
• UX-01 (supplemental — first-run prompt presence honors the A-Dark-Room rule the bible cites)

The Phase-2 vertical slice that "could plausibly ship as a free standalone Season-1 prologue" now actually feels like one to a brand-new player on frame one.

Self-Check: PASSED

All claimed files exist:

• src/index.css ✓
• src/index.css.test.ts ✓
• src/ui/first-run/FirstRunHint.tsx ✓
• src/ui/first-run/FirstRunHint.test.tsx ✓
• src/ui/first-run/index.ts ✓
• src/render/garden/tile-renderer.test.ts ✓
• src/render/garden/gate-renderer.test.ts ✓

All claimed commits exist (verified via git log --oneline -8):

• f52de0b fix(02-06,G1): add src/index.css and import from main.tsx ✓
• c46fc75 fix(02-06,G2): first-run hint after Begin ✓
• ab48c7e fix(02-06,G3): brighten tile outline and hover state ✓
• 88adc4f fix(02-06,G4): add wall band primitive in gate-renderer ✓
• 47b5b8d test(02-06): playwright e2e assertions for G1+G2 ✓

Final gates:

• npm run ci: exit 0, 333/333 vitest green ✓
• npm run test:e2e: exit 0, 1 passed in 4.7s ✓
• No new npm deps: ✓
• V1Payload unchanged: ✓
• No painted assets: ✓