@field/cascade 0.10.0 → 0.11.0

package/AGENTS.md

@@ -35,10 +35,12 @@ my-project/
 └── tsconfig.json
 ```
 
-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.
+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 render <graph.cascade> --node <id>` renders an animation across worker processes (`--workers N`, default cores minus a few) and encodes a half-size H.264 preview (`--final` full size, `--prores` a master); a node must write each frame to its own file (frame in the name, or `saveImage(…, cachePath(…))`), and one that writes a fixed path is refused before the render starts. `cascade projects` shows or sets the default projects directory.
 
 Never hand-edit a `.cascade` file. Change graphs with `cascade node add|rm`, `connect`, `disconnect`, `set` and `subnet create|move|dissolve` (or `cascade edit` for a batch); they check the edit like `cascade check`, keep the diff minimal and lay new nodes out. Every command takes `--json`, and `cascade mcp` serves the same operations as MCP tools. Read `doc/CLI_REFERENCE.md` and `doc/MCP.md`.
 
+For agents working headlessly: `cascade help node <type>` prints a node's ports and description from the installed package; `cascade run <graph> --out <dir> [--out-node <id>]` saves image outputs as `<node>[.<port>].<ext>` (and `run --json` lists them in `data.images`); `cascade.assert.*` nodes fail a run with a readable message; what nodes and stages print is in the run trace under `.cascade/runs/`; `--env NAME=value` replaces a shell prefix; `cascade doctor --fix` builds the Python environment a project declares in `cascade.json` `python`; every MCP tool takes `project` to work in another 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
@@ -219,6 +221,7 @@ type system knows what a `vec2` is; nothing tells it that `offset_x` and
 - Studio uses `StudioGraphController` over its compatibility `Graph`/`Node` engine and reuses runtime mechanisms. Custom frontends consume the neutral runtime directly; full Studio migration remains incomplete.
 - User modules are trusted project code, not a sandbox. Static definitions improve tooling and portability, not isolation.
 - Keep legacy support inside the existing Studio/CLI compatibility engine; do not spread compatibility branches into the deterministic runtime.
+- `src/engine`, `src/nodes`, `src/cli` and `src/player` never import the Studio editor (`src/editor`, `src/App.svelte`); the server never imports `src/`. `tests/architecture-layers.test.ts` enforces these and the two above, and allows no new import cycle.
 
 ## Change workflow
 
@@ -228,9 +231,23 @@ the TypeScript 7 preview until it is stable and the repository gates pass.
 1. Add or update a focused regression test.
 2. Make the smallest change at the owning layer.
 3. Prefer deletion or an existing utility over another wrapper.
-4. Run the focused test, then `npm run check`, `npm run test:run`, `npm --prefix server run build`, `npm run build`, and `npm run build:cli` when the affected surface warrants it. Both builds write to a staging directory and replace `dist/` only on success, so a failed build leaves the previous CLI working.
+4. While iterating, run the focused test or `npm run verify:fast` (types for src, tests and server, the node reference, the architecture ratchets, and `vitest related` for the files you changed). Before you commit, run `npm run verify`: it builds the packages, then runs the typechecks, `check:packages`, svelte-check, the whole vitest suite, the package tests and the Studio bundle budget, stopping at the first failure. It never touches `dist/`. Run `npm run build` and `npm run build:cli` only when you need the built CLI or Studio; both replace `dist/` only on success, so a failed build leaves the previous CLI working.
 5. For package/public API changes, also test the packed tarball from an empty temporary project.
-6. When a built-in definition or a node library registry changes, regenerate the node reference with `npm run build:node-reference` and commit the result. `build:cli` runs it too, so a full build will produce the diff whether or not you meant to. Nothing tests that the committed file is current, so a stale one ships silently — and it is the first thing a project's agent reads.
+6. When a built-in definition or a node library registry changes, regenerate the node reference with `npm run build:node-reference` and commit the result. `verify` fails on a stale one (`npm run check:node-reference`).
+7. The ratchets in `tests/architecture-*.test.ts`, `scripts/bundle-budget.mjs` and the test type-error list in `scripts/verify.mjs` only go down. When one fails, fix the code: split the file, move the shared code down a layer, break the cycle, lazy-load the new Studio code. Never add to a list or raise a number; when your change lowers one, lower the number in the same commit.
+
+### Where a change goes
+
+| To add | Touch |
+| --- | --- |
+| A node in a project | `cascade node <Name>`, then `nodes/<Name>/index.ts` (see "Create a deterministic node") |
+| A built-in node in an existing namespace | `packages/runtime/src/builtins/<ns>/<node>.ts`, its entry in `builtins/<ns>/index.ts`, a test in `packages/runtime/test/`, then `npm run build:node-reference` |
+| A built-in namespace | `packages/runtime/src/builtins/<ns>/` and `builtins/index.ts`; Studio's `src/nodes/<ns>/index.ts` and `library.ts`, and `src/nodes/initializeLibraries.ts`; `scripts/build-node-reference.mjs` |
+| A CLI verb or MCP tool | One row in `src/cli/verbs.ts`, its handler, and its line in `doc/CLI_REFERENCE.md` (plus `doc/MCP.md` for a tool); `tests/cli-verbs.test.ts` checks the docs |
+| A graph edit operation | `packages/runtime/src/edit/operations.ts` and `graphEditor.ts`, then the verb row above |
+| A param type | `packages/contracts/src/values.ts`, `definition.ts`, `validate.ts`; `packages/runtime/src/runtime.ts`; `src/types/coreTypes.ts`, `node.types.ts`, `src/utils/propUtils.ts`; `src/editor/Inspector.svelte`, `CodeEditor.svelte`; `server/src/projectTemplate.ts`; `doc/PROJECT_AUTHORING.md` |
+| A Studio panel | `src/editor/panels/<Name>Panel.svelte` and its `registerPanelComponent` (or lazy) line in `src/editor/dockview/DockviewContainer.svelte`; keep it out of the entry chunk if it is not on first paint |
+| Shared code for the server and the CLI | `server/src/` (the CLI imports it); pure document code such as the `.cascade` formatter (`formatCompactJSON`) lives in `packages/contracts/src/` |
 
 Do not add dependencies without a concrete need. Do not create extra packages unless they need independent publication or versioning.
 

package/CHANGELOG.md

@@ -2,6 +2,193 @@
 
 Notable changes to Cascade. Newest first.
 
+## Unreleased
+
+## 0.11.0 — 2026-11-07
+
+### Added
+
+- **`cascade/image`: one node body for the browser and headless.** A
+  portable node declaring `capabilities: ['assets']` draws on `surface()` /
+  `createCanvas()` (the realm's `OffscreenCanvas` in Studio and an exported
+  editor, Skia's under `cascade run`/`render`/MCP), reads with `readImage` /
+  `readBytes` and writes with `writeImage` through the assets capability (the
+  host picks the stored path), and registers fonts with `registerFont`
+  (`FontFace` in a browser realm, Skia's `GlobalFonts` headless). No canvas or
+  no declared `assets` is refused with a sentence. Resolved from Cascade's own
+  install by Studio, the editor export, the web player and the CLI. This was
+  the missing browser image contract that kept commons nodes headless-only:
+  commons `plotter-social` (plotter, social-layout, foil ported; source
+  frozen) now exports as an editor, and renders pixel-identically to the old
+  server nodes headless. `cascade freeze --fields path,...` on an image output
+  now ships the image file with the snapshot.
+- **The sketch kit, `@field/cascade-kit` (`packages/kit`).** One package for
+  what the sketch projects kept rebuilding: OKLCH colour and gamut mapping,
+  k-means palettes in OKLab, seeded random (`Rng`, mulberry32, Python-equal
+  `hashParts`) and noise, paper, pen plot documents for a 0.1 mm pen, frames
+  to MP4, Cairn and Observatory snapshot loaders, and a disk cache keyed on
+  the code's import closure. Each module's tests pin it to the exact bits of
+  the copies it replaces. `cascade-kit nodes <provider>` writes the stubs for
+  using another project's nodes from a `file:` dependency, replacing the
+  `shared/` symlink and hand-copied stubs; `--check` reports drift. Outside the
+  core: Cascade does not import it and the published package does not ship
+  it. See `doc/KIT.md`. cloud-volumes, commons and cairn-strata-hd use it.
+- **`npm run verify`, one gate for everything.** Packages build, types for
+  src, tests and server, `check:packages`, svelte-check, vitest, the package
+  tests (192, outside `test:run` until now) and a Studio bundle budget, in
+  order, stopping at the first failure; `verify:fast` for the edit loop.
+  Architecture ratchets in `tests/architecture-*.test.ts`: the layer rules
+  from ARCHITECTURE.md, no new import cycle, no new file over 750 lines, no
+  unimported source file, duplicated lines capped. `build-node-reference
+  --check` fails on a stale `doc/NODE_REFERENCE.md`.
+- **Ladder, pick, lock.** `cascade ladder <graph> <node> --name
+  --vary node.prop=a,b,c | --seeds a,b,c` cooks three to five variants from
+  the stored code and writes each image, a labelled contact sheet and
+  `ladders/<id>.json` (per variant: graph, params, seed, inputs, output
+  fingerprint; the code and git commit once). `cascade pick <ladder> <n>`
+  writes the lock from that record at approval without cooking again, so
+  `cascade replay` reproduces the approved image pixel for pixel with no
+  worktree. Both are MCP tools (`ladder`, `pick`). New built-in
+  `cascade.image.ContactSheet` (definition-v1, headless; not yet in Studio):
+  images in, one labelled grid out.
+- **`cascade run --out`, outputs as files.** A still run with `--out <dir>`
+  copies each image output to `<dir>/<node>[.<port>].<ext>` (it was ignored
+  without `--frames`), and `run --json` lists every image output with its file
+  in `data.images`. A node with several image outputs writes one file per port
+  instead of overwriting itself; a `cascade.core.Null` passing an image counts
+  as an output; `--out-node <id>` (repeatable, MCP `outNodes`) saves a
+  mid-graph node as well; an absolute `--out` is accepted.
+- **Assertion nodes, `cascade.assert.Range`, `Equals`, `True` and
+  `NotBlank`.** A check in the graph that fails `cascade run` (exit 1, and
+  `run --json` gives `error.message: "Assertion failed in \"<node>\" …"`)
+  when it does not hold: a value in a range, equal to an expected JSON value,
+  true, or an image (PNG/PPM) that is not one flat colour or fully
+  transparent. Each passes its input through. Headless only for now: the CLI
+  registers them, Studio does not (its entry bundle has no room) and shows
+  them unresolved. Listed in `doc/NODE_REFERENCE.md`.
+- **MCP: the project directory per call.** Every tool takes an optional
+  `project`; the call's paths resolve against it and may not leave it, and
+  CLI-backed tools run there. One server started in commons can work on any
+  sketch. See `doc/MCP.md`.
+- **`cascade help node [<type>]`, node docs from the package.** Prints a node
+  type's inputs, props and outputs (type, default, range, description), where
+  it runs and its capabilities, from the definitions bundled in the CLI or
+  read statically from the project's `nodes/`; without a type, lists every
+  type. Short names work (`Circle`, `NotBlank`); a typo gets suggestions; a
+  class-based Studio node says so and points at the shipped
+  `doc/NODE_REFERENCE.md`. `--json`, and MCP `node_help`.
+- **Debug output in the run trace, and `--env`.** What a node prints while it
+  cooks (console, and its Python stages' stderr, which was shown only with
+  `--verbose`) is kept per node in `.cascade/runs/…json` and in
+  `run --json` as `data.logs`. A failed run now writes its trace too and
+  names it in the error. `cascade run|render --env NAME=value` (MCP `env`)
+  sets a variable for the run's stages and render workers without a shell
+  prefix; the trace records the names only.
+- **A declared Python environment for stages, and `cascade doctor`.**
+  `cascade.json` `"python": { "requirements": ["numpy", "Pillow"] }` (or a
+  requirements file) declares what a project's stages import; `cascade
+  doctor --fix` builds a venv for it in `.cascade-cache/python/venv`, never
+  system-wide, and stages then run under it instead of a bare `python3`. A
+  stage call with the environment missing or stale fails naming the fix,
+  not later on an ImportError. `cascade doctor` (MCP `doctor`) also checks
+  the stage interpreter, ffmpeg and the headless canvas.
+
+### Removed
+
+- **The Studio's single-file HTML export (File > Export…, ⌘E).** It ran a
+  third, minimal engine that understood neither definition-v1, expressions
+  nor animation. `cascade build` exports the browser player and `cascade
+  export` the shareable editor; the other exports are unchanged. Five unused Studio components and the code-history store only
+  they used are gone too.
+
+### Changed
+
+- **The CLI starts in 30 ms, not 300.** Each verb's handler loads when the
+  verb runs and the published bundle is split, so `cascade --version`, the
+  graph commands and every child the MCP server spawns no longer load the
+  engine, TypeScript, esbuild, sharp and express first (start-up: 3 modules,
+  was 225; `--version` 29 ms and 46 MB, was 286 ms and 155 MB).
+- **One verb table, `src/cli/verbs.ts`.** Dispatch, `--help`, `--json`
+  handling, the graph commands' options and the MCP tools all read it, so a
+  new verb is one row, its handler and its line in `doc/CLI_REFERENCE.md`,
+  which now lists every command.
+- `cascade graph list` skips `renders/` and `out/`.
+- The `.cascade` compact formatter has one copy, `formatCompactJSON` in
+  `cascade/contracts`, used by Studio, the server and the CLI; the server and
+  CLI share one atomic-write helper.
+- **The stage cache is on by default for node cooks.** A stage called from a
+  node's cook through `cascade/stage` is treated as pure and cached on its
+  code, arguments and input file bytes; a panel's `api.runStage` call is an
+  action and is not cached unless declared. A re-cook of
+  cloud-plots/relief.cascade went from 4.2 s to 0.45 s (all 17 stage calls
+  hit; no Python started). Opt a stage out with
+  `exec.stages.cache.exclude`, or everything with `"cache": false`; see
+  "The stage cache default" in `doc/PROJECT_AUTHORING.md`.
+
+### Fixed
+
+- **A node fed a different image of the same size re-cooks.** The input
+  fingerprint sampled three values of a typed array and only the dimensions of
+  an image, so two same-size images looked identical and a clean node kept
+  its old picture. A connected input is now keyed by its producer's output
+  version (O(1), exact), and a value set directly on a port is hashed in full.
+- The node and graph file watchers take an injected clock and watcher, and
+  their tests no longer sleep on real FSEvents; they had failed in every
+  loaded full run.
+- The MCP `locks` tool always answered "no locks command yet": the lock tools
+  probed `cascade --help` first and the probe never matched. The probe is
+  gone, so `lock`, `replay` and `locks` also spawn one process instead of two.
+
+## 0.10.2 — 2026-11-06
+
+### Added
+
+- **`cascade render`: an animation across worker processes.** `cascade render
+  <graph> --node <id> [--frames <range>] [--workers N]` splits the range across
+  processes (default: cores minus a few), each pulling contiguous batches from
+  one queue, and writes the same `<out>/<node>.<frame>.<ext>` sequence a serial
+  `run --frames` writes. A node that writes every frame to one fixed file is
+  refused before the other workers start: the first worker renders the first
+  two frames alone, and two frames on one path stop the render with the node
+  and the path. 144 ripple frames at 540 px on a shared 16-core machine at load
+  33-44: 59 s serial, 8-14 s on 8-12 workers, frames byte-identical to the
+  serial render.
+- **Preview by default.** An animation render also encodes
+  `<out>/<node>.preview.mp4`, half size, H.264 yuv420p with faststart.
+  `--final` encodes `<node>.mp4` at full size, `--prores` adds a ProRes
+  `<node>.mov` (4444 with alpha when the frames have any, else 422 HQ),
+  `--no-video` skips it. ffmpeg is checked before the render, not after.
+- **Progress and ETA.** One line every N frames (`--progress N`, default about
+  twenty a render), and the same as a note on a Cairn job with `--job <id>` or
+  `CAIRN_JOB` (`cairn jobs update <id> --note`).
+
+### Fixed
+
+- **Project nodes compile atomically.** The bundle is written beside its name
+  and renamed into place, so processes compiling the same node at once never
+  import a half-written file.
+
+## 0.10.1 — 2026-10-12
+
+### Fixed
+
+- **A phone never scales the editor page.** The viewport is fixed at the
+  device width (`maximum-scale=1`). iOS ignores `user-scalable=no`, so the shell
+  also blocks Safari's gesture events and two-finger moves outside the preview,
+  and sets `touch-action: manipulation` on controls so a double-tap on a button
+  does not zoom. Pinching the preview still zooms the preview. The page clips
+  any horizontal overflow, and the header truncates within the screen width.
+
+### Added
+
+- **Fonts in exported editors.** `editor.fonts` lists OFL-1.1 fonts that
+  `cascade export` ships and loads in the page and the engine worker, so
+  canvas and panel text draw with the project's font. Other licences and
+  `licensed/` files are refused.
+- **`cascade export --deploy vercel --public`** for an editor meant to be
+  public: an anonymously readable site is reported as intended instead of
+  failing the deploy.
+
 ## 0.10.0 — 2026-10-12
 
 ### Added

package/README.md

@@ -36,7 +36,7 @@ cascade .                          # reopen it later
 cascade run index.cascade --frames 1 --json   # render headlessly
 ```
 
-The npm package is at 0.8.0. The 0.9 commands below (`export`, `publish`, `freeze`, `scene`) need a checkout of this repository until 0.9 is published.
+The npm package is at 0.11.0 and includes every command below. 0.11 adds `cascade/image`, `ladder`/`pick`, `run --out`, assertion nodes, `help node` and `doctor`; see the [changelog](CHANGELOG.md).
 
 ## New in 0.9: shareable editors
 
@@ -383,7 +383,6 @@ a second set of node algorithms.
 | 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