@field/cascade 0.8.0 → 0.10.0

package/AGENTS.md

@@ -37,11 +37,19 @@ my-project/
 
 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.
 
+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`.
+
 `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 +79,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
@@ -212,7 +228,7 @@ 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. 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.
 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.
 

package/CHANGELOG.md

@@ -2,6 +2,220 @@
 
 Notable changes to Cascade. Newest first.
 
+## 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.8.0. The 0.9 commands below (`export`, `publish`, `freeze`, `scene`) need a checkout of this repository until 0.9 is published.
+
+## 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
 
@@ -426,6 +441,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)