@field/cascade 0.3.1 → 0.5.1

package/AGENTS.md

@@ -1,6 +1,6 @@
 # Cascade agent guide
 
-Cascade is a reusable generative-design graph runtime with an optional Studio UI. Keep authored algorithms independent from the editor so the same graph can run in Studio, on a server, or in a UI-free browser host.
+Cascade is a reusable generative-design graph runtime with an optional Studio UI. Keep authored algorithms independent from the editor so a graph can run in Studio, on a server, or in a UI-free browser host when its declared execution locus and capabilities are supported.
 
 ## Start here
 
@@ -37,6 +37,15 @@ my-project/
 
 Use `cascade new <name>` to create a project and `cascade node <Name>` to scaffold a custom node in one. Run `cascade .` from a project root to open Studio, `cascade validate <graph.cascade>` for validation, `cascade check <graph.cascade>` for static definition/type checks, `cascade inspect <graph.cascade>` for a JSON summary, `cascade run <graph.cascade>` for headless execution, and `cascade run <graph.cascade> --frames 1-100` for an offline image sequence. `cascade projects` shows or sets the default projects directory.
 
+`cascade build <graph.cascade> --out <new-directory>` exports a static browser
+player. Use repeatable `--asset <project-relative-file>` for inputs whose paths
+are computed in code. Read `doc/WEB_PLAYER.md` before exporting: server stages
+and dynamic modules are not supported, assets must be explicit, and an existing
+output directory is never overwritten. Serve the result over HTTP, not file://.
+The player is an application host under `src/player`, not another graph engine.
+Each embed owns an iframe realm, assets, IO bridge and GPU lifecycle. No Studio
+imports or `/api/*` dependency may enter the static deployment.
+
 ## Launch Studio
 
 For a browser on the same machine, use the secure loopback default:
@@ -73,7 +82,7 @@ Project panels are trusted Studio extensions, not graph/runtime modules. Put the
 
 ## Create a deterministic node
 
-Two node styles exist and both are current. A **definition-v1** module exports a literal `definition` and a typed `execute(context)`; it is statically inspectable, it is what `cascade check` requires, and it runs through the deterministic runtime. A **dynamic** module exports `execute(node, graph)` and declares its ports and parameters imperatively inside it; that is what `cascade run --frames` renders. Studio cooks both, dispatching on what the compiled module exports (`src/nodes/definition/projectDefinition.ts`), so a project node written either way runs in the editor. Prefer definition-v1 for anything new inside this repository, and do not call dynamic modules "legacy" — the naming was retired in 0.3.0, and while Studio no longer blocks the migration, the existing sketches are still dynamic.
+Two node styles exist and both are supported. A **definition-v1** module exports a literal `definition` and a typed `execute(context)`; it is statically inspectable and is what `cascade check` requires. A **dynamic** module exports `execute(node, graph)` and declares its ports and parameters imperatively inside it. Studio cooks both through `src/nodes/definition/projectDefinition.ts`. The CLI supports stills and frame sequences for fully deterministic graphs and for supported dynamic graphs, but rejects graphs mixing the two execution styles. Prefer definition-v1 for new nodes; inspect a project's current modules before assuming its style. Do not call dynamic modules "legacy" in user-facing guidance.
 
 A definition-v1 module looks like this:
 
@@ -107,6 +116,9 @@ Definition rules:
   and have the host registration select the executor. Never expose execution
   location as an artist parameter; parity-test the shared contract.
 - Declare every capability used. File, Python, and shell access are server-only; WebGL is browser-only.
+- `context.nodeId` identifies the instance for namespaces such as `cachePath(context.nodeId, '.png')`; it does not grant access to siblings or hierarchy. A final output may instead have an artist-authored filename.
+- Vector props support `min`, `max`, and `step`, shared across components. Props may declare a default `expression`; an explicitly saved value overrides that default, including when it equals the numeric default.
+- WebGPU nodes declare `gpu` and use its shared device and per-node `cache`. Portable GPU nodes can run through optional Dawn in the CLI; browser-only declarations remain refused. Import constants and explicit `readTexture` (RGBA8 only) from `cascade/gpu`. Graph texture exchange remains future work. See `doc/HEADLESS_GPU.md` for bounded agent renders, diagnostics and hardware tests.
 - Treat graph wires as the primary data boundary. A node may observe only its connected inputs, its props, and declared host capabilities; it must not inspect sibling nodes or the graph to discover data.
 - Deterministic node modules may not retain module-level mutable values, access ambient state such as `globalThis`, browser storage, or `process`, run top-level effects, or import sibling node implementations. `cascade check` reports these as `architecture/*` diagnostics.
 - A cache may memoize computation from wired inputs, but it must never supply unwired data. Make cache use an explicitly labelled prop and keep cache keys derived from the complete wired input and relevant props.
@@ -124,6 +136,7 @@ Use the runtime-native core vocabulary before creating a project wrapper:
 - `cascade.core.Null` passes any value through unchanged so downstream wiring can remain stable while upstream branches are reorganized.
 - `cascade.core.Random` maps explicit integer `seed` and `sample` inputs to a stable float in `[0, 1)`.
 - `cascade.core.Remap` maps scalar ranges and optionally clamps via its `clamp` prop.
+- `cascade.core.Camera` emits the one `camera` type, following Houdini's `/obj/cam`: `translate` and `rotate` (degrees, XYZ) with an optional `lookat`, and a lens given as `focal` and `aperture` in millimetres rather than as a field of view. A camera looks down its own **-Z** with **+Y** up. `resolution` is on the camera because Houdini derives the vertical aperture from the frame shape, and it is one `vec2i` rather than Houdini's `resx`/`resy` because the vec rule below is the more specific one. Every derivation — the basis, the view and projection matrices, the horizontal and vertical angles — lives in `packages/runtime/src/camera`; never derive them a second time in a renderer.
 
 The geometry set is reserved the same way, under `cascade.geo.*`:
 `Rectangle`, `Circle`, `Transform`, `Merge`, `CopyToPoints`, and `SvgExport`.
@@ -131,6 +144,15 @@ They all speak the one `geometry` type, so any output fits any input, and they
 follow Houdini's parameter names where Houdini has an equivalent node. Geometry
 is +Y up; the flip into SVG's frame lives in `SvgExport` alone.
 
+`cascade.pop.*` uses geometry-native particle state; forces accumulate and the
+solver integrates once. `cascade.core.Feedback` owns previous state and bounded
+history, including nested loops. Trails are geometry, not a second canvas
+history. A checkpoint is only an accelerator: cold and warm runs must match
+complete geometry and trails. `cascade.scene.*` assembles geometry, camera and
+lights; the current renderer draws wireframes/points and does not shade lights.
+Read the generated reference for the complete library rather than extending
+the partial vocabulary examples in this guide.
+
 These modules are reserved and need no file under `nodes/`. Do not override a
 `cascade.core.*` module or use ambient random/time state in a portable node.
 Time and randomness reach a parameter as an expression or a keyframe channel,
@@ -146,13 +168,13 @@ type system knows what a `vec2` is; nothing tells it that `offset_x` and
 
 ## Animation, expressions, and parameters
 
-- **`Node.evalParm` in `src/nodes/Node.ts` is the only place a parameter's bindings resolve**, in the order channel, expression, value. Never read `prop.value` to obtain an animated parameter, and never add a second resolution path: an expression badge and a viewer disagreeing about the same frame is exactly what one produced.
+- **`resolvePropBinding` in `packages/runtime/src/params/resolve.ts` owns binding precedence:** channel, expression, value. Studio's `Node.evalParm` and the neutral runtime both call it with their own expression scope and frame. Never read `prop.value` to obtain an animated parameter or implement a second precedence rule.
 - **A parameter is one store.** `param()` declares the parameter; the value, the expression and the channel live in the prop of the same name. `NodeParameter.value` reads *resolved*; `rawParameterValue()` reads what the author typed, and is what serialization and cache keys must use. `param()` is re-declared on every cook of a dynamic node, so it must stay idempotent — it may never reset a value, an expression, or a channel.
 - **Mechanisms belong to the runtime, composition to the host.** `packages/runtime/src/expressions` owns preprocessing, scope and the maths library; `packages/runtime/src/animation` owns the channel model, sampling, interpolation, serialization and frame-range walking. Both depend only on contracts. Do not implement interpolation, a frame clock, or a second `$T` anywhere else.
 - **The serialized shape is owned by contracts** (`packages/contracts/src/animation.ts`): a channel is `{ keys: [{ frame, value, interpolation? }] }` inside the node's `props`, with `interpolation` omitted when it is the `smooth` default. There is no timeline section in the document, and adding one would need reconciling on every rename, delete and embed.
 - Bare trigonometry is **radians**, deliberately unlike Houdini; `sind`/`cosd`/`tand`/`radians()`/`degrees()` exist for formulae carried over. Only `ch()`, `chs()` and `chv()` are scanned for dependencies, so a new way to reach another parameter also needs a dependency pattern or it will not recook.
-- The deterministic runtime has no parameter animation. `cascade run --frames` refuses a definition-v1 graph rather than rendering frame 1 repeatedly. Extending animation to that runtime is a migration step; do not add a compatibility branch to Studio for it.
-- Studio's timeline panel holds its own frame range, loop and playhead. Only fps reaches the engine clock. Nothing about playback is saved with the document.
+- The deterministic runtime resolves parameter animation through `setFrame`, `setFps`, and `run({ frame, fps })`. `cascade run --frames` supports fully definition-v1 graphs when the Node host can supply their capabilities. A browser-only node still cannot run in that host.
+- Studio's timeline supplies the playhead and fps to the engine; its range and loop setting are panel state. Parameter channels are saved in the document, but playback settings are not.
 
 ## Agent sessions
 
@@ -178,7 +200,7 @@ type system knows what a `vec2` is; nothing tells it that `offset_x` and
 - Contracts have no runtime dependencies.
 - Runtime depends only on contracts and contains no DOM, Svelte, Express, Node filesystem, or child-process imports.
 - Hosts inject capabilities explicitly.
-- Studio consumes runtime through its controller; custom frontends consume runtime directly.
+- Studio uses `StudioGraphController` over its compatibility `Graph`/`Node` engine and reuses runtime mechanisms. Custom frontends consume the neutral runtime directly; full Studio migration remains incomplete.
 - User modules are trusted project code, not a sandbox. Static definitions improve tooling and portability, not isolation.
 - Keep legacy support inside the existing Studio/CLI compatibility engine; do not spread compatibility branches into the deterministic runtime.
 
@@ -198,9 +220,10 @@ Do not add dependencies without a concrete need. Do not create extra packages un
 
 ## Versioning
 
-Cascade `0.2.0` is the 2026 architecture rework. The current release is `0.3.0`,
-which added the animation system and the agent console; `CHANGELOG.md` records
-what changed and is the file to update before a release commit. Increment the
+Cascade `0.2.0` is the 2026 architecture rework; `0.3.0` added animation and the
+agent console. Read `package.json` for the checkout version and `CHANGELOG.md`
+for release history and unreleased changes; a local build can contain changes
+not yet in the published package. Update the changelog before a release commit. Increment the
 root package and CLI patch version for every committed feature or release
 change, keeping `package.json`, the lockfile, and CLI output aligned. A minor
 bump is for a feature large enough to need its own `CHANGELOG.md` section.

package/ARCHITECTURE.md

@@ -20,18 +20,19 @@ Contracts contain no DOM, Svelte, Express, filesystem, process, or implementatio
 
 The runtime is environment-neutral. It works in Node and browsers without importing either platform’s APIs, and it never imports Studio. Registration is sealed after the first graph load. Each graph permits one active run and has explicit lifecycle states.
 
-The reserved `cascade.core.*` registry is owned here. `Subnet`, `Input`,
-`Output`, `Switch`, `Merge`, `Select`, `Null`, seeded `Random`, and `Remap` resolve
-without a project module loader. Named, typed root Input/Output nodes form an
-explicit headless graph interface; typed child Input/Output nodes form a subnet interface.
-Randomness is a pure function of an authored seed, never ambient process state.
+Reserved built-ins are registered once in `packages/runtime/src/builtins`:
+core hierarchy/routing/time/camera, geometry operations, particle simulation,
+and scene assembly. They need no project module file. The generated
+[node reference](doc/NODE_REFERENCE.md) owns the complete port/parameter list.
+Named, typed root Input/Output nodes form the public graph interface; child
+Input/Output nodes form a subnet interface. Randomness takes an authored seed.
 
 ## Hosts
 
 Hosts adapt the neutral runtime to an environment:
 
-- Node: files, assets, media, Python, and shell.
-- Browser: assets, media, and WebGL.
+- Node: files, assets, media, Python, shell, and optional Dawn WebGPU in the CLI.
+- Browser: assets, media, and the `gpu` capability when WebGPU is available.
 - Mixed application: an explicit bridge for serializable server stages.
 
 Capabilities are injected. A node’s literal `runsOn` and `capabilities` fields are checked before its `execute` module is loaded.
@@ -44,11 +45,19 @@ resize, composite, and encode when both Canvas/WebGL and native implementations
 exist. Both executors must obey the same definition and should share golden
 parity tests for geometry, metadata, and edge cases.
 
+`packages/runtime/src/gpu.ts` owns shared device/cache lifecycle with an injected
+acquisition function. Studio acquires browser WebGPU; `src/cli/headlessGpu.ts`
+loads optional Dawn lazily. The runtime awaits readiness and supplies a per-node
+view; the application owns disposal. `cascade/gpu` supplies explicit RGBA8
+readback without encoding or colour conversion. Graph ports still exchange
+images; GPU-resident intermediate connections remain future work. See
+[headless GPU rendering](doc/HEADLESS_GPU.md).
+
 `server/` is the project-scoped Node application host. It owns project paths, compilation, HTTP transport, media serving, Python workers, shell policy, and credentials. It is separately manifested and is not a third contracts/runtime workspace.
 
 ## Applications and controllers
 
-Studio’s Svelte components under `src/editor` own rendering, selection, panels, and interaction state. Its compatibility graph now has one graph-owned cook scheduler, while `StudioGraphController` centralizes an increasing set of structural mutations and publishes view snapshots. Compatibility adapters still present runtime-owned built-ins in Studio; collapse/extract and the remaining legacy nodes must migrate before Studio can consume `packages/runtime` directly.
+Studio’s Svelte components under `src/editor` own rendering, selection, panels, and interaction state. Its compatibility graph now has one graph-owned cook scheduler, while `StudioGraphController` centralizes an increasing set of structural mutations and publishes view snapshots. Compatibility adapters still present runtime-owned built-ins in Studio; collapse/extract and the remaining dynamic compatibility nodes must migrate before Studio can consume `packages/runtime` directly.
 
 Studio uses Dockview through the public `dockview` API. Code panels lazy-load
 Monaco and its native editor/TypeScript workers rather than adding Monaco to the
@@ -59,9 +68,12 @@ Custom server applications and browser frontends use `cascade/runtime` directly
 
 ## Distribution
 
-The repository has exactly two internal npm workspaces: `@cascade/contracts` and `@cascade/runtime`. The root `cascade` package is the only published package and the only owner of the executable.
+The repository has exactly two internal npm workspaces: `@cascade/contracts` and `@cascade/runtime`. The root `@field/cascade` package, normally installed under the alias `cascade` in projects, is the only published package and executable owner.
 
-Public subpaths are `cascade/contracts`, `cascade/contracts/schema`, `cascade/runtime`, `cascade/runtime/node`, `cascade/runtime/browser`, `cascade/runtime/expressions`, `cascade/runtime/animation`, `cascade/runtime/definition/extract`, `cascade/io`, `cascade/net`, `cascade/stage`, and the compatibility `cascade/shell`.
+Public subpaths include contracts/schema, runtime and its Node/browser,
+expression, animation, camera, render, scene and definition-extraction entries,
+plus `cascade/io`, `cascade/gpu`, `cascade/net`, `cascade/stage`,
+`cascade/shell`, and `cascade/player`. `package.json` is the exact export map.
 
 Studio-only project extensions use the type-only `cascade/studio/panel` contract. They are compiled and loaded only by Studio; the neutral runtime and headless hosts never discover or import them.
 
@@ -113,15 +125,57 @@ Data runs follow graph dependencies. Explicit triggers use a FIFO queue, authore
 
 Execution failures resolve to a failed `RunResult`; API misuse and invalid preflight reject. Cancellation propagates through capability calls. Inspection and output values are immutable snapshots; browser-only live resources remain host-owned handles.
 
+### Geometry, simulation and feedback
+
+Geometry is a shared typed value with point/vertex/primitive attributes,
+topology and groups, not an editor object. POP uses that same value for
+particle state. Forces accumulate acceleration; the solver integrates once
+per timestep. Trails are geometry and can feed the ordinary render/export nodes.
+
+`cascade.core.Feedback` is an explicit stateful container within the data DAG.
+Its children run per step; nested Feedback owns its own descendants. Previous
+state and bounded history are wired values, not sibling lookups. Result and
+history use normal output staging and cancellation, with transient loop state
+released even when a child throws.
+
+POP checkpoints accelerate deterministic re-simulation; clearing them must not
+change particles **or trails**. The sparse derived cache is module-local, has a
+64-checkpoint bound across keys, and copies snapshots at its boundary. It does
+not define simulation state. CLI `--frames` already reuses a loaded runtime,
+so it can benefit from checkpoints within the sequence. Separate CLI launches
+do not share that cache.
+
+A `scene` contains geometry, an optional camera and lights. A missing camera
+means the viewer supplies its view; an explicit render requires an authored
+camera. The current shared CPU renderer draws wireframes and points, not lit
+surfaces. Camera derivations belong to `packages/runtime/src/camera`; Studio's
+3D view and offline rendering use that convention rather than separate matrices.
+
+### Browser player
+
+The player is a browser application host under `src/player`, not another graph
+engine or package. Static export compiles definition-v1 project modules into
+browser ESM and supplies assets locally. Studio, Python, shell and project
+server routes are not deployment dependencies. Unsupported server operations
+fail explicitly during export. See [browser player](doc/WEB_PLAYER.md) for the
+build/embed contract and current limitations.
+
+Each embed has its own iframe realm, runtime, IO bridge, assets and GPU host.
+This isolates existing ambient `cascade/io` imports without swapping global
+transports between asynchronous runs. Shared browser GPU acquisition lives in
+`src/browser/gpu.ts`, also used by Studio. A future migration to explicit
+capability-only IO could permit direct DOM mounts; that is not implemented by
+the iframe player.
+
 ## Animation
 
-A parameter carries up to three bindings: a raw value, an expression, and a keyframe channel. They resolve in exactly one place, `Node.evalParm` in the compatibility engine (`src/nodes/Node.ts`), in the order channel, expression, value. A channel that samples takes precedence and leaves the expression stored but inert, so emptying the channel restores it. Nothing else in Studio may read a prop's `value` directly to obtain an animated parameter; a second resolution path is how an expression badge and a viewer disagree about the same frame.
+A parameter carries up to three bindings: a raw value, an expression, and a keyframe channel. `packages/runtime/src/params/resolve.ts` owns their shared resolution rule: channel, expression, value. A channel that samples takes precedence and leaves the expression stored but inert, so emptying the channel restores it. Studio invokes the resolver from `Node.evalParm`; the deterministic runtime invokes it through `PropAnimator`. Nothing else in Studio may read a prop's `value` directly to obtain an animated parameter; a second rule is how an expression badge and a viewer disagree about the same frame.
 
-The mechanisms are runtime-owned and the composition is not. `packages/runtime/src/expressions` owns preprocessing (`$F`, `$FF`, `$T`, `$FPS` rewritten to plain identifiers), the evaluation scope, and the maths library; `packages/runtime/src/animation` owns the channel model, sampling, interpolation, serialization, and frame-range walking. Both depend only on contracts, so `cascade run` and Studio animate a dynamic graph through the same code rather than two implementations of Hermite interpolation.
+The mechanisms are runtime-owned and the composition is host-specific. `packages/runtime/src/expressions` owns preprocessing (`$F`, `$FF`, `$T`, `$FPS` rewritten to plain identifiers), the evaluation scope, and the maths library; `packages/runtime/src/animation` owns the channel model, sampling, interpolation, serialization, and frame-range walking; `packages/runtime/src/params` owns binding resolution and deterministic graph-wide animation. These modules depend only on contracts or other runtime modules. Studio supplies its compatibility graph scope, while `PropAnimator` supplies the neutral runtime scope, including lazy `ch()` dependency resolution.
 
 `packages/contracts/src/animation.ts` owns the serialized shape. A channel lives inside the node's `props`, not in a separate timeline object, because a parameter's animation belongs to the parameter; a document with a timeline section would need reconciling every time a node was renamed, deleted, or embedded.
 
-The deterministic runtime has no parameter animation. A definition-v1 graph owns its own clock, so `cascade run --frames` refuses it explicitly rather than producing a hundred copies of frame 1. Extending animation to the deterministic runtime is a migration step, not a compatibility branch to add in Studio.
+The deterministic runtime has parameter animation and an explicit graph clock. `setFrame(frame)` and `setFps(fps)` re-resolve bound props without cooking, so inspection can scrub deterministically. `run({ frame, fps })` resolves every bound prop before node execution; the same graph at the same authored state, frame, and fps receives the same parameter values. `cascade run --frames` uses this path for definition-v1 graphs and passes each requested frame and fps into the run. The runtime never reads wall-clock time.
 
 ## Agent sessions
 
@@ -139,6 +193,14 @@ Document freshness is a watcher, not a poll of the agent. `server/src/graphWatch
 
 Project node modules are trusted code. Capabilities describe support and portability; they are not a sandbox.
 
+Studio binds to loopback by default. Remote access requires a specific
+hostname or private interface address via `--host`; wildcard remote binds are
+rejected. That non-loopback host becomes the default trusted browser hostname,
+and repeatable `--trusted-host` values add exact browser authorities when the
+bind address and public hostname differ, including a reverse proxy to a
+loopback bind. Every reachable peer on that trusted interface can access the
+project APIs, so this mode is intended for an authenticated VPN or trusted LAN.
+
 All project HTTP APIs require an exact allowed Host. Origin is validated when
 present and hostile or null Origins are rejected; same-origin GETs may omit it.
 Filesystem resolution checks lexical paths and canonical existing targets or

package/CHANGELOG.md

@@ -2,7 +2,69 @@
 
 Notable changes to Cascade. Newest first.
 
-## Unreleased
+## 0.5.1 — 2026-09-09
+
+- Prepared the 0.5 browser-player release for npm, with updated README and
+  cascade.field.io documentation covering web embeds, geometry, subnets,
+  particles, Feedback, scenes, animation and bounded Dawn renders for agents.
+- Clarified browser/server execution limits, current wireframe/point rendering,
+  explicit asset packaging and same-origin player controls. The npm homepage
+  now points to cascade.field.io.
+
+## 0.5.0 — 2026-09-09
+
+### Browser player
+
+- `cascade build <graph> --out <new-directory>` exports definition-v1 graphs as
+  static pages with a lightweight iframe embed API. Browser execution supports
+  assets and WebGPU; server capabilities and dynamic modules are rejected at
+  build time. No Studio server is required. See [Web player](doc/WEB_PLAYER.md).
+- Each embed owns its runtime, IO bridge and generated assets. Playback and
+  edits serialize, failed cooks pause playback, and disposal releases resources.
+  Generated images have immutable paths and explicit retention limits.
+- Browser image loading now decodes bridged assets correctly, including SVG
+  bitmaps. Studio and the player share browser GPU acquisition.
+
+### Runtime correctness and performance
+
+- POP checkpoint caching enforces its 64-entry bound even for one simulation,
+  copies mutable particle state at the boundary, and replays the trail window
+  so warm and cold renders agree. Malformed field and trail data report errors.
+- Nested Feedback runs children only in their owning loop, orders dependencies
+  across container boundaries, publishes history consistently, and clears
+  transient state after failures or cancellation.
+
+### Documentation and verification
+
+- Updated architecture, authoring and agent guides for geometry, simulations,
+  scenes and static deployment. Added real-browser embed and packed-consumer
+  checks alongside focused runtime and IO regressions.
+- Retired archived Quill examples with a recoverable backup; removed incidental
+  Quill examples from current guidance while retaining removed-node rejection tests.
+- Streamlined shared player image decoding, MIME inference and cleanup error
+  handling without changing the public player contract.
+- Removed unused Studio component props and consolidated CLI execution-style
+  checks. Empty/dynamic fallback and mixed-graph rejection remain unchanged.
+- Deleted the unreachable WindowManager UI and its private window/tab components;
+  Dockview remains Studio's sole layout host. Removed the commented-out Canvas
+  sample initializer. The active Graph/Node compatibility engine is unchanged.
+
+## 0.4.0 — 2026-09-09
+
+### Documentation
+
+- Updated current guides and generated project instructions for definition-v1
+  animation, stored `props`, instance identity, vector metadata, and the shared
+  GPU capability. Clarified host requirements, Studio's remaining runtime
+  migration, export limitations, and the distinction between implemented
+  workflows and future product directions.
+
+### Animation
+
+- The deterministic runtime resolves expressions and keyframe channels at an
+  explicit frame through the shared parameter resolver. `cascade run --frames`
+  can render fully definition-v1 graphs with compatible Node-host capabilities;
+  mixed definition-v1/dynamic graphs remain unsupported by the CLI.
 
 ### Node authoring
 
@@ -27,6 +89,41 @@ Notable changes to Cascade. Newest first.
 
 - **The CLI build resolves `@cascade/runtime/params`.** `src/nodes/Node.ts` imports `resolvePropBinding` from it, the browser build resolved it through `vite.config.ts`, and the CLI build had no alias — so the CLI, which is what the sketches actually run, was the broken half.
 
+### Camera
+
+- **A camera is a core type, and it is Houdini's camera.** `camera` joins `CORE_TYPES`, `cascade.core.Camera` emits one, and every derivation — basis, view and projection matrices, horizontal and vertical angle — lives in `cascade/runtime/camera` so no renderer derives it twice. Following `/obj/cam` costs the two things the obvious design would have done instead: there is **no field of view** (`focal` and `aperture` in millimetres, angle derived — Houdini's 50 mm on 41.4214 mm is exactly 45°), and the orientation is **`translate` and `rotate`** rather than eye-and-target, looking down its own **-Z** with **+Y** up, with look-at layered on top as an override. `resolution` is on the camera because Houdini derives the vertical aperture from the frame shape; it is one `vec2i` rather than `resx`/`resy` because the vec rule is the more specific one. Matching a frame is therefore always one number, never two.
+- `rotate.z` is a roll about the camera's own view direction. The first two rotation orders tried were indistinguishable from this one by every test in the suite — with `rotate.z` at zero all three agree exactly — so the test that separates them asserts that roll changes the up and leaves the view direction alone.
+
+### Series
+
+- **A series is a graph plus an ordered list of parameter sets** (`CascadeSeries`, `runSeries`), cooked once per set and addressed by **record id, never index**, because a filter change reorders a set and a judgement pinned to a position silently becomes a different picture. `CascadePreset` and `applyPreset` already were the parameter set and had no callers. There is no marked region: the affected subgraph is derived from the overrides, so nothing can be marked wrongly.
+- A parameter set is **sparse**, so every instance cooks from a baseline captured before the first `applyPreset` — otherwise an instance that overrides nothing inherits the previous one's values, which is accidental feedback in a mechanism specified as having none, and it presents as a flaky renderer rather than as a bug. `first` reorders the work and never the results, so a gallery fills in as instances land without the list reshuffling under a selection.
+
+### Capabilities
+
+- **Studio can reach the shell.** The server has had an allowlist-gated `/api/shell` for a while and Studio never wired it as a node capability, so a definition declaring `capabilities: ['shell']` ran through `cascade run` and threw in the browser — a node marked `runsOn: 'portable'` that runs in one host is what `runsOn` exists to prevent. A `CascadeAbortSignal` is bridged to a DOM one rather than serialised; a 403 re-handshakes exactly once and then reports, naming the Allowed Commands editor rather than a status code.
+
+### Correctness
+
+- **A `vec3` prop stays a `vec3`.** `isColorValue` answers true for any three- or four-number array and the deserialise path had no `type === 'color'` guard, so every vector prop in every sketch was rewritten on load — `[0.55, 0.12, 1.95]` reached `execute` as a colour object, coerced and divided by 255. A guard existed one branch away and never ran, because a **project** module's definition arrives asynchronously and `node.parameters` is empty at load. Coercion is now decided by ambiguity: objects and strings still normalise, arrays only where the prop is already declared a colour.
+- **An error in the log says what it is.** The Log panel `JSON.stringify`s any object and `Error.message` is non-enumerable, so a `TypeError` and a `GPUPipelineError` were equally invisible as `{}`.
+- **Selecting a failing node no longer cooks it forever.** The Viewer's rAF pump is throttled to 100 ms and polls its watched node while dirty; an execute that throws never reaches `clean`, so it ran a full `scheduler.flush()` ten times a second, re-fetching inputs over the network, at 61 fps and never looking wrong. `Node.hasSettledFailure` is what the poll now skips — deliberately not folded into `isDirty`, because an explicit `requestOutput` still retries and that is the transient GPU and network case.
+- **Renaming a node is a double click.** The name label sits in the middle of the node body and a single click opened the rename editor, so aiming at a node to select it renamed it instead, in memory only and discarded on reload.
+- **A proxied Studio can save.** `https` origins are accepted and default ports matched, so a reverse-proxied or Tailscale-served Studio can POST — which is also what unblocks WebGPU, the clipboard and the microphone, all of which need a secure context.
+
+### Headless GPU
+
+- Optional pinned Dawn (`webgpu@0.6.0`) in the CLI, loaded only for GPU execution.
+  Browser and Node hosts reuse shared device/cache lifecycle; portable and server
+  definitions may declare `gpu`. Browser-only nodes remain browser-only.
+- Explicit `cascade/gpu` RGBA8 texture readback, with padded-row removal and
+  cancellation cleanup. Graph texture transport remains outside this stage.
+- `run --frames ... --json` returns an image manifest and adapter metadata;
+  `--timeout <ms>` runs a supervised render process for agent/test callers.
+  Dedicated opt-in hardware and packed-package gates exercise real GPU output.
+- Documented the decision, local/unreleased status, CLI manifest contract,
+  verification evidence and platform limits in [Headless GPU](doc/HEADLESS_GPU.md).
+
 ## 0.3.1
 
 ### Fixed

package/CONTRIBUTING.md

@@ -0,0 +1,104 @@
+# Contributing to Cascade
+
+Cascade is a free, MIT-licensed creative graph platform. Contributions can be
+bug reports, reproducible sketches, documentation, tests, or code. Core
+development does not require an AI provider or a paid service account.
+
+## Find the owning layer
+
+Read [AGENTS.md](AGENTS.md) for repository conventions, [DESIGN.md](DESIGN.md)
+for product decisions, and [ARCHITECTURE.md](ARCHITECTURE.md) for dependencies.
+
+- `packages/contracts/` owns public types and serialized formats.
+- `packages/runtime/` owns environment-neutral execution mechanisms.
+- `server/` owns project files, compilation, processes, and host transports.
+- `src/editor/` owns Studio interactions and presentation.
+- `src/player/` owns the standalone browser host and embed controls.
+- Sketch repositories own creative algorithms, providers, and project panels.
+
+Keep provider SDKs and client-specific data in projects. Do not add dependencies
+or packages without a demonstrated need and an agreed scope.
+
+## Develop and verify
+
+Use Node.js 22.13 or newer. Install dependencies with `npm install`; the core
+uses TypeScript 6. `npm run dev` starts the Studio development frontend.
+Project-host workflows are exercised through a built CLI and a project folder.
+
+Add a focused regression test for a behavior change, make the smallest change
+at the owning layer, and run that test first. Use the applicable repository gates:
+
+```bash
+npm run check
+npm run test:run
+npm --prefix server run build
+npm run build
+npm run build:cli
+git diff --check
+```
+
+`npm run build` also runs `build:cli` through its postbuild hook. Keep a final
+CLI build after any separate Vite build because Vite refreshes `dist/`. Coordinate
+rebuilds when running Studio servers serve from that checkout.
+Do not run package builds concurrently with tests that read generated package
+files: the builds replace those directories while tests may be importing them.
+
+For public API or packaging changes, run `npm run test:package`, which exercises
+the packed distribution from a temporary consumer. Built-in node-definition or
+registry changes also require `npm run build:node-reference`; include its result.
+
+For player changes, run `npm run test:player` after building the CLI. It opens
+an isolated headless Chrome profile and checks actual pixels, multiple embeds,
+playback and disposal on a static server. Set `CASCADE_CHROME` to the Chrome
+executable on non-macOS systems. `CASCADE_TEST_PLAYER=1 npm run test:package`
+also runs that proof against the installed tarball. GPU package verification
+is opt-in separately with `CASCADE_TEST_DAWN=1`.
+
+For prose-only changes, verify source claims, links, examples, and diff hygiene.
+When changing generated project instructions in `server/src/projectTemplate.ts`,
+also run `npx --no-install vitest run tests/project-template.test.ts`.
+
+## Report useful evidence
+
+A bug report should identify the Cascade version and whether it is a published
+package or local checkout, the host/browser and relevant GPU, the smallest
+reproducing graph, and expected versus observed output. Include safe fixtures
+instead of credentials or private client data. A static check passing is not
+proof that a graph rendered successfully.
+
+For visual changes, preserve the inputs, seed, frame/fps, dimensions, and code
+revision used for comparison. Compare decoded pixels or geometry where useful;
+file size and image-wide averages do not establish visual equivalence.
+
+## Documentation and releases
+
+Update current instructions alongside behavior changes. Keep historical notes
+dated and mark proposals as unimplemented. Update the root
+[CHANGELOG.md](CHANGELOG.md); `spec/CHANGELOG.md` preserves earlier history.
+Never edit the generated [node reference](doc/NODE_REFERENCE.md) by hand.
+
+Release/version rules live in [AGENTS.md](AGENTS.md). Publishing and deployment
+are separate maintainer actions; a documentation update does not publish a release.
+
+With an explicit release request, update the README, feature guides, changelog,
+root package/lock version and `site/index.html` together. Run the checks above
+and `CASCADE_TEST_PLAYER=1 CASCADE_TEST_DAWN=1 npm run test:package` on a supported
+GPU machine before publishing. The packed test checks a fresh consumer, browser
+embeds, native GPU output and the optional-renderer-absent path.
+
+The public package is `@field/cascade` (`npm publish --access public`). Check
+`npm whoami` and `npm view @field/cascade dist-tags` first; verify the published
+version and a fresh installation afterward. Git push, npm publication and the
+website deployment are separate operations, not an automatic release pipeline.
+
+The documentation website is the static **`site/` directory**, not Studio's
+`dist/`. Its existing Vercel project is `field-io/cascade`:
+
+```sh
+vercel link --cwd site --project cascade --scope field-io --yes
+vercel deploy --cwd site --scope field-io --prod --yes
+```
+
+Confirm the linked project before deployment and check `https://cascade.field.io`
+afterward. Do not deploy the repository root or expose a Studio server as the
+public site. `.vercel` is local deployment metadata and stays ignored.

package/DESIGN.md

@@ -3,9 +3,11 @@
 ## Source of truth
 
 - Status: Active
-- Last refreshed: 2026-09-08 (0.3.0)
-- Primary product surfaces: reusable graph runtime, optional Studio workbench, headless Node/browser hosts, Inspector, Viewer, Timeline, agent console, node ports, project-defined workbenches
-- Evidence reviewed: `VISION.md`, `ARCHITECTURE.md`, `CHANGELOG.md`, `spec/CASCADE_SUBNET_AND_SHELL_SPEC.md`, `src/types/coreTypes.ts`, `src/editor/Inspector.svelte`, `src/editor/Viewer.svelte`, `src/editor/panels/TimelinePanel.svelte`, `src/editor/panels/AgentPanel.svelte`, `src/editor/components/PortEditor.svelte`, `src/editor/components/typeRenderers.ts`, `packages/runtime/src/expressions/`, `packages/runtime/src/animation/`, `server/src/agent/`, and the approved plans under `.omx/plans/`
+- Last refreshed: 2026-09-09 (0.4.0 checkout; player work is unreleased)
+- Primary product surfaces: reusable graph runtime, optional Studio workbench, headless Node/browser hosts, static browser player, Inspector, 2D/3D Viewer, Timeline, agent console, node ports, project-defined workbenches
+- Evidence reviewed: `VISION.md`, `ARCHITECTURE.md`, `CHANGELOG.md`, `spec/CASCADE_SUBNET_AND_SHELL_SPEC.md`, `src/types/coreTypes.ts`, `src/editor/Inspector.svelte`, `src/editor/Viewer.svelte`, `src/editor/panels/TimelinePanel.svelte`, `src/editor/panels/AgentPanel.svelte`, `src/editor/components/PortEditor.svelte`, `src/editor/components/typeRenderers.ts`, `src/browser/gpu.ts`, `src/player/`, `packages/runtime/src/runtime.ts`, `packages/runtime/src/params/`, `packages/runtime/src/expressions/`, `packages/runtime/src/animation/`, `server/src/agent/`, `server/src/security.ts`, and `server/src/cliCommands.ts`
+
+This document contains both current product rules and intended direction. Sections labelled **Current** describe implemented behavior in the repository. Sections labelled **Target** or **Planned** describe design direction and are not a release commitment. Open questions remain undecided until accepted in a specification or implementation plan.
 
 ## Brand
 
@@ -29,22 +31,23 @@
 
 - Primary navigation: canvas selection determines Inspector and Viewer context
 - Core screens: Graph, Inspector, Viewer, Timeline, Definition, Agent console, Logs/diagnostics
+- The standalone player presents the artwork and minimal playback/error controls, not the graph editor. It launches as a static page or embeds in an iframe. Programmatic controls are same-origin; a cross-origin iframe is display/playback only.
 - Content hierarchy: value preview first, type and shape metadata second, expandable raw structure last
 
 ## Design principles
 
 - One type, one presentation contract: the same type vocabulary drives ports, Inspector, and Viewer.
 - Progressive disclosure: compact summaries in dense panels; richer previews and metadata in Viewer; raw JSON only on demand.
-- Edit only what can be authored honestly: inputs may edit portable values; connected inputs and outputs are read-only; live GPU textures are inspected, not fabricated through form fields.
-- Expensive context changes stay explicit: texture readback, server materialization, and file writes are actions or nodes, never invisible UI coercions.
+- Edit only what can be authored honestly: inputs may edit portable values; connected inputs and outputs are read-only. Future live GPU texture values should be inspected rather than fabricated through form fields.
+- Expensive context changes stay explicit: server materialization, file writes and GPU readback are requested operations, never invisible UI coercions. Graph texture connections remain future work.
 - Project types extend by registration, not central switch statements.
 - The graph runtime is a product surface independent from Studio. Headless hosts consume it now; Studio's compatibility graph has one scheduler/controller boundary but still requires a deliberate built-in and structural-command migration before it consumes the neutral runtime directly.
 - Node metadata is deterministic. A literal exported definition declares ports, properties, types, execution locus, and capabilities; `execute` performs computation only.
-- A parameter is one store with three bindings. A value, an expression, and a keyframe channel live on the same parameter and resolve in one place in a fixed order: channel, then expression, then value. Two stores is what 0.3.0 removed — `param()` wrote to one and every binding read the other, so no parameter a sketch actually declared could carry an expression or a key, and nothing errored. A stronger binding hides a weaker one rather than destroying it, so emptying a channel returns the expression that was already there.
+- A parameter is one store with three bindings. A value, an expression, and a keyframe channel live on the same parameter and use the shared `resolvePropBinding` rule in a fixed order: channel, then expression, then value. Studio calls that rule from `Node.evalParm`; the neutral runtime calls it through `PropAnimator`. Two stores is what 0.3.0 removed — `param()` wrote to one and every binding read the other, so no parameter a sketch actually declared could carry an expression or a key, and nothing errored. A stronger binding hides a weaker one rather than destroying it, so emptying a channel returns the expression that was already there.
 - Time is an expression, not a node. A parameter holding `sin($T) * 40` is the whole of an oscillator, which is why there is no oscillator node and why portable nodes still must not read ambient time or randomness themselves. The variables and the function names are Houdini's, because the people this is for already have them in their hands; the one deliberate divergence is that bare trigonometry is in radians, with `sind`/`cosd`/`tand` provided for formulae carried across.
 - An agent run belongs to the server, not to the browser looking at it. Closing a tab detaches a reader; the transcript is buffered with sequence numbers so reopening replays what was missed and says how much it dropped. The alternative — a run owned by an HTTP request — kills the agent mid-edit on a reload, which is what 0.3.0 fixed.
 - Rendering offline stops at a numbered image sequence. Handing frames to an encoder is a separate decision with its own dependency, and a directory of frames is the input every encoder already takes.
-- Hosts provide explicit capabilities. File, Python, media, WebGL, and shell access are never ambient runtime assumptions. Provider-specific AI abstractions belong to projects or embedding hosts, not Cascade core.
+- Hosts provide explicit capabilities. File, Python, media, GPU, and shell access are never ambient runtime assumptions. Provider-specific AI abstractions belong to projects or embedding hosts, not Cascade core.
 - Neutral-runtime graph loads are atomic. Compatibility Studio collapse/extract are a known migration gap and must move behind transactional structural commands before that guarantee applies to every editor operation.
 - Tradeoff: geometry editors favor transparent structured editing and previews over specialized CAD interactions in this pass.
 
@@ -53,9 +56,10 @@
 - `@cascade/contracts` is the dependency-free source of truth for graph documents, core and namespaced types, deterministic node definitions, diagnostics, run results, capabilities, and schemas.
 - `@cascade/runtime` is the deterministic environment-neutral graph loader, validator, scheduler, serializer, trigger engine, and hierarchy implementation. It depends only on contracts; dynamic compatibility remains in Studio/CLI during migration.
 - The root `cascade` package is the sole published distribution and CLI owner. It exposes `cascade/contracts`, `cascade/contracts/schema`, `cascade/runtime`, `cascade/runtime/node`, `cascade/runtime/browser`, `cascade/runtime/expressions`, `cascade/runtime/animation`, `cascade/runtime/definition/extract`, `cascade/io`, `cascade/net`, `cascade/stage`, and the compatibility `cascade/shell` entry point.
-- Node and browser hosts inject only the capabilities they support. Browser-only WebGL and server-only file, Python, and shell capabilities make portability constraints explicit before execution.
+- Node and browser hosts inject only the capabilities they support. GPU can be supplied by browser WebGPU or optional Dawn; file, Python and shell remain server-only. A portable declaration still requires compatible capabilities.
 - The Studio owns canvas/view classes and a single `StudioGraphController`; its compatibility `Graph`/`Node` engine is still being reduced. Custom frontends and backend services use the neutral runtime directly and do not load editor code.
-- **Web technology is the default renderer, and Python is the exception.** Canvas 2D, WebGL and WebGPU first; reach for a Python stage only for work that genuinely cannot be pushed to the browser — exotic ML libraries and the like. Marcus's ruling, 2026-09-07: *"Cascade should prefer web tech canvas/webgpu to keep things smooth and fast. only use Python for exotic ML libraries and similar things that can't be easily pushed to the browser."* The reason is interaction rather than taste: a Python stage costs a process spawn and a round trip per cook, which is invisible on one still frame and fatal to dragging a parameter or playing an animation. It also tends to be more faithful, not less — a gradient drawn with `createRadialGradient` is the same primitive the source artwork carries, where a per-pixel reimplementation is a guess about what that primitive means.
+- **Current GPU stage:** Studio and the optional Dawn CLI host share device/cache lifecycle through the neutral runtime. Each declaring node gets a cache namespace. Explicit RGBA8 readback supports image export in either host; graph ports still exchange images. GPU-resident intermediate connections remain a later stage.
+- **Web technology is the default renderer, and Python is the exception.** Canvas 2D, WebGL and WebGPU first; reach for a Python stage for libraries or tools that cannot reasonably run in the browser. Marcus's ruling, 2026-09-07: *"Cascade should prefer web tech canvas/webgpu to keep things smooth and fast. only use Python for exotic ML libraries and similar things that can't be easily pushed to the browser."* The reason is interaction: process startup, transport, and serialization can dominate a cook. Persistent workers avoid repeated process/model startup, but still have transfer costs. Existing project Python renderers need deliberate parity-tested migrations; this direction does not mean those implementations are already gone.
 - Python interoperability remains a host capability for exotic libraries and compute stages. Exchange values cross explicit typed node boundaries rather than leaking Python process details into the neutral runtime.
 - Internal packages remain two workspaces until independent versioning or external consumption justifies separate publication. More npm packages are not a goal by themselves.
 
@@ -72,9 +76,11 @@
 
 ## Headless and deployment model
 
-- `createRuntime()` is the common entry point for Studio, Node services, UI-free browser embeds, tests, and custom web frontends.
+- `createRuntime()` is the common entry point for deterministic Node services, UI-free browser embeds, tests, and custom frontends. Studio still runs through its compatibility `Graph`/`Node` engine and controller while that migration continues.
 - Registration is sealed after the first graph load. A loaded graph supports inspect, input/property/preset mutation, trigger, run, cancel, subscription, output retrieval, and disposal without editor dependencies.
+- A loaded deterministic graph owns an explicit caller-controlled clock. `setFrame()` and `setFps()` re-resolve animated props for inspection without cooking; `run({ frame, fps })` resolves the same bindings before execution. The runtime never reads ambient time.
 - One run is active per graph; there is no hidden run queue. API misuse rejects, while graph execution resolves to an explicit success/failure/cancelled result.
+- Browser-player playback coalesces requested frames; it must not queue unbounded work. Failure pauses playback and exposes its diagnostic. Static assets and generated images are realm-owned; immutable image references preserve Feedback history, and explicit resource limits prevent unbounded retention.
 - A graph may run wholly in a backend, wholly in a compatible browser, or across an explicitly designed bridge. The runtime never silently moves a stage between hosts.
 - File loading/saving, format versioning, presets, project paths, and workspace conveniences belong to stable platform services around the neutral runtime, not to individual generative algorithms.
 
@@ -82,7 +88,7 @@
 
 - User node modules are trusted project code, not a sandbox. Deterministic definitions and architecture checks prevent common hidden-state designs and improve inspection, tooling, and portability; hard isolation would additionally require a separate realm or worker per node instance.
 - Shell is a server-only capability backed by one project-scoped service. Projects invoke configured aliases as a fixed executable plus argument array with `shell: false`; arbitrary executables, interpolation, unsafe working directories, dangerous request-time environment overrides, and unbounded output are rejected. The subprocess inherits the server environment before project and allowlisted request overrides are applied.
-- Browser shell transport is loopback-only, uses exact Host and Origin checks plus a process-lifetime random capability token, has route-local request limits, and never logs tokens, paths, arguments, environment, stdin, stdout, or stderr.
+- Sensitive browser transport is enabled for loopback and for an explicitly configured exact trusted host. Every request passes exact Host validation and Origin validation when present; sensitive routes also require a process-lifetime random capability token, apply route-local request limits, and avoid logging tokens, paths, arguments, environment, stdin, stdout, or stderr. Remote Studio rejects wildcard binds and grants every peer that can reach the trusted private interface the same project access.
 - Timeout, cancellation, and output limits terminate the full process tree and wait for closure before reporting completion.
 
 ## Agent workflow contract
@@ -102,12 +108,14 @@
 
 ## Components
 
-- Existing components to reuse: `PortEditor`, `JsonTree`, `ColorPicker`, Viewer image zoom/pan behavior, type renderer registry
-- New/changed components: shared `TypeValue` presentation shell, structured JSON editor, image/texture inspector, geometry summary/preview, asset inspector, Viewer output list
+- **Current:** `PortEditor`, `JsonTree`, `ColorPicker`, `CoreValue`, `StructuredValue`, Viewer image zoom/pan, geometry summaries/previews, `SceneViewport` with orbit/track/dolly camera controls, and the type renderer registry. Scene rendering currently shows wireframes and points; lights are represented but do not imply shaded rendering.
+- **Planned:** a shared type-value presentation shell, structured JSON editing, richer image/asset inspection, a Viewer output list, and texture inspection after texture values exist.
 - Variants and states: `compact`, `inspect`, `view`; editable/read-only; empty/loading/error/stale; connected source; truncated/expanded
 - Token/component ownership: `coreTypes.ts` owns semantic type metadata; the presentation registry owns components; Inspector/Viewer only choose context and mode
 
-### Core type presentation contract
+### Target core type presentation contract
+
+This table defines the intended presentation contract. Individual rows may be only partially implemented; it does not imply that texture ports or every specialized editor currently exists.
 
 | Family | Inspector/editor | Viewer |
 | --- | --- | --- |
@@ -135,6 +143,7 @@
 - Supported breakpoints/devices: desktop-first; Inspector remains usable from 240px width; Viewer adapts to Dockview panel size
 - Layout adaptations: vector/matrix fields wrap or scroll; Viewer metadata collapses beneath previews; structured trees virtualize or truncate large collections
 - Touch/hover differences: no essential information exists only in hover tooltips
+- Player embeds fit their container; resize changes the view size, not authored graph resolution. Start paused unless autoplay is requested. Controls need native keyboard semantics and errors remain readable over the artwork.
 
 ## Interaction states
 
@@ -161,6 +170,6 @@
 
 ## Open questions
 
-- [ ] Whether mesh Viewer should gain an interactive WebGL orbit view after the lightweight projected preview proves useful / product / medium impact
+- [ ] Whether scene rendering needs shaded GPU surfaces beyond the current CPU wireframe/point view / product / medium impact
 - [ ] Whether project packages can eventually ship Svelte renderers directly rather than app-side registration / architecture / high impact
 - [ ] Whether large structured values need virtualization beyond bounded initial expansion / performance / medium impact