@field/cascade 0.8.0 → 0.10.0

package/doc/PROJECT_AUTHORING.md

@@ -269,6 +269,58 @@ The reason is not tidiness. Two floats cannot connect to a `vec2` output, take t
 
 Keep them separate only when the components differ in kind or in range — a `width` and a `depth` that mean different things are two props, not a `vec2`.
 
+#### Bundle ports
+
+When a node would fan out more than three or four outputs that travel together, export one `bundle` instead: a single port carrying named fields. Each field is any Cascade type; an image or cache entry travels as its reference (`ImageRef`, `AssetRef`), never its pixels.
+
+```ts
+// Producer: declares the fields it carries, and optionally a schema name.
+outputs: {
+  format: {
+    kind: 'data', type: 'bundle', schema: 'format',
+    fields: {
+      size: 'vec2i',
+      size_mm: 'vec2',
+      dpi: { type: 'float', description: 'Resolution of the working canvas' },
+      paper: 'string',
+    },
+  },
+},
+// in execute:
+context.outputs.format.set({ size, size_mm, dpi, paper });
+```
+
+```ts
+// Consumer: declares the fields it reads.
+inputs: {
+  format: { kind: 'data', type: 'bundle', schema: 'format', fields: ['size', 'paper'] },
+},
+// in execute:
+const { size, paper } = context.inputs.format ?? {};
+```
+
+- **`fields` on an output** maps each field to its type. A producer may set only declared fields; a declared field may be left unset. Without `fields` the bundle is untyped and nothing can check it.
+- **`fields` on an input** lists the fields the node reads. The node then sees only those, and Studio re-cooks it only when one of them changed: a change to `dpi` does not re-cook a consumer that reads `size` and `paper`. Without `fields` a consumer depends on the whole bundle. Field access is not tracked at run time, so declare the selection when the node is expensive.
+- **`schema`** names the bundle's shape. Two named schemas must match to connect; a port without one takes any bundle.
+- **Expressions** read a field of a wired bundle input with a dotted path: `ch("format.dpi")`, `chv("format.size_mm")`, `chs("format.paper")`. The path names an input on the same node, not another node's output, so the wire is the dependency and the producer always cooks first. `ch("/spread-format/format.dpi")` is refused by `cascade check`, which says which wire to add. A field read in an expression counts as a declared field for caching.
+- **`cascade.core.Pick`** reads one field (`field` prop) for a node that wants a single value, and **`cascade.core.Pack`** builds a bundle from loose values, one name per input in its comma-separated `names` prop. Pick is cheap and its output only changes when the picked field does, so it is also how a node that cannot declare fields depends on one.
+- **`cascade check`** reports a field that the producer does not declare, in a consumer's `fields`, in an expression, or on a Pick, with the nearest declared name: `dot-layer.radius reads unknown bundle field "dpu" — did you mean "dpi"?`.
+- **Studio** draws a bundle as one port in the neutral wire colour. Hovering it lists every field with its type and current value, and the Inspector shows each field with its own control.
+
+A bundle passed to a Python stage is an ordinary JSON object, so the worker receives a `dict`; reference fields arrive as their small JSON form, e.g. `args["format"]["preview"]["path"]`. A stage that returns a dict can be set straight onto a bundle output:
+
+```ts
+const result = await runStage('signals', { format: context.inputs.format });
+context.outputs.signals.set(result as Record<string, unknown>);
+```
+
+```python
+def signals(args):
+    fmt = args["format"]            # a dict
+    w, h = fmt["size"]
+    return {"brightness": {"path": cache_png(...), "size": [w, h], ...}, "edge_count": 412}
+```
+
 ### dynamic
 
 A dynamic module declares its interface imperatively, inside `execute`, which runs once to discover the interface and again on every cook. There is no `definition` export; `runsOn` and `icon` are plain exports.
@@ -512,6 +564,60 @@ It may also accept inline JSON after `--args` for manual compatibility. Projects
 with expensive imports may additionally declare a newline-delimited JSON
 `worker`; Cascade keeps that process warm and correlates requests by `id`.
 
+Cascade sends the worker one request at a time. When a newer edit supersedes a
+running stage, Cascade withdraws it: a queued request is never sent, and the
+one in flight gets `SIGINT`. A worker that catches `KeyboardInterrupt` around a
+request should answer `{"id": <id>, "ok": false, "cancelled": true}` and keep
+serving, so warm models survive a scrub; it should also ignore an interrupt
+that arrives between requests. A worker that does not handle it exits and is
+respawned on the next call, and one that has not answered within three seconds
+is killed. Whatever a cancelled request returns is discarded. Write cache
+entries atomically (temp file plus rename), since a stage can now be
+interrupted part-way. Nodes can pass `{ signal }` as `runStage`'s third
+argument; without it the signal of the cook in flight is used.
+
+#### Stage code, cache keys and the run trace
+
+Cascade keys every stage call on four things: the stage code (a hash of every
+`.py` file under `exec.stages.sources`), the arguments with each input file
+replaced by a hash of its bytes, those input hashes, and the Cascade version.
+The key and the cache state are reported on every call, hit or miss: in the
+server log (`[stage] ink: miss (no entry) key 3f2a… code 99dad29d… 1204 ms`),
+in `cascade run --json` under `stages`, and in the run trace.
+
+```json
+{
+  "exec": {
+    "stages": {
+      "entrypoint": "runtime/node_cli.py",
+      "worker": "runtime/worker.py",
+      "sources": ["runtime", "src", "shared/bridge"],
+      "cache": { "exclude": ["plot-status"], "outputs": ["out", "svg_out"] }
+    }
+  }
+}
+```
+
+- `sources` lists the files and folders whose `.py` files are the stage code.
+  Without it: the folders of the entrypoint and the worker, plus `src/`. A
+  symlinked folder (such as `shared/`) is followed only when it is listed.
+- The warm worker fingerprints those sources when it starts and again before
+  every request, and restarts first when they changed, so an edited stage never
+  keeps running its old code in a live Studio. Its bytecode cache is keyed by
+  the code hash, because Python accepts a `.pyc` whose source kept its size
+  within the same second.
+- `cache` turns on Cascade's own result cache: `true`, or an object with
+  `exclude` (stages whose answer changes under an identical call) and
+  `outputs` (arguments naming files a stage writes, which are not inputs). Off
+  by default. A stored result is served only while every file it names still
+  has the bytes it had, so a stage that writes a fixed path and was re-run with
+  other inputs misses rather than serving the overwritten file.
+- A request carries `"cascade": {"key", "code", "cache"}` beside `args` (the
+  worker), or `CASCADE_STAGE_ENVELOPE` in the environment (one-shot). A
+  project that keeps its own cache should stand aside when `cache` is `"off"`,
+  which `cascade parity` sets, and may answer `"cache": "hit" | "miss"` beside
+  `result` so the trace shows its state too.
+
 ## Work with `.cascade` files
 
 A graph document stores authored elements separately from runtime state. Nodes and annotations remain flat even inside subnets:
@@ -550,6 +656,11 @@ cascade run index.cascade --frames 1-100x2 --fps 25 --out frames
 cascade run index.cascade --frames 42 --entry-node logo-1024
 ```
 
+Every run writes a trace to `.cascade/runs/<time>-<graph>.json` (the last 200
+are kept): each node that cooked, its time, and every stage call it made with
+the key and cache state. `--verbose` prints the stage lines as they happen, and
+`--json` prints the status, the seed, the trace path and the stage calls.
+
 `--frames` takes a range, a stepped range, or a single frame, and refuses a range it cannot parse rather than repairing it. Files are written as `<out>/<node id>.<frame>.<ext>`, zero-padded to at least four digits, into `renders/` unless `--out` says otherwise. One rule whether the graph has one output or three. Every image output with nothing connected downstream is saved, or the outputs of `--entry-node` when one is named. Cascade stops at the image sequence; a directory of numbered frames is what an encoder takes.
 
 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.
@@ -583,6 +694,32 @@ 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.
 
+## Seeds and parity
+
+A graph has one `seed` (an unsigned 32-bit integer, 0 when absent) and each
+node gets `context.seed`, derived from it and the node id, plus
+`context.random()`, a stream seeded with it that restarts at every cook. Both
+hosts derive them the same way, so a node that draws with `context.random`
+draws the same thing headless and in Studio. `Math.random` cannot be
+reproduced by any host; pass `context.seed` on to a Python stage instead of
+seeding there from the clock. `cascade run --seed N` cooks with another seed
+without editing the file.
+
+```bash
+cascade parity index.cascade                 # every node
+cascade parity index.cascade --node ink      # one node and what feeds it
+cascade parity index.cascade --tolerance 2 --json
+```
+
+`parity` cooks three times with every cache off: headless, headless again, and
+through Studio's own executor (the compatibility graph and its definition
+adapter) run headlessly with the same Dawn GPU and project capabilities. It
+prints one row per node output with both comparisons side by side (`same`,
+`within tolerance`, or the difference: pixels and the largest channel delta
+for an image, both values for a number) and exits 1 when anything differs.
+See [Headless GPU](HEADLESS_GPU.md#determinism) for what makes a GPU stage
+repeatable.
+
 ## Verify a project
 
 Before committing a custom node or graph:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@field/cascade",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Visual programming for generative art",
   "license": "MIT",
   "author": "FIELD.IO <marcus@field.io>",
@@ -35,6 +35,9 @@
     "doc/PROJECT_AUTHORING.md",
     "doc/HEADLESS_GPU.md",
     "doc/WEB_PLAYER.md",
+    "doc/EDITOR_EXPORT.md",
+    "doc/CLI_REFERENCE.md",
+    "doc/MCP.md",
     "README.md",
     "LICENSE"
   ],
@@ -86,6 +89,10 @@
       "types": "./dist/runtime/scene/index.d.ts",
       "default": "./dist/runtime/scene/index.js"
     },
+    "./runtime/editor": {
+      "types": "./dist/runtime/editor/index.d.ts",
+      "default": "./dist/runtime/editor/index.js"
+    },
     "./runtime/definition/extract": {
       "types": "./dist/runtime/definition/extract.d.ts",
       "default": "./dist/runtime/definition/extract.js"
@@ -121,12 +128,12 @@
   "scripts": {
     "dev": "vite",
     "dev:client": "vite",
-    "build": "vite build",
-    "postbuild": "npm run build:cli",
-    "build:packages": "npm run build --workspace @cascade/contracts && npm run build --workspace @cascade/runtime && node scripts/copy-package-builds.mjs",
+    "build": "node scripts/build.mjs",
+    "build:workspaces": "npm run build --workspace @cascade/contracts && npm run build --workspace @cascade/runtime",
+    "build:packages": "npm run build:workspaces && node scripts/copy-package-builds.mjs",
     "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:cli": "node scripts/build.mjs --cli",
     "build:server": "npm --prefix server run build",
     "prepack": "npm run build",
     "preview": "vite preview",
@@ -136,7 +143,9 @@
     "test:coverage": "vitest run --coverage",
     "test:package": "node scripts/smoke-package.mjs",
     "test:player": "node scripts/smoke-player.mjs",
-    "build:node-reference": "tsx scripts/build-node-reference.mjs"
+    "build:node-reference": "tsx scripts/build-node-reference.mjs",
+    "site:versions": "node site/build-versions.mjs",
+    "site:deploy": "node site/build-versions.mjs && vercel deploy --prod --yes --cwd site"
   },
   "dependencies": {
     "esbuild": "^0.28.2",