# Phase 2: Season 1 Vertical Slice (Soil) - Research

**Researched:** 2026-05-09
**Domain:** Browser narrative idle game vertical slice (Phaser 4 canvas + React 19 DOM overlay + pure-sim core + Ink narrative + extended IndexedDB save)
**Confidence:** HIGH on stack/architecture (entire stack already locked + scaffolded in Phase 1, code-surface verified file-by-file). HIGH on tick scheduler / BigQty / Zustand-bridge patterns (Phaser 4's React EventBus pattern is the documented integration; idle-game tick-scheduler shape is canonical per `.planning/research/ARCHITECTURE.md`). MEDIUM on Ink↔Zustand bridge specifics (inkjs API verified in installed module; integration shape is ours to design). MEDIUM on Playwright fast-forward strategy (multiple viable mechanisms; the choice is partly ergonomic).

## Summary

Phase 2 is a vertical slice on top of an already-laid foundation. Phase 1 shipped all the retrofit-hostile infrastructure: the save layer (IndexedDB + LocalStorage + CRC-32 + lz-string + Base64 + migration chain), the Vite-native content pipeline (Markdown+frontmatter / YAML, Zod-validated), the ESLint firewall (sim cannot import render or ui — `eslint-plugin-boundaries` flat config in `eslint.config.js`), the Phaser 4 + React 19 + Vite + TypeScript scaffold (`src/game/main.ts`, `src/PhaserGame.tsx`, `src/App.tsx`), the Vitest + Playwright test rig, the asset provenance gate, the doctrine docs, and `npm run ci` as the gate. Phase 2 lands the three deferred "day-one of feature code" foundations in a single phase (`BigQty`, the Zustand 5 store, the tick scheduler), then builds the vertical slice on top: 4×4 garden, 2–3 plant types, click+inline seed picker, sprout→mature→ready growth, harvest yields exactly one fragment, full-screen Memory Journal, three Ink-authored Lura gate visits gated on 1st/4th/8th harvest, authored Ink letter-from-the-garden, save-management Settings, Playwright e2e proving the full loop end-to-end.

The phase's load-bearing technical decisions are: (1) the **tick scheduler** is the only owner of wall-clock access — sim modules stay pure, time is injected, negative deltas refused, single offline catch-up clamped to 24h, with the Phaser update loop driving the scheduler from `src/game/scenes/`; (2) the **BigQty** wrapper around `break_eternity.js` lands in `src/sim/numbers/` and is the type all economic values flow through, even though Season 1's actual numbers never need it (per CLAUDE.md "from day one of feature code" + Pitfall 7); (3) the **Phaser↔React bridge** uses Phaser 4's official template `EventBus` pattern (a `Phaser.Events.EventEmitter` instance accessible to both worlds) plus a Zustand 5 vanilla `createStore` — the sim writes to the store via a slim adapter (sim cannot import `src/store/` directly, since the store imports from `src/ui/` selectors), and React reads from it via hooks; (4) the **save-schema extension** updates `V1Payload` in-place per CONTEXT D-34 — Phase 1's v1 has shipped no production saves, so adding fields is type-extension, not a `migrate_v1_to_v2`, which keeps `migrations[1]`'s synthetic v0→v1 demo green; (5) the **fragment selector** is a pure function in `src/sim/memory/` taking `(state, currentSeason, gardenContext, fragmentPool, seed) → fragmentId`, gating on Season + plant type + harvest count and tracking exhaustion via the existing `harvestedFragmentIds` array; (6) **Ink integration** uses `inklecate` (installed) compiled at build via an npm script that emits `*.ink.json` into `src/content/compiled-ink/`, with `inkjs` (installed, v2.4.0) loading the JSON at runtime; Lura's branches read game state by setting Ink variables from Zustand snapshots before `Continue()` is called.

**Primary recommendation:** Plan Phase 2 as **5 vertical-slice plans** delivered in 3 waves: Wave 0 lands the three foundations (BigQty + Zustand store + tick scheduler) as a single non-feature plan that unblocks everything; Wave 1 lands two parallel vertical slices (the planting-and-growth slice + the journal-and-fragments slice); Wave 2 lands two more parallel slices (Lura gate visits + the offline-letter loop) and the Playwright e2e smoke. Each Wave-1+ plan must pass `npm run ci` standalone.

## Architectural Responsibility Map

Each capability of the Phase 2 vertical slice is owned by a primary architectural tier, with the firewall enforced by `eslint.config.js`. Cross-tier communication goes through the Zustand store and the Phaser EventBus.

| Capability | Primary Tier | Secondary Tier | Rationale |
|------------|-------------|----------------|-----------|
| Garden tile state (16 tiles, plant data, plantedAtTick) | `src/sim/garden/` | — | Pure data; sim mutates; rendering reads via store. |
| Plant growth state machine (sprout → mature → ready) | `src/sim/garden/` | — | Deterministic from `(plantedAtTick, currentTick, plantType.duration)`. No DOM. |
| Tick scheduler / monotonic clock | `src/sim/scheduler/` | `src/game/scenes/` (drives via Phaser update) | Only owner of wall-clock. Sim's `simulate(state, dtTicks)` is pure; scheduler injects time. |
| Offline catch-up (24h cap, refuse negative dt) | `src/sim/scheduler/` | — | Pure function over saved state + delta. Fires `silent: true` to suppress UI side effects. |
| BigQty wrapper around break_eternity.js | `src/sim/numbers/` | — | Pure math; serialization helpers; no DOM. |
| Fragment selector (deterministic, gating, no-dup) | `src/sim/memory/` | — | Pure function over `(state, fragments, seed)`. |
| Lura beat gating (1st/4th/8th harvest count) | `src/sim/narrative/` | — | Reads sim state's harvest count; enqueues `beatId` events. Does NOT load Ink content. |
| Auto-harvest during offline (D-10) | `src/sim/garden/` | — | Same simulate loop, with auto-harvest branch when player is absent (state flag). |
| Garden tile rendering (Phaser primitives) | `src/render/garden/` | — | Empty-tile outline + plant stage shape + ready-pulse via Phaser primitives. No DOM. |
| Begin screen (gesture gate + AudioContext.resume) | `src/ui/begin/` | — | Full-screen React DOM modal; first-run only per D-22; tap calls `audioContext.resume()`. |
| Memory Journal (full-screen modal) | `src/ui/journal/` | — | DOM per MEMR-05 (selectable / copy-pasteable); reveals after 1st harvest per D-23. |
| Lura dialogue overlay | `src/ui/dialogue/` | `src/sim/narrative/` (gates), Ink runtime (renders) | DOM-rendered per D-15 (selectable text from day one). |
| Letter-from-the-garden (full-screen modal) | `src/ui/letter/` | Ink runtime (templates) | DOM full-screen per D-20 (≥5min absence threshold). |
| Settings (Export/Import/Restore) | `src/ui/settings/` | `src/save/` (already shipped) | DOM modal; corner icon + hotkey per D-29. |
| Inline seed picker (popover over clicked tile) | `src/ui/garden/` | `src/render/garden/` (provides tile screen position) | DOM popover positioned over Phaser canvas via tile→screen coord conversion. |
| Persistence-result toast (D-30) | `src/ui/toast/` | `src/save/persist.ts` (data) | One-time soft toast in voice on first save if denied. |
| Save persistence (already shipped) | `src/save/` | — | Phase 1's complete layer. Phase 2 imports only via `src/save/index.ts`. |
| Save lifecycle hooks (visibilitychange, beforeunload, Season transition) | `src/save/` (existing) + `src/PhaserGame.tsx` (subscribes) | — | Browser event listeners live with the React shell; serialize calls go through the save barrel. |
| Content loader (already shipped) | `src/content/` | — | Phase 2 drops `/content/seasons/01-soil/*.{md,yaml}` and `/content/dialogue/season1/*.ink`. |
| Ink runtime bridge | `src/sim/narrative/` (gates only) + `src/ui/dialogue/` (rendering) | — | inkjs `Story` instances live in UI tier; sim never imports inkjs. |
| Phaser ↔ React EventBus | `src/PhaserGame.tsx` (mounts) + scenes + UI | Zustand store (alternate channel) | Per Phaser 4 official template. Used for one-shot scene-ready / scene-event signals; persistent state goes through Zustand. |

**Architectural firewall reminder (CORE-10, ESLint-enforced):** `src/sim/` cannot import from `src/render/` or `src/ui/`. The store sits in `src/store/` and is allowed both directions (sim writes; UI reads). The Phaser scene (`src/game/`) reads from the store and writes commands; it does NOT import sim modules directly — it dispatches commands via the store, and the scheduler picks them up.

## User Constraints (from CONTEXT.md)

### Locked Decisions

(Copied verbatim from `02-CONTEXT.md`. Numbering preserved.)

**Garden Geometry & Input**
- **D-01:** Garden is a **4×4 fixed grid (16 tiles)**.
- **D-02:** Seed placement is **click-empty-tile → inline seed picker** (small popover anchored to the clicked tile, listing currently-unlocked plant types; single tap commits). No persistent seed sidebar.
- **D-03:** **2–3 plant types** ship in Season 1. Each plant has its own growth duration and fragment pool.
- **D-04:** **Infinite seed supply from start** — anti-FOMO. Meaningful constraint is *time*, not seed inventory.
- **D-05:** **First plant available from start; remaining 1–2 unlock by fragment-count thresholds** harvested.
- **D-06:** Empty tile look = **faint outlined tile + subtle hover state** (Phaser primitive draw).
- **D-07:** Post-harvest tile **returns immediately to empty** with a brief acknowledgement beat.

**Time Density (Growth + Offline)**
- **D-08:** First-plant active-play growth = **~2–5 minutes** (sprout → ready).
- **D-09:** **Per-plant durations vary** (short / medium / longer) within the ~2–5min band.
- **D-10:** **Auto-harvest during offline; manual in active play.** Auto-harvested plants queue into the offline event log; the *letter* narrates them.
- **D-11:** **24h offline cap is surfaced silently in the letter's voice** — no numeric "you were gone for 28 hours" copy.

**Lura's Season 1 Arc**
- **D-12:** Lura is present as **discrete visits at the gate** — not a persistent chat thread.
- **D-13:** **3 beats in Season 1: arrival · mid · farewell.**
- **D-14:** Beats gated by fragment-count thresholds — beat 1 after **1st** harvest; mid after **4th**; farewell after **8th**. Counts come from sim ticks, not wall time (STRY-10).
- **D-15:** Beat-fire UX = **subtle gate indicator + player-initiated visit.** Conversation opens as a **React DOM dialogue overlay**.
- **D-16:** All Lura dialogue is authored in **Ink (`.ink`) under `/content/dialogue/`**.

**Letter-from-the-Garden (UX-02)**
- **D-17:** Letter composed from **authored skeleton + templated insertions**. Hand-authored Ink passages with named variable slots; specifics flow in from the offline event log.
- **D-18:** Letter authoring lives in **Ink (`.ink` files in `/content/dialogue/`)**.
- **D-19:** Save schema gains a small **`offlineEvents`** block: per-plant counts of plants bloomed, list of auto-harvested fragment IDs, flag for any newly-unlocked Lura beat queued. Phase-2 schema *extension*, not a migration.
- **D-20:** Letter triggers when **absence ≥ 5 minutes**. Below threshold, no letter. Full-screen DOM overlay; one tap dismisses.

**Begin Screen (AEST-07 + UX-01)**
- **D-21:** **Tasteful placeholder; Phase 3 paints.** Typographic title + a single "Begin" affordance, calls `AudioContext.resume()` on tap.
- **D-22:** **Begin screen shows on first run only.** Subsequent loads skip directly to the live garden; AudioContext enables on the first interaction. "First run" = no save exists.

**Memory Journal (MEMR-04, MEMR-05)**
- **D-23:** Journal affordance **reveals after the player's first harvest**, then is persistent.
- **D-24:** Journal layout = **full-screen modal overlay**, fragments grouped by Season; back affordance returns to garden. DOM-rendered per MEMR-05.
- **D-25:** Newly harvested fragments (in active play) **surface immediately in a full-text reveal modal**; dismissing files into the journal. Offline auto-harvested fragments are surfaced via the *letter* and re-readable in the journal.

**Visual Placeholders (Phase 2 only)**
- **D-26:** Plants render as **simple Phaser-primitive shapes per growth stage, tinted by plant type**. No PNG asset work in Phase 2.
- **D-27:** Ready-state cue = **subtle glow / pulse on ready tiles**.

**Phase 2 Settings UI Scope**
- **D-28:** Settings menu in Phase 2 ships **save-management surfaces only** — Export, Import, Restore. Persistence-result toast folds in.
- **D-29:** Settings access = **small icon in a corner of the main view + keyboard shortcut**. Persistent.
- **D-30:** `navigator.storage.persist()` outcome surfaced as a **one-time soft toast in voice on first save if denied; nothing if granted**.

**Foundations That Must Land in Phase 2 (per CLAUDE.md)**
- **D-31:** **`BigQty` wrapper around `break_eternity.js`** is Phase 2's first task. Lands in `src/sim/numbers/`.
- **D-32:** **Zustand 5 store** is the bridge between Phaser scene and React UI. Sim writes to the store; React reads. Sim never imports the store directly.
- **D-33:** **Tick scheduler / monotonic clock** is the *only* owner of wall-clock access. Tick rate is Claude's discretion (likely 4–10Hz). Negative deltas refused; offline catch-up clamps to 24h.
- **D-34:** **Save extension for Phase 2** updates `V1Payload` (in `src/save/migrations.ts`) — Phase-2-scope schema *extension* (not a v1→v2 migration).

### Claude's Discretion

- Specific growth-duration values per plant type within the 2–5min band (D-08 / D-09).
- Exact fragment-count threshold values for plant-type unlocks (D-05) and Lura beats (1st/4th/8th may shift ±1–2 during playtest).
- Form of the post-harvest acknowledgement beat (D-07).
- Form of the gate indicator when Lura's beat unlocks (D-15).
- Tick rate / sim cadence (likely 4–10Hz).
- Internal shape of the Zustand store slices.
- Internal shape of the scene/state machine inside Phaser (Boot → Preloader → Garden, or simpler).
- Specific copy of the Begin screen, the persistence-denied toast, and the post-harvest acknowledgement (all reviewed by user).
- Choice of e2e test fast-forward mechanism (hidden dev hotkey vs URL flag vs sim-clock injection).
- Specific copy of the Memory Journal "no fragments yet" empty state.
- Whether the offline letter's slot vocabulary is finalized in this phase or expanded incrementally.

### Deferred Ideas (OUT OF SCOPE)

- Hybrid Lura presence (gate visits + ambient text-message drip) — rejected for Phase 2 in favor of pure discrete gate visits (D-12). May be reconsidered Phase 4+.
- Plant-type unlocks tied to specific authored fragments — rejected for Phase 2 in favor of fragment-count thresholds (D-05). Phase 4+ may explore narrative-keyed unlocks.
- Fully procedural letter from event-log templates — rejected (D-17). Phase 2 commits to authored skeleton + slots.
- Audio sliders (UX-04), keyboard nav (UX-06), browser-zoom guarantees (UX-07), color-redundant icons (UX-08), tab-title bloom (UX-09), Lura-not-numbers UX (UX-12) — all confirmed for **Phase 8**.
- Visual regression for asset library (PIPE-04) — Phase 8.
- Roothold prestige currency, Season transitions, die-off, finite-ceiling enforcement — Phase 4. Phase 2 plants nothing in the save schema for Roothold.
- Cross-pollination, Memory Storms, place-memory vignettes, ecosystem planting, the Below, the Loom, the Archivist, Lura's full multi-Season arc, the Nameless Man — Phase 4–7.
- Watercolor post-process, painted plants, painted Begin screen, solo cello + ambient buses + crossfade, reduced-motion toggle (UX-05) — Phase 3.
- Real production-volume AI assets + locked north-star reference set — Phase 5 follow-up. Phase 2 ships zero AI-generated assets (D-26 = primitive shapes).
- Real `migrate_v1_to_v2` — Phase 4. Phase 2 only extends `V1Payload` shape (D-34).
- Per-plant duration variance via dynamic content authoring — out of scope.
- Compost yielding seeds back — rejected (D-04 = infinite seeds).
- Persistent Settings element on Begin screen — rejected (D-29).

## Phase Requirements

| ID | Description | Research Support |
|----|-------------|------------------|
| CORE-02 | Deterministic, fixed-timestep sim advancing by elapsed real time. | Tick Scheduler section + Pattern: Fixed-Timestep Accumulator. |
| CORE-03 | Closed-and-returned garden progresses by elapsed time, capped at 24h. | Tick Scheduler + Offline Catch-up section. |
| CORE-11 | Sim refuses negative deltas + caps any single offline progression at 24h. | Tick Scheduler boundary checks + tests. |
| GARD-01 | Plant a seed into an unoccupied tile. | Garden Sim section + Inline Seed Picker section + sim/garden module. |
| GARD-02 | Plant has visible growth state, updates from save data on load, advances over time. | Plant State Machine section + render/garden + tick scheduler. |
| GARD-03 | Harvest mature plant → exactly one fragment; tile empties. | Harvest Logic section + Fragment Selector section. |
| GARD-04 | Compost an immature plant → tonal beat acknowledging the choice to let go. | Compost Logic section + UI overlay. |
| MEMR-01 | Each harvest yields exactly one memory fragment from authored pool gated by Season + progression. | Fragment Selector section. |
| MEMR-02 | Fragments authored in plain text (Markdown + frontmatter) under `/content/`, compiled per-Season at build time. | Phase 1 already shipped; Phase 2 drops Season 1 files. |
| MEMR-03 | Stable string IDs (`season1.soil.first-bloom`). | FragmentSchema regex already enforces; Season 1 IDs follow convention. |
| MEMR-04 | Memory Journal (React DOM panel) listing every collected fragment, organized by Season. | Memory Journal section. |
| MEMR-05 | Player can read any collected fragment in full, selectable + copy-pasteable. | Memory Journal section (DOM, not canvas). |
| MEMR-06 | Deterministic selector respecting authored gating + no-duplicates within playthrough until pool exhausted. | Fragment Selector section. |
| STRY-01 | Lura appears at gate during Season 1 with text-message-cadence dialogue authored in Ink. | Lura's Season 1 Arc section + Ink Integration section. |
| STRY-06 | All authored dialogue uses Ink (`.ink` → JSON for runtime via inkjs). | Ink Compilation Pipeline section. |
| STRY-07 | Keeper has no name, no backstory, no dialogue beyond final binary choice (Phase 7). | Vacuously satisfied — Phase 2 authors no Keeper-spoken lines. |
| STRY-10 | Story progression gates on tick count, not wall time. | Lura Beat Gating section (counts harvest events = sim ticks). |
| AEST-07 | First screen is "Tend the garden / Begin" gesture gate that calls `AudioContext.resume()`. | Begin Screen section + AudioContext Bootstrap section. |
| UX-01 | Single, clean "Begin" screen; UI grows as player progresses (A Dark Room rule). | Begin Screen section + Memory Journal reveal logic. |
| UX-02 | Returning-player letter from the garden — written in voice, not a stat dump. | Letter-from-the-Garden section. |
| UX-10 | Save on `visibilitychange` to hidden, on `beforeunload`, on Season transitions. | Save Lifecycle Hooks section. |
| UX-11 | Numbers display in human-readable formats (1.2K, 4.5M, scientific past threshold). | BigQty section (`format()` method). |
| PIPE-02 | Player loads only current Season at runtime; future Seasons not in initial bundle. | Per-Season Lazy Loading section. |
| PIPE-07 | E2E smoke (Playwright) loads game, plants seed, harvests fragment, verifies persistence across reload. | Playwright E2E section + Sim-Clock Injection section. |

## Standard Stack

### Core (already locked + installed; verified against `package.json` 2026-05-09)

| Library | Version | Purpose | Why Standard |
|---------|---------|---------|--------------|
| `phaser` | `^4.1.0` (installed: 4.1.0) [VERIFIED: package.json + npm view] | 2D game framework: scenes, input, rendering, time, tweens, events. Phase 2 uses scene tree, input system, basic graphics primitives, ready-pulse via tween. | Already locked in Phase 1; vertical-slice owner. |
| `react` / `react-dom` | `^19.2.6` (installed: 19.2.6) [VERIFIED] | DOM overlay shell: Begin, Journal, Letter, Lura dialogue, Settings, seed picker. | Locked Phase 1. |
| `zustand` | `^5.0.0` (npm view: 5.0.13 — needs install in Phase 2) [VERIFIED: npm registry] | Phaser↔React state bridge. | Locked Phase 1; install is Phase 2's first task per D-32. |
| `break_eternity.js` | `^2.1.3` (npm view: 2.1.3 — needs install) [VERIFIED: npm registry] | Big-number library wrapped by `BigQty`. | Locked Phase 1; install is Phase 2's first task per D-31. |
| `inkjs` | `^2.4.0` (installed: 2.4.0) [VERIFIED: package.json] | Runtime for compiled Ink stories. ESM imports `Story` from `inkjs` per `node_modules/inkjs/ink.d.mts`. | Locked Phase 1; runtime usage begins Phase 2. |
| `inklecate` (devDep) | `^1.8.1` (installed: 1.8.1) [VERIFIED: package.json] | Build-time Ink compiler. CLI invoked from `npm run compile:ink`. | Locked Phase 1; first real usage Phase 2. |
| `idb` | `^8.0.3` (installed) [VERIFIED] | Already wired by `src/save/`. | — |
| `lz-string` | `^1.5.0` (installed) [VERIFIED] | Already wired by `src/save/codec.ts`. | — |
| `crc-32` | `^1.2.2` (installed) [VERIFIED] | Already wired by `src/save/checksum.ts`. | — |
| `zod` | `^4.4.3` (installed) [VERIFIED] | Already used by `src/content/schemas/` and `src/save/envelope.ts`. Phase 2 uses for `OfflineEvent` schema in V1Payload extension. | — |
| `gray-matter` | `^4.0.3` (installed) [VERIFIED] | Already wired in `src/content/loader.ts` for Markdown frontmatter. | — |
| `yaml` | `^2.8.4` (installed) [VERIFIED] | Already wired. | — |

### Supporting (already in devDeps)

| Library | Version | Purpose | When to Use |
|---------|---------|---------|-------------|
| `vitest` | `^4.1.5` [VERIFIED: package.json] | Unit + integration tests for sim modules, BigQty, scheduler, fragment selector, save migrations, Zustand slices. | All Phase 2 plans add tests. |
| `@playwright/test` | `^1.59.1` [VERIFIED] | E2E smoke (PIPE-07). | Wave 2 plan. |
| `happy-dom` | `^20.9.0` [VERIFIED] | Vitest DOM env (already configured in `vitest.config.ts`). | UI component tests. |
| `fake-indexeddb` | `^6.2.5` [VERIFIED] | Used by `src/save/db.test.ts`; Phase 2's Vitest tests for the extended save flow continue to use it. | All save-touching unit tests. |

### Howler.js — Phase 2 Stub Strategy

Howler.js is the locked audio library per `.planning/research/STACK.md` and CLAUDE.md, but Phase 3 owns audio bus setup. **Phase 2 does NOT install or use Howler.** It still must satisfy AEST-07's "calls `AudioContext.resume()`". The minimum-viable approach: Phase 2's Begin screen creates a fresh `AudioContext` (or accesses an existing one if Phase 3 has shipped) and calls `.resume()`. No buffers are loaded, no sounds are played. Phase 3 will rewire the Begin screen to also boot Howler's master gain.

Concretely: `src/ui/begin/use-audio-bootstrap.ts` exports `bootstrapAudioContext()` returning `Promise<AudioContext | null>`. The function:

1. Lazily creates `new AudioContext()` (with `webkitAudioContext` fallback for Safari).
2. Calls `audioContext.resume()` and awaits it.
3. Returns the context (Phase 3 will retrieve it via the Zustand store and feed Howler).
4. On any error or unsupported browser, returns `null` and logs once. Phase 2's loop does not depend on audio working.

[CITED: developer.chrome.com/blog/web-audio-autoplay] — Web Audio gesture requirement and `resume()` pattern.

### Installation (additions Phase 2 makes)

```bash
npm install zustand@^5.0.0
npm install break_eternity.js@^2.1.3
```

That is the entire dependency-installation surface for Phase 2. Everything else is already on disk from Phase 1.

**Version verification (2026-05-09):**

- `npm view zustand version` → `5.0.13` [VERIFIED 2026-05-09]
- `npm view break_eternity.js version` → `2.1.3` [VERIFIED 2026-05-09]
- `npm view phaser version` → `4.1.0` (already installed) [VERIFIED 2026-05-09]
- `npm view inkjs version` → `2.4.0` (already installed) [VERIFIED 2026-05-09]
- `npm view inklecate version` → `1.8.1` (already installed) [VERIFIED 2026-05-09]
- `npm view howler version` → `2.2.4` (NOT installed in Phase 2; deferred to Phase 3) [VERIFIED 2026-05-09]

### Alternatives Considered (and rejected for Phase 2)

| Instead of | Could Use | Tradeoff |
|------------|-----------|----------|
| Phaser 4 EventBus + Zustand | Mitt-only event bus | Mitt is a fine event emitter, but Phaser's official template already provides an `EventBus` (Phaser.Events.EventEmitter) — using it removes a dependency and matches the documented Phaser+React pattern. Persistent state still needs Zustand; events alone do not survive reloads. |
| Zustand 5 react binding | Vanilla `createStore` only | Vanilla works fine for the sim side, but the React side needs the hook-style binding (`useStore`) for clean re-renders. Use Zustand 5's pattern: `createStore` from `zustand/vanilla` for the underlying store + `useStore` from `zustand` for React subscriptions. [CITED: zustand.docs.pmnd.rs/reference/apis/create-store] |
| `BigQty` as direct re-export of `Decimal` | Hand-roll wrapper class | The wrapper is non-negotiable per CLAUDE.md ("Never raw `Decimal` values in app code"). Re-export-only would let raw Decimals leak into call sites. |
| Inline R3F-style React-Phaser bridge | Phaser 4 official EventBus + `<canvas ref>` | The official `phaser/template-react-ts` shape is what `src/PhaserGame.tsx` already implements. Replacing this would touch Phase-1 code unnecessarily. |
| 60Hz sim tick | 4–10Hz sim tick | A 4–10Hz sim tick is the canonical idle-game rate per `.planning/research/ARCHITECTURE.md` Pattern 2 (5Hz example) and gives `24h × 3600 × 5 = 432,000` ticks per offline cap, comfortably catchable in <100ms. 60Hz would need 5.18M ticks for the same offline window — pointless cost when growth resolution is in minutes. |
| Phaser scene tree Boot → Preloader → Garden | Single Garden scene | Phase 2 has near-zero asset loading (no PNG plants — D-26 says primitives only). A single `Garden` scene plus a tiny `Boot` is enough; Preloader becomes meaningful in Phase 3 when watercolor textures arrive. |

## Architecture Patterns

### System Architecture Diagram

```
                            BROWSER TAB
┌─────────────────────────────────────────────────────────────────────┐
│  React 19 DOM Overlay (z-index above canvas)                        │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐   │
│  │  Begin   │ │  Journal │ │  Letter  │ │  Dialogue│ │ Settings │   │
│  │  Screen  │ │  (modal) │ │  (modal) │ │ (overlay)│ │  (modal) │   │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘   │
│       │            │            │            │            │         │
│       │            └────┬───────┴────┬───────┴────┬───────┘         │
│  ┌────┴────────────────┴────┐  ┌─────┴────────────┴─────┐           │
│  │  Inline Seed Picker      │  │  HUD chrome (corner    │           │
│  │  (DOM popover positioned │  │   icons + journal      │           │
│  │   over Phaser tile)      │  │   icon, optional)      │           │
│  └────┬─────────────────────┘  └────────────┬───────────┘           │
│       │                                     │                       │
│       │  read state, dispatch commands      │                       │
│       ↓                                     ↓                       │
│  ┌────────────────────────────────────────────────────┐             │
│  │  Zustand 5 Store (createStore from zustand/vanilla,│             │
│  │  read in React via useStore)                       │             │
│  │  ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌─────────┐  │             │
│  │  │ garden  │ │ memory  │ │ narrative│ │ session │  │             │
│  │  │ slice   │ │ slice   │ │ slice    │ │ slice   │  │             │
│  │  └─────────┘ └─────────┘ └──────────┘ └─────────┘  │             │
│  └─────────┬────────────────────────────────────┬─────┘             │
│            │     command queue (intent only)    │                   │
│            ↓                                    ↑                   │
│  ┌─────────────────────────┐         ┌─────────────────────────┐    │
│  │ Phaser 4 Scene Tree     │         │ Pure Sim (src/sim/)     │    │
│  │ (src/game/, src/render/)│   read  │ ┌──────────────────┐    │    │
│  │ ┌─────────────────┐     │  state  │ │ scheduler        │    │    │
│  │ │ Boot → Garden   │←────┼─────────┼─│ (only owner of   │    │    │
│  │ │ scene           │     │         │ │  wall-clock)     │    │    │
│  │ └─────────────────┘     │         │ └────────┬─────────┘    │    │
│  │   • tile rendering      │         │          │ injects t    │    │
│  │   • plant primitives    │   write │          ↓              │    │
│  │   • ready-pulse tween   │   state │ ┌────────────────┐      │    │
│  │   • pointerdown handler │←────────┼─│ simulate(s,dt) │      │    │
│  │   • Phaser EventBus     │  events │ │  garden.tick   │      │    │
│  │     (scene-ready, etc.) │         │ │  growth.advance│      │    │
│  └─────────────────────────┘         │ │  fragment.sel  │      │    │
│                                      │ │  narrative.gate│      │    │
│  ┌──────────────────────────────────┐│ │  numbers/BigQty│      │    │
│  │ Browser event listeners          ││ └────────────────┘      │    │
│  │  visibilitychange → save         │└──────────┬──────────────┘    │
│  │  beforeunload → save             │           │                   │
│  │  click → AudioContext.resume()   │           │                   │
│  └──────────────────────────────────┘           │                   │
│                                                 │                   │
│  ┌──────────────────────────────────────────────┴──────────────┐    │
│  │  src/save/ (Phase 1, frozen barrel)                         │    │
│  │  wrap/unwrap, snapshot, requestPersistence,                 │    │
│  │  exportToBase64/importFromBase64, openSaveDB,               │    │
│  │  migrate, V1Payload (extended Phase 2)                      │    │
│  └────────────────────────────┬────────────────────────────────┘    │
│                               ↓                                     │
│                ┌──────────────────────────────────┐                 │
│                │  IndexedDB (primary) +           │                 │
│                │  LocalStorage fallback           │                 │
│                │  Stores: saves, save_snapshots   │                 │
│                └──────────────────────────────────┘                 │
│                                                                     │
│  Build time: /content/seasons/01-soil/*.{md,yaml}                   │
│              /content/dialogue/season1/*.ink                        │
│   ── Vite import.meta.glob (per-Season lazy from Phase 2) ──        │
│   ── inklecate compile → src/content/compiled-ink/*.ink.json ──     │
└─────────────────────────────────────────────────────────────────────┘
```

**Data flow summary:**
1. **Boot:** `main.tsx` mounts `App`; `App` mounts `<PhaserGame>`; `PhaserGame.tsx` creates Phaser; Boot scene transitions to Garden scene; Garden scene wires the tick scheduler into its `update()` callback.
2. **Resume from save:** `src/save/index.ts` is read; if a save exists, the envelope is unwrapped, migrated (still v1), and committed to the Zustand store; the scheduler computes elapsed-since-`lastTickAt`, clamps to 24h, runs the catch-up loop, and emits an `offlineEvents` aggregate that triggers the letter overlay if absence ≥ 5min.
3. **First run:** No save → Begin screen mounts; tap calls `AudioContext.resume()` and dismisses the Begin screen; Garden scene activates.
4. **Live tick:** Garden scene's `update(time, delta)` calls `scheduler.tick(now)`. Scheduler accumulates wall-clock `delta`, drains in fixed-size `TICK_MS` chunks, calls `simulate(state, dt, commands)`, applies the result to the Zustand store. Render reads from the store.
5. **Plant a seed:** Player clicks empty tile in Phaser → React seed picker pops up (positioned via tile→screen coord conversion provided by `src/render/garden/`) → click commits → command dispatched into the store → next sim tick the command is drained and applied.
6. **Harvest:** Player clicks ready tile → `harvest` command queued → simulate runs `harvestPlant` → fragment selector picks one fragment id → `harvestedFragmentIds` array gets a new entry → store updates → React renders fragment-reveal modal.
7. **Lura beat:** `narrative.gate` checks `harvestedFragmentIds.length` after each harvest; on count ∈ {1, 4, 8} (config-tunable), enqueues a `pendingLuraBeat: 'arrival'|'mid'|'farewell'` flag; the gate icon glows; player taps gate → React loads compiled `season1/lura-arrival.ink.json` into a fresh inkjs `Story`, sets variables from the store snapshot, drives the dialogue overlay.
8. **Save on visibility hidden / beforeunload:** Listener invokes the save layer's `wrap` + IndexedDB write path. Save is small (<10KB) so synchronous serialization completes well within `beforeunload`'s tight window.

### Recommended Project Structure (Phase 2 additions)

```
src/
├── sim/                            (NEW Phase 2 — was empty firewall dir)
│   ├── numbers/
│   │   ├── big-qty.ts              D-31; wrapper around break_eternity.js
│   │   ├── big-qty.test.ts
│   │   └── format.ts               UX-11 human-readable display (1.2K, 4.5M, …)
│   ├── scheduler/
│   │   ├── clock.ts                D-33; the only owner of Date.now()
│   │   ├── tick.ts                 fixed-timestep accumulator + simulate dispatcher
│   │   ├── catchup.ts              CORE-03/CORE-11; refuse negative dt; clamp 24h
│   │   └── *.test.ts
│   ├── garden/
│   │   ├── types.ts                Tile + PlantInstance + PlantType
│   │   ├── plants.ts               2–3 PlantType definitions (durations, fragmentPool)
│   │   ├── growth.ts               sprout → mature → ready state machine
│   │   ├── commands.ts             plantSeed / harvest / compost (pure)
│   │   ├── auto-harvest.ts         D-10 offline auto-harvest branch
│   │   └── *.test.ts
│   ├── memory/
│   │   ├── selector.ts             MEMR-06 deterministic, gating, no-dup
│   │   ├── selector.test.ts
│   │   └── pool.ts                 reads from src/content/, applies Season + plant gate
│   ├── narrative/
│   │   ├── lura-gate.ts            D-14 1st/4th/8th harvest count → pending beat
│   │   ├── lura-gate.test.ts
│   │   └── beat-queue.ts           store-shape contract for pending Lura beats
│   ├── offline/
│   │   ├── events.ts               OfflineEvent schema (zod) + aggregator
│   │   └── events.test.ts
│   ├── state.ts                    SimState root shape + serialization (matches V1Payload)
│   └── index.ts                    barrel; the application layer imports from here
│
├── store/                          (NEW Phase 2)
│   ├── garden-slice.ts             16 tiles + plant-type unlocks + commands
│   ├── memory-slice.ts             harvested fragment ids + reveal modal state
│   ├── narrative-slice.ts          Lura beat queue + dialogue overlay state
│   ├── session-slice.ts            Begin gate state + persistence-result toast
│   ├── store.ts                    composes slices with createStore from zustand/vanilla
│   ├── selectors.ts                React-friendly selectors for components
│   └── index.ts
│
├── save/                           (FROZEN Phase 1 barrel; Phase 2 only edits migrations.ts)
│   └── migrations.ts               extends V1Payload per D-34
│
├── content/                        (FROZEN Phase 1 barrel; Phase 2 adds Season-1 lazy split)
│   ├── ink-loader.ts               (NEW) runtime loader for compiled-ink JSON
│   ├── compiled-ink/               (GENERATED, gitignored) by `npm run compile:ink`
│   │   └── season1/
│   │       ├── lura-arrival.ink.json
│   │       ├── lura-mid.ink.json
│   │       ├── lura-farewell.ink.json
│   │       └── letter-from-the-garden.ink.json
│   └── (existing Phase 1 modules unchanged)
│
├── render/
│   └── garden/
│       ├── tile-renderer.ts        D-06 outlined tile, hover state
│       ├── plant-renderer.ts       D-26 primitive shapes per growth stage
│       ├── ready-pulse.ts          D-27 alpha cycle / shader pulse
│       ├── gate-renderer.ts        gate visual + indicator on pending Lura beat (D-15)
│       └── tile-coords.ts          tile↔screen coord conversion (used by seed picker)
│
├── ui/
│   ├── begin/
│   │   ├── BeginScreen.tsx         D-21 typographic placeholder
│   │   └── use-audio-bootstrap.ts  AudioContext.resume() on tap
│   ├── journal/
│   │   ├── Journal.tsx             D-24 full-screen modal
│   │   ├── FragmentRevealModal.tsx D-25 active-play harvest reveal
│   │   └── journal-icon.tsx        D-23 reveals after 1st harvest
│   ├── letter/
│   │   ├── Letter.tsx              D-20 full-screen, ≥5min absence
│   │   └── letter-renderer.ts      drives inkjs Story + variable bindings
│   ├── dialogue/
│   │   ├── LuraDialogue.tsx        D-15 React DOM overlay
│   │   ├── ink-renderer.tsx        text-message-cadence drip
│   │   └── ink-runtime.ts          inkjs Story instantiation + variable wiring
│   ├── settings/
│   │   ├── Settings.tsx            D-28 Export/Import/Restore
│   │   └── persistence-toast.tsx   D-30 in-voice soft toast
│   └── garden/
│       └── SeedPicker.tsx          D-02 inline popover positioned over canvas
│
├── game/
│   ├── main.ts                     EXPAND scene list to include Garden
│   ├── event-bus.ts                (NEW) Phaser.Events.EventEmitter singleton (per Phaser 4 template)
│   └── scenes/
│       ├── Boot.ts                 EXPAND: transition to Garden after `MainScene.create`
│       └── Garden.ts               (NEW) the canvas scene; wires tick scheduler + tile input
│
└── PhaserGame.tsx                  EXPAND: subscribe to event-bus, expose audio context, register lifecycle save hooks
```

```
content/
├── seasons/
│   ├── 00-demo/                    REMOVED Phase 2 (per CONTEXT canonical_refs)
│   └── 01-soil/                    NEW
│       ├── fragments.yaml          bulk Season-1 fragments (≥8 to satisfy 8th-harvest threshold)
│       └── fragments/
│           └── *.md                long-form fragments (one-per-file, frontmatter)
└── dialogue/                       NEW (was empty)
    └── season1/
        ├── lura-arrival.ink
        ├── lura-mid.ink
        ├── lura-farewell.ink
        └── letter-from-the-garden.ink
```

```
tests/
└── e2e/                            NEW Phase 2
    └── season1-loop.spec.ts        PIPE-07 smoke
```

### Pattern 1: Tick Scheduler / Monotonic Clock

**What:** A scheduler module in `src/sim/scheduler/` that owns all wall-clock access (`Date.now()` / `performance.now()`), accumulates real-time deltas, drains them in fixed-size `TICK_MS` chunks, and calls `simulate(state, dtTicks, commands) → state'`. It is the single boundary point between wall time and sim time.

**When to use:** Always for the live tick. Same module also handles offline catch-up.

**Recommended tick rate:** 5 Hz (`TICK_MS = 200`). Rationale:
- A 24h offline catch-up = `24 × 3600 × 5 = 432,000` ticks. Even at 1µs per tick, that catches up in ~0.4s — well within "boot to playable".
- Plant growth in the 2–5min band has natural granularity (a 5-min plant ticks 1500 times sprout→ready; plenty of resolution for sprout/mature/ready transitions).
- Render runs at `requestAnimationFrame` (60Hz on most displays); sim runs at 5Hz independently. They're decoupled by design.
- 5Hz matches the example in `.planning/research/ARCHITECTURE.md` Pattern 2 — keeping the documented rate keeps everyone on the same page.

**Example:**

```typescript
// Source: .planning/research/ARCHITECTURE.md Pattern 2 + CONTEXT D-33
// src/sim/scheduler/tick.ts — pure, no I/O. Time is INJECTED.

import type { SimState } from '../state';
import { simulate } from '../simulate';

export const TICK_MS = 200; // 5Hz
export const MAX_OFFLINE_MS = 24 * 3600 * 1000;

export interface TickResult {
  state: SimState;
  ticksApplied: number;
  silent: boolean;
}

/**
 * Drain the accumulator. Called by the Phaser scene's update() loop OR by
 * the catch-up function during boot. Returns the new state and how many
 * ticks were actually applied.
 *
 * REFUSES negative deltas (CORE-11); CLAMPS at MAX_OFFLINE_MS (CORE-03).
 */
export function drainTicks(
  state: SimState,
  accumulatorMs: number,
  silent = false,
): { state: SimState; remainderMs: number; ticksApplied: number } {
  if (accumulatorMs < 0) {
    // System-clock cheat or save-corruption case. Sim refuses to advance.
    // The application layer logs and resets the accumulator.
    return { state, remainderMs: 0, ticksApplied: 0 };
  }
  const cappedMs = Math.min(accumulatorMs, MAX_OFFLINE_MS);
  const ticks = Math.floor(cappedMs / TICK_MS);
  let next = state;
  for (let i = 0; i < ticks; i++) {
    next = simulate(next, TICK_MS, /* commands */ [], { silent });
  }
  return {
    state: next,
    remainderMs: cappedMs - ticks * TICK_MS,
    ticksApplied: ticks,
  };
}
```

```typescript
// src/sim/scheduler/clock.ts — the ONLY allowed Date.now() in the project.

export interface Clock {
  now(): number; // monotonic-enough wall clock in ms
}

/** Production clock. Reads Date.now(). */
export const wallClock: Clock = {
  now: () => Date.now(),
};

/** Test clock. Lets Vitest tests advance time deterministically.
 *  Also used by Playwright's fast-forward URL flag (?devtime=fake). */
export class FakeClock implements Clock {
  private t: number;
  constructor(start = 0) {
    this.t = start;
  }
  now(): number {
    return this.t;
  }
  advance(ms: number): void {
    this.t += ms;
  }
}
```

The Phaser `Garden` scene's `update(_time, _delta)` calls `scheduler.advanceLive(clock.now())` once per frame; the scheduler owns the `lastFrameTime` and the accumulator. Note: Phaser's `time` and `delta` arguments are also wall-derived, but we ignore them and call `clock.now()` ourselves so a `FakeClock` injection is the *only* knob. [CITED: gafferongames.com/post/fix_your_timestep — Fix Your Timestep accumulator pattern, the canonical reference.]

**Boot path (catch-up from save):**

```typescript
// Application layer — src/app/boot.ts (or inlined in PhaserGame.tsx).
// 1. Read save (src/save/).
// 2. Migrate (still v1).
// 3. Compute offlineMs = clock.now() - savedPayload.lastTickAt.
// 4. drainTicks(state, offlineMs, /* silent */ true) → aggregates events.
// 5. If offlineMs >= 5*60*1000 (D-20 threshold), pop the Letter overlay.
// 6. Commit final state to the Zustand store; live tick begins.
```

**Anti-patterns to avoid:**
- `setInterval(tick, 200)` — breaks under tab throttling (`.planning/research/PITFALLS.md` #12).
- Calling `Date.now()` anywhere in `src/sim/garden/`, `src/sim/memory/`, `src/sim/narrative/` — would silently bypass the FakeClock. The ESLint `no-restricted-syntax` rule should be added for `CallExpression[callee.object.name='Date'][callee.property.name='now']` inside `src/sim/**` except `src/sim/scheduler/clock.ts`.

### Pattern 2: BigQty wrapper around break_eternity.js

**What:** A typed wrapper around `Decimal` (the class exported from `break_eternity.js`) that all economic values flow through. Phase 2 lands this even though Season 1 numbers never exceed `Number.MAX_SAFE_INTEGER` — per CLAUDE.md "BigNumbers go through the typed BigQty wrapper around break_eternity.js. Never raw Decimal values in app code."

**Minimum-viable surface:**

```typescript
// Source: .planning/research/PITFALLS.md #7 + CLAUDE.md "Code Style"
// src/sim/numbers/big-qty.ts

import Decimal from 'break_eternity.js'; // ships index.d.ts; no @types needed

export class BigQty {
  private constructor(private readonly d: Decimal) {}

  // Constructors
  static fromNumber(n: number): BigQty { return new BigQty(new Decimal(n)); }
  static fromString(s: string): BigQty { return new BigQty(new Decimal(s)); }
  static zero(): BigQty { return BigQty.fromNumber(0); }
  static one(): BigQty { return BigQty.fromNumber(1); }

  // Arithmetic (returns NEW BigQty — immutable)
  add(b: BigQty): BigQty { return new BigQty(this.d.add(b.d)); }
  sub(b: BigQty): BigQty { return new BigQty(this.d.sub(b.d)); }
  mul(b: BigQty): BigQty { return new BigQty(this.d.mul(b.d)); }
  div(b: BigQty): BigQty { return new BigQty(this.d.div(b.d)); }

  // Comparison
  eq(b: BigQty): boolean { return this.d.eq(b.d); }
  gte(b: BigQty): boolean { return this.d.gte(b.d); }
  gt(b: BigQty): boolean  { return this.d.gt(b.d); }
  lt(b: BigQty): boolean  { return this.d.lt(b.d); }
  lte(b: BigQty): boolean { return this.d.lte(b.d); }

  // Display (UX-11)
  format(): string { return formatHumanReadable(this.d); }
  toNumberSaturating(): number {
    // Phase 2: returns safe-int saturating value for UI bookkeeping.
    if (this.d.gte(Number.MAX_SAFE_INTEGER)) return Number.MAX_SAFE_INTEGER;
    return this.d.toNumber();
  }

  // Serialization (round-trips through Save)
  toJSON(): string { return this.d.toString(); }
  static fromJSON(s: string): BigQty { return BigQty.fromString(s); }
}

// src/sim/numbers/format.ts — UX-11
export function formatHumanReadable(d: Decimal): string {
  // Phase 2 minimum: K/M/B/T then scientific past 1e15.
  const n = d.toNumber();
  if (Number.isFinite(n) && Math.abs(n) < 1000) return n.toFixed(0);
  if (Math.abs(n) < 1e6)  return `${(n / 1e3).toFixed(1)}K`;
  if (Math.abs(n) < 1e9)  return `${(n / 1e6).toFixed(1)}M`;
  if (Math.abs(n) < 1e12) return `${(n / 1e9).toFixed(1)}B`;
  if (Math.abs(n) < 1e15) return `${(n / 1e12).toFixed(1)}T`;
  // break_eternity-only territory: scientific via Decimal#toExponential
  return d.toExponential(2);
}
```

**Why an immutable wrapper:** every operation returns a fresh `BigQty`, so the sim's state shape is purely value-oriented. This composes with Zustand 5's structural-equality detection (no accidental mutation tripping subscriber loops) and with snapshot persistence (the save layer just calls `JSON.stringify` on values that include `BigQty` instances — `toJSON()` is invoked automatically).

**Save round-trip:** `BigQty.toJSON()` returns the canonical Decimal string. On load, `BigQty.fromJSON(s)` reconstructs. This must round-trip in all migration tests; add a Vitest case in `migrations.test.ts` once Phase 4 starts using BigQty fields.

**Phase 2 actual usage sites:** Phase 2's economy is intentionally minimal — the only BigQty-typed values are likely:
- `harvestCount` (could remain plain `number`; promoting to BigQty here is the discipline-tax that buys retrofit safety later).
- The (deferred-to-Phase-4) Roothold value — Phase 2 does NOT add it to V1Payload, but the wrapper is ready when it does.

[CITED: github.com/Patashu/break_eternity.js — TypeScript-native via `index.d.ts`; v2.1.3.]

### Pattern 3: Zustand 5 + Phaser EventBus Bridge

**What:** Two communication channels between Phaser scenes and React UI:

1. **Persistent state** lives in a Zustand 5 store created via `createStore` from `zustand/vanilla` (works without React). The sim writes to it via a slim adapter; React components read from it via the `useStore` hook.
2. **Transient events** ("scene-ready", "tile-clicked-with-coords") flow through a `Phaser.Events.EventEmitter` singleton — the official Phaser 4 React-template `EventBus` pattern. [CITED: phaser.io/news/2025/05/bringing-our-phaserjs-templates-into-the-future]

**Why both:** Persistent state needs structural-equality reactivity for component re-renders (Zustand). One-shot signals (e.g., "active scene is now Garden", or "popover should appear at screen X,Y" because Phaser knows where the tile is on screen) don't need to live in state — they're transients. Routing transients through Zustand pollutes the store.

**Slice composition:**

```typescript
// Source: zustand.docs.pmnd.rs/reference/apis/create-store
// src/store/store.ts

import { createStore } from 'zustand/vanilla';
import { useStore } from 'zustand';
import type { GardenSlice } from './garden-slice';
import type { MemorySlice } from './memory-slice';
import type { NarrativeSlice } from './narrative-slice';
import type { SessionSlice } from './session-slice';

export type AppStoreShape = GardenSlice & MemorySlice & NarrativeSlice & SessionSlice;

export const appStore = createStore<AppStoreShape>()((set, get) => ({
  ...createGardenSlice(set, get),
  ...createMemorySlice(set, get),
  ...createNarrativeSlice(set, get),
  ...createSessionSlice(set, get),
}));

// React-side hook
export function useAppStore<T>(selector: (s: AppStoreShape) => T): T {
  return useStore(appStore, selector);
}

// Sim-side adapter (sim cannot import this directly per CORE-10 firewall;
// the adapter sits in src/store/ and exposes a write-only interface that
// the Phaser scene injects into the scheduler call site).
export const simAdapter = {
  applySimResult: (next: SimState, events: SimEvent[]) => {
    appStore.setState({ /* derive slice updates from next + events */ });
  },
  drainCommands: () => {
    const cmds = appStore.getState().pendingCommands;
    appStore.setState({ pendingCommands: [] });
    return cmds;
  },
};
```

**Slice example:**

```typescript
// src/store/garden-slice.ts
export interface GardenSlice {
  tiles: Tile[];                  // length 16, per D-01
  unlockedPlantTypes: PlantTypeId[];
  pendingCommands: GardenCommand[];
  enqueuePlant: (tileIdx: number, plantTypeId: PlantTypeId) => void;
  enqueueHarvest: (tileIdx: number) => void;
  enqueueCompost: (tileIdx: number) => void;
}
```

**Phaser EventBus singleton:**

```typescript
// Source: phaser.io/news/2025/05/bringing-our-phaserjs-templates-into-the-future
// src/game/event-bus.ts
import * as Phaser from 'phaser';

/** Single shared emitter — the Phaser 4 React-template pattern. */
export const eventBus = new Phaser.Events.EventEmitter();

// Sample events Phase 2 will emit/listen for:
//   'scene-ready'             (Phaser → React) signals scene tree is live
//   'tile-clicked-coords'     (Phaser → React) {tileIdx, screenX, screenY} for seed picker
//   'request-active-scene'    (React → Phaser) one-shot
//   'fragment-revealed'       (Phaser → React) one-shot for D-25 reveal modal
```

The Phaser scene calls `eventBus.emit('scene-ready', this)`; `PhaserGame.tsx` listens, surfaces the active scene to React. This is exactly what `src/PhaserGame.tsx`'s Phase-1 placeholder is shaped for (the `currentActiveScene` callback comment).

**Anti-pattern:** routing user-input intents through the EventBus instead of the store. User intents are commands (durable, replayable, save-able if needed); transient signals are not. Tile-clicks → store. Scene transitions → EventBus.

### Pattern 4: Inline Seed Picker (DOM popover over Phaser canvas)

**What:** D-02's "click empty tile → inline seed picker" with no persistent sidebar. Implementation: pointerdown on a Phaser tile fires an EventBus event with `{tileIdx, screenX, screenY}`; the React `<SeedPicker>` listens, mounts itself absolutely-positioned to those screen coords with a CSS arrow pointing at the tile.

```typescript
// src/render/garden/tile-coords.ts
export function tileToScreenCoords(
  scene: Phaser.Scene,
  tileIdx: number,
): { x: number; y: number } {
  const tile = /* Phaser GameObject for tileIdx */;
  // Account for the Scale.FIT center offset and DPI.
  const camera = scene.cameras.main;
  return {
    x: camera.x + tile.x * camera.zoom,
    y: camera.y + tile.y * camera.zoom,
  };
}

// In Garden scene's create():
this.tileObjects.forEach((t, idx) => {
  t.setInteractive();
  t.on('pointerdown', (pointer: Phaser.Input.Pointer) => {
    if (state.tiles[idx].plant === null) {
      eventBus.emit('tile-clicked-coords', {
        tileIdx: idx,
        screenX: pointer.x, // pointer event coords are in canvas space
        screenY: pointer.y,
      });
    } else if (state.tiles[idx].plant.stage === 'ready') {
      appStore.getState().enqueueHarvest(idx);
    }
    // Mature-but-not-ready tile click → no-op or compost confirmation.
  });
});
```

[CITED: docs.phaser.io/phaser/concepts/input — Phaser input system; pointerdown on interactive game objects.]

**Position translation:** `pointer.x/y` from a Phaser pointer event are in the canvas's CSS-pixel coordinate space, which matches DOM coordinates. The `<SeedPicker>` mounts at `position: absolute; left: ${pointer.x}px; top: ${pointer.y}px;` directly. (No need to `getBoundingClientRect` the canvas; the canvas's CSS layout starts at viewport origin in this app.)

**Click outside → dismiss:** the popover registers a one-shot document `click` listener that fires after the next tick (avoids capturing the same click that opened it).

### Pattern 5: Ink Compilation + Runtime

**Build-time:** `inklecate` (installed as devDep) compiles `*.ink` → `*.ink.json`. The current `package.json scripts.compile:ink` is a no-op stub from Phase 1; Phase 2 replaces it:

```json
"compile:ink": "node scripts/compile-ink.mjs"
```

```javascript
// scripts/compile-ink.mjs (NEW Phase 2)
// Walks /content/dialogue/**/*.ink, calls inklecate per file,
// emits to src/content/compiled-ink/<season>/<name>.ink.json.
// Adds --countAllVisits=false (default) so visit counts are minimal.
import { inklecate } from 'inklecate';
import { glob } from 'glob';
import path from 'node:path';

const inkFiles = await glob('content/dialogue/**/*.ink');
for (const inkPath of inkFiles) {
  const rel = path.relative('content/dialogue', inkPath);
  const outPath = path
    .join('src/content/compiled-ink', rel)
    .replace(/\.ink$/, '.ink.json');
  await inklecate({
    inputFilepath: inkPath,
    outputFilepath: outPath,
  });
}
```

This script runs as part of `npm run build` (and explicitly via `npm run compile:ink` so dev iteration is fast). The output directory is `.gitignore`'d; the Vite dev server serves the compiled JSON via standard import.

**Runtime:** `inkjs` v2.4.0 exports `Story` from the package root (verified in `node_modules/inkjs/ink.d.mts`). Usage:

```typescript
// Source: github.com/y-lohse/inkjs README; node_modules/inkjs/README.md
// src/ui/dialogue/ink-runtime.ts
import { Story } from 'inkjs';

// Lazy import the compiled JSON so Season 2-7 stays out of the Phase-2 bundle.
const luraStories = import.meta.glob('/src/content/compiled-ink/season1/lura-*.ink.json', {
  import: 'default',
});

export async function loadLuraBeat(beatId: 'arrival' | 'mid' | 'farewell'): Promise<Story> {
  const path = `/src/content/compiled-ink/season1/lura-${beatId}.ink.json`;
  const json = await luraStories[path]();
  return new Story(json);
}

// Variable wiring — Lura's branches can read game state.
export function bindGardenStateToInk(story: Story, snapshot: AppStoreShape): void {
  // Map from store keys to Ink variable names declared in the .ink files.
  story.variablesState['fragment_count'] = snapshot.harvestedFragmentIds.length;
  story.variablesState['last_plant_type'] = snapshot.lastPlantedType ?? '';
  // ... add more as the writer adds Ink variables
}
```

**Drip-fed text-message-cadence rendering (STRY-01 "text-message-cadence dialogue"):** Phase 2's React `<LuraDialogue>` component calls `story.Continue()` to fetch the next line, awaits a tunable delay (e.g., 800ms × line length / 40 characters), then renders. Choices are rendered as buttons after `story.currentChoices` resolves. The reduced-motion preference (deferred to Phase 8) will eventually short-circuit the delay; Phase 2 ships a fixed cadence.

### Pattern 6: Letter-from-the-Garden as Ink Template

**What:** D-17 says the letter is an authored Ink skeleton with named variable slots. Ink supports variables via `VAR varName = value` syntax and string interpolation `{varName}` in passages. The application sets the variables via `story.variablesState['name'] = value` BEFORE calling `Continue()`.

**Skeleton example (`content/dialogue/season1/letter-from-the-garden.ink`):**

```ink
VAR plants_bloomed = 0
VAR fragment_titles = ""
VAR lura_was_here = false

The garden held its breath while you were gone.

{plants_bloomed > 1:
    {plants_bloomed} blooms came and went, leaves heavy with their leaving.
- else:
    {plants_bloomed == 1:
        One bloom came and went.
    - else:
        Nothing bloomed. The wind carried something else, and the garden remembered it.
    }
}

{ fragment_titles ? "Among what stayed: {fragment_titles}." }

{ lura_was_here:
    Lura came by once. She did not knock. She left a folded leaf on the gate post.
}
```

**Why Ink variables, not Ink EXTERNAL functions:** EXTERNAL functions are for callbacks ("game, please tell me X"); they're heavier and require runtime registration. Simple string-substitution slots map cleanly to `variablesState[name] = value`. Phase 2 ships variable-substitution only. If Phase 4+ needs more, the `EXTERNAL function get_lura_quote() = "..."` pattern is available without re-architecting.

**Slot vocabulary for Phase 2's letter** (from D-19's `offlineEvents` block):
- `plants_bloomed: number` — total auto-harvested plants during absence
- `fragment_titles: string` — comma-joined human-readable list of just-collected fragments (or `""` if none)
- `lura_was_here: boolean` — whether a beat ticked while the player was away (the gate indicator was queued)

The writer expands the slot list as new Ink expressions need state; Phase 2 may grow from these three to ~5–6 by end of phase. CLAUDE.md "voice anchor" rule means the Ink reads as authored fiction; the slots are filled at runtime.

### Pattern 7: Save-Schema Extension (NOT a migration)

**What:** Per CONTEXT D-34 and `.planning/phases/01-foundations-and-doctrine/01-CONTEXT.md` D-04, Phase 1's v1 envelope has shipped no production saves. Phase 2 *extends* `V1Payload` in place — adds new fields with sensible defaults — and the existing `migrations[1]` synthetic v0→v1 demo continues to work because v0 → v1 already sets up the new defaults via the same factory function.

**Concrete edit to `src/save/migrations.ts`:**

```typescript
// Phase-2 V1Payload shape. EXTENSION of Phase-1's shape (compatible).
export interface V1Payload {
  garden: { tiles: TileSlot[] };
  plants: PlantInstance[];           // shape filled in Phase 2
  harvestedFragmentIds: string[];
  lastTickAt: number;

  // NEW Phase 2 fields:
  unlockedPlantTypes: PlantTypeId[];          // D-05
  luraBeatProgress: {
    arrived: boolean;
    mid: boolean;
    farewell: boolean;
    pending: 'arrival' | 'mid' | 'farewell' | null;
  };                                          // D-13/D-14
  offlineEvents: OfflineEventBlock | null;    // D-19; nulled after letter dismissed

  settings: {
    musicVolume: number;
    ambientVolume: number;
    sfxVolume: number;
    persistenceToastShown: boolean;           // D-30 one-time
  };
}

// migrations[1] becomes:
export const migrations: Record<number, Migration> = {
  1: (s: unknown): V1Payload => {
    const v0 = (s ?? {}) as V0Payload;
    return {
      garden: { tiles: v0.garden ?? [] },
      plants: [],
      harvestedFragmentIds: [],
      lastTickAt: Date.now(),
      // NEW defaults:
      unlockedPlantTypes: [], // populated by sim init when first run
      luraBeatProgress: { arrived: false, mid: false, farewell: false, pending: null },
      offlineEvents: null,
      settings: {
        musicVolume: 0.7,
        ambientVolume: 0.5,
        sfxVolume: 0.8,
        persistenceToastShown: false,
      },
    };
  },
};
```

The `migrations.test.ts` tests need updating for the new fields, but `CURRENT_SCHEMA_VERSION` stays at `1` and no `migrations[2]` is added (per `.planning/phases/01-foundations-and-doctrine/01-CONTEXT.md` D-04: "The first *real* migration is v1 → v2 in Phase 4").

**Why this is safe:** No production saves under v1 exist. Adding fields to `V1Payload` is type-extension, not data migration. The synthetic v0 → v1 chain is updated to populate the new defaults; the chain remains exercised end-to-end.

**Anti-patterns to avoid:**
- Adding a `migrations[2]` for what is fundamentally a Phase-2 init concern. Phase 4 owns `migrations[2]` per Phase 1's locked decision.
- Reading `lastTickAt` directly from save without going through the scheduler — this would let `Date.now()` leak into sim modules.
- Storing the offline letter's *body text* in the save. Only the structured `offlineEvents` block is saved; the Ink template renders it on demand from `/content/dialogue/season1/letter-from-the-garden.ink.json`.

### Pattern 8: Per-Season Lazy Loading (PIPE-02)

**What:** `import.meta.glob('/content/seasons/*/fragments/*.md', { eager: false, … })` returns functions that resolve to dynamic imports — Vite splits each into its own chunk. [CITED: vite.dev/guide/features — `import.meta.glob` is "lazy-loaded via dynamic import" by default when `eager` is not set or is `false`.]

The current `src/content/loader.ts` uses `eager: true` for Phase 1's single-Season demo. Phase 2 splits the Season-1 path into a lazy variant:

```typescript
// src/content/loader.ts (Phase 2 evolution)
// Eager bootstrap: only the season manifest (lightweight) is in the initial bundle.
const seasonManifests = import.meta.glob('/content/seasons/*/manifest.yaml', {
  eager: true,
  query: '?raw',
  import: 'default',
}) as Record<string, string>;

// Per-Season lazy: actual fragment files load only when that Season is active.
const lazyYamlFragments = import.meta.glob('/content/seasons/*/fragments.yaml', {
  query: '?raw',
  import: 'default',
});
const lazyMdFragments = import.meta.glob('/content/seasons/*/fragments/*.md', {
  query: '?raw',
  import: 'default',
});

export async function loadSeasonFragments(seasonId: number): Promise<Fragment[]> {
  const yamlPath = `/content/seasons/${pad2(seasonId)}-${slug(seasonId)}/fragments.yaml`;
  const fragmentPaths = Object.keys(lazyMdFragments).filter(p => p.includes(`/${pad2(seasonId)}-`));
  // …load + validate each via FragmentSchema as today; throw on schema violation.
}
```

For Phase 2 (Season 1 only is authored), Vite produces two chunks: the main bundle (no fragment text) and a `season1` chunk (~few KB of Markdown + YAML). When Phase 4 adds Season 2, it ships an additional chunk; Season 2-7 are never in the initial download until the player progresses.

**Initial-load budget impact:** Phase 1's initial bundle is dominated by Phaser 4 (~700KB minified) and React 19 (~50KB). Phase 2 adds Zustand (~3KB), `break_eternity.js` (~30KB), Season-1 Ink JSON (~few KB), and roughly 200 lines of Phase-2 sim code. The Season-1 fragment chunk lazy-loads after the Begin gesture, so the *gesture-to-painted-garden* path stays under CORE-01's 5s budget.

### Pattern 9: AudioContext.resume() Bootstrap

**Per CONTEXT D-21/D-22:**
- First-run (no save exists): Begin screen mounts; tap calls `audioContext.resume()`.
- Subsequent loads: Begin screen is skipped; AudioContext starts in `suspended` state and resumes on the player's first interaction (any tile click, gate click, or button click counts as a user gesture per browser autoplay policy).

```typescript
// src/ui/begin/use-audio-bootstrap.ts
let _ctx: AudioContext | null = null;
let _resumed = false;

export async function bootstrapAudioContext(): Promise<AudioContext | null> {
  if (_resumed && _ctx) return _ctx;
  if (!_ctx) {
    try {
      const Ctor =
        typeof AudioContext !== 'undefined'
          ? AudioContext
          : (window as any).webkitAudioContext;
      if (!Ctor) return null;
      _ctx = new Ctor();
    } catch {
      return null;
    }
  }
  try {
    await _ctx.resume();
    _resumed = true;
    return _ctx;
  } catch {
    return null;
  }
}

// First-interaction handler installed on the live garden when no Begin shows.
export function installFirstInteractionGestureHandler(): void {
  const handler = () => {
    bootstrapAudioContext();
    document.removeEventListener('click', handler);
    document.removeEventListener('touchstart', handler);
    document.removeEventListener('keydown', handler);
  };
  document.addEventListener('click', handler, { once: false });
  document.addEventListener('touchstart', handler, { once: false });
  document.addEventListener('keydown', handler, { once: false });
}
```

[CITED: developer.chrome.com/blog/web-audio-autoplay — explicit `context.resume()` after gesture is the canonical fix.]

**Phase 3 will:** retrieve the resumed `AudioContext` from this module (or pass it through the Zustand store) and feed it to Howler's master gain.

### Anti-Patterns to Avoid

- **`setInterval(tick, 200)` for sim progression** — breaks under tab throttling; the elapsed-time clock model is the documented fix (`.planning/research/PITFALLS.md` #12).
- **Mutating store state from sim modules directly** — sim cannot import `src/store/`. Instead, the application layer (Phaser scene + scheduler) is the bridge: scene calls `scheduler.tick(state)`, gets back `next state`, calls `simAdapter.applySimResult(next, events)` which lives in `src/store/`.
- **Naive offline catch-up** (`fragments += rate * elapsedSeconds`) — misses non-linear interactions and Lura beat unlocks. **Run the actual `simulate()` loop** with `silent: true` (`.planning/research/PITFALLS.md` Anti-Pattern 7).
- **`if (!state.luraBeatProgress) state.luraBeatProgress = {...}` at read sites** — that's a hidden migration. Instead, fix the migration once in `migrations[1]` (Phase 2) and require `V1Payload` to be fully populated.
- **Storing player-visible strings in TypeScript** — every line of Lura's dialogue, the letter, the Begin screen copy, the post-harvest acknowledgement, the persistence-denied toast lives in `/content/`. The "no fragments yet" empty-state copy lives in `/content/seasons/01-soil/ui-strings.yaml` (a small additional content file Phase 2 adds), validated by an additional Zod schema.
- **Numeric fragment IDs** — already prevented by `FragmentSchema`'s regex. Don't loosen the regex for "convenience."
- **Calling `audioContext.resume()` in `useEffect` without a user gesture** — fires before gesture, fails silently; the resume must be inside an actual click handler.
- **Rendering Memory Journal text inside Phaser** — MEMR-05 demands selectable, copy-pasteable DOM text. Phaser canvas text fails this requirement.
- **Lura's beats as `setTimeout` triggers** — would let system-clock manipulation skip beats. STRY-10 demands tick-count gating. The fragment-count-based trigger satisfies this naturally because harvest events advance during sim ticks only.
- **Reading `Date.now()` inside a React render** — would re-fire on every render. Time is in the store; React just reads it.

## Don't Hand-Roll

| Problem | Don't Build | Use Instead | Why |
|---------|-------------|-------------|-----|
| Big-number math for prestige economy | Custom BigDecimal | `break_eternity.js` (wrapped by `BigQty`) | Native JS numbers overflow at 1e308; precision loss at 1e15. `break_eternity.js` is the standard for incremental games (Pitfall 7). |
| Branching dialogue with state-aware choices | Custom dialogue tree | `inkjs` + `inklecate` | Already locked + installed. Ink is purpose-built for narrative scripting; `inkjs` runtime is battle-tested across browser deployments. (`.planning/research/STACK.md`) |
| Deterministic fragment selection with gating + no-dup | Random `Math.random()` rolling | Pure function with seeded PRNG over a filtered, exhaustion-tracking pool | MEMR-06 demands "deterministic". Use a small seeded PRNG (e.g., mulberry32, ~10 LoC pure function) seeded from a stable hash of `(harvestedFragmentIds.length, lastTickAt)` so replays are reproducible. |
| State management between Phaser and React | Custom event bus + manual state sync | Zustand 5 (createStore + useStore) + Phaser EventBus | Zustand is locked + standard. The Phaser `EventBus` pattern is the official template-react integration. |
| Idle game tick loop with fixed timestep + offline catch-up | `setInterval` + ad-hoc math | Accumulator pattern owning wall-clock at one boundary | Tab throttling, system-clock cheat, save-load sync — all solved by the documented pattern (Architecture Pattern 2). |
| Save versioning + checksum + Base64 + IndexedDB + LocalStorage fallback | Anything | `src/save/` (Phase 1) | Already shipped. Phase 2 imports only from `src/save/index.ts`. |
| Markdown frontmatter parsing | Custom regex | `gray-matter` (already installed + wired) | Standard. Phase 1 already integrated it. |
| YAML parsing | Custom YAML | `yaml` package (already installed + wired) | Standard. Phase 1 already integrated it. |
| CRC-32 checksum | Custom CRC | `crc-32` package (already installed + wired) | Standard. Phase 1 already integrated it. |
| Schema validation | Custom validator | `zod` (already installed + wired) | Standard. Phase 1 uses it for content + envelope; Phase 2 uses for `OfflineEventBlock`. |
| Audio crossfading | Custom Web Audio gain ramps | `Howler.js` (Phase 3) — Phase 2 stubs only | Howler abstracts iOS Safari quirks. Phase 2 doesn't need it; Phase 3 wires it. |
| Ink dialogue rendering with text-cadence | Custom drip animator | Compose `setTimeout` cadence around `inkjs.Story.Continue()` (~30 LoC) | The drip is genuinely small custom code; the dialogue *engine* is Ink. |
| Per-Season lazy loading | Custom dynamic-import scheme | `import.meta.glob({ eager: false })` — Vite native | Vite splits chunks automatically. (`.planning/research/STACK.md` + Vite docs) |

**Key insight:** Phase 1 already paid for the heavy infrastructure. Phase 2's "don't hand-roll" list is mostly "use what Phase 1 built" — the temptation will be to bypass the existing barrel and import from internal modules under deadline pressure. Don't.

## Common Pitfalls

### Pitfall 1: Sim modules calling `Date.now()` for "convenience"

**What goes wrong:** A sim module reads `Date.now()` to "stamp" a plant's plantedAt. The Vitest test passes (because `Date.now()` exists in node). The Playwright fast-forward fails because the FakeClock injection is bypassed.

**Why it happens:** It's one line of "obvious" code. Authors don't see the architecture.

**How to avoid:**
- The clock is an injected parameter — sim functions take `(state, dt, now)` not `(state, dt)`.
- Add an ESLint rule: `'no-restricted-syntax': ['error', { selector: "CallExpression[callee.object.name='Date'][callee.property.name='now']", message: 'src/sim/** must inject time; only src/sim/scheduler/clock.ts may read Date.now()' }]` scoped to `src/sim/**` excluding `src/sim/scheduler/clock.ts`.
- Add a Vitest test that runs through the sim with a FakeClock and asserts no real-time elapses (i.e., real-`Date.now()` and the result are unchanged).

**Warning signs:** A test passes only when run quickly; a Playwright fast-forward changes results.

### Pitfall 2: 4×4 garden state confusion (tile coords vs index)

**What goes wrong:** Tile is at `(row=2, col=3)`. Code uses `index = row * 4 + col` in some places and `index = col * 4 + row` in others. Save loads the wrong tile.

**How to avoid:** Pick one canonical encoding (`index = row * 4 + col`) in `src/sim/garden/types.ts` with an exported helper `tileIdx(row, col)` and `tileCoords(idx)`. Ban raw arithmetic at call sites.

**Warning signs:** Plant appears in wrong tile after refresh; save round-trip test fails on tile order.

### Pitfall 3: Begin-screen skip logic misclassifies returning players

**What goes wrong:** D-22 says "first run = no save exists". An IndexedDB read fails (private mode, blocked) → save layer falls through to LocalStorage → LocalStorage read returns `null` (genuinely missing) vs `null` (silently failed). Returning player sees Begin screen again.

**How to avoid:** `openSaveDB()` already wraps the IDB-or-LocalStorage decision; the SaveDB interface exposes both. Phase 2's "first run?" check is `(await db.get('saves', 'main')) === undefined`. The SaveDB abstraction makes IDB-vs-LS transparent. Test both paths in Vitest.

**Warning signs:** Returning player on iOS Safari sees Begin screen on every launch.

### Pitfall 4: Ink variable casing mismatch (case-sensitive)

**What goes wrong:** Ink declares `VAR plants_bloomed = 0`. JS sets `story.variablesState['plantsBloomed'] = 5`. No error fires; the variable stays at 0; the letter renders the wrong branch.

**How to avoid:** Use `snake_case` for all Ink variables. Centralize the mapping table in `src/ui/letter/letter-renderer.ts`:

```typescript
const INK_VARIABLE_MAP = {
  plants_bloomed: (s: AppStoreShape) => s.offlineEvents?.plantsBloomedCount ?? 0,
  fragment_titles: (s: AppStoreShape) => s.offlineEvents?.harvestedFragmentTitles.join(', ') ?? '',
  lura_was_here: (s: AppStoreShape) => s.offlineEvents?.luraBeatPending ?? false,
} as const;
```

A test asserts every key in `INK_VARIABLE_MAP` exists in the compiled `.ink.json` (parsed for `VAR` declarations).

**Warning signs:** Letter renders an unexpected branch; "fragment_titles" shows literal text.

### Pitfall 5: AudioContext spec disagreement on `resume()` timing

**What goes wrong:** Mobile Safari requires `AudioContext` to be *created* synchronously inside the gesture handler — not just `resumed` inside it. Creating in `useEffect` and calling `resume()` in click fails on iOS.

**How to avoid:** Lazy-create the `AudioContext` inside `bootstrapAudioContext()` which is called from the click handler. Don't pre-create on mount.

**Warning signs:** Audio works on Chrome desktop, fails silently on iOS.

[CITED: developer.mozilla.org/Web/Media/Guides/Autoplay — autoplay policy details for cross-browser behavior.]

### Pitfall 6: Phaser scene stale closure over Zustand state

**What goes wrong:** Phaser scene's `create()` does `const tiles = appStore.getState().tiles` once; later updates don't propagate to the scene's render. Plants never appear after planting.

**How to avoid:** Inside Phaser scenes, *subscribe* to the store: `appStore.subscribe(state => this.renderTiles(state.tiles))`. Or — simpler for Phase 2 — re-read `appStore.getState()` inside the scene's `update()` loop (it runs at 60Hz; reading is cheap). The latter is the minimum-viable choice.

**Warning signs:** Plant placed via React popover does not appear in canvas until refresh.

### Pitfall 7: Save fires AFTER React unmounts on `beforeunload`

**What goes wrong:** `beforeunload` listener calls `await saveAsync()`. Browser doesn't await async work in unload handlers. Save races and may not flush.

**How to avoid:** Use a synchronous-ish save path on `beforeunload`: serialize the envelope (synchronous), write to LocalStorage (synchronous), and *only* attempt IndexedDB best-effort. The next-load path checks both stores; whichever has the more recent `lastTickAt` wins.

**Warning signs:** Closing the tab and reopening loses 1–10 seconds of progress.

### Pitfall 8: Fragment selector returns duplicates after exhaustion

**What goes wrong:** MEMR-06 says "no duplicates within a single playthrough until the pool is exhausted." Once exhausted, the spec is silent. If the selector throws, harvests after exhaustion break.

**How to avoid:** When all fragments in the gated pool have been harvested, the selector falls back to a "memory-of-a-memory" pool (a single fragment authored as the exhaustion marker, e.g., `season1.soil.gardener-knows-this-one-already`) OR repeats the most recently harvested one (least bad option for UX). Phase 2 should ship enough Season-1 fragments that exhaustion is unlikely (target ≥10 to comfortably exceed the 8th-harvest Lura threshold + plant-type unlocks). Document the chosen behavior in PLAN.md.

**Warning signs:** Player reaches a state where harvest does nothing; or duplicate fragments appear unexpectedly.

### Pitfall 9: Letter overlay swallows tap-to-resume gesture

**What goes wrong:** Player returns after >5min. Letter overlay mounts. Player taps to dismiss → letter dismisses but `AudioContext.resume()` is not called because no `bootstrapAudioContext()` handler is registered on the letter's dismiss button.

**How to avoid:** The letter's dismiss button calls `bootstrapAudioContext()` exactly like the Begin button. Same for any first-interaction surface a returning player might hit before the live garden.

**Warning signs:** Audio fails for returning players who land directly in the letter.

### Pitfall 10: Plant-type unlock thresholds vs fragment-count off-by-one

**What goes wrong:** D-05 says "remaining 1–2 unlock by fragment-count thresholds." Player has 5 harvests. Threshold for plant 2 is `5`. Off-by-one bug: unlock fires *before* the 5th harvest is committed to the store.

**How to avoid:** Always check thresholds *after* the harvest commit, in the same simulate-step's post-step hook. Test the boundary (4 harvests = locked, 5 harvests = unlocked) explicitly.

**Warning signs:** Race condition between unlock and reveal modal.

## Code Examples

### Verified pattern: Phaser scene → React EventBus signaling scene-ready

```typescript
// Source: phaser.io/news/2025/05/bringing-our-phaserjs-templates-into-the-future
// src/game/scenes/Garden.ts
import * as Phaser from 'phaser';
import { eventBus } from '../event-bus';

export class Garden extends Phaser.Scene {
  constructor() { super('Garden'); }
  create(): void {
    // ... build tile objects, plant primitives, gate ...
    eventBus.emit('scene-ready', this);
  }
  update(_time: number, _delta: number): void {
    // Re-read from store on each frame; render.
    // The scheduler is invoked on a fixed cadence inside this loop —
    // see src/sim/scheduler/tick.ts for the accumulator drain.
  }
}
```

### Verified pattern: Zustand 5 vanilla store with React hook

```typescript
// Source: zustand.docs.pmnd.rs/reference/apis/create-store
// src/store/store.ts
import { createStore } from 'zustand/vanilla';
import { useStore } from 'zustand';

export const appStore = createStore<AppStoreShape>()((set) => ({
  // … slice spreads
}));

// React side
export const useAppStore = <T>(selector: (s: AppStoreShape) => T): T =>
  useStore(appStore, selector);
```

### Verified pattern: Tick scheduler accumulator (idle-game canonical)

```typescript
// Source: gafferongames.com/post/fix_your_timestep + .planning/research/ARCHITECTURE.md Pattern 2
// src/sim/scheduler/tick.ts (excerpt — full version above)
const TICK_MS = 200;
const MAX_OFFLINE_MS = 24 * 3600 * 1000;
// drainTicks refuses negative dt (CORE-11) and clamps offline to 24h (CORE-03).
```

### Verified pattern: inkjs Story instantiation

```typescript
// Source: github.com/y-lohse/inkjs README; node_modules/inkjs/ink.d.mts
// src/ui/dialogue/ink-runtime.ts (excerpt)
import { Story } from 'inkjs';
const story = new Story(compiledJson);
story.variablesState['fragment_count'] = snapshot.harvestedFragmentIds.length;
const line = story.Continue();
```

## State of the Art

| Old Approach | Current Approach (2026) | When Changed | Impact |
|--------------|-------------------------|--------------|--------|
| `setInterval` for idle tick | Elapsed-time-based progression with `requestAnimationFrame`-driven scheduler | Chrome 88+ background-tab timer throttling (Jan 2021) | Mandatory for any idle game; `.planning/research/PITFALLS.md` #12. |
| Phaser 3 with custom React shell | Phaser 4 official `template-react-ts` with `EventBus` singleton | Phaser 4 release (April 2026) + template refresh (May 2025 announcement) | Removes ~6 months of custom integration; what `src/PhaserGame.tsx` already implements. |
| Zustand 4 with React-only API | Zustand 5 with `zustand/vanilla` `createStore` | Zustand 5 release | Lets sim-side adapters and Phaser scenes participate without React-fiber overhead. |
| Ink with hand-rolled drip rendering | `inkjs` v2.4 + ESM `import { Story } from 'inkjs'` | inkjs 2.x ESM exports landed | TypeScript-friendly imports; compiled output stays portable. |
| `@types/howler` always required | Howler.js 2.2.4 ships compatible types via `@types/howler` (DefinitelyTyped) | — | Phase 3 concern. |

**Deprecated/outdated (avoid):**
- `setInterval`-driven game logic (Pitfall 12).
- Storing entitlements client-side (Pitfall 4 in `.planning/research/ARCHITECTURE.md`'s Anti-Patterns) — moot for Phase 2 (no entitlements yet, but worth knowing for v2).
- `process.env.NODE_ENV` in browser code — Vite uses `import.meta.env` (already used by Phase 1).
- `phaser/types/Phaser` deep imports — Phaser 4 exports types from the package root.

## Assumptions Log

| # | Claim | Section | Risk if Wrong |
|---|-------|---------|---------------|
| A1 | The Phaser 4 `EventBus` pattern (Phaser.Events.EventEmitter singleton) is the documented Phaser-React integration in Phaser 4's official template, just as it was in Phaser 3's template. | Pattern 3 + System Architecture Diagram | LOW — verified via [phaser.io/news/2025/05/bringing-our-phaserjs-templates-into-the-future]; the template's EventBus pattern explicitly says the May 2025 update prepared the template for Phaser 4. If Phaser 4's release shifted this, Phase 2 falls back to `mitt` which is already research-confirmed in `.planning/research/STACK.md`. |
| A2 | A 5Hz sim tick rate (TICK_MS=200) is appropriate for 2–5 minute plant growth. | Pattern 1 | LOW — derived from `.planning/research/ARCHITECTURE.md` Pattern 2's worked example. If playtest shows visible stepping in growth animation, Phase 2 can bump to 10Hz (TICK_MS=100) without changing any sim code (only the constant). |
| A3 | A 24h offline catch-up at 5Hz (=432K ticks) catches up in well under 1s on a modern device. | Pattern 1 | LOW — the per-tick work is small (state mutation + accumulator drain); but if the simulate function ends up doing string allocations per tick, this could degrade. Vitest benchmark in scheduler tests should assert ≤500ms for 432K ticks. |
| A4 | Ink variables (`VAR plants_bloomed = 0`) set via `story.variablesState['plants_bloomed'] = N` work for letter templating in inkjs 2.4.0. | Pattern 6 | LOW — verified via [github.com/y-lohse/inkjs README "Differences with the C# API: Getting and setting ink variables"]; this is the documented mechanism. |
| A5 | Phaser pointer event coordinates (`pointer.x`, `pointer.y`) are in CSS-pixel space and can be used directly as DOM `position: absolute` coords for the seed picker without `getBoundingClientRect` adjustments. | Pattern 4 | MEDIUM — depends on the canvas's CSS layout. Phase 1's scaffold uses `Phaser.Scale.FIT`, which adds letterboxing. The popover may need to `getBoundingClientRect` the `#game-container` and add its `left/top` offset. Plan 2 should test on a non-fullscreen window. |
| A6 | `inklecate` (the npm wrapper around the .NET binary) runs cleanly on Windows + macOS + Linux CI. | Pattern 5 | MEDIUM — `inklecate.exe` ships in `node_modules/inklecate/bin/`; the wrapper picks the right binary per platform. Phase 2's `compile-ink.mjs` script must not assume a specific binary path; it should call the `inklecate` package's exported function. The package was installed in Phase 1 but never invoked beyond the no-op stub — Plan 2 should confirm with one real compile on Windows-the-dev-machine before authoring all Lura content. |
| A7 | Phase 2's letter rendering uses Ink variable substitution + conditional branches, not `EXTERNAL` functions. | Pattern 6 | LOW — variable substitution is sufficient for D-19's slot vocabulary; flagged here so reviewers know we explicitly chose simpler over more powerful. |
| A8 | Authoring "≥10 Season-1 fragments" is sufficient to satisfy 1st/4th/8th Lura thresholds + 1–2 plant-type unlocks + buffer. | Pitfall 8 | LOW — covers the worst case (8 harvests + 1 plant-type unlock margin). User reviews specific count during planning. |
| A9 | The first-interaction gesture handler installed on returning-player loads (Pattern 9) is reliable across browsers (no edge case where audio fails silently). | Pattern 9 | LOW — the `click`+`touchstart`+`keydown` triple-listener is the documented pattern. iOS quirks were the historical bug; modern Safari respects `resume()` after any user gesture. Phase 8 e2e test on iOS Safari is the right place to verify. |
| A10 | Per-Season lazy loading via `import.meta.glob({ eager: false })` produces real chunk splits for Phase 2 even with only one Season authored. | Pattern 8 | LOW — Vite always splits each lazy import; the chunk happens to be a single file in Phase 2, but the wiring is correct for Phase 4+. Verify with a `npm run build && ls dist/assets/` showing a `season1`-named chunk. |

**If this table is empty:** All claims in this research were verified or cited — no user confirmation needed.

This table has 10 entries; all are `LOW` risk except A5 and A6 (`MEDIUM`). Plan 2 should explicitly verify A5 (canvas-to-DOM coord mapping under FIT scale) and A6 (inklecate wrapper invocation) early.

## Open Questions (RESOLVED)

> All five open questions resolved during /gsd-discuss-phase 2 + planning. Resolutions are codified in CONTEXT.md decisions and the per-plan PLANs. Recommendations below are ratified, not pending.


1. **Plant-type identity per the 2–3 plant types in Season 1 (per D-03 + D-09).**
   - What we know: 2–3 plants, varying durations within 2–5min, distinct fragment pools, distinct visual primitive (different tint per plant), tonal identity per plant. First plant from start; remaining unlock at fragment-count thresholds.
   - What's unclear: the actual identities (e.g., "rosemary vs. yarrow vs. winter-rose"?). Bible says "real flora, slightly wrong" but Phase 2 doesn't need painted flora — names matter for fragment authoring.
   - RESOLVED: Plan 2's content authoring step proposes 3 names tied to 3 fragment-pool tonal registers (warm / contemplative / heavy). Locked names: rosemary (warm), yarrow (contemplative), winter-rose (heavy). See Plan 02-02 PLANT_TYPES.

2. **Compost UX shape (GARD-04 "tonal beat acknowledging the choice to let go").**
   - What we know: composting is a Phase 2 mechanic; tonal beat must "acknowledge the choice to let go". Bible voice is warm + specific.
   - What's unclear: is the beat a small text snippet, a particle effect, a sound? D-07 leaves form to Claude's discretion *for harvest*; GARD-04 is the *compost* analog and isn't in CONTEXT.
   - RESOLVED: a single Ink-authored line per compost (`content/dialogue/season1/compost-acknowledgements.ink`, ~3–5 short lines, randomly selected). Authored in Plan 02-04. UI-wiring deferral acknowledged in 02-04 SUMMARY → 02-05 toast surface.

3. **Save trigger on Season transitions (UX-10).**
   - What we know: UX-10 specifies "saves on visibilitychange to hidden, on beforeunload, AND on Season transitions."
   - What's unclear: Phase 2 has no Season transitions (Season 1 only). The save-on-transition hook is dormant until Phase 4.
   - RESOLVED: implement the save hook as a pure function callable by future-phase code (`saveOnSeasonTransition(state)` exported from `src/save/index.ts`). Phase 2 verifies it via unit test only; first real call is Phase 4. See Plan 02-01 src/save/lifecycle.ts.

4. **PIPE-02 lazy-loading scope when only Season 1 is authored.**
   - What we know: PIPE-02 says "future Seasons are not in the initial bundle."
   - What's unclear: with only Season 1 authored, the lazy split is a wiring exercise — Phase 2's actual *initial* bundle contains everything because there's nothing else to lazy-load. Is the requirement satisfied "vacuously" (no Seasons 2-7 exist), or does the pattern need to demonstrably work?
   - RESOLVED: ship the lazy pattern (`{ eager: false }`) so Phase 4 inherits it without rework. Plan 02-03 ships scripts/check-bundle-split.mjs; PIPE-02 verification is structural via that script + a Vitest case. PIPE-07 e2e covers the runtime loop.

5. **Should the offline letter ALSO surface the just-unlocked Lura beat indicator, or are they decoupled?**
   - What we know: D-19 says `offlineEvents` includes "a flag for any newly-unlocked Lura beat queued for first-visit." D-15 says the beat-fire UX is "a soft cue at the gate." D-20 says the letter is full-screen.
   - What's unclear: when a beat unlocks during absence, does the letter mention Lura? Or does the player dismiss the letter into the live garden where the gate glows?
   - RESOLVED: the letter mentions Lura's presence in voice (Ink slot `lura_was_here`), the gate also indicates the queued beat. Both surfaces, complementing each other. See Plan 02-05 letter-from-the-garden.ink + Plan 02-04 gate-renderer.ts.

## Environment Availability

| Dependency | Required By | Available | Version | Fallback |
|------------|------------|-----------|---------|----------|
| Node.js | Build, test, CI | ✓ | (Phase 1 ran on Node 22 per `.github/workflows/ci.yml`) | — |
| `npm` | Install + scripts | ✓ | (bundled with Node) | — |
| Phaser 4 | Canvas rendering | ✓ | 4.1.0 | — |
| React 19 | UI overlays | ✓ | 19.2.6 | — |
| Vite | Dev server + bundler | ✓ | 8.0.11 | — |
| TypeScript | Source compilation | ✓ | 6.0.3 | — |
| Vitest | Unit + integration tests | ✓ | 4.1.5 | — |
| Playwright | E2E smoke | ✓ | 1.59.1 | — |
| `idb` | Save layer | ✓ | 8.0.3 | LocalStorage adapter (already shipped in `src/save/`) |
| `lz-string` | Save compression | ✓ | 1.5.0 | — |
| `crc-32` | Save checksum | ✓ | 1.2.2 | — |
| `zod` | Schema validation | ✓ | 4.4.3 | — |
| `gray-matter` | Markdown frontmatter | ✓ | 4.0.3 | — |
| `yaml` | YAML parsing | ✓ | 2.8.4 | — |
| `inkjs` | Ink runtime | ✓ | 2.4.0 | — |
| `inklecate` | Ink build-time compilation | ✓ | 1.8.1 (binaries shipped per platform) | — |
| `happy-dom` | Vitest DOM env | ✓ | 20.9.0 | — |
| `fake-indexeddb` | IDB tests | ✓ | 6.2.5 | — |
| `eslint` + `eslint-plugin-boundaries` | CORE-10 firewall | ✓ | 9.39.4 + 6.0.2 | — |
| **`zustand`** | State bridge (D-32) | ✗ | — | **Install in Phase 2** (`npm install zustand@^5.0.0`) |
| **`break_eternity.js`** | BigQty wrapper (D-31) | ✗ | — | **Install in Phase 2** (`npm install break_eternity.js@^2.1.3`) |
| `howler` | Audio (Phase 3 only) | ✗ | — | Phase 2 stubs `AudioContext.resume()` only (D-21); Phase 3 installs and wires Howler. |
| AudioContext API | Begin gesture (AEST-07) | ✓ (browser) | All evergreen + iOS Safari | None — handled gracefully in `bootstrapAudioContext()` (returns `null`). |
| `navigator.storage.persist()` API | CORE-05 (already shipped) | ✓ in modern browsers; ✗ in iOS Safari | — | Phase 1's `requestPersistence()` returns `apiAvailable: false` and the toast doesn't fire. |
| IndexedDB | Save primary (already shipped) | ✓ in all browsers; ✗ in private mode (some) | — | Phase 1's `LocalStorageDBAdapter` fallback. |

**Missing dependencies with no fallback:** None.

**Missing dependencies with fallback:** None blocking — Howler.js is intentionally Phase-3 (D-21).

## Validation Architecture

### Test Framework

| Property | Value |
|----------|-------|
| Framework | Vitest 4.1.5 + Playwright 1.59.1 |
| Config files | `vitest.config.ts` (env: happy-dom; pre-existing) + `playwright.config.ts` (pre-existing — first specs land Phase 2) |
| Quick run command | `npm test` (= `vitest run --passWithNoTests=false`) |
| Full suite command | `npm run ci` (= `lint + test + validate:assets + build`) |
| E2E run command | `npx playwright test` |

### Phase Requirements → Test Map

| Req ID | Behavior | Test Type | Automated Command | File Exists? |
|--------|----------|-----------|-------------------|-------------|
| CORE-02 | Sim runs deterministic fixed-timestep loop, advancing by elapsed real time | unit | `vitest run src/sim/scheduler/tick.test.ts` | Wave 0 |
| CORE-03 | Closing tab + returning advances by elapsed time, capped at 24h | unit | `vitest run src/sim/scheduler/catchup.test.ts` | Wave 0 |
| CORE-11 | Sim refuses negative deltas + clamps offline at 24h | unit | `vitest run src/sim/scheduler/catchup.test.ts -t 'refuses negative'` | Wave 0 |
| CORE-11 | Sim refuses negative deltas (integration with FakeClock) | integration | `vitest run src/sim/scheduler/clock.test.ts` | Wave 0 |
| GARD-01 | Plant a seed into unoccupied tile | unit | `vitest run src/sim/garden/commands.test.ts -t 'plantSeed'` | Wave 1A |
| GARD-01 | Click empty tile → seed picker appears at correct screen coords (DOM) | integration | `vitest run src/ui/garden/SeedPicker.test.tsx` | Wave 1A |
| GARD-02 | Plant advances sprout → mature → ready over time | unit | `vitest run src/sim/garden/growth.test.ts` | Wave 1A |
| GARD-02 | Growth state survives save round-trip + load | integration | `vitest run src/save/round-trip.test.ts -t 'plant growth state'` | Wave 1A (extends existing test) |
| GARD-03 | Harvest mature plant yields exactly one fragment, empties tile | unit | `vitest run src/sim/garden/commands.test.ts -t 'harvest'` | Wave 1B |
| GARD-04 | Compost immature plant + tonal beat | unit + UI | `vitest run src/sim/garden/commands.test.ts -t 'compost'` + `src/ui/garden/CompostBeat.test.tsx` | Wave 1B |
| MEMR-01 | Each harvest yields exactly one fragment from authored pool gated by Season + progression | unit | `vitest run src/sim/memory/selector.test.ts -t 'one fragment per harvest'` | Wave 1B |
| MEMR-02 | Fragments authored in `/content/seasons/01-soil/`, compiled at build | manual + CI | `npm run build` succeeds with Season-1 content present; loader test green | Wave 1B (extends `src/content/loader.test.ts`) |
| MEMR-03 | Stable string IDs (regex enforced) | unit | `vitest run src/content/loader.test.ts -t 'rejects numeric id'` (existing) | ✅ |
| MEMR-04 | Memory Journal lists every collected fragment, organized by Season | integration | `vitest run src/ui/journal/Journal.test.tsx` | Wave 1B |
| MEMR-05 | Player can read fragment in full; text is selectable + copy-pasteable (DOM, not canvas) | integration | `vitest run src/ui/journal/Journal.test.tsx -t 'selectable text'` | Wave 1B |
| MEMR-06 | Selector deterministic; respects gating; no duplicates within playthrough until exhausted | unit | `vitest run src/sim/memory/selector.test.ts -t 'no duplicates' + 'gating' + 'deterministic'` | Wave 1B |
| STRY-01 | Lura appears at gate during Season 1 with text-message-cadence dialogue authored in Ink | integration + e2e | `vitest run src/ui/dialogue/LuraDialogue.test.tsx` + Playwright e2e | Wave 2A |
| STRY-06 | All dialogue is `.ink` compiled to JSON | manual + CI | `npm run compile:ink` produces `src/content/compiled-ink/season1/lura-*.ink.json` | Wave 2A |
| STRY-07 | Keeper has no dialogue beyond final binary choice (Phase 7) | manual | Vacuously true; document in PLAN.md verification | ✅ (vacuous) |
| STRY-10 | Story progression gates on tick count, not wall time | unit | `vitest run src/sim/narrative/lura-gate.test.ts -t 'gates on harvest count'` + clock-cheat test (FakeClock advance ≠ beat advance) | Wave 2A |
| AEST-07 | First screen is "Begin" gesture gate that calls `AudioContext.resume()` | integration + e2e | `vitest run src/ui/begin/BeginScreen.test.tsx -t 'resume on tap'` + Playwright e2e | Wave 1A |
| UX-01 | Single Begin screen with no UI clutter; UI grows progressively | manual + integration | A Dark Room rule manual verification + journal-icon-hidden-pre-harvest test | Wave 1A + Wave 1B |
| UX-02 | Returning-player letter from the garden, in voice | integration | `vitest run src/ui/letter/Letter.test.tsx` | Wave 2B |
| UX-10 | Save on `visibilitychange` hidden, on `beforeunload`, on Season transitions | integration | `vitest run src/save/lifecycle.test.ts` (NEW) | Wave 0 (or extends existing round-trip) |
| UX-11 | Numbers display as 1.2K / 4.5M / scientific past threshold | unit | `vitest run src/sim/numbers/format.test.ts` | Wave 0 |
| PIPE-02 | Initial bundle excludes Seasons 2-7; per-Season lazy chunks | structural | `npm run build` + filesystem assertion (new `scripts/check-bundle-split.mjs`) | Wave 1B |
| PIPE-07 | E2E smoke: load → begin → plant → fast-forward → harvest → journal-shows-fragment → reload → fragment-persists | e2e | `npx playwright test tests/e2e/season1-loop.spec.ts` | Wave 2C |

### Sampling Rate

- **Per task commit:** `npm test` (Vitest unit + integration only; Playwright excluded for speed; current p50 ≈ ~5s based on Phase 1's 53-tests-in-12-files rate)
- **Per wave merge:** `npm run ci` (lint + test + validate:assets + build); manual `npx playwright test` for Wave 2C
- **Phase gate:** `npm run ci` green AND `npx playwright test` green before `/gsd-verify-work`

### Wave 0 Gaps

Wave 0 (the foundations plan) is the only plan that adds testing infrastructure beyond what Phase 1 shipped:

- [ ] `src/sim/scheduler/clock.test.ts` — FakeClock fixture + monotonic invariants
- [ ] `src/sim/scheduler/tick.test.ts` — accumulator drain math + tick rate
- [ ] `src/sim/scheduler/catchup.test.ts` — 24h cap + negative-delta refusal
- [ ] `src/sim/numbers/big-qty.test.ts` — arithmetic + comparison + serialization round-trip
- [ ] `src/sim/numbers/format.test.ts` — UX-11 thresholds (1.2K, 4.5M, etc.)
- [ ] `src/save/lifecycle.test.ts` — visibilitychange + beforeunload + Season transition save firing (UX-10)
- [ ] `src/store/store.test.ts` — slice composition + selectors
- [ ] `src/store/garden-slice.test.ts` — command queueing + apply-result semantics

Wave 1A (planting + growth + Begin) gaps:
- [ ] `src/sim/garden/commands.test.ts` — plantSeed, harvest, compost (pure functions)
- [ ] `src/sim/garden/growth.test.ts` — state machine
- [ ] `src/sim/garden/auto-harvest.test.ts` — D-10 offline branch
- [ ] `src/ui/begin/BeginScreen.test.tsx` — tap calls bootstrapAudioContext
- [ ] `src/ui/garden/SeedPicker.test.tsx` — popover positioning + dismiss

Wave 1B (memory + journal + fragments + content) gaps:
- [ ] `src/sim/memory/selector.test.ts` — deterministic + gating + no-dup + exhaustion
- [ ] `src/ui/journal/Journal.test.tsx` — list + select + copy
- [ ] `src/ui/journal/FragmentRevealModal.test.tsx` — D-25 reveal flow
- [ ] `src/content/loader.test.ts` extension — Season-1 fragments load via lazy path
- [ ] `scripts/check-bundle-split.mjs` — PIPE-02 structural test

Wave 2A (Lura beats) gaps:
- [ ] `src/sim/narrative/lura-gate.test.ts` — 1st/4th/8th gating + STRY-10 tick-count semantics
- [ ] `src/ui/dialogue/LuraDialogue.test.tsx` — Ink runtime integration + drip cadence
- [ ] `src/ui/dialogue/ink-runtime.test.ts` — variable wiring

Wave 2B (offline letter) gaps:
- [ ] `src/sim/offline/events.test.ts` — `OfflineEventBlock` schema + aggregator
- [ ] `src/ui/letter/Letter.test.tsx` — Ink template render + dismiss
- [ ] `src/ui/letter/letter-renderer.test.ts` — variable mapping table coverage

Wave 2C (e2e) gaps:
- [ ] `tests/e2e/season1-loop.spec.ts` — full loop smoke
- [ ] Playwright fast-forward mechanism (URL flag `?devtime=fake`, recommended) — implementation in `src/sim/scheduler/clock.ts` + boot wiring

**No framework install needed** — Vitest, Playwright, fake-indexeddb, happy-dom are all already on disk from Phase 1.

### Sim-Clock Injection for Playwright Fast-Forward

The Phase 2 e2e (PIPE-07) needs to fast-forward growth without waiting 2–5 minutes per plant. Three viable mechanisms:

| Mechanism | How | Pros | Cons |
|-----------|-----|------|------|
| **URL flag (`?devtime=fake`) + FakeClock injection** ⭐ | Boot reads `URLSearchParams`; if `devtime=fake`, the scheduler binds to a `FakeClock` instance exposed on `window.__tlgFakeClock`. Playwright calls `await page.evaluate(() => window.__tlgFakeClock.advance(5 * 60 * 1000))` to fast-forward 5 minutes. | Cleanly reusable in Vitest tests via the same FakeClock; no production code path differs; cleanly excluded from prod builds via build-time check. | URL flag must be respected only in dev/test contexts (Vite's `import.meta.env.DEV`). |
| Hidden dev hotkey | `?+fast` keyboard combo advances FakeClock | Useful for manual playtest. | Doesn't compose with Playwright; still need the URL flag. |
| Sim-tick-count manipulation | E2E test directly mutates `appStore.getState().lastTickAt` | Avoids the FakeClock entirely. | Bypasses the whole scheduler boundary; risk of false-positive test results if scheduler has bugs. |

**Recommendation:** Implement the URL flag + FakeClock injection (option ⭐). The FakeClock already exists in `src/sim/scheduler/clock.ts` for Vitest tests; the URL flag merely chooses the production wallClock vs the dev FakeClock at boot. Phase 2's PIPE-07 spec ships with this mechanism. Add a guard: in `import.meta.env.PROD` builds, the URL flag is silently ignored (the wallClock is always used).

## Security Domain

`security_enforcement` is not explicitly false in `.planning/config.json`, so this section is included.

### Applicable ASVS Categories

| ASVS Category | Applies | Standard Control |
|---------------|---------|-----------------|
| V2 Authentication | no | No accounts in v1 (single-player local). |
| V3 Session Management | no | Same. |
| V4 Access Control | no | Same. |
| V5 Input Validation | yes | All save imports go through `SaveEnvelopeSchema` (Zod) and the 50MB cap (already shipped Phase 1). All Ink-runtime variable injection is type-checked at the JS boundary; no string concatenation into Ink source at runtime. |
| V6 Cryptography | partial (integrity only) | CRC-32 checksum on save envelopes (already shipped Phase 1) detects corruption, NOT adversarial tampering. Phase 2 inherits this policy — single-player save tampering is by-design acceptable per `src/save/envelope.ts` `SaveCorruptError` doc comment. |
| V7 Error Handling and Logging | partial | Toast surfaces persistence-result respectfully (D-30); no PII in logs (none collected in v1). |
| V8 Data Protection | yes | No telemetry in Phase 2; saves are local-only; Base64 export is user-initiated and contains no secrets. |
| V12 Files and Resources | yes | `validate-assets.mjs` already shipped Phase 1; no new asset surfaces in Phase 2 (D-26 = primitives only). |

### Known Threat Patterns for Phase 2 Stack

| Pattern | STRIDE | Standard Mitigation |
|---------|--------|---------------------|
| Save tampering (player edits Roothold via DevTools) | Tampering | **Accepted** — single-player; CRC-32 detects accidental corruption only. Documented in `src/save/envelope.ts` (already Phase 1). |
| Malformed Base64 import (DoS via giant inflated string) | Denial-of-service | 50MB cap before lz-string decompression (already Phase 1). |
| System-clock manipulation to skip Lura beats | Tampering | Beats gate on tick count (harvest events), not wall time (STRY-10). FakeClock advance ≠ beat advance unless harvests also fire. |
| `Date.now()` returns negative delta (clock-rewind cheat) | Tampering | Scheduler refuses negative deltas (CORE-11); state does not advance; logged once. |
| AudioContext blocked → muted experience that misleads about audio failures | Information disclosure (sort of) / UX | Bootstrap function returns `null` gracefully; Phase 2 has no audio anyway. |
| Cross-origin script injection via Ink content | XSS | Ink content is repo-controlled (no user-authored Ink); inkjs renders to string and React renders strings, not HTML. No `dangerouslySetInnerHTML`. |
| Storage eviction silently wiping save | Tampering / data loss | `navigator.storage.persist()` request (CORE-05, already Phase 1) + LocalStorage fallback + Base64 export; soft toast respects user agency (D-30). |

## Project Constraints (from CLAUDE.md)

These directives have the same authority as locked decisions and constrain Phase 2 plans:

- **Stack is locked, do not re-litigate:** Phaser 4, React 19, Zustand 5, break_eternity.js (via BigQty), Ink + inkjs, Howler.js, IndexedDB + LocalStorage + lz-string + versioned schema + Base64 export, Markdown+frontmatter / YAML / .ink in `/content/`, Vitest + Playwright. Phase 2 plans must use these; alternatives are out of scope unless explicitly requested.
- **Architectural firewall (load-bearing):** Phaser owns the canvas; React 19 owns the UI shell; Zustand bridges them; simulation core (`src/sim/`) does not import from `src/render/` or `src/ui/`. Enforced by `eslint.config.js` `boundaries/element-types` rule. Plans that introduce sim→render or sim→ui edges fail CI.
- **TypeScript strict; no `any` in production code.** Phase 2 sim code is fully typed; Zod schemas produce inferred types throughout.
- **Player-visible strings are externalized in `/content/`, never hardcoded.** Lura's lines, the letter, the Begin copy, the post-harvest acknowledgement, the persistence-denied toast, the journal empty-state — all in `/content/`.
- **Memory fragment IDs are stable strings (`season3.canopy.lura_07.vignette`), never numeric.** Already enforced by `FragmentSchema` regex.
- **Simulation modules are pure** — no `Date.now()`, no `setInterval`, no DOM, no fetch. **Inject time as a parameter; the tick scheduler owns wall-clock access.** This is exactly D-33 + Pattern 1.
- **BigNumbers go through the typed `BigQty` wrapper around `break_eternity.js`. Never raw `Decimal` values in app code.** This is exactly D-31 + Pattern 2.
- **Save format always carries `{schemaVersion, payload, checksum}`. Never serialize raw state.** Already shipped by `src/save/envelope.ts` Phase 1.
- **New AI-generated assets must carry full provenance metadata and pass the curation gate.** Phase 2 ships zero AI-generated assets (D-26 = primitives), so the gate is not exercised; remains green.
- **Anti-FOMO doctrine** must be consulted at every UX decision. Phase 2's UX decisions all comply: no daily login bonus, no streaks, no limited-time content, no nag notifications, no loss-aversion copy, no countdown timers in core UI, persistence-denied is a soft in-voice toast (not nag).
- **Banner concerns 1–10** (CLAUDE.md): all carry forward. Banner concern #1 (story ends but loop doesn't) is constrained by Phase 2's growth/economy choices not foreclosing Season 7's finite ceiling — confirmed by Pattern 7 (`V1Payload` extension, no Roothold pre-allocation; Phase 4 owns the prestige machinery).
- **Tone:** Player-facing copy "warm, specific, intermittent, sometimes funny, sometimes devastating." Lura is the warmth anchor — write her as the contrast, not a co-griever.
- **GSD config:** Mode=YOLO (auto-approve gates), Granularity=Standard (5–8 phases), Plans run in parallel within a phase, Quality model profile, research+plan-check+verifier all on, `nyquist_validation: true`. Plans use the Validation Architecture section above.

## MVP Slice Proposal

Phase 2's mode is `mvp` (vertical-slice planning). Each plan should deliver an end-to-end thin slice rather than a horizontal layer. Recommended **5 plans across 3 waves**:

### Wave 0: Foundations (1 plan, blocks everything else)

**Plan 02-01 — Foundations: BigQty + Zustand store + Tick scheduler**
- Install `zustand@^5` and `break_eternity.js@^2.1.3`.
- Author `src/sim/numbers/big-qty.ts` + `format.ts` with full Vitest coverage (UX-11 surface).
- Author `src/sim/scheduler/clock.ts`, `tick.ts`, `catchup.ts` with Vitest coverage (CORE-02, CORE-03, CORE-11). Add the no-`Date.now`-in-sim ESLint rule.
- Author `src/store/store.ts` + four slices (garden, memory, narrative, session) with Vitest tests of slice composition + selectors.
- Extend `V1Payload` per D-34 (D-19's `offlineEvents`, `unlockedPlantTypes`, `luraBeatProgress`, `settings.persistenceToastShown`).
- Add `src/save/lifecycle.test.ts` covering UX-10 trigger points.
- Wire the scheduler into `Garden` scene (tiny placeholder scene) so the live tick boots end-to-end.
- Adds `src/game/event-bus.ts` for the Phaser EventBus singleton (per Phaser 4 template pattern).
- Verifies `npm run ci` green.

**Output: A running scaffold where the sim ticks, the store updates, the save schema is extended, and the firewall holds.** Nothing player-visible yet — but Wave 1 plans can build features without re-running Wave 0's infrastructure.

### Wave 1: Two parallel vertical slices (2 plans)

**Plan 02-02 — Vertical slice: Begin + Plant + Grow**
- Authors Season-1 plant types (2–3) in `src/sim/garden/plants.ts` with durations + tonal identity.
- Implements `src/sim/garden/{types,growth,commands}.ts` (plantSeed + grow).
- Implements `src/render/garden/{tile-renderer,plant-renderer,ready-pulse,tile-coords}.ts`.
- Implements `src/ui/begin/{BeginScreen,use-audio-bootstrap}.ts` (D-21, D-22, AEST-07).
- Implements `src/ui/garden/SeedPicker.tsx` (D-02 inline popover).
- Wires Phaser's tile pointerdown → EventBus → React popover → command dispatch.
- Implements first-interaction gesture handler for returning players (D-22).
- Tests: vitest unit + integration (Begin tap calls resume; tile click positions popover; plant grows through stages).
- E2E manual smoke: launch → press Begin → click empty tile → seed picker → place seed → watch sprout primitive appear → fast-forward via FakeClock.
- Satisfies: AEST-07, UX-01, GARD-01, GARD-02 (partial — full save round-trip in Plan 02-04).

**Plan 02-03 — Vertical slice: Harvest + Journal + Compost + Fragments**
- Author Season-1 fragments (≥10) in `/content/seasons/01-soil/fragments.yaml` and a few long-form `.md` per the existing convention.
- Implements `src/sim/memory/{selector,pool}.ts` (MEMR-06).
- Implements `src/sim/garden/commands.ts` `harvest` + `compost` (GARD-03, GARD-04).
- Implements `src/ui/journal/{Journal,FragmentRevealModal,journal-icon}.tsx` (MEMR-04, MEMR-05, D-23, D-24, D-25).
- Implements GARD-04 compost tonal beat (Ink-authored line per D-07 model — see Open Question 2).
- Implements PIPE-02 lazy-loading wiring in `src/content/loader.ts` and `scripts/check-bundle-split.mjs`.
- Tests: vitest unit (selector deterministic / gated / no-dup) + integration (Journal renders fragments; selectable text; reveal modal).
- E2E manual smoke: launch → plant → fast-forward → harvest → reveal modal → close → journal shows it.
- Satisfies: GARD-03, GARD-04, MEMR-01, MEMR-02, MEMR-04, MEMR-05, MEMR-06, PIPE-02, UX-01 (Journal-icon-on-first-harvest reveal), UX-11 (number formatting in journal counts).

**Wave 1 plans run in parallel.** Plan 02-02 and Plan 02-03 share `src/sim/garden/types.ts` (small surface, lock in Wave 0) and Plan 02-03 depends on Plan 02-02 only for the harvest action wiring; both can be drafted simultaneously and merged with a small integration moment.

### Wave 2: Two parallel vertical slices + e2e (3 plans)

**Plan 02-04 — Vertical slice: Lura's Three Beats**
- Replaces `npm run compile:ink` no-op stub with `scripts/compile-ink.mjs` invoking the `inklecate` package.
- Authors `/content/dialogue/season1/lura-{arrival,mid,farewell}.ink` (Ink files).
- Implements `src/sim/narrative/{lura-gate,beat-queue}.ts` (D-13, D-14, STRY-10).
- Implements `src/ui/dialogue/{LuraDialogue,ink-runtime,ink-renderer}.tsx` (D-15, D-16, STRY-01, STRY-06).
- Implements `src/render/garden/gate-renderer.ts` (gate visual + indicator on pending beat).
- Tests: vitest unit (gate fires at 1st/4th/8th harvest; doesn't fire on FakeClock advance alone — STRY-10) + integration (Ink runtime drives drip cadence).
- E2E manual smoke: harvest 1st fragment → gate glows → click gate → Lura arrival dialogue → continue.
- Satisfies: STRY-01, STRY-06, STRY-07 (vacuous), STRY-10.

**Plan 02-05 — Vertical slice: Letter from the Garden + Settings + Save Lifecycle Hooks + Playwright E2E (PIPE-07)**
- Authors `/content/dialogue/season1/letter-from-the-garden.ink` (D-17, D-18) with the slot vocabulary from D-19.
- Implements `src/sim/offline/events.ts` (`OfflineEventBlock` zod schema + aggregator from sim's silent-mode events).
- Implements `src/ui/letter/{Letter,letter-renderer}.tsx` (D-20).
- Implements `src/ui/settings/{Settings,persistence-toast}.tsx` (D-28, D-29, D-30).
- Wires save-lifecycle hooks (visibilitychange, beforeunload, Season transition stub) per UX-10.
- Implements `src/sim/garden/auto-harvest.ts` (D-10).
- Implements URL-flag `?devtime=fake` FakeClock injection at boot for Playwright.
- Authors `tests/e2e/season1-loop.spec.ts` (PIPE-07 full smoke).
- Tests: vitest unit + integration (letter renders Ink slots; settings export round-trips; save fires on visibility change; URL-flag injects FakeClock); Playwright e2e green.
- Satisfies: UX-02, UX-10, PIPE-07 + finishes any GARD-02-style save-survival assertions left dangling.

**Wave 2 plans 02-04 and 02-05 run in parallel.** Plan 02-05 depends on plan 02-04's `src/sim/narrative/` only for the `lura_was_here` slot; plan 02-04 doesn't depend on 02-05. Both depend on Wave 1 work being merged. Plan 02-05 owns Playwright PIPE-07.

### Why this shape

- **Wave 0 lands the three foundations together** because they're tightly coupled (the scheduler updates the store; BigQty values flow through state; the firewall rule enforces the boundary). Splitting them risks circular blocking.
- **Wave 1's two slices each touch sim + store + render + ui** — true vertical slices, not horizontal layers. Plan 02-02's smoke test (plant a seed, see it grow) is end-to-end. Plan 02-03's smoke test (harvest, see fragment in journal) is end-to-end.
- **Wave 2 isolates the heaviest authored content (Lura's Ink + the letter) into the latest plans** so the writer's work integrates against working mechanics, not against speculative shapes.
- **PIPE-07 lives in the last plan** because it asserts the full loop. Earlier-plan e2e tests would assert partial loops — fragile.
- **Each plan ships `npm run ci` green standalone.** No plan leaves CI red mid-phase.

## Sources

### Primary (HIGH confidence)

- `.planning/phases/02-season-1-vertical-slice-soil/02-CONTEXT.md` — User decisions D-01 through D-34.
- `.planning/REQUIREMENTS.md` — 24 Phase 2 REQ-IDs verbatim.
- `.planning/PROJECT.md` — story bible synthesis, hard thematic constraints.
- `.planning/ROADMAP.md` — Phase 2 success criteria (5).
- `.planning/STATE.md` — Phase 1 verification table (16/16 PASS).
- `.planning/anti-fomo-doctrine.md` — 17 banned UX patterns + review checklist.
- `.planning/season-7-end-state.md` — principle-level rest-state contract.
- `.planning/phases/01-foundations-and-doctrine/01-CONTEXT.md` — Phase 1 D-01..D-12 (save format, content pipeline, firewall locks).
- `.planning/research/STACK.md` — locked stack rationale, version compatibility, content pipeline shape.
- `.planning/research/ARCHITECTURE.md` — three-layer firewall, tick scheduler shape, six architectural patterns.
- `.planning/research/PITFALLS.md` — 14 critical pitfalls (esp. #1, #4, #6, #7, #11, #12).
- `CLAUDE.md` — stack lock, architectural firewall, banner concerns 1–10, code style.
- `src/save/index.ts`, `src/save/migrations.ts`, `src/save/envelope.ts`, `src/save/codec.ts`, `src/save/db.ts`, `src/save/db-localstorage-adapter.ts`, `src/save/persist.ts`, `src/save/snapshots.ts` — Phase 1 save layer (frozen).
- `src/content/index.ts`, `src/content/loader.ts`, `src/content/schemas/{fragment,season,index}.ts` — Phase 1 content pipeline.
- `src/game/main.ts`, `src/game/scenes/Boot.ts` — Phaser entry.
- `src/App.tsx`, `src/PhaserGame.tsx` — React shell + Phaser bridge.
- `eslint.config.js` — flat config + `eslint-plugin-boundaries` element types.
- `package.json` — exact dependencies + scripts (verified 2026-05-09).
- `vitest.config.ts`, `playwright.config.ts`, `vite.config.ts` — test + build infrastructure.
- `content/README.md` — content authoring conventions.
- `content/seasons/00-demo/fragments.yaml` — demo to be removed in Phase 2.
- `node_modules/inkjs/ink.d.mts` + `node_modules/inkjs/README.md` — inkjs API verification.
- `node_modules/inklecate/README.md` + `node_modules/inklecate/package.json` — inklecate npm wrapper API.

### Secondary (MEDIUM confidence — verified via WebSearch + cross-referenced with Primary)

- [Phaser 4 React template EventBus pattern (May 2025 announcement, prepared for Phaser 4)](https://phaser.io/news/2025/05/bringing-our-phaserjs-templates-into-the-future) — cross-referenced with `src/PhaserGame.tsx`'s template structure.
- [Phaser input documentation — pointerdown on interactive game objects](https://docs.phaser.io/phaser/concepts/input)
- [Phaser EventEmitter](https://docs.phaser.io/api-documentation/class/events-eventemitter)
- [Zustand 5 createStore (vanilla)](https://zustand.docs.pmnd.rs/reference/apis/create-store)
- [Zustand vanilla store usage outside React](https://github.com/pmndrs/zustand/discussions/1866)
- [Vite import.meta.glob lazy code-splitting](https://vite.dev/guide/features) — confirmed default-lazy when `eager` is omitted/false.
- [Web Audio Autoplay Policy + AudioContext.resume()](https://developer.chrome.com/blog/web-audio-autoplay)
- [MDN Autoplay guide](https://developer.mozilla.org/en-US/docs/Web/Media/Guides/Autoplay)
- [Fix Your Timestep — Gaffer On Games](https://gafferongames.com/post/fix_your_timestep/)
- [break_eternity.js (Patashu)](https://github.com/Patashu/break_eternity.js) — TypeScript-native, ships `index.d.ts`.
- [inkjs README — getting/setting variables](https://github.com/y-lohse/inkjs)
- npm registry verification (`npm view <pkg> version`) for phaser, zustand, break_eternity.js, inkjs, howler, inklecate (2026-05-09).

### Tertiary (LOW confidence — flagged for verification during planning)

- The exact tile→DOM coordinate mapping under `Phaser.Scale.FIT` letterboxing (Assumption A5) — verify in Plan 02-02.
- The `inklecate` npm wrapper's behavior on Windows with the `inputFilepath`/`outputFilepath` argument shape — verify with one real compile in Plan 02-04 (Assumption A6).

## Metadata

**Confidence breakdown:**
- Standard stack: HIGH — entire stack already locked + installed + verified.
- Architecture: HIGH — patterns are documented in `.planning/research/ARCHITECTURE.md` and align with the existing scaffolded structure in `eslint.config.js`.
- Tick scheduler: HIGH — canonical pattern from Gaffer On Games + research doc; one degree of design freedom (tick rate) is justified at 5Hz.
- BigQty: HIGH — `break_eternity.js` is TypeScript-native + drop-in; the wrapper surface is small and obvious.
- Zustand-Phaser bridge: HIGH — exact pattern is the official template's; `src/PhaserGame.tsx` is already shaped for it.
- Ink integration: MEDIUM — `inkjs` and `inklecate` are installed and documented; the variable-substitution pattern is verified, but the inklecate Windows-binary invocation needs one real run in Plan 02-04.
- Letter slot vocabulary: MEDIUM — three slots are ample for D-19's contract, but playtest may want more (acknowledged in Open Question 5 and Claude's Discretion).
- Pitfalls: HIGH — derived from `.planning/research/PITFALLS.md` (14 documented + 2 phase-specific surfacings) plus implementation specifics.
- Validation Architecture: HIGH — every requirement maps to a concrete test file; Wave-0 gaps explicit.

**Research date:** 2026-05-09
**Valid until:** 2026-06-09 (30 days; stack is stable, no rapidly-evolving deps in Phase 2 surface)

## REQ-ID Coverage Map

| REQ-ID | Requirement | Sections in this RESEARCH.md addressing it |
|--------|-------------|-------------------------------------------|
| CORE-02 | Deterministic, fixed-timestep sim advancing by elapsed real time | Pattern 1 (Tick Scheduler / Monotonic Clock); Architectural Responsibility Map row "Tick scheduler"; Validation Architecture row CORE-02 |
| CORE-03 | Closed/returned game progresses by elapsed time, capped at 24h | Pattern 1; Boot path subsection; Validation Architecture row CORE-03 |
| CORE-11 | Sim refuses negative deltas + caps offline at 24h | Pattern 1 (`drainTicks` rejects `accumulatorMs < 0`); Pitfall 1 + Common Pitfall 1; Security Domain row "system-clock manipulation"; Validation Architecture row CORE-11 |
| GARD-01 | Plant a seed into unoccupied tile | Pattern 4 (Inline Seed Picker); Architectural Responsibility Map; MVP Slice Plan 02-02; Validation Architecture row GARD-01 |
| GARD-02 | Visible growth state, advances over time, persists across save | Pattern 1 (sim ticks growth); Pattern 7 (V1Payload extension stores plant state); Architectural Responsibility Map; MVP Slice Plan 02-02 |
| GARD-03 | Harvest mature plant → exactly one fragment; tile empties | MVP Slice Plan 02-03; Validation Architecture row GARD-03 |
| GARD-04 | Compost immature plant + tonal beat | MVP Slice Plan 02-03; Open Question 2; Validation Architecture row GARD-04 |
| MEMR-01 | Each harvest yields exactly one fragment from gated authored pool | Pattern (Fragment Selector — sim/memory module); MVP Slice Plan 02-03 |
| MEMR-02 | Fragments authored in `/content/`, compiled per-Season at build | Already shipped Phase 1; Phase 2 drops Season-1 files (Pattern 8 lazy split); MVP Slice Plan 02-03 |
| MEMR-03 | Stable string IDs (regex enforced) | Already enforced by `FragmentSchema`; Common Pitfall — numeric IDs; MVP Slice Plan 02-03 |
| MEMR-04 | Memory Journal lists fragments by Season | Architectural Responsibility Map row "Memory Journal"; MVP Slice Plan 02-03 |
| MEMR-05 | Selectable + copy-pasteable fragment text (DOM, not canvas) | Architectural Responsibility Map; Anti-Patterns ("Rendering Memory Journal text inside Phaser"); MVP Slice Plan 02-03 |
| MEMR-06 | Deterministic selector with gating + no-dup until exhaustion | Pattern (Fragment Selector); Common Pitfall 8 (exhaustion); MVP Slice Plan 02-03 |
| STRY-01 | Lura at gate during S1 with text-message-cadence Ink dialogue | Pattern 5 (Ink Compilation + Runtime); Architectural Responsibility Map; MVP Slice Plan 02-04 |
| STRY-06 | All dialogue is `.ink` compiled to JSON | Pattern 5; MVP Slice Plan 02-04 (compile-ink.mjs) |
| STRY-07 | Keeper has no dialogue beyond final binary choice (Phase 7) | Vacuously satisfied; documented in Phase Requirements table + Validation Architecture |
| STRY-10 | Story progression gates on tick count, not wall time | Pattern 1 + Lura beat gating in `src/sim/narrative/`; Common Pitfall (tick-count gating); MVP Slice Plan 02-04 |
| AEST-07 | First screen "Begin" gesture gate, calls `AudioContext.resume()` | Pattern 9 (AudioContext.resume() Bootstrap); Common Pitfall 5 (iOS Safari); Common Pitfall 9 (letter dismiss); MVP Slice Plan 02-02 |
| UX-01 | Single Begin screen, no clutter; UI grows progressively | D-21, D-22, D-23 in User Constraints; A Dark Room rule applied across slices; MVP Slice Plan 02-02 (Begin) + Plan 02-03 (Journal reveals) |
| UX-02 | Returning-player letter from the garden, in voice | Pattern 6 (Letter as Ink Template); MVP Slice Plan 02-05 |
| UX-10 | Save on visibilitychange/beforeunload/Season transition | Pattern 7 (V1Payload extension); Common Pitfall 7 (beforeunload synchronous path); Open Question 3 (Season-transition hook is dormant Phase 2); MVP Slice Plan 02-05 |
| UX-11 | Numbers as 1.2K / 4.5M / scientific past threshold | Pattern 2 (BigQty `format()` + `formatHumanReadable`); MVP Slice Plan 02-01 |
| PIPE-02 | Player loads only current Season; future Seasons not in initial bundle | Pattern 8 (Per-Season Lazy Loading); MVP Slice Plan 02-03 |
| PIPE-07 | Playwright e2e smoke covering full loop | Validation Architecture (Sim-Clock Injection); MVP Slice Plan 02-05 |

**All 24 REQ-IDs are addressed.** Each maps to at least one architectural pattern, one or more files in the proposed structure, and at least one test in the Validation Architecture.

---
*Research date: 2026-05-09*
*Phase: 2 — Season 1 Vertical Slice (Soil)*