@field/cascade 0.8.0 → 0.11.0

package/AGENTS.md

@@ -35,13 +35,23 @@ 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
 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://.
+`cascade export <graph.cascade> (--plan | --out <dir>)` exports the graph's
+`editor` section (published parameters, outputs, presets) as a shareable static
+editor. Read `doc/EDITOR_EXPORT.md` first. The export is an allowlist: live
+sources must be frozen (`cascade freeze`), and `licensed/`, hidden and
+gitignored files are refused. Scenes round-trip through the editor, Studio and
+`cascade run --scene`.
 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.
@@ -71,6 +81,14 @@ curl -fsS http://KURO:3030/health
 curl -fsS http://KURO:3030/api/graph
 ```
 
+For a Studio that should stay up, use `cascade serve` instead of a `screen`:
+`cascade serve start <project> --host KURO --port 3030`, then
+`cascade serve status [project] --json`, `logs`, `restart` and `stop`. It keeps
+one supervisor per project, restarts a crashed Studio, and stops the Python
+worker with it. If the host is unavailable (Tailscale down) Studio binds
+`127.0.0.1` and moves back when the host returns; `status` shows the actual
+binding. Never stop or restart a served Studio you did not start.
+
 Remote access is explicit: a specific non-loopback `--host` is also the default
 trusted browser hostname. Use `--trusted-host` only when the bind address and
 browser hostname differ. Hostnames are exact and case-insensitive; wildcard
@@ -203,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
 
@@ -212,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. Keep the CLI build last because Vite refreshes `dist/`.
+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,407 @@
 
 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
+
+- **The timeline is saved with the graph.** `timeline: { fps, start, end,
+  loop }` in the document: Studio's Timeline opens on it and writes it back,
+  the runtime uses its fps, and `cascade run --frames timeline` renders its
+  range.
+- **`run --frames … --mp4 <file> [--crf N]`** encodes the rendered sequence
+  with ffmpeg as H.264 yuv420p at the run's fps, and reports it as `video` in
+  the `--json` manifest.
+- **Stage cache keys Cascade owns.** Every Python stage call, Studio or
+  headless, is keyed on the stage code (a hash of `exec.stages.sources`), the
+  arguments with input files replaced by their content hash, and the Cascade
+  version, and its cache state (`hit`, `miss`, `off`) and key are reported on
+  every call: in the server log, in `run --json` under `stages`, and in the run
+  trace. `exec.stages.cache` turns on a core result cache that verifies the
+  files a stored result names before serving it.
+- **Run traces.** Every `cascade run` writes `.cascade/runs/<time>-<graph>.json`
+  with each node's time and its stage calls. `run --json` works without
+  `--frames`.
+- **Seeds.** `context.seed` (from the document's `seed` and the node id) and
+  `context.random()` in both hosts; `cascade run --seed N`.
+- **`cascade parity <graph> [--node] [--tolerance] [--json]`** cooks headless
+  twice and through Studio's executor with caches off and reports every node
+  output side by side.
+- **Locks and replay.** `cascade lock <graph> <node> --name <name>` records one
+  render in `locks/<id>.json`: the graph as cooked, every prop and seed, input
+  file hashes, the project's source code (stored by hash in
+  `.cascade/objects/`), versions and git state, and a fingerprint of every
+  output. `cascade replay <id>` rebuilds that code in a throwaway copy of the
+  project and compares fingerprints, without a worktree; `--live` uses the
+  current code instead. `cascade lock verify` replays every lock and
+  `cascade locks` lists them. All take `--json`.
+
+- **`cascade serve`.** `start | stop | restart | status | logs | install |
+  uninstall [project]` runs Studio as a supervised background service: one
+  lock, record and log per project under `~/.cascade/serve/`, restart with
+  backoff after a crash, and a stop that takes the Python worker with it.
+  `status --json` reports port, actual host, pids, uptime, version and worker
+  state. `install` writes and loads a macOS launchd job.
+- **Host fallback.** When `--host` does not resolve (a MagicDNS name while
+  Tailscale is down) or is not on this machine (`EADDRNOTAVAIL`), Studio binds
+  `127.0.0.1` (or `--fallback-host`, repeatable) instead of crashing, and moves
+  back to the preferred host when it returns.
+- **Graph editing from the CLI.** `cascade graph create|read|list`, `node add|rm`, `connect`, `disconnect`, `set` (value, `--expr`, `--key frame=value`, `--unset`), `subnet create|move|dissolve` and `cascade edit` for a batch. Each edit is checked with the same code as `cascade check`, written atomically in the file's own formatting, and leaves a minimal diff: an edit and its inverse leave the file byte-identical. New nodes get stable kebab-case ids and are placed along the graph's flow when wired; wires across a subnet boundary go through named `Input`/`Output` nodes. See `doc/CLI_REFERENCE.md`.
+- **`--json` on every command**: one `{ ok, data, warnings }` envelope on stdout.
+- **`cascade mcp`**: the same operations as MCP tools over stdio (graph read/list, node add/remove, connect, set, subnets, check, cook, render, export; lock and replay once they land). See `doc/MCP.md`.
+- The editing API (`GraphEditor`, `readGraph`, the operation types) is exported from `@field/cascade/runtime`.
+
+### Changed
+
+- `cascade run --frames --json` prints its manifest inside the envelope, as `data`, rather than at the top level.
+
+### Fixed
+
+- **Headless frame renders no longer start Python per stage per frame.**
+  `cascade run` uses the project's warm worker for the whole run, and frames
+  after the first re-cook only what the frame changed (`reuse: "strict"`;
+  `--fresh` cooks everything). cloud-plots' morph, frames 1–60: 588 s to 5 s,
+  byte-identical.
+
+- **An edited stage no longer runs its old code in a live Studio.** The warm
+  Python worker restarts before the next request when its stage sources
+  change, with Python's bytecode cache keyed by the code hash so a quick
+  same-length edit is not served from an old `.pyc`.
+
+- **A failed build keeps the previous `dist/`.** `npm run build` and
+  `build:cli` build into `.dist-staging/` and swap it in only when every step
+  passed; the log names the step that failed.
+
+## 0.9.2 — 2026-10-12
+
+### Added
+
+- **Exported editors work on phones.** The preview is full width at the top,
+  with pinch, pan and double-tap to fit. Controls sit in a bottom sheet with
+  three snap points and folded groups, sized for thumbs (44 px targets, 16 px
+  text, steppers). The header is one row with a ⋯ menu. Safe-area insets and
+  `100dvh` keep everything clear of Safari's toolbar. Exports and scenes use the
+  share sheet, with a download as the fallback. Landscape uses a side panel, and
+  desktop is unchanged.
+- **`editor.peek` and `editor.draft`.** These choose the controls kept in reach
+  at the sheet's lowest point, and the values cooked while a slider is dragged
+  (a lower density, say).
+
+## 0.9.1 — 2026-10-11
+
+### Added
+
+- **Share from the Inspector.** Studio's Inspector has a `share` toggle per
+  parameter that publishes it to the exported editor, with label, group and
+  min/max/step fields.
+
+### Changed
+
+- **The exported editor cooks in a module worker** (`editor-worker.js`), so a
+  slow stage no longer freezes the page while someone drags a slider.
+
+### Fixed
+
+- **A fresh tree builds.** `npm run build` compiles the workspace packages
+  before vite, and no longer leaves `dist/` without a CLI.
+
+## 0.9.0 — 2026-10-11
+
+### Added
+
+- **Shareable editors (0.9.0).** `cascade export <graph> --out <dir>` builds a
+  static editor site from a graph's new `editor` section. It has the published
+  parameters (with a UI generated from their types), presets, scene files, one
+  export button per declared output, and a read-only inspect view of every
+  stage. `--plan` prints the manifest without building, and
+  `--deploy vercel` deploys the site and checks that Vercel Authentication is
+  on.
+
+  The export is an allowlist. It ships the subgraph the outputs need and the
+  selected assets, and nothing else. It refuses Python and dynamic nodes,
+  wired-in live sources, `licensed/`, hidden and gitignored files. It scans the
+  built site for credentials, local paths and backend URLs.
+  `cascade freeze` snapshots chosen fields of a live source, and
+  `cascade publish` marks a prop as a parameter. Scenes (`*.scene.json`) open
+  in the editor, in Studio (File › Open/Save Scene) and in the CLI
+  (`cascade scene`, `cascade run --scene --write`), with versioned,
+  degrade-gracefully matching.
+
+  The runtime gains `run({ reuse: true })`, an early cutoff for hosts that
+  re-run on every edit, and `cascade.core.Frozen`. Node definitions gain
+  `source: "live"`. See `doc/EDITOR_EXPORT.md`.
+
+- **Bundle ports.** A node can export one `bundle` port carrying named fields
+  instead of a dozen loose outputs. A producer declares `fields` (name to type)
+  and an optional `schema`; a consumer declares the `fields` it reads, sees only
+  those, and in Studio re-cooks only when one of them changed (per-field
+  versions on top of early cutoff). Expressions read a wired bundle's fields
+  with `ch("format.dpi")`. `cascade.core.Pick` and `cascade.core.Pack` convert
+  between bundles and single values. `cascade check` reports unknown fields with
+  the nearest declared name, and refuses an absolute read of another node's
+  bundle. Studio draws a bundle as one neutral port whose hover and Inspector
+  list its fields and values. Bundles reach Python stages as dicts. See
+  "Bundle ports" in `doc/PROJECT_AUTHORING.md`.
+
+- **Node previews on the canvas.** A project that sets
+  `settings.nodePreviews: true` in `cascade.json` shows each node's first
+  output as a readable preview card on the graph, refreshed per node cook. The
+  same settings can carry a `workspace` used as the first-open dock layout when
+  the browser has none saved; a layout that fails to load falls back to the
+  built-in one.
+
+- **Groups own their contents.** A group frame keeps an explicit
+  `containedElements` list, separate from subnet parenting. Drag the frame
+  header to move its members (nested contents move once); drop an item's
+  centre inside a frame to add it, outside to remove it, and the smallest
+  enclosing frame wins. The target frame highlights before release, and
+  membership and positions share one undo step. Deleting a frame leaves its
+  contents. View → Clean Up Layout now treats each group as a cluster: it lays
+  out members first, fits the frame, then places the groups.
+
+- **The Agent console keeps a Codex conversation, and panels can hand it a
+  draft.** A Codex console resumes the thread id from `thread.started`, so
+  later prompts continue one conversation per sketch as Claude's do; project
+  `--sandbox` flags are normalised for `exec resume`. Codex item events
+  (assistant messages, commands with their output, file changes) render in the
+  console. Project panels get `api.openAgent(prompt)`, which opens the Agent
+  panel with a draft to review and send, never sending it.
+
+### Changed
+
+- **Dragging a node re-renders only what moved.** Each node reads its position
+  through its own motion store, and the graph is published once when the drag
+  ends rather than copied every frame. At 100 nodes a pointer move costs 1.6 ms
+  of script instead of 8.9 (5.6 ms of task time instead of 13.1).
+
+- **Node drags apply once per frame.** Moving a node or a selection batches
+  pointer moves to one update per animation frame instead of one per event.
+
+- **Identical output stops invalidating the graph below it.** A node that
+  re-cooks and commits the same values (compared structurally; the same
+  object reference counts as changed, since it may be mutated in place) keeps
+  its output version, and a node stale only because of that upstream re-cook
+  is skipped. A node whose own parameters, code or wiring changed always
+  cooks, and `node.earlyCutoff = false` opts a node out. The cook status
+  carries the count as `cutOff`. Python projects get the matching half by
+  keying their stage cache on content; cloud-plots does (see its
+  `runtime/node_cli.py`). There, a no-op edit to `area-filter-mask` now costs
+  2 stage calls and 47 ms instead of 13 calls and 866 ms.
+
+- **What a Viewer shows cooks first.** A pass ran in plain topological order,
+  so a sink nobody was looking at (an export, a plot check, the mockup) could
+  run ahead of the node on screen. Now the selected or pinned node of each open
+  Viewer and everything it depends on cook first, and the rest of the pass runs
+  after, in the same order as before. With no Viewer (the CLI, tests, cook-all)
+  nothing changes. On cloud-plots, a Viewer on `hatch-curves` showed its result
+  after 3.4 s instead of 7.4 s on a cold cook.
+
+- **An edit cancels the stage it supersedes.** Changing a parameter while a
+  long Python stage runs used to wait for that stage, and then for every
+  request queued behind it. Now the superseded cook is aborted: its request is
+  withdrawn from the worker (dropped if queued, interrupted with SIGINT if
+  running, killed if it does not answer), its result is never applied, and the
+  pass restarts from the edit. The cook strip shows how many cooks were
+  superseded. Measured on cloud-plots, an edit during a 12 s stage now lands in
+  0.6 s instead of 10.9 s. Project workers should answer an interrupt with
+  `{"cancelled": true}` to stay warm; see `doc/PROJECT_AUTHORING.md`.
+
+### Fixed
+
+- **Three wire and runtime fixes.** Studio's browser-shell adapter sends
+  execution options (stdin, timeout, cwd, env) at the top level of the
+  `/api/shell` body again; nested under `options` the route dropped them. A
+  Switch node's `index` is a document prop, serializes, and re-routes on cook.
+  Project CLI instances of one module share a single executor build, so one
+  cannot import the `.mjs` while another rewrites it.
+
 ## 0.8.0 — 2026-10-10
 
 ### Added

package/DESIGN.md

@@ -109,6 +109,8 @@ This document contains both current product rules and intended direction. Sectio
 ## Components
 
 - **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.
+- **Canvas previews:** Projects may opt into readable first-output previews on graph nodes with `settings.nodePreviews: true` in `cascade.json`. The canvas reuses `CoreValue` in compact, read-only mode, including project type renderers; the default remains the compact computational graph. A serialized Dockview layout in `settings.workspace` may also suggest the first-open workspace, but a browser's saved layout always wins.
+- **Group-aware cleanup:** View → Clean Up Layout treats each group as a visual cluster. It arranges and measures members first, fits the frame around them, then places clusters in the graph's top-to-bottom flow. Nested groups stay nested, wide source ranks wrap, and standalone notes move to a clear margin. The command changes positions and group sizes only; membership and subnet hierarchy remain authored data.
 - **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
@@ -173,3 +175,15 @@ This table defines the intended presentation contract. Individual rows may be on
 - [ ] 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
+
+## Canvas groups
+
+Groups own explicit `containedElements` independently of subnet parenting. Drag
+a frame header to move its members together. Dropping an item’s centre inside a
+frame adds it; dropping outside removes it; the smallest enclosing frame wins
+when frames overlap. The target frame highlights before release. Moving a frame
+does not collect stationary items it passes over. Nested contents move once.
+Membership and positions persist together and share a gesture’s undo snapshot.
+Deleting a frame leaves its contents alive. Unselected wires are neutral grey;
+selection restores their type colour. Preview cards use one surface with
+controls appearing on hover or selection.

package/README.md

@@ -11,6 +11,7 @@ under the MIT license. [Getting started and features](https://cascade.field.io).
 - 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.
+- Shareable editors: `cascade export` builds a static site where someone else can change published parameters, save scenes and export, without Studio or an account.
 - 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.
@@ -25,31 +26,45 @@ under the MIT license. [Getting started and features](https://cascade.field.io).
 
 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.
+## Quick start
+
+```bash
+npm install -g @field/cascade
+cascade new my-sketch              # scaffolds ~/Documents/Cascade/my-sketch and opens Studio
+cd ~/Documents/Cascade/my-sketch && npm install
+cascade .                          # reopen it later
+cascade run index.cascade --frames 1 --json   # render headlessly
+```
+
+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
+
+`cascade export` turns a graph into a small static website: a viewer, the parameters you chose to publish, presets, scene files and an export button per output. Send the link and someone without Studio can change your scene, save it as a scene file and send it back.
+
+```bash
+cascade publish index.cascade spec.capMm --label "Cap height" --min 3 --max 60 --unit mm
+cascade freeze index.cascade moment --output moment --fields photos[0],instant
+cascade export index.cascade --plan                  # what ships and what stays
+cascade export index.cascade --out export/site
+cascade export index.cascade --out export/site --deploy vercel --project my-editor
+```
+
+In Studio, the `share` toggle beside a parameter in the Inspector publishes it, with a label, group and range. Scenes (`*.scene.json`) open in the editor, in Studio and in the CLI (`cascade scene`, `cascade run --scene`). The editor cooks in a module worker, so a slow stage does not stall the page.
+
+<img src="https://cascade.field.io/img/inspector-share@2x.webp" width="360" alt="The Studio Inspector with share buttons beside each parameter">
+
+The export is an allowlist. It ships the subgraph the outputs need and the assets you name, refuses live sources until you freeze the fields you want, refuses Python, licensed and ignored files, and scans the built site for credentials and local paths. Read [Shareable editors](doc/EDITOR_EXPORT.md) before sharing anything.
+
+**Cloud Type** is the first exported editor: the dotted headline generator for FIELD's Human First book. Try it at [cloud-type.vercel.app](https://cloud-type.vercel.app); the project is at [marcuswendt/cloud-type](https://github.com/marcuswendt/cloud-type).
+
+![Cloud Type, an editor exported from a Cascade graph](https://cascade.field.io/img/cloud-type@2x.webp)
+
+Large graphs stay readable when they open as a few stages with the detail in subnets. The cloud-plots print graph has 98 nodes and opens as seven.
+
+![The cloud-plots graph in Studio, seven stage nodes](https://cascade.field.io/img/graph-stages@2x.webp)
+
+0.9.1 also fixes a fresh checkout's build: `npm run build` compiles the workspace packages before vite, so `dist/` is never left without a CLI. See the [changelog](CHANGELOG.md).
 
 ## Install
 
@@ -368,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
@@ -426,6 +440,7 @@ trusted-host session; an untrusted remote bind does not expose them.
 - [Design source of truth](DESIGN.md)
 - [Architecture](ARCHITECTURE.md)
 - [Browser player](doc/WEB_PLAYER.md)
+- [Shareable editors](doc/EDITOR_EXPORT.md)
 - [September quality review and sketch verification](doc/QUALITY_REVIEW_2026-09.md)
 - [Subnet and shell specification](spec/CASCADE_SUBNET_AND_SHELL_SPEC.md)