@field/cascade 0.4.0 → 0.5.2

package/AGENTS.md

@@ -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:
@@ -135,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,

package/ARCHITECTURE.md

@@ -20,11 +20,12 @@ 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
 
@@ -67,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.
 
@@ -121,6 +125,48 @@ 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. `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.

package/CHANGELOG.md

@@ -2,6 +2,74 @@
 
 Notable changes to Cascade. Newest first.
 
+## 0.5.2 — 2026-09-10
+
+### Fixed
+
+- **The load warm-up no longer reports false errors.** A node's ports are
+  created by running its code, so on load a connection into a node that has
+  never executed has no port to attach to, and Studio cooks the graph
+  repeatedly until the wiring settles. Early passes reached nodes whose
+  upstream edge had not bound, those nodes ran with `undefined` on that input
+  and threw their own "nothing wired to my image input", and a later pass then
+  succeeded — leaving a correct graph and a log full of errors that never
+  cleared. Reported against the `volume-field` sketch by someone who had
+  verified from the cache files that the render was in fact right.
+
+  The scheduler now distinguishes an input that is *pending* from one that is
+  *missing*: a node with an unbound inbound edge is held back as not-ready
+  rather than cooked and failed. Once the warm-up stops making progress the
+  graph says so, and an edge that still has not bound is treated as unbindable
+  — so a genuinely unwired node errors as it always did, rather than silently
+  never cooking.
+
+## 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

package/CONTRIBUTING.md

@@ -13,6 +13,7 @@ for product decisions, and [ARCHITECTURE.md](ARCHITECTURE.md) for dependencies.
 - `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
@@ -39,11 +40,20 @@ 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`.
@@ -69,3 +79,26 @@ 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,9 @@
 ## Source of truth
 
 - Status: Active
-- Last refreshed: 2026-09-08 (0.3.1)
-- 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`, `src/nodes/definition/gpuCapability.ts`, `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`
+- 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.
 
@@ -31,6 +31,7 @@ This document contains both current product rules and intended direction. Sectio
 
 - 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
@@ -79,6 +80,7 @@ This document contains both current product rules and intended direction. Sectio
 - 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.
 
@@ -106,8 +108,8 @@ This document contains both current product rules and intended direction. Sectio
 
 ## Components
 
-- **Current:** `PortEditor`, `JsonTree`, `ColorPicker`, `CoreValue`, `StructuredValue`, Viewer image zoom/pan behavior, and the type renderer registry.
-- **Planned:** a shared type-value presentation shell, structured JSON editing, richer image and asset inspection, geometry summaries/previews, a Viewer output list, and texture inspection after texture values exist.
+- **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
 
@@ -141,6 +143,7 @@ This table defines the intended presentation contract. Individual rows may be on
 - 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
 
@@ -167,6 +170,6 @@ This table defines the intended presentation contract. Individual rows may be on
 
 ## 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

package/README.md

@@ -2,25 +2,55 @@
 
 Cascade is a TypeScript node-graph runtime and optional visual workspace for generative design. It is built for projects that move between interactive web work, WebGL, print, motion, sound, Python, and external services without rebuilding the surrounding application infrastructure each time.
 
-Created by Marcus Wendt at [FIELD.IO](https://www.field.io).
+Created by Marcus Wendt at [FIELD.IO](https://www.field.io). Free and open source
+under the MIT license. [Getting started and features](https://cascade.field.io).
 
 ## What Cascade provides
 
 - A typed, inspectable graph model with lazy execution and explicit triggers.
 - Deterministic custom-node definitions that tools can inspect without running user code.
 - An environment-neutral runtime for Node services and UI-free browser applications.
+- A standalone browser player: build static pages and embeddable sketches without a Studio server.
 - A Studio compatibility controller that already presents deterministic definitions alongside dynamic project nodes while its graph engine migrates to the neutral runtime.
 - Project-native `.cascade` files, assets, presets, and Git-backed version history.
 - Nested subnets with persistent hierarchy.
+- Geometry-native particles, explicit Feedback loops, bounded simulation checkpoints, and printable trail geometry.
+- Scenes with cameras and lights, a 3D Viewer, and shared CPU wireframe/point rendering.
 - Expressions on parameters, with Houdini's variables and functions: `$F`, `$FF`, `$T`, `$FPS`, and `ch()` to read another parameter.
 - Keyframe channels on parameters, edited through a timeline panel with transport, playhead, scrubbing, and a dope sheet.
-- Offline rendering with `cascade run`, including `--frames 1-100` for a numbered image sequence, rasterised through Skia rather than a browser.
+- Offline rendering with `cascade run`: Skia for Canvas2D, optional Dawn for compatible WebGPU nodes, and `--frames 1-100` for numbered image sequences.
 - A coding-agent console per project, running in the project directory, with a watcher that picks up the files it rewrites without a reload.
 - Explicit browser and server capabilities for WebGPU, files, media, Python, and allowlisted shell commands.
 - A Svelte Studio with an infinite canvas, Inspector, Viewer, timeline, and project workbench.
 
 Cascade separates the generative algorithm from the platform. Custom nodes describe stages of a pipeline; the runtime schedules and validates them; hosts supply environment-specific capabilities; Studio is only one possible frontend.
 
+## New in 0.5
+
+Build a visual system once, then use its supported host for print, stills,
+motion frames or an interactive web embed. This release adds the standalone
+player and hardens the geometry, simulation and scene tools added during 0.4:
+
+- **Web delivery:** `cascade build` packages a compatible graph and its explicit
+  assets. Embeds have independent runtimes, playback, parameter/input controls,
+  image downloads and disposal; no editor or Cascade API is required.
+- **Geometry and subnets:** compose shapes, transforms and copies through one
+  geometry type; organize reusable networks with typed Input/Output boundaries.
+- **Particles and feedback:** wire sources, forces and a solver, retain bounded
+  history, and turn particle trails into geometry for SVG or raster output.
+  Checkpoint reuse now preserves complete trails; nested Feedback respects loop
+  ownership and dependency order.
+- **Scenes and cameras:** assemble geometry, a camera and lights, inspect in the
+  3D Viewer, and use shared camera math for output. Rendering currently draws
+  wireframes and points; lights do not yet shade surfaces.
+- **Agent-ready rendering:** static node checks, finite render timeouts and JSON
+  image manifests let an agent edit, render and inspect results. Dawn is optional
+  native WebGPU for the Node host, not a browser emulator or model integration.
+
+Studio now uses only its active Dockview layout; the unreachable old window UI
+has been removed. No new dependencies or graph engine were introduced for the
+player. See the [changelog](CHANGELOG.md) for release details.
+
 ## Install
 
 Cascade needs Node.js 22.13 or newer.
@@ -125,6 +155,33 @@ cascade run index.cascade
 
 See [Project authoring](doc/PROJECT_AUTHORING.md) for project layout, nodes, `.cascade` files, capabilities, and headless embedding.
 
+## Publish a browser sketch
+
+The standalone player in Cascade 0.5+ exports compatible definition-v1 graphs to
+static files, without Studio or a Cascade server:
+
+```bash
+cascade build index.cascade --out web-player
+```
+
+Serve the generated directory through a static HTTP server or hosting service.
+Open `index.html`, embed `player.html` in an iframe, or import `embed.js` for
+same-origin controls. Server/Python/shell-dependent graphs must first separate
+or replace those stages; export does not move them into the browser silently.
+See [Browser player](doc/WEB_PLAYER.md) for assets, inputs, animation and limits.
+
+For example, after hosting the output at `/artwork/`:
+
+```html
+<iframe src="/artwork/player.html" title="Generative artwork"
+  style="width:100%;height:600px;border:0"></iframe>
+```
+
+Ordinary iframe embeds can cross origins. JavaScript controls through the
+generated `embed.js` require the same origin. WebGPU requires a compatible
+browser/device and HTTPS or localhost. Use `--asset assets/photo.png` for a
+file whose path is computed in code; export never copies the whole project.
+
 Projects may also provide trusted, dockable Studio panels as plain TypeScript modules under `panels/`. These extensions remain outside graph documents and are never loaded by headless execution.
 
 ## Animation
@@ -172,6 +229,20 @@ Frames are written as `<out>/<node id>.<frame>.<ext>`, zero-padded to at least f
 
 Drawing offline goes through Skia rather than a browser. The optional `@napi-rs/canvas` supplies `OffscreenCanvas`, `Image`, `Path2D` and the rest as globals in the Node process, deliberately not `document`, since that is how a node detects its host. So a node that draws on an `OffscreenCanvas` needs no separate headless implementation, and the built-in `cascade.image.*` library rasterises through Skia in Node too, so a graph built from it renders headlessly with no browser involved. A run without the renderer installed still works for graphs that draw nothing, and says what is missing if a cook fails in a canvas-shaped way.
 
+Compatible definition-v1 GPU nodes use optional Dawn instead. For a bounded
+still render that a test or agent can consume:
+
+```bash
+cascade check index.cascade
+cascade run index.cascade --frames 1 --json --timeout 60000
+```
+
+Check the exit code before parsing the success manifest on stdout, then inspect
+the images listed in `files`; diagnostics go to stderr. Dawn does not make DOM,
+WebGL or browser-only nodes portable, and pixel equality across GPU drivers is
+not guaranteed. See [Headless WebGPU](doc/HEADLESS_GPU.md) for host requirements,
+readback and testing guidance. Cascade does not upload these images to a model.
+
 `--frames` works for an all-dynamic graph and for an all-definition-v1 graph. Definition-v1 runs resolve stored expressions and keyframe channels from the explicit `frame` and `fps` supplied to each deterministic run. A CLI graph that mixes the two node styles is rejected explicitly because there is not yet a bounded adapter between the execution engines.
 
 ## The agent console
@@ -295,8 +366,9 @@ a second set of node algorithms.
 | Studio authoring | Supports dynamic and definition-v1 nodes in one document through the compatibility controller. |
 | Headless CLI | Executes all-definition-v1 or all-dynamic documents; mixed documents are rejected. Both styles can render frame sequences. |
 | Embedded runtime | `cascade/runtime` is the neutral definition-v1 API for Node and browser hosts. It does not load Studio or interpret dynamic nodes. |
+| Static browser player | `cascade build` exports definition-v1 browser/portable graphs with assets and optional browser WebGPU. No server operations, dynamic modules or project Studio panels. Same-origin JavaScript controls; ordinary cross-origin iframe embeds. |
 | GPU | Studio and the optional Dawn CLI host provide a shared device, adapter metadata, limits, and per-node caches. Portable GPU nodes render offscreen and explicitly read RGBA8 pixels through `cascade/gpu`; graph ports still carry images. See [headless GPU rendering](doc/HEADLESS_GPU.md). |
-| Standalone HTML export | The existing Studio exporter uses a separate minimal runtime and supports only a subset of graph behavior. Treat it as an experimental convenience, not as a universal deployment artifact. |
+| Studio HTML export | The older Studio exporter uses a separate minimal runtime and supports only a subset of graph behavior. Use `cascade build` for supported definition-v1 web deployment. |
 | External services | Project-owned and optional. Cascade itself requires no paid provider or model subscription. |
 
 ## Repository map
@@ -307,12 +379,14 @@ packages/runtime/    environment-neutral graph runtime and adapters
 src/editor/          optional Svelte Studio, including the timeline and agent panels
 src/nodes/           current class-based built-in node libraries (core, geo, image)
 src/engine/          current compatibility services
-src/cli/             the `cascade` command: new, validate, check, inspect, run, Studio
+src/cli/             the `cascade` command: new, validate, check, inspect, run, build, Studio
+src/player/          standalone browser host and iframe controls
 server/              project-scoped Node host and transports, including the agent session host
 scripts/             package build, node-reference generation, and release verification tooling
 tests/               behavior, workflow, security, and performance tests
 spec/                accepted feature specifications
 doc/                 authoring guides and implementation plans
+site/                static documentation at cascade.field.io
 ```
 
 The root `cascade` package is the distribution and CLI owner. The two internal workspaces define architectural boundaries; they are not independently published until independent versioning or external consumption requires it.
@@ -351,6 +425,8 @@ trusted-host session; an untrusted remote bind does not expose them.
 - [Node reference](doc/NODE_REFERENCE.md) — every built-in node and its declared ports, generated from the definitions
 - [Design source of truth](DESIGN.md)
 - [Architecture](ARCHITECTURE.md)
+- [Browser player](doc/WEB_PLAYER.md)
+- [September quality review and sketch verification](doc/QUALITY_REVIEW_2026-09.md)
 - [Subnet and shell specification](spec/CASCADE_SUBNET_AND_SHELL_SPEC.md)
 
 Inspired by Nodes.io, SideFX Houdini, TouchDesigner, Maya, Cinder, openFrameworks, and Processing.