Cascade

An open-source node-graph runtime with a visual Studio, for building generative design systems that move between print, motion, installations, and the web. Built at FIELD.IO and used for our own work.

Current release: 0.10.0. The npm package is still 0.8.0, so cascade export needs a checkout of the repository until 0.9 is published.

What it is

Cascade separates a visual system from the application around it. You author typed stages as a graph; the runtime validates and schedules them; Studio, the CLI, a browser player, or another host supplies the environment. A project is an ordinary folder of TypeScript, assets, and diffable .cascade files.

Houdini is the conceptual north star: small composable operators, explicit data flow, nested networks, parameters, animation, feedback, and a result that can be cooked again in another context.

What you can build

2D and 3D geometry systems using a shared geometry type, transforms, merging, copying to points, SVG export, scenes, lights, and Houdini-style cameras.
Motion and simulation with expressions, keyframes, a timeline, explicit Feedback loops, particles, forces, bounded checkpoints, and trails that remain printable geometry.
Interactive browser work as a standalone static player, without shipping Studio or running a Cascade server.
Offline stills and sequences through the CLI, using Skia for Canvas2D work or optional Dawn for portable WebGPU nodes.
Project-specific tools as typed TypeScript nodes and trusted Studio panels, including file, Python, media, and allowlisted shell stages where the host permits them.

Before you start

You need Node 22.13 or newer. Check with node --version; if it is older, or missing, install it from nodejs.org or with brew install node.

macOS and Linux are what we run. Studio is a web app; use a current Chromium, Firefox, or Safari release. Individual nodes can have narrower requirements, especially WebGPU work.

Getting started

Install the CLI.

npm install -g @field/cascade

Make a sketch. This creates ~/Documents/Cascade/my-sketch and opens Studio in your browser.

cascade new my-sketch

Install the sketch's own dependencies. Do not skip this.

cd ~/Documents/Cascade/my-sketch
npm install

A global CLI is not enough on its own. Any node that touches files, images, a shell command or a Python stage imports from cascade/…, and that resolves from the sketch's own node_modules. Without this step those nodes fail at run time with Cannot find package 'cascade', while simpler graphs keep working — which makes it a confusing thing to debug later.

Reopen it any time, from the sketch folder or by name.

cascade .
cascade my-sketch

Working in Studio

Studio is dockable: a graph canvas, an inspector, a viewer, a code editor, logs, and panels a project defines itself. Tab adds a node, and the graph is a plain .cascade file you can commit and diff.

A sketch owns its own nodes as ordinary TypeScript under nodes/<Name>/index.ts, so anything you can write in a file you can wire into a graph. Read the AGENTS.md in your new sketch first — it is short, and written for both you and whatever coding agent you point at the folder.

Keep a graph readable by giving it a few top-level stages and putting the detail in subnets. The cloud-plots print graph has ninety-odd nodes and opens as seven stages, from the moment and the paper format through to marks, type and output.

The cloud-plots graph in Studio: seven stage nodes in a diagonal line, each with a short note — The cloud-plots graph at the top level.

Inside the drawing stage: input and output nodes and four groups of nodes for grain layers, hatches, daylight dots and stipple — The drawing stage opened. Groups keep its four drawing modes apart.

Subnets let a network become a reusable operator without changing the document into a second graph format. The 3D Viewer displays geometry, cameras, and scenes as wireframes and points; light data is part of the scene contract, while shaded scene rendering is still future work.

Animation and simulation

Parameters can use values, expressions, or keyframe channels. Expressions include $F, $T, $FPS, ch(), noise, fitting, and familiar maths functions. Keyframes are edited in the Inspector and Timeline, with constant, linear, or smooth interpolation.

Feedback is explicit graph state. Particle nodes accumulate forces and integrate them once; trails are normal geometry, so the same simulation can feed a viewport, an SVG export, or an offline render. Checkpoints accelerate repeated work, but do not change the result.

Publish to the web

A compatible definition-v1 graph can become a self-contained static site. The output directory must be new; add repeatable --asset <project-relative-file> options for asset paths computed in node code.

cascade build index.cascade --out web-player

Serve the generated directory over HTTP or HTTPS. Open its index.html, embed player.html directly, or use the same-origin embed.js API for play, pause, seek, parameter changes, output selection, and downloads.

<iframe src="/artwork/player.html"
  title="Generative artwork"
  style="width:100%;height:600px;border:0"></iframe>

Each embed owns its graph runtime, assets, generated images, and GPU lifecycle, so multiple sketches can coexist safely on one page. Compatible geometry and scenes render in the player. Browser WebGPU nodes use the visitor's device and require WebGPU support plus a secure HTTPS or localhost context; unsupported devices fail with a diagnostic.

The static player supports deterministic definition-v1 graphs. Dynamic modules and nodes requiring Python, shell, server files, or Studio APIs are rejected during the build. Package any explicit assets and move heavy preprocessing outside the live browser graph.

Share an editor

New in 0.9. cascade export turns a graph into a small static site with a viewer, the parameters you chose to publish, presets, scene files and export buttons. Someone without Studio can change your scene, save it and send it back.

cascade publish index.cascade spec.capMm --label "Cap height" --min 3 --max 60 --unit mm
cascade export index.cascade --plan
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. Scenes are *.scene.json files that open in the editor, in Studio and in the CLI with cascade scene. The editor cooks in a worker, so a slow stage does not stall the page while someone drags a slider. It also works on a phone, with the controls in a bottom sheet.

The Studio Inspector for a node, with share buttons beside each parameter and label, group and range fields under the shared ones — Shared parameters in the Inspector, with their label, group and range.

The export is an allowlist. Only the nodes your outputs need and the assets you name are shipped. Live sources such as files, Python or a network service are refused until you freeze the fields you want with cascade freeze, and the built site is scanned for credentials and local paths. --plan shows what goes and what stays.

For Cloud Type, the plan starts like this:

$ cascade export cloud-type.cascade --plan
Editor Cloud Type (cloud-type, h4704ea9ff9b4d898) from cloud-type.cascade

Nodes shipped (26):
  spec  project.spec  props: capMm, density, pitchMm, seed, penMm, quality
  source  cascade.core.Subnet
  stipple  project.stipple  props: order
  ...

Not shipped (0): none

Published parameters (78):
  seed → spec.seed
  text → type-set.text
  ...

Outputs:
  png → png.image (png)
  plot-svg → plot-svg.svg (svg)
  preview-svg → preview-svg.svg (svg)

Files:
  assets/assets/fonts/InterDisplay-Medium.otf  609 KB  asset  from assets/fonts/InterDisplay-Medium.otf
  assets/assets/fonts/Inter-OFL-LICENSE.txt  4 KB  asset  from assets/fonts/Inter-OFL-LICENSE.txt

Cloud Type

The first exported editor. It makes the dotted headlines for the Human First book, and "Inspect stages" shows every step of the graph behind it.

Cloud Type with Inspect stages on: a grid of cards, one per stage, showing each stage output from the spec values to the dotted lettering — Inspect stages shows what each stage of the graph produced.

Headless rendering for agents

The CLI can produce a still or numbered image sequence without opening Studio. Its JSON mode gives an agent or test process a small machine-readable contract: output files, frames, timing, and GPU adapter metadata when used.

cascade run index.cascade --frames 1 --json --timeout 60000
cascade run index.cascade --frames 1-48 --fps 24 --out renders --json --timeout 120000

Portable WebGPU nodes run through optional Dawn on supported machines. Dawn loads only when a GPU node cooks; CPU projects do not require it. It is a native GPU host, not a browser emulator, and does not provide DOM, video, WebGL, or browser-only APIs. Agent callers should bound frame counts and dimensions, set a timeout, check the exit code, and retain the graph, code, assets, seed, and settings with selected outputs.

Useful commands

cascade new <name>            create a sketch and open it
cascade .                     open the sketch in this folder
cascade node <Name>           scaffold a typed custom node
cascade run <graph.cascade>   execute a graph headlessly, no browser
cascade run <graph> --frames 1-48 --fps 24
cascade build <graph> --out <new-directory>
cascade export <graph> --plan   what a shared editor would ship
cascade export <graph> --out <dir>
cascade publish <graph> <node.prop>  share a parameter
cascade freeze <graph> <node>  snapshot a live source
cascade scene <file.scene.json>
cascade check <graph.cascade>  static check of types and structure
cascade inspect <graph.cascade> print a JSON graph summary
cascade projects <dir>        move where sketches live
cascade --help                all of it

A few things worth knowing

Some sketches need more than Node. A project may use Python, native image libraries, external tools, or optional Dawn; check its README and package.json before assuming it is broken.
Studio serves on localhost by default. --host exposes it on your network for a browser on another machine, and that is for a trusted network only. Never put Studio on the public internet; it compiles and runs code from the project folder by design.
A static player is the public deployment surface. It includes only compatible graph code and declared assets, and needs no Cascade API.
GPU output can vary across hardware and drivers. Record adapter information and use image tolerances rather than assuming identical pixels everywhere.
A project declares the credential names it needs, never their values. Values default to ~/.cascade/credentials.yaml, or to the file selected by CASCADE_CREDENTIALS, and are never stored in a graph.

Versions

Notable changes, newest first. Every release, in full, is in the changelog and on GitHub releases.

0.10.0 12 Oct 2026

The timeline is saved with the graph.
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.
Run traces. Every cascade run writes .cascade/runs/<time>-<graph>.json with each node's time and its stage calls.

0.9.2 12 Oct 2026

Exported editors work on phones.
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 11 Oct 2026

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.
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.

0.9.0 11 Oct 2026

Shareable editors. cascade export <graph> --out <dir> builds a static editor site from a graph's new editor section.
Bundle ports. A node can export one bundle port carrying named fields instead of a dozen loose outputs.
Node previews on the canvas.
Groups own their contents. A group frame keeps an explicit containedElements list, separate from subnet parenting.

0.8.0 10 Oct 2026

Number fields scrub. Middle-drag any numeric field (vector components, ints, a scalar's number box, colour channels) to drag its value, Houdini style.
Drag a node onto a Viewer to pin it there.
The graph stays calm until you select.
Dragging a parameter's name into the agent console is now Option-drag, because a plain drag on the name scrubs.

0.7.1 12 Sept 2026

File › Open lists the graphs on the machine running the server.
cascade run --node <id> renders only the outputs you name.

0.7.0 12 Sept 2026

One execution path. cascade run no longer falls back to a second, dynamic executor.
A files capability for the CLI, so headless runs can read and write project files.
A stage's log output now reaches whoever is running it.
cascade.geo.FromRects turns rectangles into geometry.

0.6.0 10 Sept 2026

cascade.math.*: arithmetic as nodes.
Connections can be made backwards.

0.5.2 10 Sept 2026

The load warm-up no longer reports false errors.

0.5.1 9 Sept 2026

Ready for npm, with the README and this site rewritten for the browser player.

0.5.0 9 Sept 2026

The browser player. cascade build exports a graph as a static page with an iframe embed, no Studio server needed.
Each embed runs on its own, so several sketches can share a page.
Particle simulations render the same warm or cold, and nested Feedback loops run in the right order.

0.4.0 9 Sept 2026

A camera node that works like Houdini's, and scenes with lights.
Series: one graph cooked once per parameter set.
Headless WebGPU through Dawn, for renders without a browser.
Studio can call allowlisted shell commands.

0.3.1

A gpu capability, stage one of WebGPU support.
A stored value equal to its default is no longer dropped on save.
A browser-only node is refused on the run path again.
cascade run reports stranded params values.

0.3.0

Animation: a timeline with a dope sheet, keyframes and expressions on any parameter.
Offline rendering. cascade run --frames 1-100 writes an image sequence.
A coding agent per sketch, working in the project folder.

Going deeper

Project authoring — project layout, graph files, and typed nodes.
Shareable editors: publishing parameters, the export boundary, scenes and deploying.
Browser player — embedding, controls, assets, and host limits.
Headless WebGPU — Dawn setup, JSON render manifests, testing, and platform caveats.
Node reference — the generated reference for core, geometry, particle, and scene nodes.
Architecture — contracts, runtime, hosts, and dependency boundaries.