Checkpoint WebGL book playback refactor state

docs/webgl-3d-ui-spec.md

@@ -6,16 +6,16 @@ This document captures the agreed direction for the WebGL book UI. Later decisio
 
 Build a beautiful, readable, extensible WebGL book interface for the interactive fiction UI.
 
-The current stable milestone is `public/webgl-book-lab.html`: an open procedural book lying on a polished wooden table, lit by flickering candles, with the existing application page content rendered into textures that are applied to the actual top surfaces of the paper stacks.
+The current stable milestone is the integrated 3D game UI at `http://localhost:3001/`: an open procedural book lying on a polished wooden table, lit by flickering candles, with game content typeset directly into texture-space canvases and applied to the actual top surfaces of the paper stacks.
 
-The later product goal is a procedural book UI that supports virtual scrolling, animated page flips, dynamic page stacks, and content backfilling across spreads.
+The product goal is a procedural book UI that supports virtual scrolling, animated page flips, dynamic page stacks, and content backfilling across spreads.
 
 ## Current Implementation Snapshot
 
 This section records the current state after the procedural book integration work.
 
-- The active standalone scene is `public/webgl-book-lab.html`.
-- The intended local test URL is `http://localhost:3001/webgl-book-lab.html`.
+- The active integrated scene is loaded through the game at `http://localhost:3001/`.
+- `public/webgl-book-lab.html` remains a reference/prototype file, not the primary implementation target.
 - The current test server is expected to be the single Node process listening on port `3001`.
 - The procedural book model lives in `public/js/procedural-book-model.js`.
 - The WebGL lab integration lives in `public/js/webgl-book-lab.js`.
@@ -29,7 +29,7 @@ This section records the current state after the procedural book integration wor
 - `PAGE_SPLINE_LENGTH` must match `PAGE_WIDTH`.
 - Cover width is derived from page width plus cover overhang.
 - The spine bottom is aligned to the table plane with only a tiny render clearance.
-- The book controls are in the top bar: fast backward, backward, progress slider, page-count slider, forward, and fast forward.
+- The book navigation controls are the bottom media-style navigation controls: return to beginning, flip backward, page-position scrollbar, flip forward, and go to end.
 - Slow page flips and fast 10-page transitions are implemented.
 - Fast transitions run overlapping flip animations before shifting the book by one bundle.
 - The readable page content belongs on the visible top cap of the paper stacks.
@@ -52,6 +52,41 @@ This section records the current state after the procedural book integration wor
 - The custom book material shader includes a small local indirect/bounce-light term for book surfaces. This is not emissive; it is multiplied by material albedo so paper, leather, and head/end-band colors remain distinct while shadowed side faces stay readable.
 - Temporary screenshots and generated debug images are not product assets unless explicitly promoted.
 
+## Current Page-Flow Architecture
+
+The 3D book pipeline is module-owned. No page content should be generated by ad hoc scene code.
+
+- `ui-display-handler` owns the live 3D prepare -> optional page flip -> activate sequence for story text.
+- `sentence-queue` may prepare future page presentations during lookahead using the same pagination and texture renderer modules.
+- `book-pagination` owns page/spread construction, page metadata, widows/orphans/hyphenation decisions, image placement decisions, and explicit blank/title/body page records.
+- `book-texture-renderer` owns drawing final page canvases, reveal-region coordinates, reveal timing metadata, and publishing explicit `webgl-book:page-texture-records`.
+- `webgl-page-cache` owns persistent page canvases, memory canvases, prepared reveal plans, prepared GPU textures, resident VRAM textures, blank page texture, and visible texture bindings.
+- `webgl-book-lab` owns the Three.js scene, materials, geometry, pointer projection, page flip meshes, and consuming page texture records. It must not become a second page cache.
+
+Problem states must be surfaced instead of hidden:
+
+- A missing persistent page canvas during prewarm is a `db-cache-miss`.
+- A missing source or required back texture before a page flip is a `flip-source-texture-missing` or `flip-back-texture-missing`.
+- These problem states must appear in `webglPageCacheProblems` and must not be silently fixed by borrowing unrelated visible stack textures.
+
+## Event Surface
+
+The preferred 3D book content path is direct module calls through `ui-display-handler` for live playback and `sentence-queue` for lookahead preparation.
+
+The following events remain formal integration events and must keep their meaning stable while they exist:
+
+- `webgl-book:page-texture-records` publishes explicit page texture records from `book-texture-renderer` to the WebGL scene.
+- `webgl-book:page-reveal-start` starts shader reveal timing for the prepared block.
+- `webgl-book:page-reveal-fast-forward` accelerates reveal timing without replacing the page pipeline.
+- `webgl-book:reveal-committed` reports that a page-side reveal completed; if `pageFlipAfterReveal` is true, the WebGL scene may arm a page flip.
+- `webgl-book:request-page-flip` requests a physical page flip through the WebGL scene.
+- `webgl-book:page-flip-started`, `webgl-book:page-flip-near-end`, and `webgl-book:page-flip-finished` describe the physical flip lifecycle.
+
+Deprecated or forbidden event contracts:
+
+- `webgl-book:page-canvases` is obsolete. New code must use `webgl-book:page-texture-records`.
+- `preloadOnly` and `allowFutureUnrendered` are obsolete boolean flags. New code must use explicit `phase` and `visibility` values.
+
 ## Non-Negotiable Workflow Rules
 
 - Do not continue visual coding without a concrete plan for the current sprint.