@field/cascade 0.3.1 → 0.5.1

package/README.md

@@ -2,24 +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.
-- The same runtime in Studio, a Node service, or a UI-free browser application.
+- 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 WebGL, files, media, Python, and allowlisted shell commands.
+- 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.
@@ -29,7 +60,9 @@ npm install -g @field/cascade
 cascade --version
 ```
 
-That installs the `cascade` command: `cascade new` scaffolds a project, `cascade <directory>` opens it in Studio, and `cascade run` renders a graph headlessly.
+That installs the latest published release and the `cascade` command: `cascade new` scaffolds a project, `cascade <directory>` opens it in Studio, and `cascade run` executes a graph headlessly. A generated project records the published package under the local alias `cascade`, so imports such as `cascade/contracts` resolve to `@field/cascade`.
+
+The repository checkout can be ahead of the published release, even with the same version number. Use the global install to scaffold projects, then use their npm scripts or `npx --no-install cascade` to select the project-local version. For checkout development, see [Contributing](CONTRIBUTING.md). When diagnosing a difference, record the installed version and whether it resolves to a local checkout; a version match alone does not prove the same code is installed.
 
 Offline image rendering uses Skia through `@napi-rs/canvas`, an optional dependency of about 26 MB. It installs by default; if you skipped optional dependencies, add it yourself:
 
@@ -63,10 +96,15 @@ npm run build:cli
 
 ## Create a project
 
+`cascade new` scaffolds a project and starts Studio. After stopping that first
+server, install the project's dependencies before reopening it. The example
+below assumes the default projects directory; `cascade projects` reports yours.
+
 ```bash
 cascade new my-artwork
 cd ~/Documents/Cascade/my-artwork
-cascade .
+npm install
+npx --no-install cascade .
 ```
 
 Studio binds to loopback by default. To use a Cascade workstation over a
@@ -81,6 +119,18 @@ both the bind target and allowed browser hostname. Use repeatable
 `--trusted-host` only when the bind address and browser hostname differ.
 Wildcard remote binds, unknown options, and invalid ports fail immediately.
 
+An HTTPS reverse proxy may terminate TLS and forward to a loopback Studio. In
+that case, name both sides explicitly:
+
+```bash
+cascade . --host 127.0.0.1 --port 3030 --trusted-host cascade.example.internal
+```
+
+The proxy must preserve the browser's exact `Host`. If the external URL uses a
+non-default port, include it in `--trusted-host`. Use `--no-open` and open the
+HTTPS URL yourself: automatic opening still uses an HTTP URL. This flag admits
+the authority; it does not configure TLS or the proxy itself.
+
 A project is an ordinary directory or Git repository:
 
 ```text
@@ -105,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
@@ -152,7 +229,21 @@ 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.
 
-`--frames` renders dynamic graphs. A definition-v1 graph runs through the deterministic runtime, which owns its own clock and has no parameter animation, and `cascade run` refuses the flag rather than rendering frame 1 a hundred times.
+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
 
@@ -219,7 +310,7 @@ host's executor, so the graph stays portable and contains no backend selector.
 This is the intended pattern for media transforms such as crop or resize; use
 shared parity tests to keep their outputs and metadata aligned.
 
-There is a second node style, and it is not deprecated. A **dynamic** module exports `execute(node, graph)` and declares its ports and parameters imperatively inside it, as `node.param('size', 1024, { min: 16, max: 4096 })`, running once for discovery and again on every cook. Studio cooks both styles and a Studio graph may mix them: it dispatches on what a compiled module exports, building a definition-v1 node's ports from its literal and calling `execute` with a real context, and calling a dynamic module as `execute(node, graph)`. `cascade run --frames` renders dynamic graphs, and the deterministic runtime cooks definition-v1 ones, which are what `cascade check` inspects statically. A malformed definition never falls back to dynamic execution — it is reported. A project's own `AGENTS.md`, written by `cascade new`, states which style that project expects.
+There is a second node style, and it is not deprecated. A **dynamic** module exports `execute(node, graph)` and declares its ports and parameters imperatively inside it, as `node.param('size', 1024, { min: 16, max: 4096 })`, running once for discovery and again on every cook. Studio cooks both styles and a Studio graph may mix them through its compatibility controller. The CLI uses the deterministic runtime for an all-definition-v1 document and the compatibility engine for an all-dynamic document; it rejects a mixed document. `cascade check` requires definition-v1 modules because it inspects them statically. A malformed definition never falls back to dynamic execution — it is reported. A project's own `AGENTS.md`, written by `cascade new`, states which style that project expects.
 
 Provider integrations are project code, not Cascade infrastructure. A project
 can call a remote service from a Studio/browser node, invoke Python or an
@@ -262,11 +353,23 @@ cancellation, event subscriptions, output retrieval, and disposal. Hosts
 decide which capabilities exist; Cascade never silently moves a stage between
 browser and server.
 
-The same registration path exposes the initial `cascade.geo.*` library in
-Studio and headless hosts: `Rectangle`, `Circle`, `Transform`, `Merge`,
-`CopyToPoints`, and `SvgExport`. Their definitions, ports, and executors are
-owned by the runtime; Studio adapts those definitions instead of maintaining a
-second set of node algorithms.
+The same definitions expose the initial `cascade.geo.*` library in Studio and
+headless hosts: `Rectangle`, `Circle`, `Transform`, `Merge`, `CopyToPoints`,
+and `SvgExport`. Their definitions, ports, and executors are runtime-owned;
+Studio adapts them through its compatibility controller instead of maintaining
+a second set of node algorithms.
+
+## Current capability boundaries
+
+| Surface | Current status |
+| --- | --- |
+| 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). |
+| 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
 
@@ -276,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.
@@ -320,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.