@field/cascade 0.3.1 → 0.4.0

package/dist/cli/index.js

@@ -21,6 +21,26 @@ var init_animation = __esm({
   }
 });
 
+// packages/contracts/src/camera.ts
+var CAMERA_DEFAULTS;
+var init_camera = __esm({
+  "packages/contracts/src/camera.ts"() {
+    "use strict";
+    CAMERA_DEFAULTS = Object.freeze({
+      translate: [0, 0, 0],
+      rotate: [0, 0, 0],
+      focal: 50,
+      aperture: 41.4214,
+      near: 1e-3,
+      far: 1e4,
+      resolution: [1280, 720],
+      aspect: 1,
+      projection: "perspective",
+      orthowidth: 2
+    });
+  }
+});
+
 // packages/contracts/src/capabilities.ts
 var init_capabilities = __esm({
   "packages/contracts/src/capabilities.ts"() {
@@ -540,6 +560,13 @@ var init_geometry = __esm({
   }
 });
 
+// packages/contracts/src/series.ts
+var init_series = __esm({
+  "packages/contracts/src/series.ts"() {
+    "use strict";
+  }
+});
+
 // packages/contracts/src/values.ts
 function normalizeCascadeType(type) {
   if (!type) return "any";
@@ -577,6 +604,7 @@ var init_values = __esm({
       "mesh",
       "rects",
       "color",
+      "camera",
       "asset",
       "array",
       "object",
@@ -670,17 +698,17 @@ function validateNodeDefinition(value) {
       "capabilities"
     );
   const seen = /* @__PURE__ */ new Set();
-  for (const [index, capability] of (Array.isArray(value.capabilities) ? value.capabilities : []).entries()) {
+  for (const [index, capability2] of (Array.isArray(value.capabilities) ? value.capabilities : []).entries()) {
     const path23 = `capabilities.${index}`;
-    if (!seen.has(capability) && !allowed.includes(capability))
+    if (!seen.has(capability2) && !allowed.includes(capability2))
       add(
         "capability-not-allowed",
-        `${String(capability)} is not available on ${String(environment)}`,
+        `${String(capability2)} is not available on ${String(environment)}`,
         path23
       );
-    if (seen.has(capability))
-      add("duplicate-capability", `${String(capability)} is duplicated`, path23);
-    seen.add(capability);
+    if (seen.has(capability2))
+      add("duplicate-capability", `${String(capability2)} is duplicated`, path23);
+    seen.add(capability2);
   }
   const inward = /* @__PURE__ */ new Map();
   const outward = /* @__PURE__ */ new Map();
@@ -743,6 +771,29 @@ function validateNodeDefinition(value) {
           "options require the select control",
           `${path23}.options`
         );
+      if (Array.isArray(raw.options))
+        for (const [index, option] of raw.options.entries()) {
+          if (option === null || typeof option !== "object") continue;
+          const entry = option;
+          if (!("value" in entry))
+            add(
+              "invalid-option",
+              "a labelled option needs a value",
+              `${path23}.options[${index}]`
+            );
+          if (typeof entry.label !== "string" || !entry.label)
+            add(
+              "invalid-option",
+              "a labelled option needs a non-empty label",
+              `${path23}.options[${index}].label`
+            );
+          if ("disabled" in entry && typeof entry.disabled !== "boolean")
+            add(
+              "invalid-option",
+              "disabled must be a boolean",
+              `${path23}.options[${index}].disabled`
+            );
+        }
       const type = raw.type;
       if (!validType(type)) {
         add(
@@ -814,9 +865,9 @@ var init_validate = __esm({
     CORE = new Set(CORE_TYPES);
     CONTROLS = /* @__PURE__ */ new Set(["number", "slider", "range", "int", "boolean", "text", "textarea", "select", "vector", "matrix", "color", "image", "asset"]);
     CAPABILITIES_BY_ENVIRONMENT = {
-      portable: ["assets", "media"],
+      portable: ["assets", "media", "gpu"],
       browser: ["assets", "media", "gpu"],
-      server: ["files", "assets", "media", "python", "shell"]
+      server: ["files", "assets", "media", "python", "shell", "gpu"]
     };
     ALLOWED = CAPABILITIES_BY_ENVIRONMENT;
     fields = (names) => new Set(names.split(" "));
@@ -828,7 +879,7 @@ var init_validate = __esm({
     );
     OUTPUT_FIELDS = fields("kind type description");
     PROP_FIELDS = fields(
-      "type default label description min max step accept control options expression"
+      "type default label description min max step accept control options expression action"
     );
   }
 });
@@ -838,11 +889,13 @@ var init_src = __esm({
   "packages/contracts/src/index.ts"() {
     "use strict";
     init_animation();
+    init_camera();
     init_capabilities();
     init_color();
     init_definition();
     init_document();
     init_geometry();
+    init_series();
     init_validate();
     init_values();
   }
@@ -2886,7 +2939,7 @@ var init_panels = __esm({
 });
 
 // server/src/pythonWorker.ts
-import { spawn as spawn2 } from "child_process";
+import { spawn as spawn3 } from "child_process";
 import readline from "readline";
 var REQUEST_TIMEOUT_MS, PythonWorker;
 var init_pythonWorker = __esm({
@@ -2906,7 +2959,7 @@ var init_pythonWorker = __esm({
       ensureStarted() {
         if (this.proc && !this.proc.killed) return this.proc;
         const scriptPath = this.project.resolve(this.entrypoint);
-        const proc = spawn2(this.python, [scriptPath], { cwd: this.project.root, env: this.env });
+        const proc = spawn3(this.python, [scriptPath], { cwd: this.project.root, env: this.env });
         readline.createInterface({ input: proc.stdout }).on("line", (line2) => this.handleLine(line2));
         proc.stderr.on("data", (chunk) => console.error("[python-worker]", chunk.toString().trimEnd()));
         proc.on("exit", (code) => {
@@ -3001,8 +3054,8 @@ function createProjectRequestBoundary(options) {
 function createBrowserCapabilityBoundary(options, label, header) {
   const origins = new Set(options.trustedOrigins.map((origin) => validateOrigin(origin, label)));
   const authorities = allowedAuthorities(options, origins);
-  const capability = randomBytes(32).toString("base64url");
-  const expectedBytes = Buffer.from(capability);
+  const capability2 = randomBytes(32).toString("base64url");
+  const expectedBytes = Buffer.from(capability2);
   return {
     guardOrigin(req, res, next) {
       const origin = req.get("Origin");
@@ -3022,7 +3075,7 @@ function createBrowserCapabilityBoundary(options, label, header) {
     issueCapability(_req, res) {
       res.setHeader("Cache-Control", "no-store, private");
       res.setHeader("Pragma", "no-cache");
-      res.json({ capability });
+      res.json({ capability: capability2 });
     },
     requireCapability(req, res, next) {
       const supplied = req.get(header);
@@ -3040,12 +3093,36 @@ function allowedAuthorities(options, origins) {
   if (isLoopbackHost(options.host)) {
     authorities.add(`127.0.0.1:${options.port}`);
     authorities.add(`localhost:${options.port}`);
-  } else if (options.trustedHosts.length === 0) {
+  } else if (!isWildcardHost(options.host)) {
     authorities.add(authority(options.host, options.port));
   }
-  for (const host of options.trustedHosts) authorities.add(authority(host, options.port));
+  for (const host of options.trustedHosts) {
+    const value = trustedAuthority(host, options.port);
+    authorities.add(value);
+    const bare = value.replace(/:(?:80|443)$/, "");
+    if (bare !== value) authorities.add(bare);
+  }
   return authorities;
 }
+function isWildcardHost(host) {
+  const normalized = host.trim().toLowerCase().replace(/^\[|\]$/g, "");
+  return normalized === "0.0.0.0" || normalized === "::" || normalized === "*";
+}
+function trustedAuthority(value, defaultPort) {
+  const trimmed = value.trim().toLowerCase();
+  const bracketed = /^\[([^\]]+)\]:(\d+)$/.exec(trimmed);
+  if (bracketed) return authority(`[${bracketed[1]}]`, checkedPort(bracketed[2]));
+  const hostAndPort = /^([^:]+):(\d+)$/.exec(trimmed);
+  if (hostAndPort) return authority(hostAndPort[1], checkedPort(hostAndPort[2]));
+  return authority(trimmed, defaultPort);
+}
+function checkedPort(raw) {
+  const port = Number(raw);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(`Invalid trusted host port: ${raw}`);
+  }
+  return port;
+}
 function authority(host, port) {
   const normalized = host.trim().toLowerCase().replace(/^\[|\]$/g, "");
   if (!normalized || /[\s/?#@]/.test(normalized)) throw new Error(`Invalid trusted host: ${host}`);
@@ -3403,7 +3480,7 @@ var init_allowlist = __esm({
 });
 
 // server/src/agent/session.ts
-import { spawn as spawn3 } from "node:child_process";
+import { spawn as spawn4 } from "node:child_process";
 function childEnvironment() {
   const env = { ...process.env };
   for (const key2 of Object.keys(env)) {
@@ -3633,7 +3710,7 @@ var init_session = __esm({
         const resumed = Boolean(state.sessionId);
         const args = argsFor(request.agent, request.prompt, state.sessionId, agentExtraArgs(this.project.root, request.agent));
         run.emit({ type: "started", agent: request.agent, sketch: request.sketch, resumed });
-        const child = spawn3(executable, args, {
+        const child = spawn4(executable, args, {
           cwd: this.project.root,
           env: childEnvironment(),
           shell: false,
@@ -4297,7 +4374,27 @@ function startServer(project, opts = {}) {
   const trustedHosts = Object.freeze([...opts.trustedHosts ?? []]);
   const defaultOrigins = [
     ...isLoopbackHost(HOST) ? [`http://127.0.0.1:${PORT}`, `http://localhost:${PORT}`] : [],
-    ...trustedHosts.map((host) => `http://${authority(host, PORT)}`)
+    // Both schemes for a trusted host, because the server cannot know whether
+    // something is terminating TLS in front of it.
+    //
+    // This was `http://` only, and behind a TLS proxy a browser sends
+    // `Origin: https://name:port` — so the Host check passed and the **Origin
+    // check refused it**, which 403s every POST and PUT while GETs without an
+    // Origin header sail through. That is a Studio that loads, renders and
+    // then silently cannot save. Measured before fixing: `httpsOrigin: 403`,
+    // `httpOrigin: 200` on the same server.
+    //
+    // Not a widening: the Host allowlist already decides which authorities are
+    // acceptable, and this only says the same authority may arrive over either
+    // scheme.
+    ...trustedHosts.flatMap((host) => {
+      const value = trustedAuthority(host, PORT);
+      const bare = value.replace(/:(?:80|443)$/, "");
+      return [.../* @__PURE__ */ new Set([value, bare])].flatMap((authority3) => [
+        `http://${authority3}`,
+        `https://${authority3}`
+      ]);
+    })
   ];
   const security = Object.freeze({
     host: HOST,
@@ -4356,7 +4453,7 @@ function startServer(project, opts = {}) {
   server.listen(PORT, HOST, () => {
     console.log(`\u{1F680} Cascade running on http://${HOST}:${PORT}`);
     console.log(`\u{1F4C1} Project: ${project.root}${project.isGitRepo ? " (git)" : " (not a git repo yet)"}`);
-    if (trustedHosts.length > 0) console.log(`\u{1F510} Trusted Studio URL: http://${authority(trustedHosts[0], PORT)} (all reachable VPN/interface peers are trusted)`);
+    if (trustedHosts.length > 0) console.log(`\u{1F510} Trusted Studio URL: http://${trustedAuthority(trustedHosts[0], PORT)} (all reachable VPN/interface peers are trusted)`);
   });
   return server;
 }
@@ -4455,10 +4552,11 @@ Read \`node_modules/cascade/AGENTS.md\` for the framework itself. What follows i
 
 ## Read this first
 
-\`node_modules/cascade/doc/NODE_REFERENCE.md\` \u2014 every built-in node with its inputs, props and outputs, generated from the definitions themselves. Under 2,500 tokens for the whole catalogue. **Read it instead of searching the codebase for what a node does**, and note before you start that anything time-based is an expression rather than a node.
+\`node_modules/cascade/doc/NODE_REFERENCE.md\` \u2014 every built-in node with its inputs, props and outputs, generated from the definitions themselves. Read it before creating a wrapper for an existing node. Time-based parameter changes usually need an expression or channel.
 
 ## Common commands
 
+- Run \`npm install\` in this directory first. Scripts use the project's installed Cascade version; use \`npx --no-install cascade\` for direct local CLI commands.
 - \`npm run check\` \u2014 type-check custom nodes.
 - \`npm run check:graph\` \u2014 statically check the graph and node definitions.
 - \`npm run validate\` \u2014 validate \`index.cascade\`.
@@ -4471,7 +4569,7 @@ both the explicit bind address and the exact trusted browser hostname.
 
 ## The \`.cascade\` document format
 
-Hand-editing this file is normal and expected. The shape is not what you would guess, and getting it wrong fails **silently** \u2014 the graph loads, reports its nodes, says it executed, and does nothing.
+Hand-editing is supported. Preserve metadata, source fields, IDs, and valid connection endpoints, then run the static checks. This example uses the node below; save it at \`nodes/Multiply/index.ts\` before running the graph.
 
 \`\`\`json
 {
@@ -4479,28 +4577,25 @@ Hand-editing this file is normal and expected. The shape is not what you would g
   "metadata": { "name": "My Sketch" },
   "nodes": [
     {
-      "id": "logo-1024",
-      "module": "project.field-io-gradient-logo",
+      "id": "multiply",
+      "module": "project.Multiply",
       "position": [240, 200],
       "source": "project",
-      "params": [{ "name": "size", "value": 1024 }],
-      "props": { "angle": { "value": 0, "expression": "$T * 40" } }
+      "props": { "factor": { "value": 2, "expression": "2 + sin($T)" } }
     }
   ],
-  "connections": [
-    [["oscillator", 0, "value"], ["logo-1024", 0, "angle"]]
-  ],
+  "connections": [],
   "annotations": []
 }
 \`\`\`
 
 Five things that are easy to get wrong:
 
-- **\`module\`, not \`type\`.** And \`"source": "project"\` is required for a project module \u2014 without it the engine never loads the module at all, and nothing complains.
+- **Use \`module\` for the module identity and \`"source": "project"\` for project modules.** Unresolved modules need investigation even when validation only warns.
 - **\`position\` is \`[x, y]\`**, an array, not \`{x, y}\`.
-- **\`params\` is an array** of \`{name, value}\`, not an object.
+- **Definition-v1 stored parameter values belong under \`props\`.** A leftover \`params\` array is not read by the deterministic runtime; \`runtime/stray-params\` warns about stranded values.
 - **A connection is a pair of triples**: \`[[fromNode, portIndex, portName], [toNode, portIndex, portName]]\`. Direction comes from *position in the pair* \u2014 first is the source. The middle number is the **port index**, not a direction.
-- **An expression lives under \`props\`** as \`{ value, expression }\`. \`params\` holds plain values.
+- **A prop is a bare value or \`{ value, expression?, channel? }\`.** Channels take precedence over expressions, then stored values. Save the binding, not just its value at the playhead.
 
 ## Before writing a node, check whether you need one
 
@@ -4529,25 +4624,22 @@ import type { NodeDefinition, NodeExecutionContext } from 'cascade/contracts';
 
 export const definition = {
   apiVersion: 1,
-  label: 'Grain',
+  label: 'Multiply',
   icon: 'Circle',                    // a Lucide icon name
   runsOn: 'portable',                // 'portable' | 'browser' | 'server'
   inputs: {
-    value: { kind: 'data', type: 'float', default: 0 },
+    value: { kind: 'data', type: 'float', default: 3 },
   },
   outputs: {
-    image: { kind: 'data', type: 'image' },
+    result: { kind: 'data', type: 'float' },
   },
   props: {
-    size: { type: 'int', default: 1024, min: 16, max: 4096, step: 16 },
+    factor: { type: 'float', default: 2, min: 0, max: 10, step: 0.1 },
   },
 } as const satisfies NodeDefinition;
 
 export function execute(context: NodeExecutionContext<typeof definition>) {
-  const { value } = context.inputs;
-  const { size } = context.props;
-  // ... work ...
-  context.outputs.image.set({ path, size: [size, size], channels: 'rgb', depth: 'u8', space: 'srgb' });
+  context.outputs.result.set(context.inputs.value * context.props.factor);
 }
 \`\`\`
 
@@ -4555,7 +4647,7 @@ The declaration is the point: ports, types, props and the execution locus are re
 
 ### Use the vector types
 
-Anything with an x and a y is **one** \`vec2\`, not two floats. Same for \`vec3\` and \`vec4\`, with \`vec2i\`, \`vec3i\` and \`vec4i\` for integer counts and pixel sizes. A position, an offset, a size, a scale, a colour with alpha, a resolution \u2014 all single vector ports.
+Anything with an x and a y is **one** \`vec2\`, not two floats. Same for \`vec3\` and \`vec4\`, with \`vec2i\`, \`vec3i\` and \`vec4i\` for integer counts and pixel sizes. Positions, offsets, scales, and resolutions use vector ports; colours use the core \`color\` type.
 
 \`\`\`ts
 // Wrong
@@ -4567,22 +4659,26 @@ props: { offset: { type: 'vec2', default: [0, 0] } }
 
 Not a style preference. Two floats that are really one vector cannot be connected to a \`vec2\` output, get two rows in the Inspector instead of one control, need two keyframes to animate one movement, and let a graph carry an x without its y. The type system knows what a \`vec2\` is; it cannot know that \`offset_x\` and \`offset_y\` belong together.
 
-Split them only when the components genuinely differ in kind or in range \u2014 a \`width\` and a \`depth\` that are separately meaningful are two props, not a \`vec2\`.
+Split only when the components differ in kind. Vector props support \`min\`, \`max\`, and \`step\`, with one range across their components.
+
+Studio and a compatible CLI host cook this style. **Studio** builds ports from the compiled definition and calls \`execute\` with a real \`NodeExecutionContext\`; **\`cascade run\`** uses the deterministic runtime when the node's execution locus and capabilities are supported. A browser-only declaration still prevents a Node-host run.
 
-Both hosts cook this style. **Studio** builds the node's ports from the literal and calls \`execute\` with a real \`NodeExecutionContext\`; **\`cascade run\`** runs it through the deterministic runtime. Studio reads the definition from the compiled module, so a definition edit shows up on the next save like any other change.
+The **dynamic** style \u2014 \`execute(node, graph)\` declaring ports with \`node.in\`, \`node.param\`, and \`node.out\` \u2014 remains supported by Studio and the CLI compatibility engine. It cannot provide the same static checks. Studio may mix both styles; the CLI rejects mixed graphs. Convert deliberately with saved-value and output comparisons.
 
-The older **dynamic** style \u2014 \`export async function execute(node, graph)\` declaring its ports imperatively inside itself with \`node.in\`, \`node.param\` and \`node.out\` \u2014 still cooks in Studio and under \`cascade run\`, so an existing node keeps working. It is not the style to write something new in: nothing can read what a dynamic node takes or returns until it has cooked, so \`cascade check\` cannot check it and the Definition panel has nothing to show. If you are editing one heavily, convert it.
+Definition-v1 props support default \`expression\` values. An explicitly saved value overrides that default, even when equal to the numeric default. Both fully definition-v1 and supported dynamic graphs can render sequences with \`cascade run index.cascade --frames 1-100\`, subject to host capabilities.
 
 Either way the module is a real ES module and the loader needs the \`execute\` export. Top-level side effects do not belong in it.
 
 ## Rendering
 
-**Web technology first** \u2014 Canvas 2D, WebGL, WebGPU \u2014 per \`DESIGN.md\` in the Cascade repo. Reach for a Python stage only for work that genuinely cannot run in a browser, such as an exotic ML library. A Python stage costs a process spawn and a round trip per cook, which is invisible on one still frame and fatal to dragging a parameter.
+Prefer Canvas 2D, WebGL, and WebGPU for interactive rendering. Use Python or another server stage for libraries and tools that require it. Transport, serialization, and cold starts can affect parameter-drag latency; persistent workers can avoid repeated process/model startup.
 
-An \`OffscreenCanvas\` plus \`saveImage(canvas, cachePath(node.id, '.png'))\` is the normal portable shape; the headless host supplies the Canvas APIs needed by \`cascade run\`.
+Definition-v1 image nodes can use \`saveImage(canvas, cachePath(context.nodeId, '.png'))\` from \`cascade/io\`. The instance ID provides a cache namespace, not graph access. Final artefacts may instead use an explicit filename. Optional Skia supplies Canvas2D APIs; optional Dawn separately supplies WebGPU. Neither overrides a browser-only declaration or supplies the DOM.
 
 Use \`browser\` only for code that genuinely needs the page, such as the DOM or WebGL. Prefer \`new OffscreenCanvas(width, height)\` to \`document.createElement('canvas')\` when both hosts can run the same node.
 
+WebGPU nodes declare \`capabilities: ['gpu']\` and use \`context.capabilities.gpu\` for the shared device and per-node cache. Portable GPU nodes run in Studio or the optional Dawn CLI host. Import usage constants and explicit RGBA8 \`readTexture\` from \`cascade/gpu\`, then encode through the image/IO host. Graph texture exchange remains future work. For agent image feedback use \`cascade run index.cascade --frames 1 --json --timeout 60000\`; see \`node_modules/cascade/doc/HEADLESS_GPU.md\` for limitations.
+
 ## Finding out what exists
 
 - \`node_modules/cascade/doc/PROJECT_AUTHORING.md\` \u2014 project layout and the node contract.
@@ -4591,11 +4687,11 @@ Use \`browser\` only for code that genuinely needs the page, such as the DOM or
 - \`node_modules/cascade/dist/runtime/builtins/\` \u2014 the built-in node definitions, as the shipped type declarations. (\`packages/\` is not in the published \`files\` list, so an installed copy has no source tree.)
 - The **Definition panel** in Studio shows, for any selected node, where it is defined and what it declares.
 
-## Two things that will waste your time
+## Verification and shared development
 
-**Never run \`npm run build\` in the Cascade repo.** It empties \`dist/\`, and the Studio servers serve from there.
+Cascade's build refreshes \`dist/\`, which running Studio servers may serve. Coordinate a core rebuild with anyone using that checkout; routine sketch edits do not require rebuilding Cascade.
 
-**Check your work by running the graph**, not by reading it: \`npm run check:graph\` for a static check, \`npm run run\` for a headless cook. A silently-wrong document is the failure mode here, so a green read proves nothing.
+Use \`npm run check:graph\` for static checks and \`npm run run\` for a compatible headless graph. A browser-only node may pass static checks with an environment warning and still be refused by the CLI; verify it in Studio instead. Compare actual outputs after edits and distinguish recorded measurements from tests run in the current session.
 `);
   return directory;
 }
@@ -4669,7 +4765,7 @@ function parseStudioArgs(args) {
       if (!value || value.startsWith("--")) throw new Error(`${name} requires a value`);
       if (name === "--host") host = value;
       else if (name === "--trusted-host") {
-        authority(value, 1);
+        trustedAuthority(value, 1);
         trustedHosts.push(value);
       } else {
         port = Number(value);
@@ -4682,8 +4778,8 @@ function parseStudioArgs(args) {
     if (argument.startsWith("-")) throw new Error(`unknown option: ${argument}`);
     positional.push(argument);
   }
-  if (trustedHosts.length > 0 && (!host || isLoopbackHost(host))) {
-    throw new Error("--trusted-host requires an explicit non-loopback --host bind address");
+  if (trustedHosts.length > 0 && !host) {
+    throw new Error("--trusted-host requires an explicit --host bind address, loopback or otherwise");
   }
   if (host && !isLoopbackHost(host)) {
     if (host === "0.0.0.0" || host === "::" || host === "[::]") {
@@ -4735,7 +4831,7 @@ async function runStudioCli(args) {
     const address = server.address();
     const port2 = typeof address === "object" && address ? address.port : 3030;
     const browserHost = trustedHosts[0] ?? (host && !isLoopbackHost(host) ? host : "localhost");
-    const url = `http://${authority(browserHost, port2)}`;
+    const url = `http://${trustedAuthority(browserHost, port2)}`;
     if (!noOpen) {
       const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
       execFile5(opener, [url], (error) => {
@@ -5639,6 +5735,34 @@ function split(path23) {
   return String(path23 ?? "").split("/").filter((segment) => segment.length > 0 && segment !== ".");
 }
 
+// src/utils/thrownError.ts
+function asError(thrown) {
+  if (thrown instanceof Error) return thrown;
+  const described = describeThrown(thrown);
+  const error = new Error(described);
+  error.cause = thrown;
+  return error;
+}
+function describeThrown(thrown) {
+  if (thrown === null) return "null was thrown";
+  if (thrown === void 0) return "undefined was thrown";
+  if (typeof thrown === "string") return thrown || "an empty string was thrown";
+  if (typeof thrown !== "object") return `${String(thrown)} was thrown`;
+  const value = thrown;
+  const kind = typeof value.name === "string" && value.name ? value.name : value.constructor?.name || "object";
+  const parts = [];
+  if (typeof value.message === "string" && value.message) parts.push(value.message);
+  if (typeof value.reason === "string" && value.reason) parts.push(`reason: ${value.reason}`);
+  if (!parts.length) {
+    try {
+      const json6 = JSON.stringify(thrown);
+      if (json6 && json6 !== "{}") parts.push(json6);
+    } catch {
+    }
+  }
+  return parts.length ? `${kind}: ${parts.join(", ")}` : `${kind} was thrown with no message`;
+}
+
 // src/nodes/Node.ts
 function inferParamType(value) {
   if (typeof value === "number") return Number.isInteger(value) ? "int" : "float";
@@ -5745,9 +5869,38 @@ var Node = class _Node {
     // Execution state
     this.hasExecuted = false;
     this.lastInputHash = "";
+    /** The inputs an execute threw on, or null if the last cook did not throw.
+     *  Read only by `isDirty` — see the comment there for why it exists. */
+    this.failedInputHash = null;
     this.cookState = "stale";
     this.cookGeneration = 0;
-    this.stagedOutputs = null;
+    /**
+     * Output values staged by the cook currently running, one map per cook.
+     *
+     * A stack rather than a field, because it was a field and that was a race.
+     * `stagedOutputs` was instance state created per cook, iterated under a
+     * `generation === this.cookGeneration` guard, and nulled in `finally` — but
+     * `cookGeneration` only advances in `invalidateCook()`, and `cook()` has no
+     * re-entrancy guard. So two overlapping cooks of the same node with no
+     * invalidation between them both ran at the same generation: the second's
+     * `finally` nulled the field, the first resumed, passed the generation check
+     * because nothing had invalidated it, and iterated `null` —
+     * `stagedOutputs is not iterable`.
+     *
+     * Worse than the crash, and the reason this is a correctness fix rather than
+     * a robustness one: the second cook's `new Map()` **replaced the first's
+     * mid-flight**, so the first cook's staged writes were lost whenever the
+     * timing did not happen to produce the throw.
+     *
+     * The underlying fault is that per-cook state lived on the instance, and the
+     * thing protecting it (the generation) was not the thing destroying it (the
+     * `finally`) — two mechanisms guarding one field, neither aware of the other.
+     * Each cook now owns its own map, holds it locally, and removes it **by
+     * identity**, so an interleaving cannot make one cook drop another's.
+     *
+     * Diagnosed by MW-OBSERVATORY-ART, 2026-09-08.
+     */
+    this.stagingStack = [];
     this.executionTimeout = 3e4;
     // Cook info - performance tracking
     this.cookInfo = {
@@ -5893,8 +6046,9 @@ var Node = class _Node {
     return port && "defaultValue" in port ? port : null;
   }
   setOutputValue(port, value) {
-    if (this.stagedOutputs) {
-      this.stagedOutputs.set(port, value);
+    const staging = this.stagingStack[this.stagingStack.length - 1];
+    if (staging) {
+      staging.set(port, value);
       return;
     }
     this.commitOutputValue(port, value);
@@ -6849,6 +7003,35 @@ var Node = class _Node {
     if (!this.hasExecuted || this.cookState !== "clean") return true;
     return this.calculateInputHash() !== this.lastInputHash;
   }
+  /**
+   * The last cook threw, and nothing has changed since it did.
+   *
+   * Separate from `isDirty` on purpose, and this is the second attempt: folding
+   * it into `isDirty` closed the Viewer's cook loop and broke a contract the
+   * scheduler tests already pinned — `requestOutput` retries a failed node,
+   * which is the transient case (a fetch that timed out, a device lost) and is
+   * right. The two callers are not the same thing wearing different names. An
+   * explicit request means *give me this output now* and should retry; the
+   * Viewer's `requestAnimationFrame` pump is a **poll** that was reaching the
+   * same entry point every 100 ms, and a poll asking again on identical inputs
+   * cannot learn anything.
+   *
+   * So the fix belongs at the poll, and the poll needs a question only the node
+   * can answer. Measured 2026-09-08 by MW-OBSERVATORY-ART against a live sketch:
+   * selecting a failing node produced 93 errors in 10 s — 9.3/sec, median gap
+   * 103.7 ms, identical stack every time — each one a full `scheduler.flush()`
+   * re-running the failing execute and re-fetching its inputs over the network,
+   * for as long as the node stayed selected. `markDirty` is not on that path,
+   * which is why auditing its call sites came back clean, and the Viewer's
+   * overlap guard is why it held 61 fps and never looked like a hang.
+   *
+   * `hasExecuted` is deliberately not consulted: a node that throws on its very
+   * first cook never sets it, and that is the reproduction case.
+   */
+  get hasSettledFailure() {
+    if (this.cookState !== "error" || this.failedInputHash === null) return false;
+    return this.calculateInputHash() === this.failedInputHash;
+  }
   /**
    * Mark all downstream nodes as dirty (lazy propagation)
    */
@@ -6892,7 +7075,8 @@ var Node = class _Node {
     const startTime = performance.now();
     const startMemory = performance.memory?.usedJSHeapSize ?? 0;
     const generation = this.cookGeneration;
-    this.stagedOutputs = /* @__PURE__ */ new Map();
+    const staging = /* @__PURE__ */ new Map();
+    this.stagingStack.push(staging);
     this.setCookState("cooking");
     let timeoutId;
     try {
@@ -6907,12 +7091,13 @@ var Node = class _Node {
       ]);
       if (generation === this.cookGeneration) {
         await this.callLifecycleHooks(needsInitialization);
-        for (const [port, value] of this.stagedOutputs) {
+        for (const [port, value] of staging) {
           this.commitOutputValue(port, value);
         }
         this.error = null;
         this.hasExecuted = true;
         this.lastInputHash = this.calculateInputHash();
+        this.failedInputHash = null;
         const carryReport = this.finishParameterCarryOver();
         if (carryReport) _Node.onParametersRetargeted?.(this.id, carryReport);
         this.setCookState("clean");
@@ -6920,20 +7105,23 @@ var Node = class _Node {
         this.setCookState("stale");
       }
       this.updateCookInfo(startTime, startMemory);
-    } catch (err) {
+    } catch (thrown) {
+      const err = asError(thrown);
       if (generation === this.cookGeneration) {
         this.error = err;
+        this.failedInputHash = this.calculateInputHash();
         this.setCookState("error");
       } else {
         this.setCookState("stale");
       }
       this.updateCookInfo(startTime, startMemory);
-      if (!err.message?.includes("timeout")) {
-        console.error(`Error executing node ${this.id}:`, err);
+      if (!err.message.includes("timeout")) {
+        console.error(`Error executing node ${this.id}: ${err.message}`, err);
       }
     } finally {
       if (timeoutId !== void 0) clearTimeout(timeoutId);
-      this.stagedOutputs = null;
+      const index = this.stagingStack.indexOf(staging);
+      if (index >= 0) this.stagingStack.splice(index, 1);
     }
   }
   /**
@@ -8141,11 +8329,20 @@ function parameterOptions(definition) {
   return {
     ...definition.label ? { label: definition.label } : {},
     ...definition.expression ? { defaultExpression: definition.expression } : {},
+    ...definition.action ? { action: definition.action } : {},
     ...definition.min === void 0 ? {} : { min: definition.min },
     ...definition.max === void 0 ? {} : { max: definition.max },
     ...definition.step === void 0 ? {} : { step: definition.step },
     ...definition.options ? {
-      choices: definition.options.map((value) => ({ value, label: String(value) }))
+      // A declared label wins; a bare value is its own label, which is what
+      // every definition written before the labelled form meant. Stringifying
+      // unconditionally is what turned "Magnific — costs money" into
+      // "magnific" and threw away the only notice that it bills per call.
+      choices: definition.options.map((option) => option !== null && typeof option === "object" && "value" in option ? {
+        value: option.value,
+        label: String(option.label ?? option.value),
+        ...option.disabled ? { disabled: true } : {}
+      } : { value: option, label: String(option) })
     } : {},
     promotable: false
   };
@@ -8277,86 +8474,238 @@ var browserAssetCapability = {
   }
 };
 
-// src/nodes/definition/gpuCapability.ts
-var PAGE_SCOPE = "\0page";
+// src/nodes/definition/browserShellCapability.ts
+var capability = null;
+function forgetShellCapability() {
+  capability = null;
+}
+async function token() {
+  if (capability) return capability;
+  const response = await fetch("/api/shell/capability", { cache: "no-store" });
+  if (!response.ok) {
+    throw new Error(
+      response.status === 404 ? "The shell capability is disabled on this server. It is available on a loopback server, or one started with an explicit trusted host." : `Could not obtain the shell capability (${response.status})`
+    );
+  }
+  const { capability: issued } = await response.json();
+  if (typeof issued !== "string" || !issued) {
+    throw new Error("Server issued no shell capability");
+  }
+  capability = issued;
+  return issued;
+}
+function domSignal(signal) {
+  if (!signal) return void 0;
+  const controller = new AbortController();
+  if (signal.aborted) controller.abort(signal.reason);
+  else signal.addEventListener("abort", () => controller.abort(signal.reason), { once: true });
+  return controller.signal;
+}
+async function post(body, signal) {
+  const bridged = domSignal(signal);
+  const send = async (issued) => fetch("/api/shell", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "X-Cascade-Shell-Capability": issued
+    },
+    body: JSON.stringify(body),
+    ...bridged ? { signal: bridged } : {}
+  });
+  let response = await send(await token());
+  if (response.status === 403) {
+    capability = null;
+    response = await send(await token());
+  }
+  return response;
+}
+function requestBody(command, args, options) {
+  const { signal: _signal, ...rest } = options ?? {};
+  return {
+    command,
+    ...args ? { args } : {},
+    ...Object.keys(rest).length > 0 ? { options: rest } : {}
+  };
+}
+async function fail2(response) {
+  let payload = null;
+  try {
+    payload = await response.json();
+  } catch {
+  }
+  const message2 = typeof payload?.error === "string" ? payload.error : `Shell request failed (${response.status})`;
+  if (payload?.code === "COMMAND_NOT_ALLOWED") {
+    throw new Error(`${message2}. Add it under Allowed Commands in Project Settings.`);
+  }
+  throw new Error(message2);
+}
+var browserShellCapability = {
+  async run(command, args, options) {
+    const response = await post(requestBody(command, args, options), options?.signal);
+    if (!response.ok) await fail2(response);
+    const { ok: _ok, ...result } = await response.json();
+    return result;
+  },
+  async runJson(command, args, options) {
+    const result = await this.run(command, args, options);
+    try {
+      return JSON.parse(result.stdout);
+    } catch {
+      throw new Error(`${command} did not print JSON`);
+    }
+  }
+};
+async function shellRouteAvailable() {
+  const forget = () => {
+    forgetShellCapability();
+    return false;
+  };
+  if (typeof fetch !== "function") return forget();
+  try {
+    const response = await fetch("/api/shell/capability", { cache: "no-store" });
+    if (!response.ok) return forget();
+    const { capability: issued } = await response.json();
+    if (typeof issued !== "string" || !issued) return forget();
+    capability = issued;
+    return true;
+  } catch {
+    return forget();
+  }
+}
+
+// packages/runtime/src/gpu.ts
+var HOST_SCOPE = "\0host";
 var MISSING_DEVICE = "The gpu capability was used before its device was ready \u2014 the host must await ensure() before a cook.";
-function createStudioGpuCapability() {
-  const gpu = globalThis.navigator?.gpu;
-  if (!gpu) return void 0;
-  let device = null;
-  let adapterInfo = null;
-  let limits = {};
+var DISPOSED = "The gpu capability has been disposed.";
+function isGpuHost(value) {
+  return !!value && typeof value.ensure === "function" && typeof value.forNode === "function" && typeof value.dispose === "function";
+}
+function createGpuHost(options) {
+  let active = null;
   let starting = null;
-  let destroyed = false;
+  let disposal = null;
+  let disposed = false;
   const caches = /* @__PURE__ */ new Map();
+  const retiring = /* @__PURE__ */ new Set();
+  const retirementErrors = [];
   function dropCaches() {
-    for (const entries of caches.values()) {
-      for (const entry of entries.values()) entry.destroy?.(entry.value);
-    }
+    const errors = [];
+    const scopes = [...caches.values()];
     caches.clear();
+    for (const entries of scopes) {
+      for (const entry of entries.values()) {
+        try {
+          entry.destroy?.(entry.value);
+        } catch (error) {
+          errors.push(error);
+        }
+      }
+    }
+    return errors;
+  }
+  async function release(acquired, destroyDevice) {
+    if (acquired.released) return [];
+    acquired.released = true;
+    const errors = [];
+    if (destroyDevice) {
+      try {
+        acquired.device.destroy();
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+    try {
+      await acquired.release?.();
+    } catch (error) {
+      errors.push(error);
+    }
+    return errors;
+  }
+  function throwCleanupErrors(errors) {
+    if (errors.length === 1) throw errors[0];
+    if (errors.length > 1) {
+      const combined = new Error("GPU host cleanup failed");
+      Object.assign(combined, { errors });
+      throw combined;
+    }
+  }
+  function watchLoss(acquired) {
+    void acquired.device.lost.then(() => {
+      if (disposed || active !== acquired) return;
+      active = null;
+      retirementErrors.push(...dropCaches());
+      const cleanup = release(acquired, false).then((errors) => {
+        retirementErrors.push(...errors);
+      });
+      retiring.add(cleanup);
+      void cleanup.finally(() => retiring.delete(cleanup));
+    }).catch(() => {
+    });
   }
   async function start() {
-    const adapter = await gpu.requestAdapter();
-    if (!adapter) {
-      throw new Error("No WebGPU adapter is available \u2014 the browser reports WebGPU but the system offers no GPU to render on.");
-    }
-    const next = await adapter.requestDevice();
-    const info = adapter.info;
-    device = next;
-    adapterInfo = {
-      vendor: info?.vendor ?? "",
-      architecture: info?.architecture ?? "",
-      device: info?.device ?? "",
-      description: info?.description ?? ""
+    const result = await options.acquire();
+    const acquired = {
+      device: result.device,
+      info: {
+        vendor: result.info?.vendor ?? "",
+        architecture: result.info?.architecture ?? "",
+        device: result.info?.device ?? "",
+        description: result.info?.description ?? ""
+      },
+      limits: readGpuLimits(result.limits),
+      release: result.release,
+      released: false
     };
-    limits = readLimits(next.limits ?? adapter.limits);
-    void next.lost.then((info2) => {
-      if (destroyed || info2?.reason === "destroyed") return;
-      device = null;
-      starting = null;
-      dropCaches();
-      console.warn(`The GPU device was lost (${info2?.reason ?? "unknown"}) \u2014 ${info2?.message || "no message given"}. A fresh device will be requested on the next cook.`);
-    });
+    if (disposed) {
+      const errors = await release(acquired, true);
+      throwCleanupErrors(errors);
+      throw new Error(DISPOSED);
+    }
+    active = acquired;
+    watchLoss(acquired);
   }
   const host = {
     get device() {
-      if (!device) throw new Error(MISSING_DEVICE);
-      return device;
+      if (!active) throw new Error(MISSING_DEVICE);
+      return active.device;
     },
     get adapterInfo() {
-      if (!adapterInfo) throw new Error(MISSING_DEVICE);
-      return adapterInfo;
+      if (!active) throw new Error(MISSING_DEVICE);
+      return active.info;
     },
     get limits() {
-      return limits;
+      return active?.limits ?? {};
     },
     cache(key2, create, destroy) {
-      return host.forNode(PAGE_SCOPE).cache(key2, create, destroy);
+      return host.forNode(HOST_SCOPE).cache(key2, create, destroy);
     },
     async ensure() {
-      if (destroyed) throw new Error("The gpu capability has been disposed.");
-      if (device) return;
-      starting ??= start().catch((error) => {
-        starting = null;
-        throw error;
-      });
+      if (disposed) throw new Error(DISPOSED);
+      if (active) return;
+      if (!starting) {
+        const attempt = start();
+        const tracked = attempt.finally(() => {
+          if (starting === tracked) starting = null;
+        });
+        starting = tracked;
+      }
       await starting;
     },
     forNode(nodeId) {
       return {
         get device() {
-          if (!device) throw new Error(MISSING_DEVICE);
-          return device;
+          if (!active) throw new Error(MISSING_DEVICE);
+          return active.device;
         },
         get adapterInfo() {
-          if (!adapterInfo) throw new Error(MISSING_DEVICE);
-          return adapterInfo;
+          if (!active) throw new Error(MISSING_DEVICE);
+          return active.info;
         },
         get limits() {
-          return limits;
+          return active?.limits ?? {};
         },
         cache(key2, create, destroy) {
-          if (!device) throw new Error(MISSING_DEVICE);
+          if (!active) throw new Error(MISSING_DEVICE);
           let entries = caches.get(nodeId);
           if (!entries) {
             entries = /* @__PURE__ */ new Map();
@@ -8364,37 +8713,84 @@ function createStudioGpuCapability() {
           }
           const existing = entries.get(key2);
           if (existing) return existing.value;
-          const value = create(device);
-          entries.set(key2, { value, destroy });
+          const value = create(active.device);
+          entries.set(key2, {
+            value,
+            destroy
+          });
           return value;
         }
       };
     },
-    async dispose() {
-      destroyed = true;
-      dropCaches();
-      device?.destroy();
-      device = null;
-      starting = null;
+    dispose() {
+      disposal ??= performDispose();
+      return disposal;
     }
   };
+  async function performDispose() {
+    disposed = true;
+    const errors = dropCaches();
+    const pending = starting;
+    if (pending) {
+      try {
+        await pending;
+      } catch (error) {
+        if (!(error instanceof Error && error.message === DISPOSED))
+          errors.push(error);
+      }
+    }
+    const acquired = active;
+    active = null;
+    if (acquired) errors.push(...await release(acquired, true));
+    await Promise.all([...retiring]);
+    errors.push(...retirementErrors);
+    retirementErrors.length = 0;
+    throwCleanupErrors(errors);
+  }
   return host;
 }
-function readLimits(source) {
+function readGpuLimits(source) {
   if (!source || typeof source !== "object") return {};
-  const out = {};
-  for (const key2 of limitNames(source)) {
-    const value = source[key2];
-    if (typeof value === "number") out[key2] = value;
-  }
-  return out;
-}
-function limitNames(source) {
   const names = new Set(Object.keys(source));
   for (let cursor = Object.getPrototypeOf(source); cursor && cursor !== Object.prototype; cursor = Object.getPrototypeOf(cursor)) {
-    for (const key2 of Object.getOwnPropertyNames(cursor)) if (key2 !== "constructor") names.add(key2);
+    for (const key2 of Object.getOwnPropertyNames(cursor)) {
+      if (key2 !== "constructor") names.add(key2);
+    }
+  }
+  const limits = {};
+  for (const key2 of names) {
+    const value = source[key2];
+    if (typeof value === "number") limits[key2] = value;
   }
-  return [...names];
+  return limits;
+}
+
+// src/nodes/definition/gpuCapability.ts
+function createStudioGpuCapability() {
+  const gpu = globalThis.navigator?.gpu;
+  if (!gpu) return void 0;
+  return createGpuHost({
+    async acquire() {
+      const adapter = await gpu.requestAdapter();
+      if (!adapter) {
+        throw new Error(
+          "No WebGPU adapter is available \u2014 the browser reports WebGPU but the system offers no GPU to render on."
+        );
+      }
+      const device = await adapter.requestDevice();
+      const info = adapter.info;
+      return {
+        device,
+        info: {
+          vendor: info?.vendor ?? "",
+          architecture: info?.architecture ?? "",
+          device: info?.device ?? "",
+          description: info?.description ?? ""
+        },
+        limits: device.limits ?? adapter.limits
+      };
+    }
+  });
 }
 
 // src/nodes/definition/projectDefinition.ts
@@ -8405,8 +8801,31 @@ var studioCapabilities = {
   // reports `runtime/missing-capability` and the adapter throws "requires the
   // Studio gpu capability", both naming what is missing. A stub that threw on
   // first use would name nothing.
-  ...gpuCapabilityIfAvailable()
+  ...gpuCapabilityIfAvailable(),
+  /**
+   * Shell is present up front and withdrawn if the route turns out not to be
+   * there, which is the opposite way round from gpu and worth the sentence.
+   *
+   * `navigator.gpu` is a synchronous check, so gpu can be absent from the map
+   * before anything reads it. Whether the shell route exists takes a fetch, and
+   * this object is a module-level const read by three default parameters — so
+   * the choice is between delaying Studio's boot on a request, racing the
+   * probe, or installing and withdrawing. Installing is the one where the
+   * common case (a loopback server, where the route is always there) has no
+   * race at all and no cost.
+   *
+   * What it costs: on a server that does NOT offer the route, a cook in the
+   * first few milliseconds after boot sees the capability present and fails at
+   * the fetch instead of at the gate. That failure still names itself — *"the
+   * shell capability is disabled on this server"* — so it is a worse-shaped
+   * error rather than a silent one, and once the probe lands the preflight is
+   * correct from then on.
+   */
+  shell: browserShellCapability
 };
+void shellRouteAvailable().then((available) => {
+  if (!available) delete studioCapabilities.shell;
+});
 function gpuCapabilityIfAvailable() {
   const gpu = createStudioGpuCapability();
   return gpu ? { gpu } : {};
@@ -9809,7 +10228,8 @@ var Graph = class _Graph {
             value = propData;
           }
           let normalizedValue = value;
-          if (isColorValue(value)) {
+          const declaredColor = node.props[key2]?.type === "color";
+          if (isColorValue(value) && (declaredColor || !Array.isArray(value))) {
             const normalized = normalizeColor(value);
             normalizedValue = normalized.a !== void 0 && normalized.a !== 1 ? { r: normalized.r, g: normalized.g, b: normalized.b, a: normalized.a } : { r: normalized.r, g: normalized.g, b: normalized.b };
           }
@@ -10081,6 +10501,81 @@ var CascadeRuntimeError = class extends Error {
   }
 };
 
+// packages/runtime/src/camera/index.ts
+var DEG = Math.PI / 180;
+function cross(a, b) {
+  return [
+    a[1] * b[2] - a[2] * b[1],
+    a[2] * b[0] - a[0] * b[2],
+    a[0] * b[1] - a[1] * b[0]
+  ];
+}
+function normalize(v) {
+  const length = Math.hypot(v[0], v[1], v[2]);
+  if (length === 0) return [0, 0, 0];
+  return [v[0] / length, v[1] / length, v[2] / length];
+}
+function subtract(a, b) {
+  return [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+}
+function dot(a, b) {
+  return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+}
+function lookAtRotation(from, to, up = [0, 1, 0]) {
+  const forward = normalize(subtract(to, from));
+  if (forward[0] === 0 && forward[1] === 0 && forward[2] === 0) return [0, 0, 0];
+  const horizontal = Math.hypot(forward[0], forward[2]);
+  const pitch = Math.atan2(forward[1], horizontal);
+  const yaw = Math.atan2(-forward[0], -forward[2]);
+  return [pitch / DEG, yaw / DEG, rollTowards(forward, pitch, yaw, up) / DEG];
+}
+function rollTowards(forward, pitch, yaw, up) {
+  const desired = normalize([
+    up[0] - forward[0] * dot(up, forward),
+    up[1] - forward[1] * dot(up, forward),
+    up[2] - forward[2] * dot(up, forward)
+  ]);
+  if (desired[0] === 0 && desired[1] === 0 && desired[2] === 0) return 0;
+  const locked = cameraBasis({
+    ...CAMERA_ROTATION_ONLY,
+    rotate: [pitch / DEG, yaw / DEG, 0]
+  }).up;
+  return Math.atan2(dot(cross(desired, locked), forward), dot(locked, desired));
+}
+var CAMERA_ROTATION_ONLY = {
+  translate: [0, 0, 0],
+  focal: 50,
+  aperture: 41.4214,
+  near: 1e-3,
+  far: 1e4,
+  resolution: [1, 1],
+  aspect: 1,
+  projection: "perspective",
+  orthowidth: 2
+};
+function cameraBasis(camera) {
+  const [rx, ry, rz] = camera.rotate;
+  const sx = Math.sin(rx * DEG);
+  const cx = Math.cos(rx * DEG);
+  const sy = Math.sin(ry * DEG);
+  const cy = Math.cos(ry * DEG);
+  const sz = Math.sin(rz * DEG);
+  const cz = Math.cos(rz * DEG);
+  const m00 = cy * cz + sy * sx * sz;
+  const m01 = -cy * sz + sy * sx * cz;
+  const m02 = sy * cx;
+  const m10 = cx * sz;
+  const m11 = cx * cz;
+  const m12 = -sx;
+  const m20 = -sy * cz + cy * sx * sz;
+  const m21 = sy * sz + cy * sx * cz;
+  const m22 = cy * cx;
+  const right = [m00, m10, m20];
+  const up = [m01, m11, m21];
+  const forward = [-m02, -m12, -m22];
+  return { eye: camera.translate, forward, right, up };
+}
+
 // packages/runtime/src/geometry/attributes.ts
 init_src();
 function geometryError(code, message2) {
@@ -10967,6 +11462,134 @@ function utf8Bytes(value) {
 // packages/runtime/src/runtime.ts
 init_src();
 
+// packages/runtime/src/builtins/core/camera.ts
+init_src();
+var cameraDefinition = {
+  apiVersion: 1,
+  label: "Camera",
+  description: "A camera, following Houdini's /obj/cam.",
+  icon: "Video",
+  runsOn: "portable",
+  inputs: {
+    translate: {
+      kind: "data",
+      type: "vec3",
+      default: [0, 0, 5],
+      description: "World position."
+    },
+    rotate: {
+      kind: "data",
+      type: "vec3",
+      default: [0, 0, 0],
+      description: "Degrees, XYZ order. The camera looks down its own -Z."
+    },
+    focal: {
+      kind: "data",
+      type: "float",
+      default: 50,
+      min: 1,
+      max: 300,
+      description: "Focal length in millimetres."
+    },
+    lookat: {
+      kind: "data",
+      type: "vec3",
+      default: [0, 0, 0],
+      description: "Point to aim at. Used only when Look At is on, and it replaces Rotate."
+    },
+    up: {
+      kind: "data",
+      type: "vec3",
+      default: [0, 1, 0],
+      description: "Up vector for Look At."
+    },
+    spin: {
+      kind: "data",
+      type: "float",
+      default: 0,
+      description: "Degrees added to the Y rotation, after Look At. For turntables."
+    }
+  },
+  outputs: {
+    camera: { kind: "data", type: "camera" }
+  },
+  props: {
+    lookAt: {
+      type: "bool",
+      default: false,
+      label: "Look At",
+      description: "Aim at the Look At point instead of using Rotate."
+    },
+    aperture: {
+      type: "float",
+      default: 41.4214,
+      min: 1,
+      max: 200,
+      label: "Aperture",
+      description: "Horizontal aperture in millimetres. With the default focal length this is a 45 degree view."
+    },
+    resolution: {
+      type: "vec2i",
+      default: [1280, 720],
+      label: "Resolution",
+      description: "Frame size in pixels. The vertical field of view is derived from this."
+    },
+    aspect: {
+      type: "float",
+      default: 1,
+      min: 0.1,
+      max: 10,
+      label: "Pixel Aspect",
+      description: "The aspect of one pixel, not of the frame."
+    },
+    projection: {
+      type: "string",
+      default: "perspective",
+      label: "Projection",
+      control: "select",
+      options: [
+        { value: "perspective", label: "Perspective" },
+        { value: "orthographic", label: "Orthographic" }
+      ]
+    },
+    orthowidth: {
+      type: "float",
+      default: 2,
+      min: 0.01,
+      label: "Ortho Width",
+      description: "Width of the orthographic frame in world units."
+    },
+    near: { type: "float", default: 1e-3, min: 0, label: "Near Clip" },
+    far: { type: "float", default: 1e4, min: 0, label: "Far Clip" }
+  }
+};
+function executeCamera(context) {
+  const { translate, rotate, focal, lookat, up, spin } = context.inputs;
+  const props = context.props;
+  const aimed = props.lookAt ? lookAtRotation(translate, lookat, up) : rotate;
+  const oriented = spin === 0 ? aimed : [aimed[0], aimed[1] + spin, aimed[2]];
+  const camera = {
+    ...CAMERA_DEFAULTS,
+    translate,
+    rotate: oriented,
+    focal,
+    aperture: props.aperture,
+    resolution: props.resolution,
+    aspect: props.aspect,
+    projection: props.projection === "orthographic" ? "orthographic" : "perspective",
+    orthowidth: props.orthowidth,
+    near: props.near,
+    far: props.far
+  };
+  context.outputs.camera.set(camera);
+}
+var cameraRegistration = {
+  kind: "definition-v1",
+  moduleId: "cascade.core.Camera",
+  definition: cameraDefinition,
+  loadExecute: async () => executeCamera
+};
+
 // packages/runtime/src/builtins/core/random.ts
 var randomDefinition = {
   apiVersion: 1,
@@ -11246,7 +11869,8 @@ var coreNodeRegistrations = Object.freeze([
   nullRegistration,
   selectRegistration,
   randomRegistration,
-  remapRegistration
+  remapRegistration,
+  cameraRegistration
 ]);
 var registrationsById = new Map(
   coreNodeRegistrations.map((registration) => [registration.moduleId, registration])
@@ -11596,10 +12220,12 @@ function builtinNodeRegistration(moduleId2) {
 // packages/runtime/src/runtime.ts
 var PREFLIGHT_WARNING_CODES = /* @__PURE__ */ new Set([
   "runtime/preflight-environment",
-  "runtime/stray-params"
+  "runtime/stray-params",
+  "runtime/unknown-props"
 ]);
 var RUN_TOLERATED_CODES = /* @__PURE__ */ new Set([
-  "runtime/stray-params"
+  "runtime/stray-params",
+  "runtime/unknown-props"
 ]);
 var MutableAbortSignal = class {
   constructor(report) {
@@ -12306,14 +12932,20 @@ var Graph2 = class {
         ]
       )
     );
-    const capabilities = Object.freeze(
-      Object.fromEntries(
-        (node.definition.capabilities ?? []).map((name) => [
+    const capabilityEntries = [];
+    for (const name of node.definition.capabilities ?? []) {
+      const installed = this.host.capabilities[name];
+      if (name === "gpu" && isGpuHost(installed)) {
+        await installed.ensure();
+        capabilityEntries.push([name, installed.forNode(node.id)]);
+      } else {
+        capabilityEntries.push([
           name,
-          name === "shell" ? bindShellToRun(this.host.capabilities.shell, signal) : this.host.capabilities[name]
-        ])
-      )
-    );
+          name === "shell" ? bindShellToRun(this.host.capabilities.shell, signal) : installed
+        ]);
+      }
+    }
+    const capabilities = Object.freeze(Object.fromEntries(capabilityEntries));
     const props = Object.freeze({ ...node.props });
     const progress = {
       report: (event) => this.emit({ type: "node:progress", runId, nodeId: node.id, ...event })
@@ -12376,6 +13008,12 @@ var Graph2 = class {
     const diagnostics = [];
     const push = (code, nodeId, message2) => diagnostics.push({ phase: "preflight", code, path: nodeId, message: message2 });
     for (const node of nodes) {
+      if (node.unknownProps.length)
+        push(
+          "runtime/unknown-props",
+          node.id,
+          `${node.moduleId} stores ${node.unknownProps.join(", ")} under "props", and its definition declares no such prop \u2014 ${node.unknownProps.length === 1 ? "that value was" : "those values were"} dropped on load. A prop renamed or removed leaves its value behind; a name that never existed is a typo`
+        );
       if (node.strayParams.length)
         push(
           "runtime/stray-params",
@@ -12414,12 +13052,12 @@ var Graph2 = class {
             `${node.moduleId} cannot send textures over the server bridge`
           );
       } else
-        for (const capability of node.definition.capabilities ?? [])
-          if (!this.host.capabilities[capability])
+        for (const capability2 of node.definition.capabilities ?? [])
+          if (!this.host.capabilities[capability2])
             push(
               "runtime/missing-capability",
               node.id,
-              `Missing capability ${capability} for ${node.moduleId} (node ${node.id}) \u2014 the ${this.host.environment} host ${this.hostProvides()}`
+              `Missing capability ${capability2} for ${node.moduleId} (node ${node.id}) \u2014 the ${this.host.environment} host ${this.hostProvides()}`
             );
     }
     return diagnostics;
@@ -12691,6 +13329,11 @@ function materialize(authored, registration) {
       false,
       `${authored.id}.${name}`
     );
+  if (Array.isArray(authored.props))
+    misuse(
+      "runtime/props-not-a-map",
+      `Node ${authored.id} stores props as a list. "props" is a map of name to value; "params" was the list. Every value in it is being dropped, silently, and the graph would run on its defaults`
+    );
   const bindings = {};
   const storedProps = authored.props ?? {};
   for (const [name, definition] of Object.entries(
@@ -12736,9 +13379,16 @@ function materialize(authored, registration) {
     props,
     bindings,
     strayParams: strayParams(authored, registration),
+    unknownProps: unknownProps(authored, registration),
     outputs: /* @__PURE__ */ new Map()
   };
 }
+function unknownProps(authored, registration) {
+  const props = authored.props;
+  if (!props || Array.isArray(props)) return [];
+  const declared = registration.definition.props ?? {};
+  return Object.keys(props).filter((name) => !(name in declared));
+}
 function strayParams(authored, registration) {
   const definition = registration.definition;
   const declared = /* @__PURE__ */ new Set([
@@ -13184,12 +13834,16 @@ function validateNodeModuleArchitecture(source, fileName, ts3) {
     ts3.ScriptKind.TS
   );
   const diagnostics = [];
+  const exportsDefinition = file.statements.some(
+    (statement) => ts3.isVariableStatement(statement) && isDefinition(statement)
+  );
   for (const statement of file.statements) {
     if (ts3.isVariableStatement(statement) && !isDefinition(statement)) {
+      const superseded = supersededByDefinition(statement);
       add(
         statement,
         "module-state",
-        "Node modules may not declare module-level values; use a pure function or pass state through ports, props, and declared capabilities"
+        superseded ? `\`${superseded}\` belongs inside the definition, not beside it \u2014 a definition-v1 node declares it as \`${superseded}: ...\` in \`export const definition\`, and a module-level copy is the module state this rule forbids. A dynamic node without a definition still declares it here.` : "Node modules may not declare module-level values; use a pure function or pass state through ports, props, and declared capabilities"
       );
     } else if (ts3.isClassDeclaration(statement) || ts3.isEnumDeclaration(statement) || ts3.isModuleDeclaration(statement)) {
       add(
@@ -13241,6 +13895,13 @@ function validateNodeModuleArchitecture(source, fileName, ts3) {
     const parent = node.parent;
     return !(ts3.isPropertyAccessExpression(parent) && parent.name === node || ts3.isPropertyAssignment(parent) && parent.name === node || ts3.isMethodDeclaration(parent) && parent.name === node || ts3.isPropertyDeclaration(parent) && parent.name === node);
   }
+  function supersededByDefinition(statement) {
+    if (!exportsDefinition) return null;
+    const declaration = statement.declarationList.declarations[0];
+    if (statement.declarationList.declarations.length !== 1) return null;
+    if (!declaration || !ts3.isIdentifier(declaration.name)) return null;
+    return declaration.name.text === "icon" || declaration.name.text === "runsOn" ? declaration.name.text : null;
+  }
   function isDefinition(statement) {
     return Boolean(statement.declarationList.flags & ts3.NodeFlags.Const) && Boolean(statement.modifiers?.some((item) => item.kind === ts3.SyntaxKind.ExportKeyword)) && statement.declarationList.declarations.length === 1 && ts3.isIdentifier(statement.declarationList.declarations[0].name) && statement.declarationList.declarations[0].name.text === "definition";
   }
@@ -13258,15 +13919,15 @@ function validateNodeModuleArchitecture(source, fileName, ts3) {
 }
 function importsSiblingNode(fileName, specifier) {
   if (!specifier.startsWith(".")) return false;
-  const file = normalize(fileName).split("/");
+  const file = normalize2(fileName).split("/");
   const nodesIndex = file.lastIndexOf("nodes");
   if (nodesIndex < 0 || !file[nodesIndex + 1]) return false;
   const sourceNode = file[nodesIndex + 1];
-  const resolved = normalize([...file.slice(0, -1), ...specifier.split("/")].join("/")).split("/");
+  const resolved = normalize2([...file.slice(0, -1), ...specifier.split("/")].join("/")).split("/");
   const resolvedNodesIndex = resolved.lastIndexOf("nodes");
   return resolvedNodesIndex >= 0 && Boolean(resolved[resolvedNodesIndex + 1]) && resolved[resolvedNodesIndex + 1] !== sourceNode;
 }
-function normalize(value) {
+function normalize2(value) {
   const output = [];
   for (const part of value.split("\\").join("/").split("/")) {
     if (!part || part === ".") continue;
@@ -13381,6 +14042,41 @@ function imagePath(value) {
   return null;
 }
 
+// src/cli/headlessGpu.ts
+var MISSING_GPU_MESSAGE = 'Cascade cannot load the optional Dawn WebGPU renderer. Install "webgpu@0.6.0" on a supported platform and run again.';
+function createDawnGpuHost() {
+  return createGpuHost({
+    async acquire() {
+      let dawn;
+      try {
+        dawn = await import("webgpu");
+      } catch (cause) {
+        throw Object.assign(new Error(MISSING_GPU_MESSAGE), { cause });
+      }
+      let gpu = dawn.create([]);
+      let device;
+      try {
+        const adapter = await gpu.requestAdapter();
+        if (!adapter) throw new Error("Dawn found no WebGPU adapter. Check GPU drivers and backend availability; headless rendering still needs a hardware or explicitly configured software adapter.");
+        device = await adapter.requestDevice();
+        const info = adapter.info;
+        return { device, info: {
+          vendor: info.vendor,
+          architecture: info.architecture,
+          device: info.device,
+          description: info.description
+        }, limits: device.limits, release: () => {
+          gpu = void 0;
+        } };
+      } catch (error) {
+        device?.destroy();
+        gpu = void 0;
+        throw error;
+      }
+    }
+  });
+}
+
 // src/cli/projectRuntime.ts
 function createProjectHost(file, registrations) {
   const project = new ProjectRoot(path9.dirname(path9.resolve(file)));
@@ -13391,7 +14087,8 @@ function createProjectHost(file, registrations) {
     // `cascade.geo.SvgExport` declares it — so an export graph passed both
     // `validate` and `check` and then refused to run. See ./nodeAssets.ts
     // for where the file lands and why.
-    assets: createNodeAssetCapability(project)
+    assets: createNodeAssetCapability(project),
+    gpu: createDawnGpuHost()
   });
 }
 async function preflightAgainstRunHost(file, registrations, document2) {
@@ -13409,9 +14106,9 @@ async function preflightAgainstRunHost(file, registrations, document2) {
   try {
     const graph = await runtime.load(document2);
     if (checkable) diagnostics = graph.preflight();
-    await graph.dispose();
   } finally {
     await runtime.dispose();
+    await disposeProjectGpu(host);
   }
   if (!diagnostics.length) return;
   const { errors, warnings } = classifyPreflight(diagnostics);
@@ -13425,7 +14122,7 @@ async function preflightAgainstRunHost(file, registrations, document2) {
 }
 function reportPreflightWarnings(host, warnings) {
   const elsewhere = warnings.filter((item) => item.code === "runtime/preflight-environment");
-  const lossy = warnings.filter((item) => item.code === "runtime/stray-params");
+  const lossy = warnings.filter((item) => item.code === "runtime/stray-params" || item.code === "runtime/unknown-props");
   if (elsewhere.length) {
     console.warn([
       `Not checkable here \u2014 ${elsewhere.length === 1 ? "one node" : `${elsewhere.length} nodes`} in this graph target${elsewhere.length === 1 ? "s" : ""} another host:`,
@@ -13435,7 +14132,7 @@ function reportPreflightWarnings(host, warnings) {
   }
   if (lossy.length) {
     console.warn([
-      `Stored values were dropped on load \u2014 ${lossy.length === 1 ? "one node" : `${lossy.length} nodes`} still keep${lossy.length === 1 ? "s" : ""} values under "params":`,
+      `Stored values were dropped on load \u2014 ${lossy.length === 1 ? "one node" : `${lossy.length} nodes`}:`,
       ...lossy.map(line),
       `  This graph will run, on the defaults, and look like it worked.`
     ].join("\n"));
@@ -13456,8 +14153,8 @@ function capabilityAdvice(host, diagnostics) {
   const hostCapabilities = CAPABILITIES_BY_ENVIRONMENT[host.environment] ?? [];
   return missing.map((name) => hostCapabilities.includes(name) ? `  ${name}: declared in @cascade/contracts but not installed by the host \u2014 drop it from the definition, or install it where the host is built (createProjectHost, src/cli/projectRuntime.ts).` : `  ${name}: a ${environmentOwning(name)} capability. The CLI runs the ${host.environment} host, so no CLI run can supply it.`);
 }
-function environmentOwning(capability) {
-  const owners = Object.entries(CAPABILITIES_BY_ENVIRONMENT).filter(([, names]) => names.includes(capability)).map(([environment]) => environment);
+function environmentOwning(capability2) {
+  const owners = Object.entries(CAPABILITIES_BY_ENVIRONMENT).filter(([, names]) => names.includes(capability2)).map(([environment]) => environment);
   return owners.length ? owners.join("/") : "unknown";
 }
 function reportUnresolved(prepared) {
@@ -13507,7 +14204,7 @@ async function runDeterministicProjectGraph(file, document2, entryNode) {
     graph = await runtime.load(document2);
     reportPreflightWarnings(
       host,
-      classifyPreflight(graph.preflight()).warnings.filter((item) => item.code === "runtime/stray-params")
+      classifyPreflight(graph.preflight()).warnings.filter((item) => item.code === "runtime/stray-params" || item.code === "runtime/unknown-props")
     );
     const result = await graph.run(entryNode ? { target: { kind: "node", nodeId: entryNode } } : {});
     if (result.status !== "completed") {
@@ -13515,8 +14212,11 @@ async function runDeterministicProjectGraph(file, document2, entryNode) {
     }
     return true;
   } finally {
-    await graph?.dispose();
-    await runtime.dispose();
+    try {
+      await runtime.dispose();
+    } finally {
+      await disposeProjectGpu(host);
+    }
   }
 }
 async function renderDeterministicProjectFrames(file, document2, options) {
@@ -13534,15 +14234,18 @@ async function renderDeterministicProjectFrames(file, document2, options) {
     host,
     nodes: prepared.registrations
   });
-  const graph = await runtime.load(document2);
-  reportPreflightWarnings(host, classifyPreflight(graph.preflight()).warnings);
-  const outDirectory = project.resolve(options.out);
-  await fs7.mkdir(outDirectory, { recursive: true });
+  let graph;
   const width = sequenceWidth(options.end);
   const frames = [];
   const files = [];
   let aborted = false;
+  let gpu;
+  const started = performance.now();
   try {
+    graph = await runtime.load(document2);
+    reportPreflightWarnings(host, classifyPreflight(graph.preflight()).warnings);
+    const outDirectory = project.resolve(options.out);
+    await fs7.mkdir(outDirectory, { recursive: true });
     for (const frame of frameRange(options.start, options.end, options.step ?? 1)) {
       if (options.signal?.aborted) {
         aborted = true;
@@ -13574,11 +14277,21 @@ async function renderDeterministicProjectFrames(file, document2, options) {
       frames.push(frame);
       if (options.verbose) console.log(`  frame ${frame}`);
     }
+    try {
+      gpu = { renderer: "dawn", adapter: host.capabilities.gpu.adapterInfo };
+    } catch {
+    }
   } finally {
-    await graph.dispose();
-    await runtime.dispose();
+    try {
+      await runtime.dispose();
+    } finally {
+      await disposeProjectGpu(host);
+    }
   }
-  return { frames, files, aborted };
+  return { frames, files, aborted, fps: graph.getFps(), durationMs: performance.now() - started, ...gpu ? { gpu } : {} };
+}
+async function disposeProjectGpu(host) {
+  await host.capabilities.gpu?.dispose();
 }
 function imageOutputs(graph, entryNode) {
   const found = [];
@@ -13644,6 +14357,8 @@ async function prepare(file, document2, compileExecutors) {
     const mentionsDefinition = /\bexport\s+const\s+definition\b/.test(source);
     const extracted = extractNodeDefinition(source, moduleFile, ts2);
     if (!extracted.ok) {
+      const reExport = reExportedDefinition(source);
+      if (reExport) throw new Error(formatDiagnostic(reExport(moduleFile)));
       if (!mentionsDefinition && extracted.diagnostics.every((item) => item.code === "definition/missing-export")) {
         registrations.push(savedRegistration(id, node));
         continue;
@@ -13683,6 +14398,18 @@ async function projectModuleFile(root, node, id) {
   tried.push(candidate);
   return { file: await exists(candidate) ? candidate : null, tried };
 }
+function reExportedDefinition(source) {
+  const named = /\bexport\s*\{[^}]*\bdefinition\b[^}]*\}\s*from\s*['"]/.test(source);
+  const star = /\bexport\s*\*\s*from\s*['"]/.test(source);
+  if (!named && !star) return null;
+  const what = named ? "this module re-exports `definition` from another file" : "this module has a star re-export and no `definition` of its own";
+  return (file) => ({
+    phase: "prepare",
+    code: "definition/re-exported",
+    file,
+    message: `${what}, and a definition cannot arrive that way \u2014 it is read statically from this file. Write the literal here, or keep the stub for \`execute\` only and leave this module dynamic. Without this the node loads as dynamic and every command reports success.`
+  });
+}
 function unresolvedModule(id, node, tried, root) {
   const relative = tried.map((candidate) => path9.relative(root, candidate) || candidate);
   const where = relative.length ? `looked for ${relative.join(" and ")}` : `no project file is possible for this module id \u2014 a project module is named "project.<dir>" or carries a source file`;
@@ -17367,28 +18094,50 @@ async function runGraph(options) {
     if (verbose) console.warn(canvasError.message);
   }
   const frameSpec = frames ? parseFrameSpec(frames) : null;
+  let hostReleased = false;
   const releaseHost = () => {
-    disposeStageBridge?.();
-    disposeIoBridge?.();
-    canvasHost?.dispose();
+    if (hostReleased) return;
+    hostReleased = true;
+    const errors = [];
+    for (const dispose of [
+      disposeStageBridge,
+      disposeIoBridge,
+      canvasHost ? () => canvasHost.dispose() : void 0,
+      () => setProjectModuleCompiler(null),
+      () => setEmbeddedCompiler(null)
+    ]) {
+      try {
+        dispose?.();
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+    if (errors.length) throw errors[0];
   };
-  if (frameSpec) {
-    const rendered = await renderDeterministicProjectFrames(file, graphData, {
-      ...frameSpec,
-      ...fps === void 0 ? {} : { fps },
-      out: out ?? "renders",
-      ...entryNode ? { entryNode } : {},
-      ...verbose ? { verbose } : {}
-    });
-    if (rendered) {
+  try {
+    if (frameSpec) {
+      const rendered = await renderDeterministicProjectFrames(file, graphData, {
+        ...frameSpec,
+        ...fps === void 0 ? {} : { fps },
+        out: out ?? "renders",
+        ...entryNode ? { entryNode } : {},
+        ...verbose ? { verbose } : {}
+      });
+      if (rendered) {
+        releaseHost();
+        if (options.json) process.stdout.write(JSON.stringify({ status: "completed", graph: path13.resolve(file), ...rendered }) + "\n");
+        else console.log(`Rendered ${rendered.frames.length} frames, ${rendered.files.length} files -> ${out ?? "renders"}/`);
+        return;
+      }
+      if (options.json) throw new Error("--json rendering requires a fully definition-v1 graph");
+    } else if (await runDeterministicProjectGraph(file, graphData, entryNode)) {
+      if (verbose) console.log("Graph execution completed");
       releaseHost();
-      console.log(`Rendered ${rendered.frames.length} frames, ${rendered.files.length} files -> ${out ?? "renders"}/`);
       return;
     }
-  } else if (await runDeterministicProjectGraph(file, graphData, entryNode)) {
-    if (verbose) console.log("Graph execution completed");
+  } catch (error) {
     releaseHost();
-    return;
+    throw error;
   }
   let activeGraph;
   try {
@@ -17498,14 +18247,60 @@ async function runGraph(options) {
   } finally {
     activeGraph?.scheduler?.dispose?.();
     releaseHost();
-    setProjectModuleCompiler(null);
-    setEmbeddedCompiler(null);
   }
 }
 
 // src/cli/index.ts
 import * as fs22 from "fs/promises";
 import { readFileSync } from "node:fs";
+
+// src/cli/supervise.ts
+import { spawn as spawn2 } from "node:child_process";
+function superviseProcess(command, args, timeoutMs) {
+  return new Promise((resolve2, reject) => {
+    const child = spawn2(command, args, { stdio: "inherit", detached: process.platform !== "win32" });
+    let timedOut = false;
+    let cancelled = false;
+    let grace;
+    const kill = (signal) => {
+      if (!child.pid) return;
+      try {
+        if (process.platform === "win32") child.kill(signal);
+        else process.kill(-child.pid, signal);
+      } catch (error) {
+        if (error.code !== "ESRCH") throw error;
+      }
+    };
+    const cancel = () => {
+      cancelled = true;
+      kill("SIGTERM");
+      grace ??= setTimeout(() => kill("SIGKILL"), 1e3);
+    };
+    process.on("SIGINT", cancel);
+    process.on("SIGTERM", cancel);
+    const timeout = setTimeout(() => {
+      timedOut = true;
+      console.error(`Render timed out after ${timeoutMs} ms`);
+      kill("SIGKILL");
+    }, timeoutMs);
+    const cleanup = () => {
+      clearTimeout(timeout);
+      clearTimeout(grace);
+      process.off("SIGINT", cancel);
+      process.off("SIGTERM", cancel);
+    };
+    child.once("error", (error) => {
+      cleanup();
+      reject(error);
+    });
+    child.once("close", (code) => {
+      cleanup();
+      resolve2(timedOut ? 124 : cancelled ? 130 : code ?? 1);
+    });
+  });
+}
+
+// src/cli/index.ts
 var VERSION = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version;
 async function main() {
   const args = process.argv.slice(2);
@@ -17550,6 +18345,8 @@ Options:
   --frames <range>   Render a frame sequence: 1-100, 1-100x2 (step), or 42
   --fps <number>     Frame rate to evaluate the range at
   --out <dir>        Sequence directory, project-relative (default: renders)
+  --json             Return a JSON render manifest (requires run --frames)
+  --timeout <ms>     Bound a run in a supervised child process (exit 124 on timeout)
   --validate-only   Validate only (same as 'validate' command)
   --verbose, -v      Show verbose output
   --version          Show version
@@ -17627,7 +18424,24 @@ image output nothing downstream consumes, or per output of --entry-node.
   }
   const out = valueOf("--out");
   if (out) options.out = out;
+  if (args.includes("--json")) {
+    if (command !== "run" || !options.frames) throw new Error("--json requires run --frames (use --frames 1 for a still)");
+    options.json = true;
+  }
+  const timeout = valueOf("--timeout");
+  if (timeout !== void 0) {
+    const ms = Number(timeout);
+    if (command !== "run" || !Number.isSafeInteger(ms) || ms <= 0 || ms > 2147483647) {
+      throw new Error("--timeout requires run and a positive integer number of milliseconds up to 2147483647");
+    }
+    const index = args.indexOf("--timeout");
+    const childArgs = [...args.slice(0, index), ...args.slice(index + 2)];
+    if (childArgs.includes("--timeout")) throw new Error("--timeout may only be specified once");
+    process.exitCode = await superviseProcess(process.execPath, [...process.execArgv, process.argv[1], ...childArgs], ms);
+    return;
+  }
   try {
+    if (options.json) console.log = console.error;
     await runGraph(options);
   } catch (error) {
     console.error(`Error: ${error.message}`);