@field/cascade 0.3.1 → 0.5.1

package/doc/NODE_REFERENCE.md

@@ -17,6 +17,68 @@ node and none is needed.
 These are definition-v1: their declarations are literal, so what follows is
 exact rather than a description.
 
+### `cascade.core.Camera`
+
+Camera — A camera, following Houdini's /obj/cam.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `translate` | `vec3` | `[0,0,5]` |  |
+| `rotate` | `vec3` | `[0,0,0]` |  |
+| `focal` | `float` | `50` | 1…300 |
+| `lookat` | `vec3` | `[0,0,0]` |  |
+| `up` | `vec3` | `[0,1,0]` |  |
+| `spin` | `float` | `0` |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `lookAt` | `bool` | `false` |  |
+| `aperture` | `float` | `41.4214` | 1…200 |
+| `resolution` | `vec2i` | `[1280,720]` |  |
+| `aspect` | `float` | `1` | 0.1…10 |
+| `projection` | `string` | `"perspective"` |  |
+| `orthowidth` | `float` | `2` |  |
+| `near` | `float` | `0.001` |  |
+| `far` | `float` | `10000` |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `camera` | `camera` |  |  |
+
+### `cascade.core.Feedback`
+
+Feedback — Runs its contents once per step, carrying the previous result forward.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `initial` | `any` | `null` |  |
+| `steps` | `int` | `1` |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `history` | `int` | `0` | 0…100000 |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `result` | `any` |  |  |
+| `history` | `array` |  |  |
+
 ### `cascade.core.Input`
 
 Input — Defines a public graph or subnet input
@@ -111,6 +173,25 @@ Runs on `portable`.
 | --- | --- | --- | --- |
 | `output` | `any` |  |  |
 
+### `cascade.core.Previous`
+
+Previous — The previous step's state, inside a Feedback container. The first step gets the container's initial value.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `initial` | `any` | `null` |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `value` | `any` |  |  |
+| `step` | `int` |  |  |
+
 ### `cascade.core.Random`
 
 Random — Generate a deterministic unit value from an explicit seed.
@@ -214,6 +295,28 @@ Runs on `portable`.
 | --- | --- | --- | --- |
 | `output` | `any` |  |  |
 
+### `cascade.core.Time`
+
+Time — The current frame and time, as values the graph can read.
+
+Runs on `portable`.
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `frame` | `int` | `1` |  |
+| `fframe` | `float` | `1` |  |
+| `time` | `float` | `0` |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `frame` | `int` |  |  |
+| `fframe` | `float` |  |  |
+| `time` | `float` |  |  |
+
 ### `cascade.geo.Circle`
 
 Circle — A closed circle, as one cubic Bezier chain or as a polygon of divisions segments.
@@ -303,6 +406,39 @@ Runs on `portable`.
 | --- | --- | --- | --- |
 | `geometry` | `geometry` |  |  |
 
+### `cascade.geo.Render`
+
+Render — Draw a scene through a camera, as a raster.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `scene` | `scene` |  |  |
+| `camera` | `camera` |  |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `size` | `vec2i` | `[1280,720]` | 16…8192 |
+| `filename` | `string` | `"render.png"` |  |
+| `background` | `color` | `[0,0,0,0]` |  |
+| `stroke` | `color` | `[0,0,0,1]` |  |
+| `strokeWidth` | `float` | `1` | 0…200 |
+| `opacity` | `float` | `1` | 0…1 |
+| `drawPoints` | `bool` | `false` |  |
+| `pointRadius` | `float` | `1.5` | 0…50 |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `image` | `image` |  |  |
+| `asset` | `asset` |  |  |
+
 ### `cascade.geo.SvgExport`
 
 SVG Export — Write geometry as an SVG document, one group element per group.
@@ -323,6 +459,8 @@ Runs on `portable`.
 | `width` | `float` | `0` |  |
 | `height` | `float` | `0` |  |
 | `margin` | `float` | `0` |  |
+| `bounds` | `vec4` | `[0,0,0,0]` |  |
+| `background` | `color` | `[0,0,0,0]` |  |
 | `stroke` | `color` | `[0,0,0,1]` |  |
 | `strokeWidth` | `float` | `1` |  |
 | `opacity` | `float` | `1` | 0…1 |
@@ -360,6 +498,275 @@ Runs on `portable`.
 | --- | --- | --- | --- |
 | `geometry` | `geometry` |  |  |
 
+### `cascade.pop.FieldForce`
+
+POP Field Force — Pull particles along a field's gradient and around its contours. The calligraphy force.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `particles` | `geometry` |  |  |
+| `field` | `geometry` |  |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `normal` | `float` | `0` | -100000…100000 |
+| `tangential` | `float` | `2600` | -100000…100000 |
+| `radius` | `float` | `20` | 0…10000 |
+| `level` | `float` | `0.28` | 0…1 |
+| `hold` | `float` | `5200` | 0…100000 |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `geometry` | `geometry` |  |  |
+
+### `cascade.pop.NoiseForce`
+
+POP Noise Force — Push particles along a heading read from a noise field.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `particles` | `geometry` |  |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `amplitude` | `float` | `6` | 0…500 |
+| `frequency` | `float` | `0.3` | 0.001…10 |
+| `evolve` | `float` | `0` | -1000…1000 |
+| `timestep` | `float` | `0.041666666666666664` | 0.004166666666666667…1 |
+| `seed` | `int` | `7` | 0…999999 |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `geometry` | `geometry` |  |  |
+
+### `cascade.pop.Separate`
+
+POP Separate — Push neighbours apart within a radius.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `particles` | `geometry` |  |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `radius` | `float` | `0.5` | 0…100 |
+| `strength` | `float` | `4` | 0…500 |
+| `timestep` | `float` | `0.041666666666666664` | 0.004166666666666667…1 |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `geometry` | `geometry` |  |  |
+
+### `cascade.pop.Simulate`
+
+POP Simulate — Re-simulate a particle system from frame zero to this frame.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `geometry` | `geometry` |  |  |
+| `frame` | `float` | `1` |  |
+| `attract` | `geometry` |  |  |
+| `field` | `geometry` |  |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `trail_length` | `int` | `14` | 1…500 |
+| `trail_increment` | `int` | `1` | 1…32 |
+| `substeps` | `int` | `1` | 1…32 |
+| `timestep` | `float` | `0.041666666666666664` | 0.004166666666666667…1 |
+| `impulse` | `int` | `6` | 0…100000 |
+| `life` | `float` | `4` | 0…3600 |
+| `lifevar` | `float` | `0.4` | 0…1 |
+| `force` | `vec2` | `[0,0]` |  |
+| `airresist` | `float` | `0.4` | 0…20 |
+| `noise_amplitude` | `float` | `14` | 0…500 |
+| `noise_frequency` | `float` | `0.02` | 0.001…10 |
+| `noise_evolve` | `float` | `0.08` | -10…10 |
+| `field_normal` | `float` | `0` | -20000…20000 |
+| `field_tangential` | `float` | `0` | -20000…20000 |
+| `field_radius` | `float` | `24` | 0.5…2000 |
+| `field_level` | `float` | `0.35` | 0…1 |
+| `field_hold` | `float` | `0` | 0…40000 |
+| `birth_area` | `vec4` | `[0,0,0,0]` |  |
+| `birth_hue` | `vec2` | `[0,0]` | 0…1 |
+| `birth_saturation` | `float` | `0.6` | 0…1 |
+| `birth_value` | `float` | `1` | 0…1 |
+| `attract_amplitude` | `float` | `0` | 0…20000 |
+| `attract_radius` | `float` | `60` | 0…5000 |
+| `separate_radius` | `float` | `0` | 0…500 |
+| `separate_strength` | `float` | `12` | 0…500 |
+| `maxspeed` | `float` | `60` | 0…10000 |
+| `wrap` | `vec4` | `[0,0,0,0]` |  |
+| `seed` | `int` | `7` | 0…999999 |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `geometry` | `geometry` |  |  |
+| `trails` | `geometry` |  |  |
+
+### `cascade.pop.Solver`
+
+POP Solver — Advance a particle system by one timestep.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `particles` | `geometry` |  |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `timestep_mode` | `string` | `"fixed"` |  |
+| `timestep` | `float` | `0.041666666666666664` | 0.004166666666666667…1 |
+| `maxspeed` | `float` | `0` | 0…10000 |
+| `force` | `vec2` | `[0,0]` |  |
+| `airresist` | `float` | `0` | 0…20 |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `geometry` | `geometry` |  |  |
+
+### `cascade.pop.Source`
+
+POP Source — Birth particles from a geometry's points.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `geometry` | `geometry` |  |  |
+| `particles` | `geometry` |  |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `impulse` | `int` | `8` | 0…100000 |
+| `life` | `float` | `3` | 0…3600 |
+| `lifevar` | `float` | `0.3` | 0…1 |
+| `velocity` | `vec2` | `[0,0]` |  |
+| `seed` | `int` | `7` | 0…999999 |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `geometry` | `geometry` |  |  |
+
+### `cascade.pop.Trail`
+
+POP Trail — Build trails from a Feedback container's history.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `history` | `array` |  |  |
+| `particles` | `geometry` |  |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `result` | `string` | `"polylines"` |  |
+| `length` | `int` | `12` | 1…100000 |
+| `increment` | `int` | `1` | 1…1000 |
+| `velocityscale` | `float` | `1` | 0…100 |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `geometry` | `geometry` |  |  |
+
+### `cascade.scene.Light`
+
+Light — A light, following Houdini's /obj/hlight. Nothing shades with lights yet — the viewport draws wireframe and points.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `translate` | `vec3` | `[0,0,5]` |  |
+| `direction` | `vec3` | `[0,0,-1]` |  |
+| `color` | `color` | `[1,1,1,1]` |  |
+| `intensity` | `float` | `1` |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `type` | `string` | `"point"` |  |
+| `coneangle` | `float` | `45` | 0…180 |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `light` | `light` |  |  |
+
+### `cascade.scene.Scene`
+
+Scene — Geometry, a camera and lights, assembled into a scene. Attach anything to the input.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `inputs` | `any` |  |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `scene` | `scene` |  |  |
+
 ## Studio node libraries
 
 Class-based nodes, available in Studio. Their parameters are declared in the
@@ -377,7 +784,7 @@ under `src/nodes/<library>/nodes/`.
 
 ### Geometry — `cascade.geo.*`
 
-**Geometry.** `cascade.geo.Rectangle` (A closed four-point polygon, counter-clockwise from bottom-left.), `cascade.geo.Circle` (A closed circle, as one cubic Bezier chain or as a polygon of divisions segments.), `cascade.geo.Transform` (Translate, rotate and scale geometry about a pivot.), `cascade.geo.Merge` (Concatenate geometries, taking the union of their attributes.), `cascade.geo.CopyToPoints` (Instance one geometry onto every point of another.), `cascade.geo.SvgExport` (Write geometry as an SVG document, one group element per group.)
+**Geometry.** `cascade.geo.Rectangle` (A closed four-point polygon, counter-clockwise from bottom-left.), `cascade.geo.Circle` (A closed circle, as one cubic Bezier chain or as a polygon of divisions segments.), `cascade.geo.Transform` (Translate, rotate and scale geometry about a pivot.), `cascade.geo.Merge` (Concatenate geometries, taking the union of their attributes.), `cascade.geo.CopyToPoints` (Instance one geometry onto every point of another.), `cascade.geo.SvgExport` (Write geometry as an SVG document, one group element per group.), `cascade.geo.Render` (Draw a scene through a camera, as a raster.)
 
 ### Image — `cascade.image.*`
 

package/doc/PROJECT_AUTHORING.md

@@ -4,10 +4,15 @@ Cascade projects are filesystem-native. The graph, custom nodes, assets, presets
 
 ## Create and open a project
 
+`cascade new` scaffolds and starts Studio. Stop that initial server before
+installing dependencies and reopening the project. This example assumes the
+default projects directory; use `cascade projects` to check your configured path.
+
 ```bash
 cascade new my-artwork
 cd ~/Documents/Cascade/my-artwork
-cascade .
+npm install
+npx --no-install cascade .
 ```
 
 For a workstation reached by name over a trusted VPN or LAN, bind deliberately
@@ -21,10 +26,41 @@ Open `http://KURO:3030`. Loopback remains the default. Cascade trusts the
 specific non-loopback bind hostname; `--trusted-host` is only needed when the
 browser uses a different hostname. Wildcard remote binds are rejected.
 
+For an HTTPS reverse proxy that terminates TLS and forwards to loopback, bind
+loopback explicitly and allow the exact external hostname:
+
+```bash
+cascade . --host 127.0.0.1 --port 3030 --trusted-host cascade.example.internal
+```
+
+The proxy must preserve that `Host` value; include a non-default external port
+in `--trusted-host` when applicable. Add `--no-open` and visit the HTTPS URL
+yourself, since automatic opening still constructs an HTTP URL. Cascade does not configure the
+proxy or certificate; the explicit trusted host only admits its browser
+authority while the server remains unreachable directly from the network.
+
 Cascade and generated projects require Node.js 22.13 or newer. Generated
 projects use TypeScript 6 so their static node definitions match Cascade's
 compiler and definition extractor.
 
+`cascade new` writes a project-local dependency named `cascade` which aliases
+the published `@field/cascade` package. Install it before using the project's
+npm scripts:
+
+```bash
+npm install
+npm run check
+npm run validate
+```
+
+That dependency uses a caret range in the CLI's current minor line; the lockfile
+records the resolved version. A local Cascade repository may contain newer
+work even with the same version number. Record both the version and whether
+the project resolves a checkout or a published package when diagnosing a
+difference. Use a deliberate local package override
+for framework development rather than committing a machine-specific
+`file:../../Dev/cascade` dependency to a shared project.
+
 `index.cascade` is the default graph name. A project may contain several `.cascade` files; pass one explicitly when there is no unambiguous default:
 
 ```bash
@@ -94,13 +130,15 @@ export const renderers = {
 
 Each renderer instance owns its cleanup. An optional `update` method receives later values without remounting.
 
-To open a panel from the Inspector, declare an action parameter:
+To open a panel from the Inspector, add an action prop to a definition-v1 node:
 
 ```ts
-node.param('asset_id', '', {
-  label: 'Choose asset',
-  action: 'panel:asset-browser',
-});
+props: {
+  asset_id: {
+    type: 'string', default: '', label: 'Choose asset',
+    action: 'panel:asset-browser'
+  }
+}
 ```
 
 The initiating node ID is captured as `api.sourceNodeId`; `setParam` uses the same history/dirty/cook path as the Inspector, so undo and save continue to work. Panels and project value renderers are Studio-only and are never imported during `cascade run` or by `cascade/runtime`.
@@ -133,11 +171,12 @@ const response = await authorizedFetch('image-api', 'https://api.example.com/v1/
 });
 ```
 
-`cascade/net` is resolved by Cascade's project compiler and backed by the
-Studio server's `/api/net` route. It is not a published package export or a
-neutral headless runtime capability. A standalone headless host must provide
-its own remote-I/O adapter or run the integration through an injected shell,
-Python, or application-specific server bridge.
+`cascade/net` is a published host bridge backed by the Studio server's
+`/api/net` route when project code is compiled by Cascade. It is not a neutral
+runtime capability and has no useful authority without that installed bridge.
+A standalone headless host must provide its own remote-I/O adapter or run the
+integration through an injected shell, Python, or application-specific server
+bridge.
 
 Browser proxy credentials must declare the exact allowed hosts and header metadata alongside the secret:
 
@@ -160,10 +199,18 @@ There are two styles. Write **definition-v1** for anything new; the dynamic styl
 
 | | Cooked by | Checked by |
 | --- | --- | --- |
-| **definition-v1**: a literal `definition` plus `execute(context)` | the deterministic runtime through `cascade run`, and Studio, which builds the ports from the literal | `cascade check`, which requires this style |
-| **dynamic**: `execute(node, graph)` declaring its own ports and parameters | Studio, and `cascade run` including `--frames` | `cascade validate` and a cook |
-
-Studio cooks both, and a Studio graph may mix them. `cascade run` picks one host per document: a graph whose project modules are all definition-v1 runs through the deterministic runtime, and anything else runs through the compatibility engine — which is also why `--frames` is refused on an all-definition-v1 graph, the deterministic runtime owning its own clock. The `AGENTS.md` that `cascade new` writes into a project states which style that project expects, and it is the file to believe over this one for a specific project.
+| **definition-v1**: a literal `definition` plus `execute(context)` | the deterministic runtime through `cascade run`, including `--frames`; Studio adapts it into its compatibility controller | `cascade check`, which requires this style |
+| **dynamic**: `execute(node, graph)` declaring its own ports and parameters | Studio and the CLI compatibility engine, including `--frames` | `cascade validate` and a cook |
+
+Studio cooks both, and a Studio graph may mix them. `cascade run` picks one host
+per document: an all-definition-v1 graph runs through the deterministic
+runtime and an all-dynamic graph runs through the compatibility engine. A
+mixed CLI document is rejected until the bounded adapter between those engines
+exists. Both homogeneous forms support `--frames`; deterministic runs receive
+an explicit frame and fps so expressions and keyframe channels resolve
+reproducibly. The `AGENTS.md` that `cascade new` writes into a project states
+which style that project expects, and it is the file to believe over this one
+for a specific project.
 
 ### definition-v1
 
@@ -244,9 +291,9 @@ export async function execute(node: any) {
 }
 ```
 
-`param()` is a method on the node the engine hands to `execute`, not an import. It is re-declared on every cook, so it never resets a value, an expression, or a keyframe someone set: reading `.value` gives the *resolved* value for the current frame, whichever of the three bindings is in force. Top-level statements outside `execute` do not run, because the loader imports a real ES module and needs the `execute` export.
+`param()` is a method on the node the engine hands to `execute`, not an import. It is re-declared on every cook, so it never resets a value, an expression, or a keyframe someone set: reading `.value` gives the *resolved* value for the current frame, whichever of the three bindings is in force. The loader imports the module as real JavaScript, so top-level code does run at import time. Keep dynamic modules free of top-level effects and put interface declaration and cooking inside `execute`.
 
-Prefer `new OffscreenCanvas(width, height)` to `document.createElement('canvas')` when both hosts could run the node, and keep `runsOn: 'browser'` for code that genuinely needs the page. Web technology comes first, meaning Canvas 2D, WebGL and WebGPU. A Python stage is for work that cannot run in a browser at all, such as an exotic ML library. 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.
+Prefer `new OffscreenCanvas(width, height)` to `document.createElement('canvas')` when both hosts can run the node. A portable declaration still requires output parity checks; installing Skia does not override a browser-only declaration. Use Python for libraries or tools that require a server. Measure transport, serialization, and cold-start costs; persistent workers can avoid repeated process/model startup.
 
 Choose the narrowest execution locus:
 
@@ -268,6 +315,25 @@ export const definition = {
 
 The runtime refuses unsupported host/capability combinations before executing the graph.
 
+### GPU nodes today
+
+A definition-v1 node may declare `capabilities: ['gpu']`. Studio and the optional
+Dawn CLI host provide one shared `GPUDevice`, adapter identity and limits, plus
+a cache scoped to each node instance for pipelines, samplers, and other
+resources that outlive one cook. The host clears cached resources on host
+disposal or device loss and requests a fresh device on a later cook.
+
+Use `runsOn: 'portable'` for shared WebGPU code without browser APIs. Render into
+a texture and use `readTexture` from `cascade/gpu` for explicit RGBA8 pixels,
+then encode through the image/IO host. See [headless GPU rendering](HEADLESS_GPU.md)
+for CLI/agent commands, restrictions and tests.
+
+This is the first GPU capability stage. Texture connections are not available:
+GPU nodes still publish images, so an image must be encoded or read back before
+another node receives it. Do not model a current graph as a chain of portable
+texture handles, and do not keep a device or pipeline in module-level mutable
+state.
+
 Some portable operations have genuinely useful browser and server
 implementations. Keep one literal definition and one module ID; let the host's
 registration load the implementation for its environment. Do not add an
@@ -340,7 +406,11 @@ In the document, a channel sits in the node's `props` next to the value and the
 }
 ```
 
-`params` holds plain values; a binding needs the object form under `props`. Playback settings, the frame range and loop, belong to the Timeline panel and are not saved with the document.
+Definition-v1 parameter values belong under `props`: use a bare value for an
+unbound parameter or the object form for an expression/channel. A leftover
+`params` array is not read by the deterministic runtime and produces a
+`runtime/stray-params` warning. Playback settings, frame range, and loop belong
+to the Timeline panel and are not saved with the document.
 
 ## Run a coding agent in the project
 
@@ -484,12 +554,35 @@ cascade run index.cascade --frames 42 --entry-node logo-1024
 
 Offline, drawing goes through Skia: the optional `@napi-rs/canvas` supplies `OffscreenCanvas`, `Image`, `Path2D` and the rest as globals in the Node process, deliberately not `document`, because that is how a node tells which host it is in. This is why a node that draws on an `OffscreenCanvas` needs no second implementation for headless runs, and why the built-in `cascade.image.*` nodes render under `cascade run` as well as in Studio. A graph that draws nothing runs without the renderer installed.
 
-`--frames` renders dynamic graphs. A definition-v1 graph runs through the deterministic runtime, which owns its own clock and has no parameter animation, and the flag is refused rather than silently rendering the first frame repeatedly.
+`--frames` renders both homogeneous graph forms. An all-definition-v1 graph
+runs once per requested frame through the deterministic runtime, which resolves
+expressions and channels from the explicit frame and fps. An all-dynamic graph
+uses the compatibility frame renderer. A mixed graph is rejected rather than
+silently choosing one engine.
 
 Applications can use `createRuntime()` from `cascade/runtime` directly. Register node modules and host capabilities, load the graph, mutate inputs or presets, run or trigger it, read outputs, then dispose it. This path loads no Svelte or Studio code and works in a backend service or a custom browser application.
 
 Server and browser hosts are deliberately explicit. A graph that uses Python or shell stages belongs on the server or behind an application-defined bridge; the runtime does not silently move computation between environments.
 
+For a browser-only deployment, build a static player:
+
+```bash
+cascade build index.cascade --out web-player --asset assets/source.svg
+```
+
+The output directory must be new. Serve it over HTTP(S), open `index.html`, or
+embed `player.html` in an iframe. `embed.js` supplies same-origin playback,
+parameter and output controls. Only explicitly included files and literal typed
+asset/image references are copied; server capabilities are rejected, not proxied.
+See [Web player](WEB_PLAYER.md) for the full deployment and asset contract.
+
+The Studio single-HTML/folder exporter is separate from this player. It currently
+serializes a compatibility graph into its own small browser runtime, so it does
+not preserve every node, capability, or runtime behavior. Use it only after
+testing the exported artifact for the particular graph. Prefer `cascade build`
+for definition-v1 browser graphs, or embed `cascade/runtime` directly when an
+application needs custom capabilities and presentation.
+
 ## Verify a project
 
 Before committing a custom node or graph:
@@ -499,4 +592,9 @@ Before committing a custom node or graph:
 3. Run the graph headlessly when its capabilities are available. This is the step that catches a document that loads, reports its nodes, and draws nothing. The characteristic failure here is silent, so a static pass alone proves little.
 4. Open Studio only for visual inspection or authoring that benefits from the graph UI.
 
-Dynamic modules are not deprecated and 0.3.0 stopped calling them legacy: the two styles are cooked by different hosts, and a project's own `AGENTS.md` says which one it expects. Convert a node when you need what the other style gives, static inspection and `cascade check` on one side or Studio cooking and `--frames` on the other, rather than on a schedule.
+Dynamic modules are not deprecated and 0.3.0 stopped calling them legacy. The
+two styles are cooked by different CLI engines, while Studio currently adapts
+both through its compatibility controller. Prefer definition-v1 for new work
+because it provides static inspection, `cascade check`, and the neutral runtime.
+Keep an existing dynamic node when its current compatibility-only APIs are
+still required, and keep CLI graphs homogeneous until mixed execution exists.