Epic: v0.4.0 — The Field Guide #92

New issue

Closed

opened 2026-07-11 17:58:40 +00:00 by manlycucumber · 1 comment

manlycucumber commented

2026-07-11 17:58:40 +00:00

(Migrated from github.com)

The Field Guide (v0.4.0) — a second way into the creatures the Library already holds: browse them by habitat and by kind, meet each one's anatomy diagram and range map, and keep a quiet per-child album of the creatures you've read about. No new content silo; it layers on Library frontmatter.

Done when (roadmap): habitat/kind index over approved creatures; the profile-scoped card album (records, no incentives); ≥1 hotspot diagram + range map (placeholder art), keyboard-accessible; offline.

Architecture is vetted (a multi-agent design workshop: 3 proposals → 3 judges → synthesis → 5 adversarial critics → reconciliation; 24 findings folded in) and written up in docs/architecture/field-guide.md.

Ratified decisions (2026-07-11)

Rendering: SVG/DOM, not PixiJS (unanimous). A WebGL canvas renders nothing at prerender / with JS off (a guard:offline hole) and is invisible to screen readers (so you'd build the accessible DOM version underneath it anyway). Pixi stays reserved for the Art Studio's raster needs. Revisit only on a true raster/deep-canvas trigger.
kind, not type for the second axis — matches shipped desktop copy ("Browse by habitat or by kind"), reads better for kids, avoids the JS reserved word.
Illustration aesthetic deferred to the owner; build art-agnostic (one swap-point per asset class).
Album is records, not rewards — an explicit anti-incentive checklist, gate-enforced (no count, no percent, no rarity/streak/score, silent record-moment).

PR slicing (each ships green)

FG-1 (#93, 4fbeb6d) · Creature schema (habitat/kind closed enums, .superRefine creatures-only; backfill red-fox)
FG-2 (#94, b01568f) · recordOnce (tombstone-aware, idempotent) + album.ts state module
FG-3a (#95, 85c03d1) · Hub route + window activation + shared anchorIntercept.ts (LibraryBody refactors onto it)
FG-3b (#96, ee48802) · Axis routes /field-guide/habitat/[habitat]/ + /kind/[kind]/ (AxisView, gated-present entries())
FG-4 (#97, c344125) · Record-on-read wiring (RecordOnRead at 3 hosts; profile snapshot at mount, silent, idempotent)
FG-5 · Album view (JS-only convenience; anti-incentive gate; pinned copy)
FG-6 · Anatomy hotspot diagram (SVG/DOM; blurbs baked no-JS-readable; validateFieldGuide)
FG-7 · Habitat range map (SVG/DOM; bundled static/maps/base.svg; regions validated against the parsed SVG)

Deps: FG-1 → FG-3a → FG-3b; FG-2 independent; FG-4 needs FG-2+FG-3a; FG-5 needs FG-3a(+FG-2); FG-6/FG-7 need FG-1.

The **Field Guide** (v0.4.0) — a second way into the creatures the Library already holds: browse them **by habitat** and **by kind**, meet each one's **anatomy diagram** and **range map**, and keep a quiet per-child **album** of the creatures you've read about. No new content silo; it layers on Library frontmatter. **Done when** (roadmap): habitat/kind index over approved creatures; the profile-scoped card album (records, no incentives); ≥1 hotspot diagram + range map (placeholder art), keyboard-accessible; offline. Architecture is vetted (a multi-agent design workshop: 3 proposals → 3 judges → synthesis → 5 adversarial critics → reconciliation; 24 findings folded in) and written up in [`docs/architecture/field-guide.md`](docs/architecture/field-guide.md). ## Ratified decisions (2026-07-11) - **Rendering: SVG/DOM, not PixiJS** (unanimous). A WebGL canvas renders nothing at prerender / with JS off (a `guard:offline` hole) and is invisible to screen readers (so you'd build the accessible DOM version underneath it anyway). Pixi stays reserved for the Art Studio's raster needs. Revisit only on a true raster/deep-canvas trigger. - **`kind`, not `type`** for the second axis — matches shipped desktop copy ("Browse by habitat or by kind"), reads better for kids, avoids the JS reserved word. - **Illustration aesthetic deferred** to the owner; build art-agnostic (one swap-point per asset class). - **Album is records, not rewards** — an explicit anti-incentive checklist, gate-enforced (no count, no percent, no rarity/streak/score, silent record-moment). ## PR slicing (each ships green) - [x] **FG-1** (#93, `4fbeb6d`) · Creature schema (`habitat`/`kind` closed enums, `.superRefine` creatures-only; backfill red-fox) - [x] **FG-2** (#94, `b01568f`) · `recordOnce` (tombstone-aware, idempotent) + `album.ts` state module - [x] **FG-3a** (#95, `85c03d1`) · Hub route + window activation + shared `anchorIntercept.ts` (LibraryBody refactors onto it) - [x] **FG-3b** (#96, `ee48802`) · Axis routes `/field-guide/habitat/[habitat]/` + `/kind/[kind]/` (`AxisView`, gated-present `entries()`) - [x] **FG-4** (#97, `c344125`) · Record-on-read wiring (`RecordOnRead` at 3 hosts; profile snapshot at mount, silent, idempotent) - [ ] **FG-5** · Album view (JS-only convenience; anti-incentive gate; pinned copy) - [ ] **FG-6** · Anatomy hotspot diagram (SVG/DOM; blurbs baked no-JS-readable; `validateFieldGuide`) - [ ] **FG-7** · Habitat range map (SVG/DOM; bundled `static/maps/base.svg`; regions validated against the parsed SVG) Deps: FG-1 → FG-3a → FG-3b; FG-2 independent; FG-4 needs FG-2+FG-3a; FG-5 needs FG-3a(+FG-2); FG-6/FG-7 need FG-1.

manlycucumber commented

2026-08-14 22:03:37 +00:00

Owner

Closing: the Field Guide engine has been complete since July. The three boxes still unticked here all merged a month ago —

FG-5 · Album view — b1da2a3 (#98)
FG-6 · Anatomy hotspot diagram — d5cb339 (#99)
FG-7 · Habitat range map — 76ad9f1 (#108)

joining FG-1 (4fbeb6d), FG-2 (b01568f), FG-3a (85c03d1), FG-3b (ee48802) and FG-4 (c344125). Against the roadmap's "done when": the habitat/kind index over approved creatures ships, the profile-scoped album ships with its anti-incentive gate test, and both the hotspot diagram and the range map ship as SVG/DOM with placeholder art, keyboard-accessible and no-JS-readable.

What remains under the v0.4.0 — Field Guide milestone is content, not engine: the guide is wired to Library frontmatter and there are two approved topics to feed it. That is owner-paced by design and does not need this epic held open.

The ratified decisions recorded here — SVG/DOM over PixiJS, kind over type, deferred illustration aesthetic, album-as-records — remain the standing design authority in docs/architecture/field-guide.md.

Closing: the Field Guide engine has been complete since July. The three boxes still unticked here all merged a month ago — - **FG-5** · Album view — `b1da2a3` (#98) - **FG-6** · Anatomy hotspot diagram — `d5cb339` (#99) - **FG-7** · Habitat range map — `76ad9f1` (#108) joining FG-1 (`4fbeb6d`), FG-2 (`b01568f`), FG-3a (`85c03d1`), FG-3b (`ee48802`) and FG-4 (`c344125`). Against the roadmap's "done when": the habitat/kind index over approved creatures ships, the profile-scoped album ships with its anti-incentive gate test, and both the hotspot diagram and the range map ship as SVG/DOM with placeholder art, keyboard-accessible and no-JS-readable. What remains under the **v0.4.0 — Field Guide** milestone is content, not engine: the guide is wired to Library frontmatter and there are two approved topics to feed it. That is owner-paced by design and does not need this epic held open. The ratified decisions recorded here — SVG/DOM over PixiJS, `kind` over `type`, deferred illustration aesthetic, album-as-records — remain the standing design authority in [`docs/architecture/field-guide.md`](docs/architecture/field-guide.md).

manlycucumber closed this issue

2026-08-14 22:03:37 +00:00