# Phase 1: Foundations & Doctrine — Research
**Researched:** 2026-05-08
**Domain:** Project scaffolding, browser save framework, content build pipeline, AI-asset provenance gate, architectural-boundary linting, principle-level doctrine documents
**Confidence:** HIGH (all stack versions verified against npm registry; all integration patterns verified against official docs)
## Summary
Phase 1's research target was narrow by design — the user has already locked the stack (Phaser 4, React 19, Vite, TypeScript, idb, lz-string, Zod, Vitest, Playwright) and rejected every overengineered shape (no curator workflow, no two-stage AI promotion, no lint rules on UX strings, no pre-allocated save slots, no BigQty/Zustand/tick scheduler in this phase). Research therefore concentrated on **the cheapest correct shape** for each of the five Phase-1 success criteria: (1) the official `npm create @phaserjs/game@latest` React+Vite+TS template structure and how to restructure `src/` into the firewall directories, (2) the ESLint boundary rule (`eslint-plugin-boundaries` v6.0.2 wins on cleanness), (3) a minimum-viable `idb` save layer with versioned `{schemaVersion, payload, checksum}` envelope, lz-string compression, last-3 snapshots, and Base64 export/import, (4) a Vite-native content pipeline using `import.meta.glob('/content/**/*', { eager, query: '?raw' })` + gray-matter + Zod (no separate build script needed), and (5) a 30-line standalone Node script that walks `assets/` and validates sidecar `.provenance.json` files.
All recommended package versions were verified against npm on 2026-05-08: Phaser 4.1.0, React 19.2.6, Vite 8.0.11, TypeScript 6.0.3, idb 8.0.3, lz-string 1.5.0, Zod 4.4.3, Vitest 4.1.5, Playwright 1.59.1, eslint-plugin-boundaries 6.0.2, crc-32 1.2.2, gray-matter 4.0.3, yaml 2.8.4, inkjs 2.4.0, inklecate 1.8.1.
**Primary recommendation:** Lean on the Phaser 4 official template heavily — do not restructure aggressively. Add the firewall directories (`src/sim/`, `src/render/`, `src/ui/`, `src/save/`, `src/content/`, `src/audio/`, `src/store/`) as siblings to the template's existing `src/game/` directory; the template's existing entry points (`src/main.tsx`, `src/App.tsx`, `src/PhaserGame.tsx`) keep working. This is the minimum-viable scaffold that exposes ESLint boundary targets without fighting the template.
## User Constraints (from CONTEXT.md)
### Locked Decisions
**AI Asset Pipeline Depth (D-01, D-02, D-03):**
- End-of-Phase-1 north-star reference set is **10–20 hand-curated AI generations** committed to the repo with full provenance metadata. Generated honestly with whatever tool was used (likely Claude/SD/Midjourney/etc. on a per-asset basis); the `model_id` and `checkpoint_hash` fields record what was actually used.
- **Tool/vendor choice deferred** — Phase 1 commits to the *schema* and *gate*, not a vendor. Tool consolidation happens in Phase 5 when production volume kicks in.
- **Curation gate is minimum-viable.** Sidecar `name.provenance.json` per asset under `/assets/` carrying the 6 required fields (`model_id`, `checkpoint_hash`, `prompt`, `seed`, `sampler`, `params`); CI script walks the tree and fails the build on any missing/invalid sidecar. Sample refused asset under `/assets/__samples__/refused/` (no sidecar) proves the gate works. **No** curator workflow, **no** two-stage promotion directory, **no** pre-commit hook, **no** CURATION-LOG.md ceremony.
**Save Schema v1 Scope (D-04, D-05, D-06):**
- v1 save payload is **minimal** — only what Phase 2 will write (garden tile state, plant growth data, harvested fragment IDs, `lastTickAt`, basic settings). It does NOT pre-allocate slots for Roothold, currentSeason, storyFlags, etc. Phase 4 ships a real `migrate_v1_to_v2` when Season-prestige state actually exists.
- Round-trip migration test in Phase 1 uses a **synthetic v0 → v1 migration** as the proof that the chain works. v0 is a tiny made-up prior schema (e.g., `{garden: []}`) used only to exercise the migration framework end-to-end.
- Save format `{schemaVersion, payload, checksum}` is locked. Checksum algorithm and exact migration registry shape are Claude's discretion.
**Doctrine Docs Concreteness (D-07, D-08, D-09):**
- Anti-FOMO doctrine is a **consolidation document** in `.planning/`. **No** lint rule on UX strings.
- Season 7 end-state design is **principle-level**, not treatment-level.
- Both doctrine documents live under `.planning/`.
**Project Scaffold Layout (D-10, D-11, D-12):**
- Use `npm create @phaserjs/game@latest` (React + Vite + TypeScript template). Restructure `src/` to expose `src/sim/`, `src/render/`, `src/ui/`, plus supporting `src/save/`, `src/content/`, `src/audio/`, `src/store/` as siblings.
- Authored content (`/content/**/*.{md,yaml,ink}`) lives at **repo root**.
- `/assets/` (with provenance sidecars) lives at repo root. Single package, **no monorepo / no workspaces**.
### Claude's Discretion
- Exact ESLint boundary rule choice (`eslint-plugin-boundaries` vs `no-restricted-paths`).
- Checksum algorithm (CRC32, simple hash, etc.).
- Migration registry shape.
- `idb` wrapper API surface inside `src/save/`.
- Vitest / Playwright config files; `vite.config.ts` boundary plugin choices.
- Where the Zod content schemas live and how the build step is invoked (Vite plugin vs separate `npm run build:content` script).
- Specific images for the 10–20 north-star generations.
### Deferred Ideas (OUT OF SCOPE)
- AI vendor lock-in / model pinning (Phase 5).
- `BigQty` wrapper around break_eternity.js (Phase 2).
- Empty Zustand store skeleton (Phase 2).
- Tick scheduler / monotonic clock (Phase 2).
- Season 7 treatment-level details (Phase 7).
- Anti-FOMO lint rule on UX strings (rejected).
- Curator workflow / two-stage asset promotion / pre-commit hook on assets (rejected).
- Visual regression testing (Phase 8).
- AudioContext / Howler.js setup (Phase 2).
- Phaser scene wiring or rendering (Phase 2-3).
- Ink dialogue authoring (Phase 2+).
## Phase Requirements
| ID | Description | Research Support |
|----|-------------|------------------|
| CORE-01 | Game loads in <5s in modern browsers (Chrome/Firefox/Safari/Edge last 2) on 25 Mbps | Phaser 4 template ships Vite 8 with sensible default code-splitting; the empty scaffold loads in well under 5s. The **enforcement** mechanism is a Playwright smoke test introduced in Phase 2 (PIPE-07); Phase 1 verifies by `npm run build` succeeding and visual sanity in dev. |
| CORE-04 | Save persists to IndexedDB with localStorage fallback | `idb` 8.0.3 wraps IndexedDB in promises; localStorage fallback is a try/catch around `openDB` failures. See "Save Layer Shape" below. |
| CORE-05 | `navigator.storage.persist()` called on first save with respectful surfacing of false | Available in Chrome/Firefox/Edge (Safari 17+ partial); when false, surface "saves may be cleared if storage runs low — export a backup from Settings" at next opportunity. |
| CORE-06 | Saves versioned `{schemaVersion, payload, checksum}`; refuse load on checksum mismatch with recovery option | crc-32 (`crc-32` package, 426k ops/sec, dependency-free, ~3KB) is the right shape. See "Checksum Choice" below. |
| CORE-07 | `migrate_vN_to_vN+1` chain with Vitest tests for every shipped migration | Ordered registry pattern; synthetic v0→v1 demo migration exercises the chain end-to-end. See "Migration Registry Shape" below. |
| CORE-08 | Last 3 pre-migration save snapshots retained; "restore previous save" reachable from settings (UI hooks land in Phase 4) | Separate `snapshots` object store keyed by `{schemaVersion, savedAt}`; pre-migration hook writes to it; pruner runs on each write. Phase 1 ships only the storage + retention; settings UI is Phase 4. |
| CORE-09 | Save export/import as Base64 text via Settings (function pair shipped Phase 1; UI button Phase 2+) | `lz-string.compressToBase64` of the JSON envelope is the export; `decompressFromBase64` is the import. Round-trip test in Vitest. |
| CORE-10 | `src/sim/` imports nothing from `src/render/` or `src/ui/` — enforced by ESLint boundary rules in CI | `eslint-plugin-boundaries` 6.0.2 with the `boundaries/element-types` rule. See "ESLint Boundary Rule" below. |
| PIPE-01 | Build compiles `/content/**/*.{md,yaml,ink}` into per-Season JSON via Zod-validated schemas; build fails on schema violation | Vite-native `import.meta.glob('/content/**/*', { eager: true, query: '?raw' })` + gray-matter + `yaml` + Zod, validated at build time. See "Content Pipeline" below. |
| PIPE-03 | AI asset pipeline records provenance per asset and refuses unprovenanced assets | Standalone `scripts/validate-assets.mjs` walks `assets/` (excluding `__samples__/refused/`); fails CI on any non-sidecar file lacking a sibling `.provenance.json` validated by a Zod schema. |
| PIPE-05 | `anti-FOMO doctrine` and `Season 7 end-state` design documents in `.planning/` before economy code | Outlined below in "Doctrine Doc Outlines". Principle-level, not treatment. |
| PIPE-06 | Vitest unit tests cover all save migrations and run on every CI build | Vitest 4.1.5 with a `pnpm/npm test` step in CI. Test files: `src/save/migrations.test.ts`, `src/save/round-trip.test.ts`. |
| AEST-08 | All AI-assisted assets carry persisted provenance metadata (`{model_id, checkpoint_hash, prompt, seed, sampler, params}`) | Sidecar `.provenance.json` schema enforced by validator script. The "pinned model" wording in REQUIREMENTS is satisfied by per-asset honest provenance for Phase 1; vendor pinning is Phase 5. |
| AEST-09 | All shipped assets pass a mandatory human curation gate before integration | The validator script *is* the gate (CI fails if sidecar missing/invalid). Phase 1 also commits the 10–20-image north-star reference set as the seed. **No** curator workflow doc, per CONTEXT D-03. |
| STRY-09 | Every player-visible string externalized in `/content/`, not hardcoded | Phase 1 establishes the `/content/` convention and the loader; **no lint rule** enforces this (per CONTEXT D-07). Phase 2 begins authoring real strings into `/content/season-01-soil/`. |
| UX-13 | No daily login bonuses, streaks, limited-time content, nag notifications, loss-aversion copy — anti-FOMO doctrine enforced in every UX review | Doctrine doc shipped in this phase; enforcement is by review, not code. |
## Architectural Responsibility Map
| Capability | Primary Tier | Secondary Tier | Rationale |
|------------|-------------|----------------|-----------|
| Project scaffold (vite, tsconfig, eslint baseline) | Build / Dev tooling | — | Ships the dev-server + bundler boundary — not user-facing. |
| Save persistence (IndexedDB, lz-string, checksum) | Browser / Client (Storage) | — | All save state is local-first per CLAUDE.md "no always-online" constraint. |
| Save migration chain | Browser / Client (Storage) | Simulation core consumer | Migration runs at load time before sim sees state; pure functions, no I/O. |
| Save export/import (Base64) | Browser / Client (Storage) | UI (Phase 2+ wires button) | Function pair lives in `src/save/`; UI surface is later. |
| Content build pipeline (md/yaml/ink → JSON) | Build / Static asset transform | Browser runtime consumer | Vite plugin pattern at build; runtime imports compiled JSON only. |
| Zod content schemas | Build / Static asset validation | Browser runtime type source | Schemas validate at build, derive TS types via `z.infer` at compile. |
| AI asset provenance gate | CI / Build-time validator | Repo discipline | Standalone Node script; no runtime import. Lives in `scripts/`. |
| ESLint boundary rule | Build / Static-analysis | — | Lints `src/sim/` ↔ `src/render/`/`src/ui/` import edges; runs in CI and IDE. |
| Anti-FOMO doctrine | Process / Documentation | UX review reference | Markdown in `.planning/`; not enforced by code. |
| Season 7 end-state doctrine | Process / Documentation | Future Phase 7 reference | Markdown in `.planning/`; principle-level. |
| North-star asset reference set | Repo / Static asset | Future Phase 5 model-pinning input | 10–20 images committed under `assets/north-stars/` with sidecars. |
**Important:** Every Phase 1 capability is **build/CI/storage tier** — there is no Simulation or Rendering responsibility in this phase. Phase 2 is where Simulation Core takes ownership.
## Standard Stack
### Core (versions verified against npm 2026-05-08)
| Library | Version | Purpose | Why Standard |
|---------|---------|---------|--------------|
| `phaser` | 4.1.0 | 2D game framework (canvas owner, Phase 2+ uses it) | Locked by CONTEXT D-10. Verified `npm view phaser version` → 4.1.0 ("Salusa", April 2026). |
| `react` / `react-dom` | 19.2.6 | UI shell (DOM overlay) | Locked by CLAUDE.md / STACK.md. `npm view react version` → 19.2.6. |
| `vite` | 8.0.11 | Dev server + bundler | Phaser 4 official template ships with Vite. `npm view vite version` → 8.0.11. **NB: STACK.md mentions Vite 6 as baseline; the template version may be 6 or 7 — accept whatever the scaffold installs and don't fight it.** Vite 8 with Rolldown is current latest. |
| `typescript` | 6.0.3 | Static typing | `npm view typescript version` → 6.0.3. |
| `idb` | 8.0.3 | Promise-based IndexedDB wrapper | Locked. `npm view idb version` → 8.0.3. ~1.19kB brotli'd; openDB + put/get covers Phase 1 entirely. |
| `lz-string` | 1.5.0 | Save compression + Base64 export | Locked. `compressToBase64` / `decompressFromBase64` is the export round-trip. |
| `zod` | 4.4.3 | Schema validation (content + save envelope + provenance) | Locked. **Note:** STACK.md cites 3.23+; current is 4.4.3 — Zod 4 is the modern major. Use 4.x for new code. |
| `vitest` | 4.1.5 | Test runner (migration tests + round-trip test) | Locked. Vite-native; covers PIPE-06. |
| `@playwright/test` | 1.59.1 | E2E smoke (no test in Phase 1; install only — first test in Phase 2) | Locked by STACK.md. Phase 1 only `npm install`s it; first real spec is PIPE-07 in Phase 2. |
| `eslint-plugin-boundaries` | 6.0.2 | Architectural-firewall lint rule | Cleaner than `no-restricted-paths` for the `src/sim/` ↔ `src/render/`/`src/ui/` rule. See decision rationale below. |
| `crc-32` | 1.2.2 | Save checksum | Dependency-free; `CRC32.str(jsonString)` returns a 32-bit signed int; ~3KB. Fastest pure-JS CRC implementation in benchmarks (~426k ops/sec). |
| `gray-matter` | 4.0.3 | Parse YAML frontmatter from `.md` files | Standard for the fragment manifest; STACK.md already endorses. |
| `yaml` | 2.8.4 | Parse pure `.yaml` content files | `eemeli/yaml`, dependency-free, full YAML 1.2 spec; replaces `js-yaml` for new code. |
### Supporting (deferred — install but do not use yet)
| Library | Version | Purpose | When to Use |
|---------|---------|---------|-------------|
| `inkjs` | 2.4.0 | Ink narrative runtime | **Install in Phase 1** so the dependency is locked. **Do NOT compile any `.ink` files in Phase 1.** Phase 2 begins authoring + compilation. |
| `inklecate` | 1.8.1 | Ink compiler CLI | Install as devDependency. Phase 1 includes a `package.json` script `compile:ink` that *exists* (so the build pipeline shape is proven) but is invoked on an empty `/content/dialogue/` directory and is a no-op. Phase 2 starts adding `.ink` files. |
**Phase 1 explicitly does NOT install:** `zustand`, `break_eternity.js`, `howler` + `@types/howler`, `mitt`, `dayjs` — those land in Phase 2 with the simulation core. Do not pre-install — keeping `package.json` honest about phase scope is itself part of the discipline.
### Alternatives Considered
| Instead of | Could Use | Tradeoff |
|------------|-----------|----------|
| `eslint-plugin-boundaries` | `eslint-plugin-import` rule `no-restricted-paths` | `no-restricted-paths` requires manually enumerating every forbidden path pair, no glob support, no element-type abstraction. For one rule (sim ↔ render/ui) it would work in ~10 lines but the model is awkward. `eslint-plugin-boundaries` defines element types once and rules read clearly. **Pick boundaries.** |
| `crc-32` | `xxhashjs` / `murmurhash` / `Web Crypto SHA-256 (sliced)` | xxhash is faster on large strings but heavier dependency; murmurhash is comparable but slightly less battle-tested in JS. SHA-256 is overkill for non-adversarial corruption detection (a save isn't a security boundary — checksum mismatch just signals "don't load this"). **CRC-32 is correct: deterministic, ~3KB, dependency-free, fast enough.** Idle-game saves are bytes-to-low-megabytes; even a slower hash would be fine. |
| Vite-native content pipeline (`import.meta.glob`) | Separate `npm run build:content` Node script | The Vite-native path is one less moving piece — content imports become typed values at build time, HMR works for free, Vite's tree-shaking handles per-Season chunking via dynamic glob in Phase 2. The standalone-script path is more flexible (can emit JSON to disk that Vite never sees) but Phase 1 has no need. **Vite-native wins on simplicity.** Keep the option to refactor later if Phase 5+ asset volume forces it. |
| Synthetic v0→v1 migration in Phase 1 | Skip migration test until Phase 4's real v1→v2 | CONTEXT D-05 explicitly mandates the synthetic test. The point is to prove the framework, not the data shape. **Synthetic v0 is correct.** |
| `crc-32` with `CRC32.str()` over JSON string | Hash the parsed object | Hashing the canonical JSON string is deterministic across runs only if `JSON.stringify` is canonical (key order). Since save state is internally controlled (we write the schema), key order is stable. Document the canonicalization in `src/save/checksum.ts`. |
### Installation
```bash
# Step 0: scaffold (run interactively, choose "React + Vite + TypeScript")
npm create @phaserjs/game@latest the-last-garden
cd the-last-garden
# Step 1: Phase 1 production deps
npm install idb@^8 lz-string@^1.5 zod@^4 crc-32@^1.2 gray-matter@^4 yaml@^2.8 inkjs@^2.4
# Step 2: Phase 1 dev deps
npm install -D vitest@^4 @playwright/test@^1.59 eslint-plugin-boundaries@^6 inklecate@^1.8
```
The Phaser 4 template already installs `phaser`, `react`, `react-dom`, `vite`, `typescript`, and an ESLint baseline. Add to it; don't replace it.
### Version verification log
| Package | Verified version | Date |
|---------|-----------------|------|
| phaser | 4.1.0 | 2026-05-08 |
| react | 19.2.6 | 2026-05-08 |
| vite | 8.0.11 | 2026-05-08 |
| typescript | 6.0.3 | 2026-05-08 |
| idb | 8.0.3 | 2026-05-08 |
| lz-string | 1.5.0 | 2026-05-08 |
| zod | 4.4.3 | 2026-05-08 |
| vitest | 4.1.5 | 2026-05-08 |
| @playwright/test | 1.59.1 | 2026-05-08 |
| eslint-plugin-boundaries | 6.0.2 | 2026-05-08 |
| crc-32 | 1.2.2 | 2026-05-08 |
| gray-matter | 4.0.3 | 2026-05-08 |
| yaml | 2.8.4 | 2026-05-08 |
| inkjs | 2.4.0 | 2026-05-08 |
| inklecate | 1.8.1 | 2026-05-08 |
| howler | 2.2.4 | 2026-05-08 (Phase 2) |
| break_eternity.js | 2.1.3 | 2026-05-08 (Phase 2) |
| zustand | 5.0.13 | 2026-05-08 (Phase 2) |
[VERIFIED: npm registry, 2026-05-08]
## Architecture Patterns
### System Architecture Diagram (Phase 1 deliverables only)
```
┌──────────────────────────────────────────────────────────────────────┐
│ REPO ROOT │
│ /content/ → authored md+yaml+ink (Phase 2+ fills it) │
│ /assets/ → AI generations + sidecar provenance JSON │
│ /.planning/ → doctrine docs (anti-fomo, season-7-end-state) │
│ /scripts/ → validate-assets.mjs (CI provenance gate) │
│ │
│ /src/ │
│ ├── main.tsx, App.tsx, PhaserGame.tsx (template-provided) │
│ ├── game/ (template-provided — Phaser scenes) │
│ ├── sim/ [FIREWALL: imports nothing from render/ or ui/] │
│ ├── render/ (Phase 2+ Phaser scene wiring) │
│ ├── ui/ (Phase 2+ React HUD) │
│ ├── save/ ← LOAD-BEARING IN PHASE 1 │
│ │ ├── db.ts (idb wrapper: openDB + 2 stores) │
│ │ ├── envelope.ts ({schemaVersion, payload, checksum}) │
│ │ ├── checksum.ts (CRC32 over canonical JSON) │
│ │ ├── migrations.ts (registry: {1: v0→v1, ...}) │
│ │ ├── snapshots.ts (last-3 pre-migration retention) │
│ │ ├── persist.ts (navigator.storage.persist + result handler) │
│ │ ├── codec.ts (lz-string + Base64 export/import) │
│ │ └── *.test.ts (vitest: round-trip + each migration) │
│ ├── content/ ← LOAD-BEARING IN PHASE 1 │
│ │ ├── schemas/ (zod schemas: fragment.ts, season.ts) │
│ │ └── loader.ts (import.meta.glob + gray-matter + zod parse) │
│ ├── audio/ (empty placeholder for Phase 2) │
│ └── store/ (empty placeholder for Phase 2) │
│ │
│ /eslint.config.js (extends template + boundaries plugin) │
│ /vitest.config.ts │
│ /playwright.config.ts (installed; no specs yet) │
│ /package.json │
└──────────────────────────────────────────────────────────────────────┘
Build pipeline (Phase 1) CI gate (Phase 1)
┌─────────────────────────┐ ┌──────────────────────────┐
│ vite build │ │ npm run lint │
│ → import.meta.glob │ │ (eslint-plugin-bounds) │
│ → zod-parse content │ │ npm test │
│ → fail on violation │ │ (vitest: migrations) │
└─────────────────────────┘ │ node scripts/ │
│ validate-assets.mjs │
│ (provenance walker) │
└──────────────────────────┘
```
### Recommended Project Structure
```
the-last-garden/
├── .planning/
│ ├── PROJECT.md (existing)
│ ├── REQUIREMENTS.md (existing)
│ ├── ROADMAP.md (existing)
│ ├── STATE.md (existing)
│ ├── anti-fomo-doctrine.md (NEW — Phase 1 deliverable)
│ ├── season-7-end-state.md (NEW — Phase 1 deliverable)
│ ├── research/ (existing)
│ └── phases/ (existing)
├── content/ (NEW empty tree — Phase 2+ fills)
│ ├── seasons/ (per-Season subdirs added in Phase 2+)
│ └── README.md (explains the content shape)
├── assets/
│ ├── north-stars/ (NEW — 10–20 curated images + sidecars)
│ │ ├── garden-soil-01.png
│ │ ├── garden-soil-01.provenance.json
│ │ └── ...
│ └── __samples__/
│ └── refused/
│ └── unprovenanced.png (proves the gate)
├── scripts/
│ └── validate-assets.mjs (NEW — CI provenance walker)
├── src/
│ ├── main.tsx (template-provided)
│ ├── App.tsx (template-provided)
│ ├── PhaserGame.tsx (template-provided)
│ ├── game/ (template-provided — Phaser scenes)
│ ├── sim/ (NEW empty — Phase 2+ fills)
│ │ └── .gitkeep
│ ├── render/ (NEW empty — Phase 2+ fills)
│ │ └── .gitkeep
│ ├── ui/ (NEW empty — Phase 2+ fills)
│ │ └── .gitkeep
│ ├── save/ (NEW — Phase 1 ships)
│ │ ├── db.ts
│ │ ├── envelope.ts
│ │ ├── checksum.ts
│ │ ├── migrations.ts
│ │ ├── snapshots.ts
│ │ ├── persist.ts
│ │ ├── codec.ts
│ │ ├── round-trip.test.ts
│ │ └── migrations.test.ts
│ ├── content/ (NEW — Phase 1 ships loader, no real content yet)
│ │ ├── schemas/
│ │ │ ├── fragment.ts
│ │ │ └── season.ts
│ │ └── loader.ts
│ ├── audio/ (NEW empty — Phase 2+)
│ │ └── .gitkeep
│ └── store/ (NEW empty — Phase 2+)
│ └── .gitkeep
├── eslint.config.js (extends template, adds boundaries plugin)
├── vitest.config.ts (NEW)
├── playwright.config.ts (NEW — empty test dir, install only)
├── tsconfig.json (template-provided, may add path alias)
├── vite.config.ts (template-provided)
├── package.json
└── CLAUDE.md (existing)
```
### Pattern 1: Save Envelope `{schemaVersion, payload, checksum}`
**What:** Every save written to disk is a top-level envelope:
```typescript
interface SaveEnvelope {
schemaVersion: number;
payload: T;
checksum: string; // hex CRC32 of canonical JSON.stringify(payload)
}
```
The checksum is computed over the canonical JSON string of the *payload only* (not the envelope). On load, recompute and compare; mismatch → refuse to load, surface recovery option.
**When to use:** Always. CLAUDE.md mandates the shape; Phase 2+ writes payloads of this shape exclusively.
**Example:**
```typescript
// src/save/envelope.ts
import { z } from 'zod';
import { crc32hex } from './checksum';
export const SaveEnvelopeSchema = z.object({
schemaVersion: z.number().int().positive(),
payload: z.unknown(),
checksum: z.string().regex(/^[0-9a-f]{8}$/),
});
export type SaveEnvelope = z.infer & { payload: T };
export function wrap(payload: T, schemaVersion: number): SaveEnvelope {
return {
schemaVersion,
payload,
checksum: crc32hex(canonicalJSON(payload)),
};
}
export function unwrap(env: SaveEnvelope): T {
const expected = crc32hex(canonicalJSON(env.payload));
if (expected !== env.checksum) throw new SaveCorruptError(env.checksum, expected);
return env.payload as T;
}
// canonicalJSON: stable key order. For Phase 1, JSON.stringify with sorted keys is enough.
function canonicalJSON(value: unknown): string {
return JSON.stringify(value, (_k, v) =>
v && typeof v === 'object' && !Array.isArray(v)
? Object.fromEntries(Object.entries(v).sort(([a], [b]) => a.localeCompare(b)))
: v
);
}
```
[CITED: zod docs https://zod.dev — schema-from-type pattern]
### Pattern 2: Migration Registry (ordered chain)
**What:** A `Record` mapping target-version → pure function. Loader walks from current envelope's version to `CURRENT_SCHEMA_VERSION`, applying each migration in turn.
```typescript
// src/save/migrations.ts
type Migration = (payload: unknown) => unknown;
export const CURRENT_SCHEMA_VERSION = 1;
// Each entry migrates FROM (key-1) TO key. So migrations[1] = v0→v1.
export const migrations: Record = {
1: (s: any) => ({
// Synthetic demo: v0 was {garden: []}. v1 is the real Phase 2 shape.
garden: { tiles: s.garden ?? [] },
plants: [],
harvestedFragmentIds: [],
lastTickAt: Date.now(),
settings: { musicVolume: 0.7, ambientVolume: 0.5, sfxVolume: 0.8 },
}),
};
export function migrate(payload: unknown, fromVersion: number): { payload: unknown; toVersion: number } {
let current = payload;
let v = fromVersion;
while (v < CURRENT_SCHEMA_VERSION) {
const next = v + 1;
const fn = migrations[next];
if (!fn) throw new Error(`No migration registered for v${v} → v${next}`);
current = fn(current);
v = next;
}
return { payload: current, toVersion: v };
}
```
**Why ordered chain over registry-with-named-functions:** The chain is the most testable shape — each migration is a pure function with a known input schema and known output schema; Vitest tests each migration in isolation (`expect(migrations[1]({garden: []})).toEqual({...v1 shape})`). Phase 4's real `migrate_v1_to_v2` slots in by adding `migrations[2] = ...`.
**Pre-migration snapshot rule:** Before invoking `migrate()` on a load, write the original envelope to the `snapshots` object store keyed by `{schemaVersion, savedAt}`. Pruner trims to last 3 entries. See "Pattern 3" below.
[CITED: shapez.io save/load post-mortem — https://deepwiki.com/tobspr-games/shapez.io/2.2-saveload-system; ARCHITECTURE.md Pattern 5]
### Pattern 3: Last-3 Pre-Migration Snapshots
**What:** A second IndexedDB object store, `save_snapshots`, holds copies of envelopes from before any migration ran. Schema:
```typescript
interface SnapshotEntry {
id: string; // `${schemaVersion}-${savedAtIso}`
schemaVersion: number;
savedAt: string; // ISO8601
envelope: SaveEnvelope;
}
```
**Retention rule:** On every snapshot write, query all entries, sort by `savedAt` desc, keep first 3, delete the rest. Synchronous logic inside one IDB transaction.
**Phase scope:** Phase 1 only ships the *storage and pruning* layer + a Vitest test that `(write 5 snapshots) → (assert 3 remain, oldest 2 deleted)`. The "Restore previous save" UI button hooks into this in Phase 4.
**Example:**
```typescript
// src/save/snapshots.ts
import { openSaveDB } from './db';
import type { SaveEnvelope } from './envelope';
const RETAIN = 3;
export async function snapshot(envelope: SaveEnvelope): Promise {
const db = await openSaveDB();
const tx = db.transaction('save_snapshots', 'readwrite');
const store = tx.objectStore('save_snapshots');
const savedAt = new Date().toISOString();
await store.put({
id: `${envelope.schemaVersion}-${savedAt}`,
schemaVersion: envelope.schemaVersion,
savedAt,
envelope,
});
// Prune
const all = await store.getAll();
const sorted = all.sort((a, b) => b.savedAt.localeCompare(a.savedAt));
const toDelete = sorted.slice(RETAIN);
await Promise.all(toDelete.map((e) => store.delete(e.id)));
await tx.done;
}
export async function listSnapshots(): Promise {
const db = await openSaveDB();
const all = await db.getAll('save_snapshots');
return all.sort((a, b) => b.savedAt.localeCompare(a.savedAt));
}
```
### Pattern 4: Vite-Native Content Pipeline
**What:** Use `import.meta.glob('/content/**/*.{md,yaml}', { eager: true, query: '?raw', import: 'default' })` to import every content file as a raw string at build time. Run gray-matter (for `.md`) or `yaml.parse` (for `.yaml`) on each, then validate via Zod schemas. Build fails on any Zod error because `loader.ts` runs at module-evaluation time and a thrown error propagates through Vite to the build process.
**Why this shape over a separate script:**
- One source of truth: the loader runs at build *and* dev (HMR works for free).
- No emitted-JSON-file problem: compiled content is just JS values bundled by Vite.
- Per-Season chunking arrives in Phase 2 by switching to `{ eager: false }` for Seasons 2–7 and `eager: true` for Season 1.
- Vite already handles file watching, glob expansion, and TypeScript types.
**Phase 1 scope:** Loader exists, schemas exist, but `/content/` is *empty* of real content. Demo schema (one tiny fragment in `/content/seasons/00-demo/fragments.yaml`) proves the round-trip and is removed in Phase 2.
**Example:**
```typescript
// src/content/schemas/fragment.ts
import { z } from 'zod';
export const FragmentSchema = z.object({
id: z.string().regex(/^season\d+\.[a-z0-9._-]+$/),
season: z.number().int().min(1).max(7),
body: z.string().min(1),
});
export type Fragment = z.infer;
export const SeasonContentSchema = z.object({
fragments: z.array(FragmentSchema),
});
```
```typescript
// src/content/loader.ts
import grayMatter from 'gray-matter';
import { parse as parseYAML } from 'yaml';
import { z } from 'zod';
import { FragmentSchema, SeasonContentSchema } from './schemas';
// Vite handles glob; ?raw imports as string; eager makes the imports available synchronously.
const yamlFiles = import.meta.glob('/content/seasons/*/fragments.yaml', {
eager: true,
query: '?raw',
import: 'default',
}) as Record;
const mdFiles = import.meta.glob('/content/seasons/*/fragments/*.md', {
eager: true,
query: '?raw',
import: 'default',
}) as Record;
const fragmentsFromYaml = Object.entries(yamlFiles).flatMap(([path, raw]) => {
const data = parseYAML(raw);
const parsed = SeasonContentSchema.safeParse(data);
if (!parsed.success) {
throw new Error(`[content] schema violation in ${path}\n${parsed.error.message}`);
}
return parsed.data.fragments;
});
const fragmentsFromMd = Object.entries(mdFiles).map(([path, raw]) => {
const { data, content } = grayMatter(raw);
const merged = { ...data, body: content.trim() };
const parsed = FragmentSchema.safeParse(merged);
if (!parsed.success) {
throw new Error(`[content] schema violation in ${path}\n${parsed.error.message}`);
}
return parsed.data;
});
export const fragments: Fragment[] = [...fragmentsFromYaml, ...fragmentsFromMd];
```
**Ink files in Phase 1:** Per CONTEXT discretion + cheaper-path recommendation, **defer Ink compilation to Phase 2**. Phase 1 ships:
1. `npm install inkjs inklecate` so the deps are locked.
2. A `package.json` script `"compile:ink": "inklecate -o src/content/compiled-ink/ content/dialogue/*.ink || true"` that exists but operates on an empty directory (no-op).
3. `/content/dialogue/.gitkeep` so the directory is real.
4. **No Ink validation** in Phase 1 — Phase 2 adds it when the first `.ink` file is written.
This is the minimum-viable shape: the *path* to compile Ink exists; nothing flows through it yet. Full Ink integration is Phase 2.
### Pattern 5: ESLint Boundary Rule (`eslint-plugin-boundaries`)
**What:** Define each top-level `src/` directory as an "element type"; declare which types each type may import from.
```javascript
// eslint.config.js (flat config, ESM)
import boundaries from 'eslint-plugin-boundaries';
export default [
// ... template's existing config first ...
{
plugins: { boundaries },
settings: {
'boundaries/elements': [
{ type: 'sim', pattern: 'src/sim/**' },
{ type: 'render', pattern: 'src/render/**' },
{ type: 'ui', pattern: 'src/ui/**' },
{ type: 'save', pattern: 'src/save/**' },
{ type: 'content', pattern: 'src/content/**' },
{ type: 'audio', pattern: 'src/audio/**' },
{ type: 'store', pattern: 'src/store/**' },
{ type: 'app', pattern: 'src/{main,App,PhaserGame}.tsx' },
{ type: 'game', pattern: 'src/game/**' },
],
},
rules: {
'boundaries/element-types': ['error', {
default: 'allow',
rules: [
// The Phase-1 firewall (CORE-10):
{ from: ['sim'], disallow: ['render', 'ui'] },
],
}],
},
},
];
```
**Why this over `no-restricted-paths`:** The element-type abstraction means that when Phase 4 adds `src/server/` (or any new tier), we add one element entry rather than enumerating new path-pair forbids. Cleaner, more declarative, future-proof. The rule above forbids only the exact CORE-10 firewall; everything else is `default: allow` — keeping Phase 1 honest about which constraints actually exist.
**CI integration:** `npm run lint` in the GitHub Actions workflow (or local pre-commit). Failure exits non-zero. Verify with one deliberately-bad file in tests (a unit test that asserts `eslint --rulesdir ... src/sim/__test_violation__/...` exits with the boundary error — only kept in the test fixture, removed from production builds).
[VERIFIED: eslint-plugin-boundaries 6.0.2 README, 2026-05-08]
### Pattern 6: Provenance Sidecar Validator
**What:** A 30-line standalone Node script that walks `assets/`, verifies that every non-sidecar file has a sibling `.provenance.json` parseable against a Zod schema, with the exception of `assets/__samples__/refused/`.
```javascript
// scripts/validate-assets.mjs
import { readdir, readFile, stat } from 'node:fs/promises';
import { join, extname, basename, dirname } from 'node:path';
import { z } from 'zod';
const ProvenanceSchema = z.object({
model_id: z.string().min(1),
checkpoint_hash: z.string().min(1),
prompt: z.string().min(1),
seed: z.union([z.string(), z.number()]),
sampler: z.string().min(1),
params: z.record(z.string(), z.unknown()),
});
const ASSETS = 'assets';
const REFUSED = ['assets/__samples__/refused'];
async function* walk(dir) {
for (const entry of await readdir(dir, { withFileTypes: true })) {
const path = join(dir, entry.name);
if (entry.isDirectory()) yield* walk(path);
else yield path;
}
}
const errors = [];
for await (const path of walk(ASSETS)) {
if (REFUSED.some((r) => path.replaceAll('\\', '/').startsWith(r))) continue;
if (path.endsWith('.provenance.json')) continue;
if (basename(path) === '.gitkeep') continue;
const sidecar = path + '.provenance.json'; // e.g. foo.png.provenance.json
// OR .provenance.json — pick one convention; document in CONTEXT for Phase 2.
try {
const raw = await readFile(sidecar, 'utf8');
const parsed = ProvenanceSchema.safeParse(JSON.parse(raw));
if (!parsed.success) errors.push(`${path}: ${parsed.error.message}`);
} catch (e) {
errors.push(`${path}: missing or unreadable provenance sidecar (${sidecar})`);
}
}
if (errors.length) {
console.error('[provenance] validation failed:');
errors.forEach((e) => console.error(' ' + e));
process.exit(1);
}
console.log('[provenance] all assets carry valid provenance.');
```
**Wire it up:**
```json
// package.json
"scripts": {
"validate:assets": "node scripts/validate-assets.mjs",
"lint": "eslint .",
"test": "vitest run",
"ci": "npm run lint && npm run test && npm run validate:assets && npm run build"
}
```
**Sidecar naming convention decision:** Use `.provenance.json` (e.g. `garden-soil-01.png.provenance.json`) — this keeps the sidecar adjacent in directory listings, makes it grep-friendly, and avoids ambiguity for files with the same stem but different extensions.
**Refused-sample test:** Commit `assets/__samples__/refused/no-provenance.png` (an actual image file, no sidecar). Then write a Vitest test that *temporarily moves* the refused asset out of `__samples__/refused/` and asserts the validator script exits non-zero — proving the gate works. Restore the file in the test teardown.
**Should this also run in Vite dev?** No. Per CONTEXT D-03, the gate is CI-only. Running it in dev would slow down `npm run dev` startup; provenance churn during development is normal and shouldn't block iteration.
### Anti-Patterns to Avoid
- **Adding a curator workflow doc / pre-commit hook / two-stage promotion directory** — explicitly rejected by CONTEXT D-03. Sidecar + CI walker is the entire pipeline.
- **Pre-allocating save schema slots for Roothold / currentSeason / storyFlags** — explicitly rejected by CONTEXT D-04. v1 schema contains only what Phase 2 will write.
- **Compiling `.ink` files in Phase 1** — explicitly out of scope. The path exists; the runtime doesn't.
- **Lint rule on UX strings** — explicitly rejected by CONTEXT D-07. Anti-FOMO is a review document, not a code rule.
- **A separate `npm run build:content` Node script** — Vite-native is simpler. Refactor only if Phase 5+ asset volume forces it.
- **BigQty wrapper / Zustand store / tick scheduler / Howler bootstrap / AudioContext gesture gate** — all explicitly Phase 2.
- **Running the asset validator in Vite dev** — CI only. Don't burden the dev loop.
- **Hand-rolling CRC32 / a custom hash** — `crc-32` is dependency-free at 426k ops/sec. Don't NIH this.
## Don't Hand-Roll
| Problem | Don't Build | Use Instead | Why |
|---------|-------------|-------------|-----|
| IndexedDB transactions | `indexedDB.open` + manual `onupgradeneeded` + Promise wrappers | `idb` (`openDB`, `db.put`, `db.get`) | Idb is 1.19kB brotli'd. Hand-rolling promise wrappers around the request-event API loses ~200 lines, has subtle bugs around transaction lifecycle, and reinvents what's already standard. |
| Save compression | DIY LZ77 / DIY Base64 wrappers | `lz-string` (`compressToUTF16`, `compressToBase64`) | The library is 30k downloads/week, battle-tested in incremental-game saves for ~10 years. UTF-16 storage avoidance + URL-safe variants are subtle. |
| Schema validation | Hand-written `if (typeof x.id !== 'string')` checks | `zod` | The whole point of Zod is type-safe runtime validation. Doing it by hand on save envelopes / content / provenance is error-prone and tedious. |
| Frontmatter parsing | Hand-rolled `--- ... ---` parser | `gray-matter` | Edge cases (escaped delimiters inside YAML strings, multi-document YAML) bite. |
| YAML parsing | Hand-rolled / `JSON.parse` of a yaml-as-json variant | `yaml` (`eemeli/yaml`) | YAML 1.2 spec is gnarly. `yaml` is the reference implementation. |
| ESLint architectural boundaries | Pre-commit grep / shell scripts | `eslint-plugin-boundaries` | IDE integration, ESLint flat-config compatibility, element-type abstraction. |
| CRC32 | Hand-rolled bit-twiddling | `crc-32` (SheetJS) | Polynomial tables and seed handling are easy to get subtly wrong; CRC-32 package is dependency-free and tiny. |
| Glob walking the filesystem | `glob` / `fast-glob` / DIY | `node:fs/promises` `readdir({withFileTypes: true, recursive: true})` for the asset validator; `import.meta.glob` for content | Node 20+ supports recursive readdir natively. No new dependency needed for the 30-line validator. |
| Test runner | Hand-rolled assertion library | `vitest` | Vite-native, parallel by default, ESM-first. |
| E2E driver | Puppeteer / DIY | `@playwright/test` | Phase 1 install only — first spec lands in Phase 2. |
**Key insight:** Phase 1 is *infrastructure plumbing*. The temptation is to over-engineer abstractions because there's no feature work to ground them. Resist. Every recommendation above is the *thinnest* shape that satisfies the success criterion. The user pushed back on overengineering before context was even gathered — the planner will too.
## Common Pitfalls
### Pitfall 1: `import.meta.glob` requires literal patterns
**What goes wrong:** Calling `import.meta.glob(somePathVariable)` silently fails. The glob string MUST be a string literal at the call site.
**Why it happens:** Vite's plugin walks the AST at build time and can't resolve runtime expressions.
**How to avoid:** Always inline the glob as a literal. If multiple patterns are needed, write multiple glob calls and merge the results.
**Warning signs:** A "Could only use literals" error at build time.
[CITED: vite docs https://vite.dev/guide/features#glob-import]
### Pitfall 2: `navigator.storage.persist()` returns false on iOS Safari most of the time
**What goes wrong:** First-save attempt to call `persist()` returns false on Safari/iOS unless the app has been added to home screen as a PWA or has been heavily interacted with. Player loses 30 days of save progress on Safari's periodic eviction (WebKit bug 266559).
**Why it happens:** Safari's persistence-grant heuristic is opaque and conservative. Apple has explicitly documented "iOS provides no persistent storage guarantee" outside PWA context.
**How to avoid:**
- Always call `navigator.storage.persist()` on first save and check the result.
- If `false`, write a sentinel flag (`saveIsBestEffort: true`) into the save envelope.
- Surface a UX message at next opportunity (Phase 2+ writes the actual UI): *"Your browser is keeping this save on a best-effort basis. Export a backup any time from Settings."*
- The Base64 export/import (CORE-09) is the resilience guarantee against this — make sure it lands in Phase 1 even though no UI button surfaces it yet.
**Warning signs:** Telemetry showing save-loaded count < expected on Safari (Phase 8 polish, not Phase 1 concern — but the affordance must exist).
[CITED: MDN https://developer.mozilla.org/en-US/docs/Web/API/StorageManager/persist; PITFALLS.md #8]
### Pitfall 3: JSON key ordering breaks checksums across runs
**What goes wrong:** `JSON.stringify({a: 1, b: 2})` and `JSON.stringify({b: 2, a: 1})` produce the same string in V8 today, but **this is not spec-guaranteed across engines** (and Object.fromEntries iteration order is technically insertion order). If a Phase 4 migration somehow re-creates an object with different key order, the checksum changes even though the data is identical.
**Why it happens:** Default `JSON.stringify` doesn't canonicalize.
**How to avoid:** Implement `canonicalJSON()` that sorts object keys recursively before stringifying, as shown in Pattern 1. Use it everywhere checksums are computed.
**Warning signs:** A migration test fails with "expected X, got Y" where X and Y are visually identical JSON.
### Pitfall 4: Vite ESM build of Phaser 4 silently breaks if peer versions misalign
**What goes wrong:** Phaser 4.0.0 had ESM build issues that 4.1.0 fixed. Mixing the wrong React version with the official template can produce runtime "cannot read property X of undefined" with no clear stack trace.
**Why it happens:** The Phaser 4.1.0 release notes explicitly call out "important fixes for the ESM module build."
**How to avoid:** Use the template-installed versions exactly. Don't manually upgrade Phaser without checking the release notes; pin Phaser to `^4.1.0`.
**Warning signs:** Game scaffold loads white screen with console errors after a dependency update.
[CITED: Phaser v4.1.0 "Salusa" release notes — https://phaser.io/news/2026/04/phaser-4-1-0-salusa-release]
### Pitfall 5: Synchronous lz-string compression of huge saves blocks the main thread
**What goes wrong:** `LZString.compressToBase64` is synchronous; on a 5MB save (Season 5+ scope) it can block the main thread for ~50ms+, dropping a frame mid-cello-ambient and ruining the watercolor mood.
**Why it happens:** lz-string predates async APIs.
**How to avoid:** Phase 1's saves are tiny (<10KB) so this isn't a real concern *yet*. Document the eventual mitigation: move save serialization into a Web Worker if Season 5+ saves grow past ~1MB. Don't build the worker now (premature) but **do** wrap save writes in `src/save/codec.ts` so the swap is one file later.
**Warning signs:** Frame drops on save in a Season-5 simulation profile (Phase 8 concern).
[CITED: PITFALLS.md #8 perf table]
### Pitfall 6: ESLint flat-config plugin imports break with mixed CJS/ESM template baseline
**What goes wrong:** The Phaser template ships an `.eslintrc.cjs` baseline (legacy config). Adding `eslint-plugin-boundaries` via the new flat-config `eslint.config.js` alongside the legacy file confuses ESLint 9+.
**Why it happens:** ESLint 9 deprecated legacy config; templates may still ship the older shape during transition.
**How to avoid:** Migrate the template's `.eslintrc.cjs` to a single `eslint.config.js` (flat) at the start of Phase 1. Don't run both. The migration is mechanical (`@eslint/migrate-config` automates it).
**Warning signs:** ESLint runs but boundaries rule never fires; or runs twice with conflicting messages.
### Pitfall 7: Synthetic v0→v1 migration test that doesn't actually exercise the registry
**What goes wrong:** It's tempting to write a "round-trip" test that wraps and unwraps the same object without ever calling `migrate()`. That tests envelope integrity but doesn't validate the migration framework.
**Why it happens:** Convenience.
**How to avoid:** The required Vitest assertions for CORE-07 are:
1. `migrate({garden: []}, 0)` returns `{payload: {...v1 shape...}, toVersion: 1}`.
2. Calling `migrate(payload, 1)` is a no-op.
3. Calling `migrate(payload, -1)` or `migrate(payload, 99)` throws.
4. The full round-trip — write v0 envelope to IDB, load it, migrate, validate via Zod — passes.
5. Snapshot retention test: write 5 successive saves, list snapshots, assert exactly 3 remain in newest-first order.
**Warning signs:** Test coverage is high but no test actually invokes `migrations[1]`.
## Code Examples
### Save round-trip (Phase 1's load-bearing test)
```typescript
// src/save/round-trip.test.ts
import { describe, it, expect } from 'vitest';
import { wrap, unwrap } from './envelope';
import { migrate, CURRENT_SCHEMA_VERSION } from './migrations';
import LZString from 'lz-string';
describe('save round-trip', () => {
it('synthetic v0 envelope migrates, round-trips through Base64, and validates', () => {
// Pretend a player had an old v0 save lying around.
const v0Payload = { garden: [{ id: 'tile-1' }, { id: 'tile-2' }] };
const v0Envelope = { schemaVersion: 0, payload: v0Payload, checksum: 'deadbeef' /* dummy */ };
// Export
const exported = LZString.compressToBase64(JSON.stringify(v0Envelope));
expect(exported.length).toBeGreaterThan(0);
// Import (in a fresh "browser")
const imported = JSON.parse(LZString.decompressFromBase64(exported)!);
expect(imported.schemaVersion).toBe(0);
// Migrate
const { payload, toVersion } = migrate(imported.payload, imported.schemaVersion);
expect(toVersion).toBe(CURRENT_SCHEMA_VERSION);
expect(payload).toMatchObject({
garden: { tiles: expect.any(Array) },
lastTickAt: expect.any(Number),
});
// Re-wrap with current version + valid checksum
const v1Envelope = wrap(payload, toVersion);
expect(unwrap(v1Envelope)).toEqual(payload);
});
});
```
### Persist API call with respectful surfacing
```typescript
// src/save/persist.ts
export interface PersistResult {
granted: boolean;
apiAvailable: boolean;
}
export async function requestPersistence(): Promise {
if (!('storage' in navigator) || !('persist' in navigator.storage)) {
return { granted: false, apiAvailable: false };
}
try {
const granted = await navigator.storage.persist();
return { granted, apiAvailable: true };
} catch {
return { granted: false, apiAvailable: true };
}
}
// Caller (Phase 2 wires UI; Phase 1 ships function only):
// const result = await requestPersistence();
// if (!result.granted) {
// // store flag in save envelope; surface in Phase 2 settings UI:
// // "Your browser is keeping this save on a best-effort basis.
// // Export a backup any time from Settings."
// }
```
### Provenance sidecar example
```json
// assets/north-stars/garden-soil-01.png.provenance.json
{
"model_id": "claude-3.7-sonnet@2025-12 / sd-xl-watercolor-lora-v3",
"checkpoint_hash": "sha256:abcd1234...",
"prompt": "A walled cottage garden at dusk in late autumn, watercolor wash, real but slightly wrong wildflowers, golden palette, no fantasy elements",
"seed": 0,
"sampler": "DPM++ 2M Karras",
"params": {
"steps": 30,
"cfg_scale": 7.5,
"width": 1024,
"height": 1024,
"lora_weight": 0.8,
"notes": "Phase 1 north-star reference image #01 of 20. Hand-curated; reroll-allowed via stored seed."
}
}
```
### Doctrine doc outline — `anti-fomo-doctrine.md`
Recommended structure (principle-level, ~1 page):
```markdown
# Anti-FOMO Doctrine
This document is referenced at every UX, monetization, and copy review. It enumerates
mechanics this game does not use, with the reason for each, so the answer to a
"should we add X?" question is in writing rather than relitigated.
## Banned Mechanics
| Mechanic | Why Banned |
|----------|------------|
| Daily login bonuses | Presence is not a debt the game collects. |
| Login streaks | Skipping a day is allowed, even encouraged. |
| Limited-time content (events that disappear) | The game's premise is *what persists*. |
| Loss-aversion copy ("you'll lose your X") | Tonally incompatible with cozy/contemplative. |
| Re-engagement push notifications | Memory Storms (opt-in) are the *only* allowed notification class. |
| Rewarded ads | Anti-cozy; tonally incoherent. |
| Visible countdown timers in core UI | The cello is the timer. |
| "Don't miss out" / "limited time" / "only X hours left" copy | Bannable phrases. |
## Allowed Engagement
- Memory Storm opt-in notifications.
- "While you were away" letter on return (in Lura's voice, not a stat dump).
- Tab-title bloom indicator (UX-09, Phase 8).
## Review Checklist
When reviewing any UX/copy/monetization change, ask:
1. Does this create urgency around presence rather than around content?
2. Does this frame absence as loss?
3. Would removing this from the game make it less *cozy*?
If yes to any → reject or rewrite.
## Source Documents
- PROJECT.md "Out of Scope" — anti-features
- REQUIREMENTS.md UX-13, "Out of Scope" table (rows: gacha, daily login, streaks,
limited-time, energy/stamina, rewarded ads, push spam)
- CLAUDE.md "Hard Thematic Constraints"
- .planning/research/PITFALLS.md #9
```
### Doctrine doc outline — `season-7-end-state.md`
Recommended structure (principle-level, ~1 page):
```markdown
# Season 7 End-State Design (Principle-Level)
This document answers the question that ends ROADMAP.md Phase 7's success criterion #4:
*"the finite Roothold ceiling from Phase 4 has held the line, and the game has ended
the way A Dark Room and Universal Paperclips ended."*
## What does *rest state* mean?
The rest state is the post-credits configuration the player can return to indefinitely
without grinding. Concretely:
- No new fragments are added to the pool. All authored content has been delivered.
- No new currency tiers unlock.
- The garden continues to render and respond to clicks. Plants can still be planted
and harvested, but harvests yield re-readable previously-collected fragments —
nothing new.
- The Pale has receded. The Heartsoil expands beyond the garden walls. Lura's
arc has resolved. The Archivist's question has been answered (in the player's
binary choice from Season 7's final scene).
- The cello and ambience continue. The world is *quiet*, *finite*, *understood*.
This is not "endgame content." It is **rest**.
## What is the finite Roothold ceiling tied to?
Roothold's ceiling is anchored in the **count of authored fragments and the count
of Seasons**, not in an arbitrary number. The ceiling is: *one cannot accumulate
more Roothold than the player has actually understood, and what the player can
understand is bounded by what the writer has actually written.*
Concrete tie:
- Roothold gain per Season is gated to a hard cap proportional to the fragment count
of that Season + a small contribution from Roothold-relevant story beats.
- Total Roothold cap = Σ(per-Season caps).
- Phase 4 enforces this cap when it implements `migrate_v1_to_v2` and the prestige
state machine. Phase 7 verifies the ceiling holds through full play.
## What tonal register does the coda live in?
- **Warm**, not pyrrhic. The garden persists *because* you tended it; this is
earned redemption, not survival.
- **Quiet**, not climactic. The cello does not crescendo. It rests.
- **Specific**, not abstract. The final visible state is a *real* garden — the
one this player built — viewed in soft dawn-silver light.
- **Final**, not infinite. There is no "Season 8." There is no New Game+. The
Pale receded *here*, in *this* garden.
## What this document is NOT
- The text of the Season 7 binary-choice scene (authored Phase 7).
- The text of either ending paragraph (authored Phase 7).
- Lura's final line (authored Phase 7).
- The credits/coda screen visual treatment (designed Phase 7).
- The tonal register or shape of the final fragments themselves.
This document is *the principle the economy obeys, the writer obeys, and the
Phase 7 designer obeys* — not the implementation of any of those.
## Source Documents
- PROJECT.md core value — "what survives is what you understood"
- REQUIREMENTS.md SEAS-04, SEAS-09, SEAS-10, STRY-08
- ROADMAP.md Phase 7
- .planning/research/PITFALLS.md #1
```
## Runtime State Inventory
(Greenfield project — no prior runtime state to migrate.)
| Category | Items Found | Action Required |
|----------|-------------|------------------|
| Stored data | None — first commit; no databases, no IndexedDB writes, no on-disk state | None |
| Live service config | None | None |
| OS-registered state | None | None |
| Secrets/env vars | None — no `.env` files, no API keys yet | None |
| Build artifacts | None — no `node_modules/`, `dist/`, or compiled output yet | First `npm install` will create `node_modules/`; `.gitignore` from template covers it |
**Nothing to migrate** — Phase 1 is the first phase that produces any artifacts.
## Common Pitfalls (CI / Tooling Specific)
(See "Common Pitfalls" section above for the full list of seven pitfalls. This
section additionally documents three CI-tooling traps unique to first-phase
infrastructure work.)
### CI Pitfall A: GitHub Actions caching `node_modules` instead of `~/.npm`
**What goes wrong:** Cache restores `node_modules/` directly; subsequent `npm install` doesn't refresh transitive deps and silently runs against stale versions.
**How to avoid:** Use `actions/setup-node@v4` with `cache: 'npm'` (caches `~/.npm` based on `package-lock.json`) — never cache `node_modules/` directly.
### CI Pitfall B: Vitest in CI doesn't fail the build on uncaught test errors
**What goes wrong:** `vitest run` exits 0 if no tests exist (Phase 1 ships only 2-3 test files); CI passes a "no tests" run as success.
**How to avoid:** Add `--passWithNoTests=false` to the vitest CLI call in CI so empty runs are flagged.
### CI Pitfall C: ESLint flat-config + `--max-warnings 0` in template
**What goes wrong:** Template may default to allowing warnings; the boundaries rule fires as a warning instead of an error.
**How to avoid:** Set `boundaries/element-types` severity to `error` (numeric `2` or string `'error'`) explicitly. Add `npm run lint -- --max-warnings 0` to the CI script.
## State of the Art
| Old Approach | Current Approach | When Changed | Impact |
|--------------|------------------|--------------|--------|
| Phaser 3 + React via webpack | Phaser 4 official template (Vite + React + TS) | April 2026 (Phaser 4 GA) | The official template is the path. Don't pick Phaser 3 in 2026. |
| ESLint legacy config (`.eslintrc.*`) | ESLint flat config (`eslint.config.js`) | ESLint 9 (2024) | Migrate the template's legacy file at start of Phase 1. |
| Zod 3.x | Zod 4.x | Zod 4 GA late 2025 | Use 4.x for new code; STACK.md's "3.23+" is conservative; 4.4.3 is current. |
| Vite 6 (current LTS) | Vite 8 (Rolldown) | 2026 | Phaser 4 template may install Vite 6 or 7. Don't aggressively upgrade — accept template version. |
| `js-yaml` | `yaml` (eemeli/yaml) | 2023+ | YAML 1.2 spec compliance; better TypeScript types. |
| Vitest workspace config | Vitest projects config | Vitest 3.2+ (2025) | Workspace is deprecated. Phase 1 doesn't need projects; single config is fine. |
**Deprecated/outdated:**
- ESLint legacy config — migrate at scaffold time.
- `js-yaml` — use `yaml` for new code.
- Phaser 3 starter templates — use Phaser 4 official template.
## Assumptions Log
> Every claim in this document is either [VERIFIED] against a tool/registry, [CITED] from a
> linked source, or [ASSUMED]. Below are the [ASSUMED] claims that the planner / discuss-phase
> may want to validate with the user before locking.
| # | Claim | Section | Risk if Wrong |
|---|-------|---------|---------------|
| A1 | The Phaser 4 official template (`npm create @phaserjs/game@latest`) installs Vite 6 or 7 (not yet 8). | Standard Stack | Low — the planner can verify by running the scaffold once. If Vite 8, no behavior change needed. |
| A2 | Sidecar naming convention `..provenance.json` (vs. `.provenance.json`) is right for Phase 1. | Pattern 6 | Low — convention can be flipped in 5 minutes if user has preference. Document choice in CONTEXT for Phase 5. |
| A3 | `JSON.stringify` with sorted keys is canonical-enough for CRC32 (vs. a stricter canonical-JSON library like `json-stable-stringify`). | Pattern 1 | Low — adding `json-stable-stringify` is a one-line change if a Phase 4 migration ever produces non-stable output. |
| A4 | The synthetic v0 schema `{garden: []}` is a sufficiently simple prior for the demo migration. | Pattern 2 | Very low — CONTEXT D-05 explicitly endorses any synthetic v0 shape. |
| A5 | The 10–20 north-star images can be produced as part of Phase 1 execution without a vendor lock-in (CONTEXT D-02). | Standard Stack | Medium — depends on whether the user has access to *some* AI image generation tool during Phase 1 execution. If not, a placeholder commit (10 hand-painted PNGs from a free reference + sidecars filled in honestly) satisfies AEST-08/09 minimally. |
| A6 | The `inkjs` + `inklecate` install in Phase 1 (with no compilation actually happening) is a "cheap path forward" the user prefers over deferring the install entirely. | Standard Stack | Very low — installing two deps that aren't used is harmless; deferring them leaves a Phase 2 task. Either is fine. |
| A7 | Phase 1's Vitest config can be a 5-line minimal `vitest.config.ts` with Node environment (not jsdom) — since save tests don't touch DOM. | Validation Architecture | Very low — jsdom is needed for Phase 2 React-component tests, not Phase 1. |
If this list is non-empty after planning, the planner should surface these for user confirmation before locking the plan. None of them block research.
## Open Questions
1. **Should the canonical-JSON implementation be `json-stable-stringify` or hand-rolled?**
- What we know: `JSON.stringify` is non-canonical by spec; sorted-key recursion is the standard fix.
- What's unclear: Does Phase 4+ need stronger canonicalization (Unicode normalization, number formatting)?
- Recommendation: Hand-roll the sorted-key recursion in Phase 1 (5 lines). Add `json-stable-stringify` as a dependency only if Phase 4+ surfaces a concrete reason.
2. **Does the asset validator need a `.provenance.json` schema versioning field for Phase 5 vendor migration?**
- What we know: CONTEXT D-02 defers vendor pinning to Phase 5.
- What's unclear: When Phase 5 picks a vendor, will the schema need to change (e.g., add `pipeline_version`, `human_curated_at`)?
- Recommendation: Add an optional `provenance_schema_version: number` field now (default `1`); Phase 5 bumps it if the schema evolves. This is one optional field — cheap insurance.
3. **Should `src/sim/`, `src/render/`, `src/ui/`, `src/audio/`, `src/store/` be created with `.gitkeep` or with stub `index.ts` files?**
- What we know: The directories must exist for ESLint boundaries patterns to match.
- What's unclear: `.gitkeep` is convention; `index.ts` would let ESLint also lint imports through them.
- Recommendation: `.gitkeep` for now (simpler). Phase 2 replaces with real entry points.
4. **Does Phase 1 need a CI workflow file at all (e.g., `.github/workflows/ci.yml`), or just `package.json` scripts?**
- What we know: Solo dev, the user has rejected ceremonial workflows.
- What's unclear: Is GitHub Actions in scope for Phase 1, or is "CI" satisfied by `npm run ci` running locally / in the dev's preferred CI?
- Recommendation: Ship a 20-line `.github/workflows/ci.yml` that runs `npm run ci` on PR + push to main. This is minimum-viable CI, not ceremony. If user prefers no GitHub Actions, swap to a simpler CI of their choice; the `ci` script is platform-agnostic.
## Environment Availability
| Dependency | Required By | Available | Version | Fallback |
|------------|------------|-----------|---------|----------|
| Node.js (≥20 for `recursive: true` readdir, ≥22 ideal for crypto.hash native) | All build steps | ✓ | 24.14.1 | — |
| npm | All install steps | ✓ | 11.11.0 | yarn / pnpm acceptable but template defaults to npm |
| git | Source control + commit_docs | ✓ | 2.51.0 | — |
| Modern browser (Chrome/Firefox/Safari/Edge last 2) for IndexedDB testing | CORE-04 verification | Assumed ✓ (dev machine) | — | Use Vitest's happy-dom for headless IndexedDB if no real browser available, but Playwright will need real browsers for Phase 2 PIPE-07 |
| Image generation tool (any) for north-star reference set | AEST-08 / AEST-09 / D-01 | Unknown — depends on user | — | If no tool available: commit 10 hand-painted reference images (or licensed-CC-BY photographs of real cottage gardens) with provenance fields filled in honestly (`model_id: "human"`, `prompt: "n/a"`, etc.). Schema accepts arbitrary `model_id` strings. |
**Missing dependencies with no fallback:** None known. All Phase 1 work runs on Node + npm + a browser.
**Missing dependencies with fallback:** Image generation tool — see above. Provenance schema is permissive enough that "honest human-painted" entries are valid.
## Validation Architecture
### Test Framework
| Property | Value |
|----------|-------|
| Framework | Vitest 4.1.5 (verified 2026-05-08) |
| Config file | `vitest.config.ts` (Wave 0 deliverable; minimal — no jsdom in Phase 1) |
| Quick run command | `npm test` (alias for `vitest run`) |
| Full suite command | `npm run ci` (lint + test + validate-assets + build) |
### Phase Requirements → Test Map
| Req ID | Behavior | Test Type | Automated Command | File Exists? |
|--------|----------|-----------|-------------------|-------------|
| CORE-04 | IndexedDB save round-trips with localStorage fallback path | unit | `npx vitest run src/save/db.test.ts` | ❌ Wave 0 |
| CORE-05 | `requestPersistence()` returns `{granted, apiAvailable}` shape and handles missing API | unit | `npx vitest run src/save/persist.test.ts` | ❌ Wave 0 |
| CORE-06 | `wrap()` produces valid envelope; `unwrap()` rejects checksum mismatch | unit | `npx vitest run src/save/envelope.test.ts` | ❌ Wave 0 |
| CORE-07 | `migrate({garden:[]}, 0)` produces v1 shape; `migrations[1]` is invoked exactly once | unit | `npx vitest run src/save/migrations.test.ts` | ❌ Wave 0 |
| CORE-08 | After 5 successive `snapshot()` calls, exactly 3 newest entries remain in `save_snapshots` store | unit | `npx vitest run src/save/snapshots.test.ts` | ❌ Wave 0 |
| CORE-09 | Base64 export → import → migrate → unwrap yields original payload | unit (round-trip) | `npx vitest run src/save/round-trip.test.ts` | ❌ Wave 0 |
| CORE-10 | `src/sim/` importing from `src/render/` produces ESLint error | static-analysis (CI) | `npm run lint` (with a fixture file in `src/sim/__test_violation__/` that *should* error, then asserted via a Vitest snapshot of `eslint --rulesdir` output) | ❌ Wave 0 |
| CORE-01 | Game scaffold `npm run build` produces a valid bundle | smoke (manual + Phase 2 Playwright) | `npm run build` (manual verification in Phase 1; Phase 2 PIPE-07 adds Playwright load-time spec) | manual-only in Phase 1 |
| PIPE-01 | Demo content file with deliberate schema violation fails the build | unit (build-time) | `npx vitest run src/content/loader.test.ts` (mocks the glob) + manual `npm run build` with bad fixture | ❌ Wave 0 |
| PIPE-03 | Asset validator script exits non-zero on a fixture missing provenance | integration | `node scripts/validate-assets.mjs` (fixture-driven Vitest test that temporarily creates `assets/__test__/no-provenance.png`, asserts script exits 1, cleans up) | ❌ Wave 0 |
| PIPE-05 | `.planning/anti-fomo-doctrine.md` and `.planning/season-7-end-state.md` exist with required H2 sections | doc lint (Vitest filesystem assertion) | `npx vitest run scripts/doctrine.test.ts` | ❌ Wave 0 |
| PIPE-06 | All save migration tests run on every CI build | meta — verified by CI script | `npm run ci` includes `npm test` | ❌ Wave 0 |
| AEST-08 / AEST-09 | All assets in `assets/` (excluding `__samples__/refused/`) have valid provenance sidecars | integration | `node scripts/validate-assets.mjs` (covered by PIPE-03 test) | ❌ Wave 0 |
| STRY-09 | (No automated test in Phase 1 — establishes `/content/` convention only; Phase 2+ enforces by code review since CONTEXT D-07 rejects lint rules on UX strings) | manual-only | — | n/a |
| UX-13 | (No automated test — doctrine doc is enforced by review per CONTEXT D-07) | manual-only | — | n/a |
### Sampling Rate
- **Per task commit:** `npm test` (vitest run, ~5 seconds for the entire Phase 1 test set).
- **Per wave merge:** `npm run ci` (lint + test + validate-assets + build, ~30 seconds).
- **Phase gate:** `npm run ci` green, plus manual smoke that `npm run dev` opens the Phaser scaffold in a browser. `gsd-verify-work` consumes the green CI run as evidence.
### Wave 0 Gaps
All test infrastructure must be created in Wave 0 (no test files exist in greenfield repo):
- [ ] `vitest.config.ts` — minimal config (test environment: node)
- [ ] `playwright.config.ts` — installed only, no specs in Phase 1
- [ ] `src/save/db.test.ts` — covers CORE-04 (idb open + put + get; happy-dom for IndexedDB shim)
- [ ] `src/save/persist.test.ts` — covers CORE-05
- [ ] `src/save/envelope.test.ts` — covers CORE-06
- [ ] `src/save/migrations.test.ts` — covers CORE-07
- [ ] `src/save/snapshots.test.ts` — covers CORE-08
- [ ] `src/save/round-trip.test.ts` — covers CORE-09 (and integrates CORE-04, 06, 07)
- [ ] `src/save/checksum.test.ts` — covers checksum determinism (canonical JSON keys)
- [ ] `src/content/loader.test.ts` — covers PIPE-01 (mocked `import.meta.glob`)
- [ ] `scripts/doctrine.test.ts` — covers PIPE-05 (asserts both doctrine docs exist with required H2 headings)
- [ ] `scripts/validate-assets.test.ts` — covers PIPE-03 / AEST-08 / AEST-09
- [ ] `eslint.config.js` — ESLint flat config with `eslint-plugin-boundaries` + boundary rule for `src/sim/` ↔ `src/render/`/`src/ui/`
- [ ] `src/sim/__test_violation__/violator.ts` (test fixture) — deliberate boundary violation that the lint rule MUST flag; lint test asserts ESLint output contains the expected error
- [ ] `.github/workflows/ci.yml` (or equivalent) — runs `npm run ci` on PR + push
- [ ] Framework install: `npm install -D vitest@^4 @vitest/ui happy-dom` — `happy-dom` is needed for IndexedDB in node-side Vitest; lighter than jsdom
## Security Domain
`security_enforcement` is not explicitly set in `.planning/config.json`; treat as enabled.
### Applicable ASVS Categories
| ASVS Category | Applies | Standard Control |
|---------------|---------|-----------------|
| V2 Authentication | no | No auth in Phase 1 (or v1 — local-first save model). Cloud sync is v2. |
| V3 Session Management | no | No sessions in Phase 1. |
| V4 Access Control | no | Single-player; no multi-tenant data. |
| V5 Input Validation | yes | Save envelope validated by Zod on every load (rejects malformed Base64 import, malformed envelope shape). Provenance sidecar validated by Zod. Content files validated by Zod at build. |
| V6 Cryptography | partial | CRC32 is not a cryptographic hash; it's a corruption-detection checksum. **Saves are not authenticated** — a player editing their save is fine (single-player, no leaderboards, no monetization gates in Phase 1). Document explicitly: this is by design, not by oversight. PITFALLS.md "Security/Integrity Mistakes" already endorses this. |
| V7 Error Handling | yes | Save load failures must surface the recovery option (CORE-06) — not silent reset. Phase 1 ships the error class + handler shape; Phase 2 wires the UI. |
| V8 Data Protection | partial | Saves contain no PII in Phase 1 (just garden state); even player-chosen names are not collected (no Keeper name per STRY-07). |
| V14 Configuration | yes | `npm audit` should be clean; pinned versions; no environment-secret leak in repo. |
### Known Threat Patterns for `Phaser 4 + React + IndexedDB + lz-string` stack
| Pattern | STRIDE | Standard Mitigation |
|---------|--------|---------------------|
| Save tampering (player edits Base64 export) | Tampering | Acceptable — single-player; if Phase 2+ economy values become interesting to tamper, document explicitly that we don't defend against client-side editing. CRC32 detects *corruption* (lossy storage, transmission errors), not adversarial tampering. |
| Malformed Base64 import (DoS via huge inflated string) | DoS | `lz-string.decompressFromBase64` has bounded output for bounded input; additionally, validate payload size before decompressing (cap at e.g. 50MB). |
| Cross-origin import from URL params (open future risk if save-via-link added) | Tampering / Spoofing | Phase 1 has no URL-import; flag for Phase 4+ if added: import flow must require explicit user confirmation, never auto-load. |
| `npm install` supply-chain (e.g., a transitive dep gets compromised) | Tampering | `package-lock.json` committed; `npm audit` in CI; pin Phase 1 deps to caret ranges (caught by lockfile). |
| Provenance sidecar spoofing (a malicious contributor adds an asset with a fabricated provenance) | Spoofing | Single-developer project in Phase 1; not a real threat. Phase 8+ if external contributors are added: provenance includes a `human_reviewed_by` field signed by the curator. Out of scope for Phase 1. |
| Path traversal via `import.meta.glob` (a malicious content file with `../../` in frontmatter) | Tampering | Vite glob expansion is at build time; no runtime user input. Not exploitable. Validation step never resolves paths from frontmatter values. |
### Phase 1 explicit security non-goals (documented for clarity)
- **Save authentication** — by design. Player tampering with their own save is acceptable in a contemplative single-player game.
- **Cloud sync security** — out of v1 scope.
- **Multi-user data isolation** — single-player; no isolation needed.
- **Auth / session tokens** — none in v1.
## Project Constraints (from CLAUDE.md)
The following directives from `CLAUDE.md` constrain Phase 1 implementation. The planner must verify the plan honors each:
| Directive | Phase 1 Application |
|-----------|---------------------|
| TypeScript strict; no `any` in production code | `tsconfig.json` ships with `"strict": true`; save-layer code uses `unknown` + Zod parsing for untrusted inputs (env on load, Base64 import). |
| Player-visible strings externalized in `/content/`, never hardcoded | Phase 1 establishes the convention by *not violating it*. No player-facing strings ship in Phase 1 source code (no UI yet). |
| Memory fragment IDs are stable strings (`season3.canopy.lura_07.vignette`), never numeric | Zod schema in `src/content/schemas/fragment.ts` enforces with regex (`^season\d+\.[a-z0-9._-]+$`). |
| Simulation modules are pure — no `Date.now()`, no `setInterval`, no DOM, no fetch | `src/sim/` is empty in Phase 1 (Phase 2+ fills); ESLint boundary rule is the structural enforcement. |
| BigNumbers go through the typed `BigQty` wrapper around `break_eternity.js` | **Phase 2 deliverable, not Phase 1.** Do not pre-create `BigQty` per CONTEXT. |
| Save format always carries `{schemaVersion, payload, checksum}`. Never serialize raw state | Pattern 1 above. |
| New AI-generated assets must carry full provenance metadata + pass curation gate | Pattern 6 above. |
| Tone — player-facing copy is warm, specific, intermittent, sometimes funny, sometimes devastating | No player copy in Phase 1; doctrine docs themselves can be functional — they are project-internal. |
| `/content/` is at repo root, alongside `src/`, `assets/`, `.planning/` | CONTEXT D-11 confirms; structure above honors it. |
| `/assets/` at repo root | CONTEXT D-12 confirms. |
| No monorepo / no workspaces | CONTEXT D-12 confirms; single `package.json`. |
## Sources
### Primary (HIGH confidence)
- [eslint-plugin-boundaries README on GitHub](https://github.com/javierbrea/eslint-plugin-boundaries/blob/master/README.md) — config patterns, element-types rule, flat-config example
- [npm registry — verified 2026-05-08 for all package versions](https://www.npmjs.com/) — `npm view version` for phaser, react, vite, typescript, idb, lz-string, zod, vitest, @playwright/test, eslint-plugin-boundaries, crc-32, gray-matter, yaml, inkjs, inklecate, howler, break_eternity.js, zustand
- [idb GitHub — jakearchibald/idb](https://github.com/jakearchibald/idb) — openDB API, upgrade callback, put/get shortcuts
- [Phaser v4.1.0 "Salusa" release notes](https://phaser.io/news/2026/04/phaser-4-1-0-salusa-release) — version, ESM fixes, Layer rework
- [Phaser official template — phaserjs/template-react-ts](https://github.com/phaserjs/template-react-ts) — root structure, src/ layout, package.json scripts, dependencies
- [MDN — `navigator.storage.persist()`](https://developer.mozilla.org/en-US/docs/Web/API/StorageManager/persist) — return value semantics, `false` conditions
- [Vite docs — features (`import.meta.glob`)](https://vite.dev/guide/features#glob-import) — eager mode, query/import options, literal-pattern requirement
- [Zod docs — z.infer + safeParse](https://zod.dev/) — type derivation, runtime validation
- [Vitest docs — projects (replaces workspace)](https://vitest.dev/guide/projects) — multi-config; not needed for Phase 1 single config
### Secondary (MEDIUM confidence)
- [SheetJS/js-crc32 — crc-32 npm package](https://github.com/SheetJS/js-crc32) — performance benchmarks (~426k ops/sec), API
- [Emanuele Feronato — Getting Started with Phaser 4 (April 2026)](https://emanueleferonato.com/2026/04/17/getting-started-with-phaser-4-vite-typescript-setup-using-the-official-create-game-app/) — `create-phaser-game` flow walkthrough
- [Trivikr — benchmark-crc32](https://github.com/trivikr/benchmark-crc32) — comparative speed of CRC32 npm packages
- [pieroxy.net — lz-string](https://pieroxy.net/blog/pages/lz-string/index.html) — `compressToBase64` / `decompressFromBase64` semantics, encoding rates
### Tertiary (LOW confidence — flagged for validation)
- [Magicbell — PWA iOS Limitations 2026](https://www.magicbell.com/blog/pwa-ios-limitations-safari-support-complete-guide) — Safari 17 partial persistence support; verified by MDN secondarily
- [DEV.to — Why Your IndexedDB Data Keeps Disappearing](https://dev.to/denyherianto/why-your-indexeddb-data-keeps-disappearing-1m0a) — Chrome storage-pressure eviction patterns
- [WebKit Bug 266559 — Safari periodic eviction of LocalStorage and IndexedDB](https://bugs.webkit.org/show_bug.cgi?id=266559) — referenced in PITFALLS.md; not re-verified in this research session
## Metadata
**Confidence breakdown:**
- Standard stack: HIGH — every package version verified against npm registry on 2026-05-08; locked versions match user constraints from CONTEXT.
- Architecture (save layer, content pipeline, ESLint, validator): HIGH — patterns verified against official docs (idb, Vite, eslint-plugin-boundaries, MDN); shape is conservative and minimum-viable per user's anti-overengineering directive.
- Pitfalls: HIGH for stack-specific, MEDIUM for browser quirks (Safari persist behavior is fast-moving; verified against MDN today but worth re-confirming if Phase 1 execution drags past 60 days).
- Doctrine doc outlines: MEDIUM — they are *suggestions* for principle-level structure; the user is the final arbiter of what "principle-level" means for The Last Garden. The shape is informed by the source documents the docs consolidate.
- Validation architecture: HIGH — every Phase 1 success criterion maps to a concrete automated test command, with one exception (CORE-01 load-time, which is manual in Phase 1 and gets Playwright coverage in Phase 2 PIPE-07).
**Research date:** 2026-05-08
**Valid until:** 2026-06-08 (30 days — stack is stable but Vite 8 / Phaser 4.x landings could rotate)