--- name: webgl-standards description: DORMANT (ADR-0017, 2026-07-20) - the TERMINAL VELOCITY scroll-film was retired and apps/landing is a static site with no GL surface; this skill is preserved for any future WebGL rebuild (conventions, verified version pins, playhead/scroll-rig/VAT/Gerstner/post-chain patterns, budgets, gate + semantic-layer machinery). Do not load for current apps/landing work - the static site routes to project-steward. ---

# apps/landing WebGL standards (TERMINAL VELOCITY)

> **DORMANT — ADR-0017 (2026-07-20).** The scroll-film was retired mid-M4; `apps/landing` > is now the self-contained static site with no `src/` and no GL surface, owned by > `project-steward`. Everything below is preserved verbatim as the starting point for a > future WebGL rebuild (M1-M3 remain in git history at #720-#722; the M4 tree is stashed > on `feat/tv-m4-robot`). Do not apply it to the static site.

The single source both GL authors (`webgl-author`, `shader-engineer`) and their critics (`webgl-reviewer`, `gate-auditor`, `webgl-perf-profiler`) read before touching `apps/landing`. Experience contract + rationale: `docs/knowledge/decision-records/0016-terminal-velocity-scroll-film-landing.md` (the source of truth). Still-binding structural machinery (Next 16 static export, Semantic layer, Experience gate, `landing/` passthrough, staged flip): `docs/knowledge/decision-records/0014-landing-gl-takeover.md`. **The ADR holds the decisions; this skill holds the tunable numbers and their current starting values.** Every constant below marked _tunable_ may move within its ADR envelope during M1..M6.

## What TERMINAL VELOCITY is

A realistic CG **scroll-film** (~2:40). Scroll IS the **playhead** (native-scroll -> timeline 0->1), fully reversible: scrolling up rewinds. One camera, one continuous vertical world, zero cuts - a burned-out job hunter tips off his chair at 2:47 AM and falls through a canyon of rejection towers into a paper ocean to the lightless bottom, where a robot finds him and carries him back up to dawn. It does everything except press send (the finale SEND button is the one real action). Copy is diegetic and in-world; the prerendered **Semantic layer** keeps the machine-readable and crawlable copy. RIPBOOK (the notebook / rip / boil / in-canvas SDF model) is fully retired - see ADR 0016 Supersessions; do not carry any RIPBOOK rule forward.

## Ownership split (who edits what)

- **`webgl-author`**: the R3F scene graph, the scroll rig + store + governor wiring, instancing and DataTexture bookkeeping, glTF-clip mixer scrub, asset loading + KTX2/DRACO decoder wiring, the a11y overlay + semantic layer, camera/animation `useFrame` loops. - **`shader-engineer`**: all GLSL, custom postprocessing `Effect`/`Pass` classes, `onBeforeCompile` material patches, `src/post/**`, the Gerstner/caustics/godrays/VAT-decode shader math. Hand those to `shader-engineer`; the author wires the material + uniforms, never authors the shader.

## The stack + version pins (verified 2026-07-18 - do NOT drift)

Full-canvas R3F v9 + three 0.185 on a **WebGL2 lane** for v1 (TSL/WebGPU is a deliberate tier-up experiment only - it would force rebuilding the whole post chain). Every pin below was verified with `npm view <pkg> version` / `... peerDependencies`; the lockfile must match `apps/landing/package.json`.

| Package | Pin | Why / peer note | | ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | three | 0.185.1 | the `~0.185` line R3F v9 + drei target | | @react-three/fiber | 9.6.1 | pairs with React 19 (peer `react >=19 <19.3`, `three >=0.156`) | | @react-three/drei | 10.7.7 | peer `@react-three/fiber ^9.0.0`, `three >=0.159`, `react ^19` | | postprocessing | 6.39.2 | pmndrs composer; peer `three >= 0.168.0 < 0.186.0` (0.185.1 OK). See caveat below | | three-good-godrays | 0.12.0 | shadow-map raymarched shafts. PEER MISMATCH - see caveat, unresolved pin | | gsap | 3.15.0 | ONE ScrollTrigger master timeline, `scrub:true` | | lenis | 1.3.25 | owns document scroll; rAF driven from `gsap.ticker` | | detect-gpu | 5.0.70 | startup quality tier (no three peer) | | zustand | 5.0.14 | per-frame scroll/store reads via `getState()`, never a per-frame hook selector | | VAT playback | in-house | `three-vat` does NOT exist on npm. In-house shader; see VAT caveat below | | react / react-dom | 19.2.7 | R3F v9 requires React 19 (peer `>=19 <19.3`) | | next | 16.2.10 | static export (`output: 'export'`) | | typescript | 6.0.3 | | | troika-three-text | 0.52.4 | OPTIONAL, chrome-only (letterbox/timecode/depth-gauge labels). NOT the copy authority any more; the Semantic layer is. TTF-only, explicit `characters`. | | framer-motion | ^12 | DOM-only: title card / mute toggle / a11y overlay - NEVER over the canvas |

**Pin caveats that bite:**

- **postprocessing - NEVER 6.39.0.** 6.39.0's three peer is `>= 0.168.0 < 0.184.0`, which excludes our three 0.185.1; a lockfile resolving 6.39.0 is a blocker. 6.39.2 (and 6.39.3, same peer `< 0.186.0`) fix it. Stay on 6.39.2 to match the lockfile; do not float. - **three-good-godrays 0.12.0 - declared peer excludes our three.** Its peer is `three '>= 0.125.0 <= 0.182.0'` (postprocessing `^6.33.4`, satisfied). Our three 0.185.1 is ABOVE that hard cap, so `pnpm install` emits an unmet-peer WARNING (not an error - the repo has no `strict-peer-dependencies`, so it installs). This is UNVERIFIED-at-runtime until M3: the godrays Pass raymarches the shadow map through stable three API, so it is likely fine on 0.185, but that is an assumption. Resolution options, decide at M3: (a) widen the peer with a `pnpm-workspace.yaml` `packageExtensions` entry and verify the shafts actually render, keeping an inline raymarch effect as fallback; (b) if it breaks, inline the raymarch as an in-house postprocessing Effect (shader-engineer). Do not silently ship broken shafts. - **VAT playback is in-house (no dep).** The package `three-vat` named in early notes does NOT exist on npm (404). The only real three.js VAT lib is `@floatingworld/vat3-threejs@0.1.1` (MIT, SideFX Labs VAT 3.0) - but it is a single unproven 0.1.1 release and its peer `three ^0.175.0` (caret on 0.x = `>=0.175.0 <0.176.0`) also excludes our 0.185.1. Decision: **do VAT decode in-house** - it is ~40 lines of deterministic vertex-shader texture sampling we must own anyway for the scrub contract, and it avoids a micro-dependency on the critical path. Crib the VAT 3.0 decode math (position + normal texture layout, fluid mode) from `@floatingworld/vat3-threejs` (MIT) as reference; do not add it as a runtime dep. (shader-engineer owns the decode shader.)

## The playhead model

Scroll = a single global **playhead** `t` in `[0,1]`, mapped 1:1 from native scroll over a total page length of **3,000 svh** (_tunable_, ADR envelope 2,000-4,000 svh) - a `100vh`-equivalent computed ONCE at mount from `window.visualViewport?.height ?? window.innerHeight` and **frozen** into a fixed pixel scroll-track height for the session (never a live `vh` unit, which reflows on mobile browser chrome show/hide and would move the playhead under the user's finger). One idea per scroll step. Everything scroll-driven is a **pure function of `t`**, scrub-safe both directions - no time-accumulated state driving scroll visuals.

**Scrub smoothing:** damp the raw playhead with a scrub factor of **0.6** (_skill-owned starting value, tunable in the 0.5-1 band - not an ADR figure) plus Lenis lerp; **both smoothings are DISABLED under reduced motion / the in-page motion toggle** (the reduced-motion path is a chapter-stepped slideshow, not a damped scrub).

**Scrub-never-hijack:** no wheel `preventDefault`, no scroll snap, no scroll-ownership override. Native scroll maps straight to the playhead. Interactions perturb particles / play vignettes but **never move the playhead** (determinism is load-bearing).

**The 9-scene scroll map** expands ADR 0016's approximate `%` ranges into **half-open intervals** `[lo, hi)` (skill-owned precision refinement) so adjacent scenes never overlap at a shared boundary; only the final scene is closed at both ends. Scene `i` is active when `t` is in `[lo_i, hi_i)` (`[0.95, 1.00]` for scene 8):

| # | Scene | playhead `t` | Locked beat | | --- | -------------- | ------------ | -------------------------------------------------------------------------------------- | | 0 | Cold open | [0.00, 0.05) | Live monitor (FINAL_v9, 2:47 AM), chair tips past balance, title card, floor dissolves | | 1 | The canyon | [0.05, 0.30) | Slow-mo backward fall down glowing rejection towers; paper storm thickens | | 2 | The surface | [0.30, 0.38) | Hits the paper ocean; the one hard beat - letterbox flexes, sound cuts, splash crown | | 3 | The deep | [0.38, 0.52) | Underwater, god-rays thin band by band; he goes limp - the saddest frame | | 4 | Blackout | [0.52, 0.58) | Near-total dark, breathing only; a single amber point of light appears below | | 5 | The catch | [0.58, 0.64) | A submersible drone catches him gently; the "Are you sure?" HUD gag | | 6 | The ascent | [0.64, 0.85) | Axis inverts; robot carries him up; paper folds into planes in formation; he sleeps | | 7 | Dawn | [0.85, 0.95) | Surface break into flat calm at sunrise; first warm full-color frame | | 8 | Finale/credits | [0.95, 1.00] | Robot surfaces holding one red SEND button (the CTA); credits roll; creature sting |

Per-scene local progress `sp` = `(t - lo) / (hi - lo)` clamped to `[0,1)` (`[0,1]` for scene 8); scenes map their own sub-beats off `sp`, never off wall-clock. The axis bends back up at the ascent so the SAME water is descended (scene 3) then re-ascended (scene 6) - one world, reversible.

## Scroll rig contract

- **Lenis owns document scroll**, its rAF driven from `gsap.ticker` (not its own rAF); call `ScrollTrigger.update` on `lenis.on('scroll', ...)`. - **ONE master GSAP ScrollTrigger, `scrub:true` timeline.** Absolute tweens ONLY - no `+=` accumulation anywh