@field/cascade 0.3.0 → 0.4.0

package/doc/HEADLESS_GPU.md

@@ -0,0 +1,160 @@
+# Headless WebGPU with Dawn
+
+The CLI can run definition-v1 nodes declaring `runsOn: 'portable'` or
+`'server'` and `capabilities: ['gpu']` through optional `webgpu@0.6.0` (Dawn).
+Studio uses browser WebGPU through the same device/cache lifecycle mechanism.
+Browser-only declarations remain browser-only; installing Dawn does not supply
+DOM, WebGL, canvas presentation, image decoding, or video APIs.
+
+## Decision and release status
+
+Implemented on 2026-09-08 and checked in as source version `0.3.2`; see the
+[changelog](../CHANGELOG.md). Checking in the source does not publish the npm
+package. Use a built checkout or a tarball known to include the feature until
+the corresponding package release is published.
+
+The decision is to use optional native Dawn for browser-independent GPU
+execution and agent image feedback. Browser automation remains useful for
+Studio interaction/presentation tests; Skia remains the Canvas2D renderer.
+Neither is replaced by Dawn. This first slice shares WGSL/rendering logic and
+device/cache ownership without introducing a new graph texture pipeline or
+requiring a browser process for production CLI rendering.
+
+## Render for a test or agent
+
+From a compatible project, using a Cascade build containing this feature:
+
+```sh
+npx --no-install cascade run index.cascade --frames 1 --json --timeout 60000
+npx --no-install cascade run index.cascade --frames 1-24 --fps 24 --out renders --json --timeout 120000
+```
+
+`--json` requires a fully definition-v1 frame render; use `--frames 1` for a
+still. Stdout contains one success manifest with absolute graph path,
+project-relative image `files`, `frames`, actual `fps`, elapsed `durationMs`,
+and Dawn adapter metadata when a GPU was used. Logs and failure diagnostics go
+to stderr; failures exit nonzero and do not emit a success manifest. This is a
+local command contract, not a chat-provider integration or an untrusted-code sandbox.
+
+Illustrative manifest for the `cloud-volumes/dawn.cascade` fixture:
+
+```json
+{
+  "status": "completed",
+  "graph": "/path/to/cloud-volumes/dawn.cascade",
+  "frames": [1, 2],
+  "files": ["renders/dawn/volume.0001.png", "renders/dawn/volume.0002.png"],
+  "aborted": false,
+  "fps": 30,
+  "durationMs": 115.1,
+  "gpu": {
+    "renderer": "dawn",
+    "adapter": {
+      "vendor": "apple",
+      "architecture": "metal-3",
+      "device": "apple-m3-max",
+      "description": "Metal driver on macOS"
+    }
+  }
+}
+```
+
+Resolve `files` relative to the directory containing `graph`. `gpu` is omitted
+if no GPU node executed. `durationMs` measures the frame-rendering section and
+cleanup, excluding CLI startup and module preparation; it is not GPU-pass time.
+
+For agent callers: set a finite timeout, check the exit code, parse stdout only
+on success, then attach the listed images to the conversation. Keep stderr for
+diagnosis. A manifest records outputs, not a complete reproducibility bundle:
+save the graph, code/assets and authored settings separately. The CLI does not
+upload images or contact a model provider.
+
+`--timeout` supervises a separate render process and returns exit 124 when its
+deadline expires. On POSIX, termination covers that process group; on Windows,
+the current supervisor terminates the direct child only. Interrupts are forwarded
+with a short grace period before forced termination. A forced stop can leave
+partial output files; consumers must check the exit code and manifest. Ordinary
+successful runs destroy cached resources and release the native GPU reference.
+
+Dawn loads lazily, only when a GPU node executes. Static `check`/`validate`
+inspect the declared host contract without initializing hardware; they do not
+prove that a native binary, driver, or adapter is usable. Missing native support
+produces an installation diagnostic at execution. Dawn itself may be omitted
+for CPU-only environments; retain the compiler's own platform dependencies.
+Skia remains the independent Canvas2D path.
+
+## Authoring contract
+
+Use `context.capabilities.gpu.device` and `.cache(key, create, destroy)`.
+Cache keys are scoped per node; destroy callbacks release textures and buffers.
+The application owns the host's disposal, not an individual graph sharing it.
+Use `createRenderPipelineAsync` to surface shader/pipeline validation failures.
+`readTexture` captures validation failures within its own operation. Arbitrary
+GPU commands issued before it need their own error scopes or async validation;
+run-aware routing of all uncaptured device errors is not implemented yet.
+
+Render into a single-sample `rgba8unorm` 2D texture with
+`TextureUsage.RENDER_ATTACHMENT | TextureUsage.COPY_SRC`. Then:
+
+```ts
+import { readTexture } from 'cascade/gpu';
+
+const pixels = await readTexture(gpu.device, target, { signal: context.signal });
+// pixels: { data: Uint8Array, width, height }, tightly packed top-left RGBA8
+```
+
+Readback strips the WebGPU buffer row padding and copies bytes before unmapping.
+It releases its staging buffer on success, mapping failure, or cancellation.
+It does not encode PNGs or perform colour conversion. Encode through the existing
+image/IO host and publish an `image` value. Graph-wide texture transport, HDR
+readback, and browser video uploads are outside this first implementation.
+
+## Verification and limits
+
+```sh
+CASCADE_TEST_DAWN=1 npx vitest run tests/dawn-native.test.ts
+CASCADE_TEST_DAWN=1 npm run test:package
+```
+
+These opt-in hardware gates fail if Dawn cannot initialize. The first checks
+repeated creation, rendering, padded readback and natural process exit. The
+second installs a packed tarball into an empty project, renders animated PNGs
+through the CLI and checks decoded pixels and the JSON manifest.
+It also removes Dawn from that temporary installation to verify that a CPU
+graph still runs and a GPU graph fails with an actionable missing-renderer
+diagnostic. No silent CPU or browser fallback is performed.
+
+Recorded implementation verification (2026-09-08):
+
+- Main test suite: 1,322 passed; the opt-in hardware test was skipped there and
+  passed separately with `CASCADE_TEST_DAWN=1`.
+- Typechecking: zero errors, eight existing Svelte warnings.
+- Contracts/runtime package checks and tests, server/Studio/CLI builds, and
+  packed-package imports/types and rendering checks passed.
+- The real `cloud-volumes/dawn.cascade` fixture passed static checks and wrote
+  two distinct animated PNGs with an adapter-bearing JSON manifest.
+
+These are recorded results, not a claim that every future checkout or platform
+passes. Rerun the gates after changes; Windows/Linux hardware has not yet been
+verified. Windows process-tree cancellation remains follow-up work.
+
+Do not require identical pixels across GPUs/drivers. Pin reference environments,
+record adapter information and use measured image tolerances. Agent callers
+should set a timeout, cap dimensions/frame counts, and preserve graph/code,
+assets, seed and frame settings alongside selected outputs.
+
+Initial proof (2026-09-08): the `cloud-volumes` shader at 130 × 96, 32 steps,
+with a fixed opaque 17 × 73 column and 144-byte uniform block produced zero
+changed channels across 49,920 channels for both original browser canvas →
+migrated browser texture and migrated browser → native Dawn. All outputs were
+nonblank. Both hosts used Apple Metal (native: M3 Max). This establishes that
+specific migration's parity, not universal GPU bit-exactness. The sketch's
+`dawn.cascade` additionally exercises the real Aoos input, image IO and animation
+through the CLI at 256 × 320.
+
+Native packaging and GPU/driver support vary by platform. The package chooses
+its default backend; Cascade does not enable unsafe Dawn toggles or silently
+configure software drivers. Software Vulkan requires separate host setup.
+See [Dawn Node bindings](https://github.com/dawn-gpu/node-webgpu),
+[software backend setup](https://dawn.googlesource.com/dawn/+/refs/heads/main/src/dawn/node/README.md),
+and [WGSL floating-point rules](https://gpuweb.github.io/gpuweb/wgsl/#floating-point-evaluation).

package/doc/NODE_REFERENCE.md

@@ -17,6 +17,42 @@ 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.Input`
 
 Input — Defines a public graph or subnet input

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,23 @@ 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.
 
+The Studio single-HTML/folder exporter is not this embedding API. 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. For a dependable
+custom experience today, embed `cascade/runtime` in an application and provide
+the graph's declared modules and capabilities explicitly.
+
 ## Verify a project
 
 Before committing a custom node or graph:
@@ -499,4 +580,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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@field/cascade",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Visual programming for generative art",
   "license": "MIT",
   "author": "FIELD.IO <marcus@field.io>",
@@ -27,11 +27,13 @@
     "dist",
     "!dist/**/*.map",
     "CHANGELOG.md",
+    "CONTRIBUTING.md",
     "AGENTS.md",
     "ARCHITECTURE.md",
     "DESIGN.md",
     "doc/NODE_REFERENCE.md",
     "doc/PROJECT_AUTHORING.md",
+    "doc/HEADLESS_GPU.md",
     "README.md",
     "LICENSE"
   ],
@@ -71,6 +73,10 @@
       "types": "./dist/runtime/animation/index.d.ts",
       "default": "./dist/runtime/animation/index.js"
     },
+    "./runtime/camera": {
+      "types": "./dist/runtime/camera/index.d.ts",
+      "default": "./dist/runtime/camera/index.js"
+    },
     "./runtime/definition/extract": {
       "types": "./dist/runtime/definition/extract.d.ts",
       "default": "./dist/runtime/definition/extract.js"
@@ -83,6 +89,10 @@
       "types": "./dist/io.d.ts",
       "default": "./dist/io.js"
     },
+    "./gpu": {
+      "types": "./dist/gpu.d.ts",
+      "default": "./dist/gpu.js"
+    },
     "./net": {
       "types": "./dist/net.d.ts",
       "default": "./dist/net.js"
@@ -104,6 +114,7 @@
     "check:packages": "npm run check --workspace @cascade/contracts && npm run build --workspace @cascade/contracts && npm run check --workspace @cascade/runtime",
     "test:packages": "npm run test --workspace @cascade/contracts && npm run test --workspace @cascade/runtime",
     "build:cli": "npm run build:packages && node scripts/build-cli.mjs && npm run build:node-reference",
+    "build:server": "npm --prefix server run build",
     "prepack": "npm run build",
     "preview": "vite preview",
     "check": "svelte-check --tsconfig ./tsconfig.json",
@@ -144,6 +155,7 @@
     "dompurify": "$dompurify"
   },
   "optionalDependencies": {
-    "@napi-rs/canvas": "^1.0.8"
+    "@napi-rs/canvas": "^1.0.8",
+    "webgpu": "0.6.0"
   }
 }

package/dist/assets/geo-DUvVbLnx.js

@@ -1 +0,0 @@
-import{b as e,f as t,s as n,x as r}from"./index-HTCN44kj.js";r(n,{assets:e});export{t as geoLibrary};