@field/cascade 0.7.0 → 0.8.0

package/dist/cli/index.js

@@ -212,9 +212,9 @@ function levelCount(geometry, level) {
   if (level === "primitive") return geometry.primitiveCount;
   return 1;
 }
-function checkName(name, path24) {
+function checkName(name, path25) {
   if (!NAME.test(name) || RESERVED_NAMES.has(name))
-    fail("invalid-name", `${path24}.${name} is not a valid attribute name`);
+    fail("invalid-name", `${path25}.${name} is not a valid attribute name`);
 }
 function checkAttributeSet(set, count, level) {
   for (const [name, attribute] of Object.entries(set)) {
@@ -826,8 +826,8 @@ var init_values = __esm({
 });
 
 // packages/contracts/src/validate.ts
-function diagnostic(code, message2, path24) {
-  return { phase: "definition", code: `definition/${code}`, message: message2, path: path24 };
+function diagnostic(code, message2, path25) {
+  return { phase: "definition", code: `definition/${code}`, message: message2, path: path25 };
 }
 function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -842,12 +842,12 @@ function finiteJson(value) {
   if (Array.isArray(value)) return value.every(finiteJson);
   return isRecord2(value) && Object.values(value).every(finiteJson);
 }
-function unknownFields(value, allowed, path24) {
+function unknownFields(value, allowed, path25) {
   return Object.keys(value).filter((key2) => !allowed.has(key2)).map(
     (key2) => diagnostic(
       "unknown-field",
-      `${path24}.${key2} is not allowed`,
-      `${path24}.${key2}`
+      `${path25}.${key2} is not allowed`,
+      `${path25}.${key2}`
     )
   );
 }
@@ -879,7 +879,7 @@ function validateNodeDefinition(value) {
   if (!isRecord2(value))
     return [diagnostic("not-object", "Definition must be an object")];
   const result = unknownFields(value, TOP_FIELDS, "definition");
-  const add = (code, message2, path24) => result.push(diagnostic(code, message2, path24));
+  const add = (code, message2, path25) => result.push(diagnostic(code, message2, path25));
   const environment = value.runsOn;
   if (value.apiVersion !== 1)
     add("api-version", "apiVersion must be 1", "apiVersion");
@@ -896,15 +896,15 @@ function validateNodeDefinition(value) {
     );
   const seen = /* @__PURE__ */ new Set();
   for (const [index, capability] of (Array.isArray(value.capabilities) ? value.capabilities : []).entries()) {
-    const path24 = `capabilities.${index}`;
+    const path25 = `capabilities.${index}`;
     if (!seen.has(capability) && !allowed.includes(capability))
       add(
         "capability-not-allowed",
         `${String(capability)} is not available on ${String(environment)}`,
-        path24
+        path25
       );
     if (seen.has(capability))
-      add("duplicate-capability", `${String(capability)} is duplicated`, path24);
+      add("duplicate-capability", `${String(capability)} is duplicated`, path25);
     seen.add(capability);
   }
   const inward = /* @__PURE__ */ new Map();
@@ -917,31 +917,31 @@ function validateNodeDefinition(value) {
       continue;
     }
     for (const [name, raw] of Object.entries(entries2)) {
-      const path24 = `${section}.${name}`;
+      const path25 = `${section}.${name}`;
       if (!IDENTIFIER.test(name))
-        add("invalid-name", `${name} is not a valid identifier`, path24);
-      if (RESERVED.has(name)) add("reserved-name", `${name} is reserved`, path24);
+        add("invalid-name", `${name} is not a valid identifier`, path25);
+      if (RESERVED.has(name)) add("reserved-name", `${name} is reserved`, path25);
       const names = section === "outputs" ? outward : inward;
       const previous = names.get(name);
       if (previous)
         add(
           "name-collision",
           `${name} is declared in ${previous} and ${section}`,
-          path24
+          path25
         );
       else names.set(name, section);
       if (!isRecord2(raw)) {
-        add("invalid-entry", `${path24} must be an object`, path24);
+        add("invalid-entry", `${path25} must be an object`, path25);
         continue;
       }
       const fields2 = section === "props" ? PROP_FIELDS : section === "outputs" ? OUTPUT_FIELDS : DATA_FIELDS;
       if (section !== "props" && raw.kind !== "data" && raw.kind !== "trigger") {
         add(
           "invalid-kind",
-          `${path24}.kind must be data or trigger`,
-          `${path24}.kind`
+          `${path25}.kind must be data or trigger`,
+          `${path25}.kind`
         );
-        result.push(...unknownFields(raw, fields2, path24));
+        result.push(...unknownFields(raw, fields2, path25));
         continue;
       }
       if (section !== "props" && raw.kind === "trigger") {
@@ -951,22 +951,22 @@ function validateNodeDefinition(value) {
           add(
             "trigger-extra",
             "Trigger ports allow only kind and description",
-            path24
+            path25
           );
         continue;
       }
-      result.push(...unknownFields(raw, fields2, path24));
+      result.push(...unknownFields(raw, fields2, path25));
       if ("control" in raw && (typeof raw.control !== "string" || !CONTROLS.has(raw.control)))
         add(
           "invalid-control",
           `${String(raw.control)} is not a Cascade control`,
-          `${path24}.control`
+          `${path25}.control`
         );
       if ("options" in raw && raw.control !== "select")
         add(
           "options-without-select",
           "options require the select control",
-          `${path24}.options`
+          `${path25}.options`
         );
       if (Array.isArray(raw.options))
         for (const [index, option] of raw.options.entries()) {
@@ -976,19 +976,19 @@ function validateNodeDefinition(value) {
             add(
               "invalid-option",
               "a labelled option needs a value",
-              `${path24}.options[${index}]`
+              `${path25}.options[${index}]`
             );
           if (typeof entry.label !== "string" || !entry.label)
             add(
               "invalid-option",
               "a labelled option needs a non-empty label",
-              `${path24}.options[${index}].label`
+              `${path25}.options[${index}].label`
             );
           if ("disabled" in entry && typeof entry.disabled !== "boolean")
             add(
               "invalid-option",
               "disabled must be a boolean",
-              `${path24}.options[${index}].disabled`
+              `${path25}.options[${index}].disabled`
             );
         }
       const type = raw.type;
@@ -996,56 +996,56 @@ function validateNodeDefinition(value) {
         add(
           "invalid-type",
           `${String(type)} is not a Cascade type`,
-          `${path24}.type`
+          `${path25}.type`
         );
         continue;
       }
       if (type === "texture" && environment !== "browser")
-        add("texture-not-portable", "texture is browser-only", `${path24}.type`);
+        add("texture-not-portable", "texture is browser-only", `${path25}.type`);
       if (type === "texture" && "default" in raw)
         add(
           "texture-default",
           "texture cannot have a default",
-          `${path24}.default`
+          `${path25}.default`
         );
       if (section === "props" && !("default" in raw))
-        add("missing-default", "Props require defaults", `${path24}.default`);
+        add("missing-default", "Props require defaults", `${path25}.default`);
       if ("default" in raw && !finiteJson(raw.default))
         add(
           "invalid-default",
           "Default must be finite JSON",
-          `${path24}.default`
+          `${path25}.default`
         );
       else if ("default" in raw && !defaultMatches(type, raw.default))
         add(
           "default-type",
           `Default does not match ${type}`,
-          `${path24}.default`
+          `${path25}.default`
         );
       if (type === "int" && "default" in raw && (!Number.isFinite(raw.default) || !Number.isInteger(raw.default)))
         add(
           "non-integer",
           "Integer defaults must be finite integers",
-          `${path24}.default`
+          `${path25}.default`
         );
       if ("step" in raw && (typeof raw.step !== "number" || !Number.isFinite(raw.step) || raw.step <= 0))
-        add("invalid-step", "step must be greater than zero", `${path24}.step`);
+        add("invalid-step", "step must be greater than zero", `${path25}.step`);
       if (section === "props" && "expression" in raw && (typeof raw.expression !== "string" || raw.expression.length === 0))
         add(
           "invalid-expression",
           "expression must be a non-empty string",
-          `${path24}.expression`
+          `${path25}.expression`
         );
       for (const field of ["min", "max"]) {
         if (field in raw && (typeof raw[field] !== "number" || !Number.isFinite(raw[field])))
           add(
             `invalid-${field}`,
             `${field} must be a finite number`,
-            `${path24}.${field}`
+            `${path25}.${field}`
           );
       }
       if (typeof raw.min === "number" && typeof raw.max === "number" && raw.min > raw.max)
-        add("invalid-range", "min must not exceed max", path24);
+        add("invalid-range", "min must not exceed max", path25);
     }
   }
   return result;
@@ -1741,10 +1741,10 @@ var init_evaluator = __esm({
           fframe: this.timeState.frameFraction,
           fps: this.timeState.fps,
           self: node,
-          ch: (path24) => this.ch(node, path24),
-          chs: (path24) => this.chs(node, path24),
-          chv: (path24) => this.chv(node, path24),
-          opexist: (path24) => this.scope?.nodeExists(node, path24) ? 1 : 0,
+          ch: (path25) => this.ch(node, path25),
+          chs: (path25) => this.chs(node, path25),
+          chv: (path25) => this.chv(node, path25),
+          opexist: (path25) => this.scope?.nodeExists(node, path25) ? 1 : 0,
           opinput: (index) => this.scope?.inputNode(node, index) ?? null,
           fit,
           fit01,
@@ -1761,8 +1761,8 @@ var init_evaluator = __esm({
         };
       }
       // ============ Channel functions ============
-      ch(node, path24) {
-        const resolved = this.resolveParam(node, path24);
+      ch(node, path25) {
+        const resolved = this.resolveParam(node, path25);
         if (!resolved) return 0;
         const value = resolved.value;
         if (typeof value === "number") return value;
@@ -1770,13 +1770,13 @@ var init_evaluator = __esm({
         if (typeof value === "boolean") return value ? 1 : 0;
         return 0;
       }
-      chs(node, path24) {
-        const resolved = this.resolveParam(node, path24);
+      chs(node, path25) {
+        const resolved = this.resolveParam(node, path25);
         if (!resolved) return "";
         return String(resolved.value ?? "");
       }
-      chv(node, path24) {
-        const resolved = this.resolveParam(node, path24);
+      chv(node, path25) {
+        const resolved = this.resolveParam(node, path25);
         if (!resolved) return [];
         const value = resolved.value;
         if (Array.isArray(value)) {
@@ -1785,12 +1785,12 @@ var init_evaluator = __esm({
         if (typeof value === "number") return [value];
         return [];
       }
-      resolveParam(node, path24) {
-        return this.scope?.resolveParam(node, path24) ?? null;
+      resolveParam(node, path25) {
+        return this.scope?.resolveParam(node, path25) ?? null;
       }
       /** True if a referenced path resolves from this node. */
-      validatePath(fromNode, path24) {
-        return this.resolveParam(fromNode, path24) !== null;
+      validatePath(fromNode, path25) {
+        return this.resolveParam(fromNode, path25) !== null;
       }
       /** Parameter paths referenced through ch/chs/chv. */
       extractDependencies(expression) {
@@ -1829,14 +1829,14 @@ function geometryError(code, message2) {
 function attributeSet(geometry, level) {
   return geometry[level];
 }
-function numericAttribute(attribute, path24, sizes) {
+function numericAttribute(attribute, path25, sizes) {
   if (attribute === void 0) return void 0;
   if (isStringAttribute(attribute))
-    geometryError("attribute-storage", `${path24} must be numeric`);
+    geometryError("attribute-storage", `${path25} must be numeric`);
   if (sizes !== void 0 && !sizes.includes(attribute.size))
     geometryError(
       "attribute-size",
-      `${path24} has size ${attribute.size}; expected ${sizes.join(" or ")}`
+      `${path25} has size ${attribute.size}; expected ${sizes.join(" or ")}`
     );
   return attribute;
 }
@@ -2647,7 +2647,7 @@ function geometryToSvg(geometry, options2 = {}) {
       if (mask2[primitive] === 1 && assigned[primitive] === -1)
         assigned[primitive] = index;
   }
-  const path24 = (primitive) => {
+  const path25 = (primitive) => {
     const attributes = [`d="${pathData(geometry, primitive, number)}"`];
     const paint = paintOf(colour, primitive, "primitive");
     if (paint !== void 0) {
@@ -2666,13 +2666,13 @@ function geometryToSvg(geometry, options2 = {}) {
   const body = [];
   if (names.length === 0) {
     for (let primitive = 0; primitive < geometry.primitiveCount; primitive += 1)
-      body.push(indent(path24(primitive), 2));
+      body.push(indent(path25(primitive), 2));
   } else {
     for (let index = 0; index < names.length; index += 1) {
       const members = [];
       for (let primitive = 0; primitive < geometry.primitiveCount; primitive += 1)
         if (assigned[primitive] === index)
-          members.push(indent(path24(primitive), 3));
+          members.push(indent(path25(primitive), 3));
       body.push(
         indent(`<g id="${escapeXml(names[index])}">`, 2),
         ...members,
@@ -2681,7 +2681,7 @@ function geometryToSvg(geometry, options2 = {}) {
     }
     const rest = [];
     for (let primitive = 0; primitive < geometry.primitiveCount; primitive += 1)
-      if (assigned[primitive] === -1) rest.push(indent(path24(primitive), 3));
+      if (assigned[primitive] === -1) rest.push(indent(path25(primitive), 3));
     if (rest.length > 0)
       body.push(
         indent(`<g id="${UNGROUPED}">`, 2),
@@ -2788,11 +2788,11 @@ function validateOptions(options2) {
   if (!Number.isSafeInteger(precision) || precision < 0 || precision > 15)
     geometryError("svg-precision", "precision must be an integer from 0 to 15");
 }
-function validateRange(attribute, path24, accepts, expectation) {
+function validateRange(attribute, path25, accepts, expectation) {
   if (attribute === void 0) return;
   for (const value of attribute.data)
     if (!accepts(value))
-      geometryError("attribute-value", `${path24} values must be ${expectation}`);
+      geometryError("attribute-value", `${path25} values must be ${expectation}`);
 }
 function indent(line2, depth) {
   return `${"  ".repeat(depth)}${line2}`;
@@ -3081,8 +3081,8 @@ var init_resolve = __esm({
 });
 
 // packages/runtime/src/params/animator.ts
-function split(path24) {
-  return String(path24 ?? "").split("/").filter((segment) => segment.length > 0 && segment !== ".");
+function split(path25) {
+  return String(path25 ?? "").split("/").filter((segment) => segment.length > 0 && segment !== ".");
 }
 var PropAnimator;
 var init_animator = __esm({
@@ -3150,8 +3150,8 @@ var init_animator = __esm({
        */
       scope() {
         return {
-          resolveParam: (from, path24) => {
-            const segments = split(path24);
+          resolveParam: (from, path25) => {
+            const segments = split(path25);
             if (!segments.length) return null;
             const name = segments[segments.length - 1];
             const owner = this.owner(from, segments.slice(0, -1));
@@ -3161,8 +3161,8 @@ var init_animator = __esm({
             if (name in owner.inputs) return { value: owner.inputs[name] };
             return null;
           },
-          nodeExists: (from, path24) => {
-            const segments = split(path24);
+          nodeExists: (from, path25) => {
+            const segments = split(path25);
             if (!segments.length) return false;
             const last = segments[segments.length - 1];
             if (last === "..") return true;
@@ -5479,12 +5479,12 @@ function buildTrails(history, current, options2 = {}) {
   for (const frame of frames) {
     for (let index = 0; index < frame.id.length; index += 1) {
       const id = frame.id[index];
-      const path24 = paths.get(id) ?? [];
-      path24.push(
+      const path25 = paths.get(id) ?? [];
+      path25.push(
         frame.position[index * frame.size],
         frame.position[index * frame.size + 1]
       );
-      paths.set(id, path24);
+      paths.set(id, path25);
     }
   }
   if (result === "velocity") {
@@ -5492,11 +5492,11 @@ function buildTrails(history, current, options2 = {}) {
   }
   const builder = new GeometryBuilder({ positionSize: 2 });
   const trailIds = [];
-  for (const [id, path24] of paths) {
-    if (path24.length < 4) continue;
+  for (const [id, path25] of paths) {
+    if (path25.length < 4) continue;
     const points = [];
-    for (let at = 0; at < path24.length; at += 2) {
-      points.push(builder.addPoint(path24[at], path24[at + 1]));
+    for (let at = 0; at < path25.length; at += 2) {
+      points.push(builder.addPoint(path25[at], path25[at + 1]));
     }
     builder.addPrimitive(points, { closed: false, kind: "poly" });
     trailIds.push(id);
@@ -5541,11 +5541,11 @@ function withDerivedVelocity(current, paths, velocityscale) {
   const ids = current.point.id?.data;
   const velocity = new Float32Array(current.pointCount * size);
   for (let index = 0; index < current.pointCount; index += 1) {
-    const path24 = ids ? paths.get(Number(ids[index])) : void 0;
-    if (!path24 || path24.length < 4) continue;
-    const last = path24.length;
-    velocity[index * size] = (path24[last - 2] - path24[last - 4]) * velocityscale;
-    velocity[index * size + 1] = (path24[last - 1] - path24[last - 3]) * velocityscale;
+    const path25 = ids ? paths.get(Number(ids[index])) : void 0;
+    if (!path25 || path25.length < 4) continue;
+    const last = path25.length;
+    velocity[index * size] = (path25[last - 2] - path25[last - 4]) * velocityscale;
+    velocity[index * size + 1] = (path25[last - 1] - path25[last - 3]) * velocityscale;
   }
   return {
     ...current,
@@ -7063,16 +7063,16 @@ function cloneValue(value, ancestors) {
   ancestors.delete(value);
   return Object.freeze(clone);
 }
-function runtimeValue(value, type, allowUndefined, path24) {
+function runtimeValue(value, type, allowUndefined, path25) {
   if (value === void 0) {
     if (allowUndefined) return void 0;
-    misuse("runtime/value-type", `${path24} requires a ${type} value`);
+    misuse("runtime/value-type", `${path25} requires a ${type} value`);
   }
   const tupleLength = TUPLE_LENGTHS[type];
   const valid = type === "float" && typeof value === "number" && Number.isFinite(value) || type === "int" && typeof value === "number" && Number.isInteger(value) || type === "bool" && typeof value === "boolean" || type === "string" && typeof value === "string" || tupleLength !== void 0 && Array.isArray(value) && value.length === tupleLength && value.every(
     (item) => type.endsWith("i") ? typeof item === "number" && Number.isInteger(item) : typeof item === "number" && Number.isFinite(item)
   ) || !tupleLength && type !== "float" && type !== "int" && type !== "bool" && type !== "string";
-  if (!valid) misuse("runtime/value-type", `${path24} is not a valid ${type}`);
+  if (!valid) misuse("runtime/value-type", `${path25} is not a valid ${type}`);
   return snapshot(value);
 }
 var PREFLIGHT_WARNING_CODES, RUN_TOLERATED_CODES, MutableAbortSignal, Runtime, Graph, TUPLE_LENGTHS;
@@ -8352,32 +8352,32 @@ function extractNodeDefinition(source, fileName, ts4) {
       diagnostics: [error.diagnostic]
     };
   }
-  function read(node, path24, depth) {
+  function read(node, path25, depth) {
     if (++visited > MAX_NODES)
       throw extraction(
         node,
         "definition/size-limit",
         "Definition exceeds 10,000 syntax nodes",
-        path24
+        path25
       );
     if (depth > MAX_DEPTH)
       throw extraction(
         node,
         "definition/depth-limit",
         "Definition exceeds 32 levels",
-        path24
+        path25
       );
     if (ts4.isParenthesizedExpression(node) || ts4.isSatisfiesExpression(node))
-      return read(node.expression, path24, depth + 1);
+      return read(node.expression, path25, depth + 1);
     if (ts4.isAsExpression(node)) {
       if (node.type.getText(file) !== "const")
         throw extraction(
           node.type,
           "definition/non-literal",
           "Only 'as const' assertions are allowed",
-          path24
+          path25
         );
-      return read(node.expression, path24, depth + 1);
+      return read(node.expression, path25, depth + 1);
     }
     if (ts4.isStringLiteral(node) || ts4.isNoSubstitutionTemplateLiteral(node))
       return node.text;
@@ -8394,9 +8394,9 @@ function extractNodeDefinition(source, fileName, ts4) {
             element,
             "definition/spread",
             "Spreads are not allowed",
-            `${path24}.${index}`
+            `${path25}.${index}`
           );
-        return read(element, `${path24}.${index}`, depth + 1);
+        return read(element, `${path25}.${index}`, depth + 1);
       });
     if (ts4.isObjectLiteralExpression(node)) {
       const object = /* @__PURE__ */ Object.create(null);
@@ -8407,14 +8407,14 @@ function extractNodeDefinition(source, fileName, ts4) {
             property,
             "definition/spread",
             "Spreads are not allowed",
-            path24
+            path25
           );
         if (!ts4.isPropertyAssignment(property) || property.name && ts4.isComputedPropertyName(property.name))
           throw extraction(
             property,
             "definition/non-literal",
             "Only explicit properties are allowed",
-            path24
+            path25
           );
         const key2 = ts4.isIdentifier(property.name) || ts4.isStringLiteral(property.name) || ts4.isNumericLiteral(property.name) ? property.name.text : void 0;
         if (key2 === void 0)
@@ -8422,17 +8422,17 @@ function extractNodeDefinition(source, fileName, ts4) {
             property,
             "definition/non-literal",
             "Property name must be literal",
-            path24
+            path25
           );
         if (keys.has(key2))
           throw extraction(
             property.name,
             "definition/duplicate-key",
             `Duplicate key ${key2}`,
-            `${path24}.${key2}`
+            `${path25}.${key2}`
           );
         keys.add(key2);
-        object[key2] = read(property.initializer, `${path24}.${key2}`, depth + 1);
+        object[key2] = read(property.initializer, `${path25}.${key2}`, depth + 1);
       }
       return object;
     }
@@ -8440,19 +8440,19 @@ function extractNodeDefinition(source, fileName, ts4) {
       node,
       "definition/non-literal",
       `Unsupported ${ts4.SyntaxKind[node.kind]}`,
-      path24
+      path25
     );
   }
   function location(node) {
     const point = file.getLineAndCharacterOfPosition(node.getStart(file));
     return { line: point.line + 1, column: point.character + 1 };
   }
-  function extraction(node, code, message2, path24) {
+  function extraction(node, code, message2, path25) {
     return new ExtractionFailure({
       phase: "definition",
       code,
       message: message2,
-      path: path24,
+      path: path25,
       file: fileName,
       ...location(node)
     });
@@ -9568,13 +9568,14 @@ export function execute(node, graph) {
 import fs6 from "node:fs/promises";
 import path6 from "node:path";
 function createNodeFileCapability(project) {
-  const root = path6.resolve(project.resolve("."));
   const within3 = (relative, what) => {
-    const clean = relative.replace(/^\.?\//, "");
-    const full = path6.resolve(project.resolve(clean));
-    if (full !== root && !full.startsWith(`${root}${path6.sep}`))
-      throw new Error(`files: ${what} outside the project is refused \u2014 ${relative}`);
-    return full;
+    try {
+      return project.resolve(relative.replace(/^\.?\//, ""));
+    } catch (error) {
+      throw new Error(
+        `files: ${what} outside the project is refused \u2014 ${relative} (${error instanceof Error ? error.message : String(error)})`
+      );
+    }
   };
   const cacheOnly = (relative) => {
     const clean = relative.replace(/^\.?\//, "");
@@ -9974,6 +9975,7 @@ async function renderDeterministicProjectFrames(file, document2, options2) {
   try {
     graph = await runtime.load(document2);
     reportPreflightWarnings(host, classifyPreflight(graph.preflight()).warnings);
+    const targets = options2.nodes?.length ? options2.nodes : options2.entryNode ? [options2.entryNode] : [];
     const outDirectory = project.resolve(options2.out);
     await fs8.mkdir(outDirectory, { recursive: true });
     for (const frame of frameRange(options2.start, options2.end, options2.step ?? 1)) {
@@ -9984,17 +9986,24 @@ async function renderDeterministicProjectFrames(file, document2, options2) {
       const result = await graph.run({
         frame,
         ...options2.fps === void 0 ? {} : { fps: options2.fps },
-        ...options2.entryNode ? { target: { kind: "node", nodeId: options2.entryNode } } : {}
+        /**
+         * One named node narrows the COOK as well as the output, because the
+         * runtime can walk back from a single target. Several cannot be
+         * expressed as one target, so the graph cooks whole and only the saving
+         * narrows — which is still the bulk of the win when the outputs are
+         * 18 MB PNGs.
+         */
+        ...targets.length === 1 ? { target: { kind: "node", nodeId: targets[0] } } : {}
       });
       if (result.status !== "completed") {
         throw new Error(
           `frame ${frame} ${result.status} \u2014 ${result.diagnostics.map((item) => item.message).join("; ") || "no diagnostics"}`
         );
       }
-      const outputs = imageOutputs(graph, options2.entryNode);
+      const outputs = imageOutputs(graph, targets);
       if (!outputs.length) {
         throw new Error(
-          "No image output to save: the graph has no unconsumed image port. Name the node to render with --entry-node."
+          targets.length ? `No image output on ${targets.join(", ")} \u2014 check the node id, and that it has an image output.` : "No image output to save: the graph has no unconsumed image port. Name the node to render with --node."
         );
       }
       for (const { nodeId, value } of outputs) {
@@ -10023,13 +10032,14 @@ async function renderDeterministicProjectFrames(file, document2, options2) {
 async function disposeProjectGpu(host) {
   await host.capabilities.gpu?.dispose();
 }
-function imageOutputs(graph, entryNode) {
+function imageOutputs(graph, nodes = []) {
+  const wanted = new Set(nodes);
   const found = [];
   for (const node of graph.inspect().nodes) {
-    if (entryNode && node.id !== entryNode) continue;
+    if (wanted.size && !wanted.has(node.id)) continue;
     for (const port of Object.values(node.outputs)) {
       if (port.type !== "image") continue;
-      if (!entryNode && port.connected) continue;
+      if (!wanted.size && port.connected) continue;
       if (port.value === void 0) continue;
       found.push({ nodeId: node.id, value: port.value });
     }
@@ -11011,6 +11021,8 @@ var init_git = __esm({
 
 // server/src/routes/graph.ts
 import { Router } from "express";
+import fs14 from "node:fs/promises";
+import path17 from "node:path";
 function handleError(res, err) {
   if (err instanceof PathSafetyError) {
     res.status(400).json({ error: err.message });
@@ -11063,6 +11075,42 @@ function createGraphRouter(project) {
       handleError(res, err);
     }
   });
+  router.get("/:filename/workspace", async (req, res) => {
+    try {
+      const target = workspacePath(project, req.params.filename);
+      await fs14.access(project.resolve(req.params.filename));
+      let content;
+      try {
+        content = await fs14.readFile(target, "utf-8");
+      } catch (err) {
+        if (err?.code === "ENOENT") {
+          res.json(null);
+          return;
+        }
+        throw err;
+      }
+      res.type("application/json").send(content);
+    } catch (err) {
+      handleError(res, err);
+    }
+  });
+  router.put("/:filename/workspace", async (req, res) => {
+    try {
+      const body = req.body;
+      if (!body || typeof body !== "object" || Array.isArray(body) || !body.layout || typeof body.layout !== "object") {
+        res.status(400).json({ error: "a workspace is an object with a layout" });
+        return;
+      }
+      const slot = req.query.slot === "failed" ? "failed" : null;
+      const target = workspacePath(project, req.params.filename, slot);
+      const temporary = `${target}.${process.pid}.tmp`;
+      await fs14.writeFile(temporary, JSON.stringify(body, null, 1), "utf-8");
+      await fs14.rename(temporary, target);
+      res.json({ ok: true, file: path17.basename(target) });
+    } catch (err) {
+      handleError(res, err);
+    }
+  });
   router.get("/:filename/versions", async (req, res) => {
     try {
       const filename = req.params.filename;
@@ -11100,6 +11148,13 @@ function createGraphRouter(project) {
   });
   return router;
 }
+function workspacePath(project, filename, slot = null) {
+  if (!filename.endsWith(".cascade") || filename !== path17.basename(filename)) {
+    throw new PathSafetyError(`not a .cascade file: ${filename}`);
+  }
+  const stem = filename.slice(0, -".cascade".length);
+  return project.resolve(`${stem}.workspace${slot ? `.${slot}` : ""}.json`);
+}
 function saveCommitMessage(filename, at = /* @__PURE__ */ new Date()) {
   const time = at.toLocaleTimeString("en-GB", { hour: "2-digit", minute: "2-digit", hour12: false });
   return `Saved ${filename} ${time}`;
@@ -11116,8 +11171,8 @@ var init_graph = __esm({
 // server/src/routes/assets.ts
 import { Router as Router2 } from "express";
 import multer from "multer";
-import path17 from "path";
-import fs14 from "fs/promises";
+import path18 from "path";
+import fs15 from "fs/promises";
 function handleError2(res, err) {
   if (err instanceof PathSafetyError) {
     res.status(400).json({ error: err.message });
@@ -11133,8 +11188,8 @@ function createAssetsRouter(project) {
       let assetType = "data";
       if (file.mimetype.startsWith("image/")) assetType = "images";
       else if (file.mimetype.startsWith("audio/")) assetType = "audio";
-      const dir = path17.join(assetsRoot, assetType);
-      await fs14.mkdir(dir, { recursive: true });
+      const dir = path18.join(assetsRoot, assetType);
+      await fs15.mkdir(dir, { recursive: true });
       cb(null, dir);
     },
     filename: (_req, file, cb) => cb(null, file.originalname)
@@ -11145,7 +11200,7 @@ function createAssetsRouter(project) {
       res.status(400).json({ error: "no file uploaded" });
       return;
     }
-    const relativePath = path17.relative(assetsRoot, req.file.path);
+    const relativePath = path18.relative(assetsRoot, req.file.path);
     res.json({
       id: req.file.filename,
       path: `./assets/${relativePath}`,
@@ -11171,7 +11226,7 @@ function createAssetsRouter(project) {
     try {
       const rel = req.params.assetPath?.join("/") ?? "";
       const full = resolveWithinRoot(assetsRoot, rel);
-      await fs14.unlink(full);
+      await fs15.unlink(full);
       res.json({ ok: true });
     } catch (err) {
       handleError2(res, err);
@@ -11187,10 +11242,10 @@ var init_assets = __esm({
 });
 
 // server/src/nodeWatch.ts
-import fs15 from "node:fs";
-import path18 from "node:path";
+import fs16 from "node:fs";
+import path19 from "node:path";
 function moduleNameFor(relative) {
-  const segments = relative.split(path18.sep).filter(Boolean);
+  const segments = relative.split(path19.sep).filter(Boolean);
   if (segments.length < 2) return null;
   const name = segments[0];
   if (!name || name.startsWith(".")) return null;
@@ -11212,9 +11267,9 @@ function createNodeWatcher(project) {
     );
   }
   function watch(directory, scope) {
-    if (!fs15.existsSync(directory)) return;
+    if (!fs16.existsSync(directory)) return;
     try {
-      const watcher = fs15.watch(directory, { recursive: true }, (_event, filename) => {
+      const watcher = fs16.watch(directory, { recursive: true }, (_event, filename) => {
         if (!filename) return;
         if (scope === "shared") {
           emit(ALL_MODULES);
@@ -11231,8 +11286,8 @@ function createNodeWatcher(project) {
   }
   watch(project.resolve("nodes"), "project");
   try {
-    const sharedNodes = fs15.realpathSync(path18.join(project.root, "shared"));
-    watch(path18.join(sharedNodes, "nodes"), "shared");
+    const sharedNodes = fs16.realpathSync(path19.join(project.root, "shared"));
+    watch(path19.join(sharedNodes, "nodes"), "shared");
   } catch {
   }
   return {
@@ -11902,15 +11957,15 @@ var init_eventBuffer = __esm({
 });
 
 // server/src/agent/allowlist.ts
-import fs16 from "node:fs";
+import fs17 from "node:fs";
 import os4 from "node:os";
-import path19 from "node:path";
+import path20 from "node:path";
 function allowlistHint(root, alias) {
   return `Add this under "commands" in ${root}/cascade.json: "${alias}": "<path>"`;
 }
 function readManifest(root) {
   try {
-    return JSON.parse(fs16.readFileSync(path19.join(root, "cascade.json"), "utf8"));
+    return JSON.parse(fs17.readFileSync(path20.join(root, "cascade.json"), "utf8"));
   } catch {
     return {};
   }
@@ -11930,8 +11985,8 @@ function agentExtraArgs(root, alias) {
 }
 function executableFile2(candidate) {
   try {
-    fs16.accessSync(candidate, fs16.constants.X_OK);
-    return fs16.statSync(candidate).isFile() ? fs16.realpathSync(candidate) : null;
+    fs17.accessSync(candidate, fs17.constants.X_OK);
+    return fs17.statSync(candidate).isFile() ? fs17.realpathSync(candidate) : null;
   } catch {
     return null;
   }
@@ -11939,10 +11994,10 @@ function executableFile2(candidate) {
 function resolveExecutable2(target) {
   if (typeof target !== "string" || !target || target.includes("\0")) return null;
   const expanded = target.replace(/^~(?=\/|$)/, os4.homedir());
-  if (path19.isAbsolute(expanded)) return executableFile2(expanded);
+  if (path20.isAbsolute(expanded)) return executableFile2(expanded);
   if (!/[\\/]/.test(expanded)) {
-    for (const dir of (process.env.PATH ?? "").split(path19.delimiter)) {
-      const found = executableFile2(path19.join(dir, expanded));
+    for (const dir of (process.env.PATH ?? "").split(path20.delimiter)) {
+      const found = executableFile2(path20.join(dir, expanded));
       if (found) return found;
     }
     return null;
@@ -12393,7 +12448,7 @@ var init_agent = __esm({
 });
 
 // server/src/graphWatch.ts
-import fs17 from "node:fs";
+import fs18 from "node:fs";
 function graphFileFor(relative) {
   const segments = String(relative).split(/[\\/]/).filter(Boolean);
   if (segments.length !== 1) return null;
@@ -12418,7 +12473,7 @@ function createGraphWatcher(project) {
     );
   }
   try {
-    watcher = fs17.watch(project.root, { recursive: false }, (_event, filename) => {
+    watcher = fs18.watch(project.root, { recursive: false }, (_event, filename) => {
       if (!filename) return;
       const graph = graphFileFor(String(filename));
       if (graph) emit(graph);
@@ -12604,8 +12659,8 @@ var init_net = __esm({
 // server/src/routes/media.ts
 import express, { Router as Router11 } from "express";
 import crypto2 from "crypto";
-import fs18 from "fs";
-import path20 from "path";
+import fs19 from "fs";
+import path21 from "path";
 async function loadSharp() {
   if (sharpModule) return sharpModule;
   if (sharpError) throw new Error(sharpError);
@@ -12692,11 +12747,11 @@ function fieldToGrey(array) {
 }
 function contentAddressed2(rel, body) {
   const hash2 = crypto2.createHash("sha1").update(body).digest("hex").slice(0, 12);
-  const dir = path20.posix.dirname(rel);
-  const name = path20.posix.basename(rel);
+  const dir = path21.posix.dirname(rel);
+  const name = path21.posix.basename(rel);
   const [stem, ...rest] = name.split(".");
   const tail = rest.length ? `.${rest.join(".")}` : "";
-  return path20.posix.join(dir, `${stem}.${hash2}${tail}`);
+  return path21.posix.join(dir, `${stem}.${hash2}${tail}`);
 }
 function clampInt(value, min, max) {
   const n = Number(value);
@@ -12718,8 +12773,8 @@ function createMediaRouter(project) {
     try {
       const target = req.query.exact === "1" ? rel : contentAddressed2(rel, req.body);
       const full = project.resolve(target);
-      await fs18.promises.mkdir(path20.dirname(full), { recursive: true });
-      await fs18.promises.writeFile(full, req.body);
+      await fs19.promises.mkdir(path21.dirname(full), { recursive: true });
+      await fs19.promises.writeFile(full, req.body);
       res.json({ ok: true, path: target, bytes: req.body.length });
     } catch (err) {
       res.status(err instanceof PathSafetyError ? 400 : 500).json({ error: String(err) });
@@ -12736,13 +12791,13 @@ function createMediaRouter(project) {
     }
     let stat;
     try {
-      stat = await fs18.promises.stat(full);
+      stat = await fs19.promises.stat(full);
       if (!stat.isFile()) throw new Error("not a file");
     } catch {
       res.status(404).json({ error: `no such file: ${rel}` });
       return;
     }
-    const ext = path20.extname(full).toLowerCase();
+    const ext = path21.extname(full).toLowerCase();
     const width = clampInt(req.query.w, 1, 2e4);
     const quality = clampInt(req.query.q, 1, 100) ?? 82;
     const requested = String(req.query.fmt ?? "").toLowerCase();
@@ -12756,7 +12811,7 @@ function createMediaRouter(project) {
     }
     if (!raw && ext === ".npy") {
       try {
-        const array = readNpy(await fs18.promises.readFile(full));
+        const array = readNpy(await fs19.promises.readFile(full));
         const { pixels, min, max } = fieldToGrey(array);
         res.setHeader("X-Field-Shape", `${array.height}x${array.width}`);
         res.setHeader("X-Field-Range", `${min}:${max}`);
@@ -12787,7 +12842,7 @@ function createMediaRouter(project) {
     if (raw || !RASTER.has(ext)) {
       res.type(MIME[ext] ?? "application/octet-stream");
       res.setHeader("Content-Length", String(stat.size));
-      fs18.createReadStream(full).pipe(res);
+      fs19.createReadStream(full).pipe(res);
       return;
     }
     let format2 = requested;
@@ -12795,7 +12850,7 @@ function createMediaRouter(project) {
     if (format2 === "gif") {
       res.type("image/gif");
       res.setHeader("Content-Length", String(stat.size));
-      fs18.createReadStream(full).pipe(res);
+      fs19.createReadStream(full).pipe(res);
       return;
     }
     try {
@@ -12862,11 +12917,11 @@ var init_media = __esm({
 });
 
 // server/src/build.ts
-import fs19 from "node:fs";
+import fs20 from "node:fs";
 import { createHash } from "node:crypto";
 function buildId(distDir) {
   try {
-    const contents = fs19.readFileSync(`${distDir}/index.html`);
+    const contents = fs20.readFileSync(`${distDir}/index.html`);
     return createHash("sha256").update(contents).digest("hex").slice(0, 16);
   } catch {
     return null;
@@ -12881,8 +12936,8 @@ var init_build = __esm({
 // server/src/index.ts
 import express2 from "express";
 import { createServer } from "http";
-import path21 from "path";
-import fs20 from "fs";
+import path22 from "path";
+import fs21 from "fs";
 import { fileURLToPath as fileURLToPath3 } from "url";
 function startServer(project, opts = {}) {
   const app = express2();
@@ -12949,7 +13004,7 @@ function startServer(project, opts = {}) {
   app.get("/api/build", (_req, res) => {
     res.json({ id: buildId(CASCADE_DIST) });
   });
-  if (fs20.existsSync(CASCADE_DIST)) {
+  if (fs21.existsSync(CASCADE_DIST)) {
     app.use(express2.static(CASCADE_DIST, {
       setHeaders(res, filePath) {
         res.setHeader(
@@ -12961,7 +13016,7 @@ function startServer(project, opts = {}) {
     app.get("/{*splat}", (req, res, next) => {
       if (req.path.startsWith("/api") || req.path === "/health") return next();
       res.setHeader("Cache-Control", "no-store");
-      res.sendFile(path21.join(CASCADE_DIST, "index.html"));
+      res.sendFile(path22.join(CASCADE_DIST, "index.html"));
     });
   } else {
     console.warn(`[cascade-server] no build found at ${CASCADE_DIST} \u2014 run "npm run build" in the Cascade repo first. API-only for now.`);
@@ -12994,18 +13049,18 @@ var init_src3 = __esm({
     init_build();
     init_service();
     __filename = fileURLToPath3(import.meta.url);
-    __dirname = path21.dirname(__filename);
-    CASCADE_DIST = path21.resolve(__dirname, "..", "..", "dist");
+    __dirname = path22.dirname(__filename);
+    CASCADE_DIST = path22.resolve(__dirname, "..", "..", "dist");
   }
 });
 
 // server/src/projectTemplate.ts
-import fs21 from "node:fs";
-import path22 from "node:path";
+import fs22 from "node:fs";
+import path23 from "node:path";
 function cascadeVersionRange() {
   try {
     const pkg = JSON.parse(
-      fs21.readFileSync(new URL("../../package.json", import.meta.url), "utf8")
+      fs22.readFileSync(new URL("../../package.json", import.meta.url), "utf8")
     );
     const match = /^(\d+)\.(\d+)\./.exec(pkg.version ?? "");
     return match ? `^${match[1]}.${match[2]}.0` : "*";
@@ -13017,14 +13072,14 @@ function createProject(projectsRoot, name) {
   if (!PROJECT_NAME.test(name)) {
     throw new Error("Project names use lowercase letters, numbers, and hyphens (maximum 64 characters).");
   }
-  const root = path22.resolve(projectsRoot);
-  const directory = path22.resolve(root, name);
-  if (path22.dirname(directory) !== root) throw new Error("Project path escapes the configured projects directory.");
-  if (fs21.existsSync(directory)) throw new Error(`Already exists: ${directory}`);
-  fs21.mkdirSync(path22.join(directory, "nodes"), { recursive: true });
-  fs21.mkdirSync(path22.join(directory, "assets"));
-  writeJson(path22.join(directory, "cascade.json"), { name });
-  writeJson(path22.join(directory, "index.cascade"), {
+  const root = path23.resolve(projectsRoot);
+  const directory = path23.resolve(root, name);
+  if (path23.dirname(directory) !== root) throw new Error("Project path escapes the configured projects directory.");
+  if (fs22.existsSync(directory)) throw new Error(`Already exists: ${directory}`);
+  fs22.mkdirSync(path23.join(directory, "nodes"), { recursive: true });
+  fs22.mkdirSync(path23.join(directory, "assets"));
+  writeJson(path23.join(directory, "cascade.json"), { name });
+  writeJson(path23.join(directory, "index.cascade"), {
     name,
     version: "0.2",
     viewport: { x: 0, y: 0, zoom: 1 },
@@ -13032,7 +13087,7 @@ function createProject(projectsRoot, name) {
     connections: [],
     annotations: []
   });
-  writeJson(path22.join(directory, "package.json"), {
+  writeJson(path23.join(directory, "package.json"), {
     name,
     private: true,
     type: "module",
@@ -13052,7 +13107,7 @@ function createProject(projectsRoot, name) {
       typescript: "^6.0.0"
     }
   });
-  writeJson(path22.join(directory, "tsconfig.json"), {
+  writeJson(path23.join(directory, "tsconfig.json"), {
     compilerOptions: {
       target: "ES2022",
       module: "ESNext",
@@ -13062,8 +13117,8 @@ function createProject(projectsRoot, name) {
     },
     include: ["nodes/**/*.ts"]
   });
-  fs21.writeFileSync(path22.join(directory, ".gitignore"), ".cascade-cache/\nrenders/\nnode_modules/\n");
-  fs21.writeFileSync(path22.join(directory, "AGENTS.md"), `# Cascade project
+  fs22.writeFileSync(path23.join(directory, ".gitignore"), ".cascade-cache/\nrenders/\nnode_modules/\n");
+  fs22.writeFileSync(path23.join(directory, "AGENTS.md"), `# Cascade project
 
 Read \`node_modules/cascade/AGENTS.md\` for the framework itself. What follows is what an agent working in *this* project needs.
 
@@ -13218,14 +13273,14 @@ function createNode(projectRoot, name) {
   if (!NODE_NAME.test(name)) {
     throw new Error("Node names start with an uppercase letter and contain only letters or numbers.");
   }
-  const directory = path22.resolve(projectRoot, "nodes", name);
-  if (fs21.existsSync(directory)) throw new Error(`Already exists: ${directory}`);
-  fs21.mkdirSync(directory, { recursive: true });
-  fs21.writeFileSync(path22.join(directory, "index.ts"), nodeSource(name));
+  const directory = path23.resolve(projectRoot, "nodes", name);
+  if (fs22.existsSync(directory)) throw new Error(`Already exists: ${directory}`);
+  fs22.mkdirSync(directory, { recursive: true });
+  fs22.writeFileSync(path23.join(directory, "index.ts"), nodeSource(name));
   return directory;
 }
 function writeJson(file, value) {
-  fs21.writeFileSync(file, `${JSON.stringify(value, null, 2)}
+  fs22.writeFileSync(file, `${JSON.stringify(value, null, 2)}
 `);
 }
 function nodeSource(name) {
@@ -13263,8 +13318,8 @@ __export(cliCommands_exports, {
   parseStudioArgs: () => parseStudioArgs,
   runStudioCli: () => runStudioCli
 });
-import fs22 from "node:fs";
-import path23 from "node:path";
+import fs23 from "node:fs";
+import path24 from "node:path";
 import { execFile as execFile5 } from "node:child_process";
 function parseStudioArgs(args) {
   const positional = [];
@@ -13319,7 +13374,7 @@ async function runStudioCli(args) {
   const config = loadConfig2();
   if (positional[0] === "projects") {
     if (positional[1]) {
-      saveConfig({ projectsRoot: path23.resolve(positional[1].replace(/^~(?=\/|$)/, process.env.HOME ?? "~")) });
+      saveConfig({ projectsRoot: path24.resolve(positional[1].replace(/^~(?=\/|$)/, process.env.HOME ?? "~")) });
       console.log(`[cascade] projects root set to ${loadConfig2().projectsRoot} (${configPath()})`);
     } else console.log(loadConfig2().projectsRoot);
     return;
@@ -13338,9 +13393,9 @@ async function runStudioCli(args) {
     return;
   }
   let target = positional[0] ?? ".";
-  if (!fs22.existsSync(path23.resolve(target))) {
-    const projectTarget = path23.resolve(config.projectsRoot, target);
-    if (fs22.existsSync(projectTarget)) target = projectTarget;
+  if (!fs23.existsSync(path24.resolve(target))) {
+    const projectTarget = path24.resolve(config.projectsRoot, target);
+    if (fs23.existsSync(projectTarget)) target = projectTarget;
   }
   const project = ProjectRoot.fromArg(target);
   const server = startServer(project, { host, port, trustedHosts });
@@ -13486,8 +13541,8 @@ var ExpressionEngine = class extends ExpressionEvaluator {
     super();
     this.graph = null;
     const scope = {
-      resolveParam: (from, path24) => this.resolveNodePath(from, path24),
-      nodeExists: (from, path24) => from.node(path24) !== null,
+      resolveParam: (from, path25) => this.resolveNodePath(from, path25),
+      nodeExists: (from, path25) => from.node(path25) !== null,
       inputNode: (from, index) => this.resolveInput(from, index)
     };
     this.setScope(scope);
@@ -13501,15 +13556,15 @@ var ExpressionEngine = class extends ExpressionEvaluator {
   /**
    * Resolve a path to get the parameter value
    */
-  resolveNodePath(fromNode, path24) {
-    const lastSlash = path24.lastIndexOf("/");
-    if (lastSlash === -1 || path24.startsWith("./")) {
-      const paramName2 = path24.replace("./", "");
+  resolveNodePath(fromNode, path25) {
+    const lastSlash = path25.lastIndexOf("/");
+    if (lastSlash === -1 || path25.startsWith("./")) {
+      const paramName2 = path25.replace("./", "");
       const prop2 = fromNode.props[paramName2];
       return prop2 ? { value: prop2.value } : null;
     }
-    const nodePath = path24.substring(0, lastSlash) || ".";
-    const paramName = path24.substring(lastSlash + 1);
+    const nodePath = path25.substring(0, lastSlash) || ".";
+    const paramName = path25.substring(lastSlash + 1);
     const targetNode = fromNode.node(nodePath);
     if (!targetNode) return null;
     const prop = targetNode.props[paramName];
@@ -13536,14 +13591,14 @@ var ExpressionEngine = class extends ExpressionEvaluator {
       for (const [propKey, prop] of Object.entries(node.props)) {
         if (!prop.expression) continue;
         const paths = this.extractDependencies(prop.expression);
-        for (const path24 of paths) {
-          if (!this.validatePath(node, path24)) {
+        for (const path25 of paths) {
+          if (!this.validatePath(node, path25)) {
             warnings.push({
               nodeId: node.id,
               nodePath: node.path(),
               propName: propKey,
               expression: prop.expression,
-              brokenPath: path24
+              brokenPath: path25
             });
           }
         }
@@ -13584,24 +13639,24 @@ var CascadeContext = class {
   /**
    * Find a node by path (absolute or relative to pwd)
    */
-  node(path24) {
+  node(path25) {
     if (!this._graph) return null;
-    if (path24.startsWith("/")) {
-      return this.resolveAbsolutePath(path24);
+    if (path25.startsWith("/")) {
+      return this.resolveAbsolutePath(path25);
     }
     if (this._pwd) {
-      return this._pwd.node(path24);
+      return this._pwd.node(path25);
     }
-    return this.resolveAbsolutePath("/" + path24);
+    return this.resolveAbsolutePath("/" + path25);
   }
   /**
    * Find a parameter by path (e.g., "/node1/radius")
    */
-  parm(path24) {
-    const lastSlash = path24.lastIndexOf("/");
+  parm(path25) {
+    const lastSlash = path25.lastIndexOf("/");
     if (lastSlash === -1) return null;
-    const nodePath = path24.substring(0, lastSlash) || "/";
-    const parmName = path24.substring(lastSlash + 1);
+    const nodePath = path25.substring(0, lastSlash) || "/";
+    const parmName = path25.substring(lastSlash + 1);
     const node = this.node(nodePath);
     return node?.parm(parmName) ?? null;
   }
@@ -13627,12 +13682,12 @@ var CascadeContext = class {
   /**
    * Navigate to a path (like cd command)
    */
-  cd(path24) {
-    if (path24 === "/") {
+  cd(path25) {
+    if (path25 === "/") {
       this._pwd = null;
       return;
     }
-    const target = this.node(path24);
+    const target = this.node(path25);
     if (target && target.isNetwork()) {
       this._pwd = target;
     }
@@ -13730,22 +13785,22 @@ var CascadeContext = class {
   /**
    * Get parameter value as number (shorthand)
    */
-  ch(path24) {
-    const p = this.parm(path24);
+  ch(path25) {
+    const p = this.parm(path25);
     return p?.evalAsFloat() ?? 0;
   }
   /**
    * Get parameter value as string (shorthand)
    */
-  chs(path24) {
-    const p = this.parm(path24);
+  chs(path25) {
+    const p = this.parm(path25);
     return p?.evalAsString() ?? "";
   }
   /**
    * Get parameter value as vector (shorthand)
    */
-  chv(path24) {
-    const p = this.parm(path24);
+  chv(path25) {
+    const p = this.parm(path25);
     const val = p?.eval();
     if (Array.isArray(val)) return val;
     if (typeof val === "number") return [val];
@@ -13782,9 +13837,9 @@ var CascadeContext = class {
     return this.fframe();
   }
   // ============ Internal Helpers ============
-  resolveAbsolutePath(path24) {
+  resolveAbsolutePath(path25) {
     if (!this._graph) return null;
-    const segments = path24.replace(/^\//, "").split("/").filter((s) => s.length > 0);
+    const segments = path25.replace(/^\//, "").split("/").filter((s) => s.length > 0);
     if (segments.length === 0) {
       return null;
     }
@@ -13820,7 +13875,7 @@ function parseFrameSpec(spec) {
 
 // src/cli/runner.ts
 async function runGraph(options2) {
-  const { file, entryNode, validateOnly, checkOnly, inspectOnly, strict, verbose, frames, fps, out } = options2;
+  const { file, entryNode, nodes, validateOnly, checkOnly, inspectOnly, strict, verbose, frames, fps, out } = options2;
   if (verbose) {
     console.log(`Loading graph from: ${file}`);
   }
@@ -13914,6 +13969,7 @@ async function runGraph(options2) {
         ...fps === void 0 ? {} : { fps },
         out: out ?? "renders",
         ...entryNode ? { entryNode } : {},
+        ...nodes?.length ? { nodes } : {},
         ...verbose ? { verbose } : {}
       });
       if (rendered) {
@@ -13923,7 +13979,7 @@ async function runGraph(options2) {
         return;
       }
       if (options2.json) throw new Error("--json rendering requires a fully definition-v1 graph");
-    } else if (await runDeterministicProjectGraph(file, graphData, entryNode)) {
+    } else if (await runDeterministicProjectGraph(file, graphData, nodes?.[0] ?? entryNode)) {
       if (verbose) console.log("Graph execution completed");
       releaseHost();
       return;
@@ -13939,7 +13995,7 @@ async function runGraph(options2) {
 }
 
 // src/cli/index.ts
-import * as fs23 from "fs/promises";
+import * as fs24 from "fs/promises";
 import { readFileSync } from "node:fs";
 
 // src/cli/supervise.ts
@@ -14056,7 +14112,8 @@ Options:
   --port <number>          Bind Studio HTTP to an explicit port
   --trusted-host <name>    Allow an exact remote browser hostname (repeatable)
   --no-open                Do not open Studio in a browser
-  --entry-node <id>  Execute from a specific entry node
+  --node <id>        Render only this node's output. Repeatable.
+  --entry-node <id>  Older spelling of --node, single valued
   --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)
@@ -14098,7 +14155,7 @@ image output nothing downstream consumes, or per output of --entry-node.
     process.exit(1);
   }
   try {
-    await fs23.access(fileArg);
+    await fs24.access(fileArg);
   } catch {
     console.error(`Error: File not found: ${fileArg}`);
     process.exit(1);
@@ -14114,6 +14171,11 @@ image output nothing downstream consumes, or per output of --entry-node.
   if (verboseIndex !== -1) {
     options2.verbose = true;
   }
+  const named = [];
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === "--node" && args[index + 1]) named.push(args[index + 1]);
+  }
+  if (named.length) options2.nodes = named;
   const entryNodeIndex = args.indexOf("--entry-node");
   if (entryNodeIndex !== -1 && args[entryNodeIndex + 1]) {
     options2.entryNode = args[entryNodeIndex + 1];