@field/cascade 0.11.0 → 0.13.0

package/dist/cli/{chunk-A4OAMOZH.js → chunk-NJFMDXHR.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-J7VK7MNF.js";
 import {
   CORE_TYPES
-} from "./chunk-BIJO5OFS.js";
+} from "./chunk-FWMSGKEH.js";
 
 // packages/contracts/src/validate.ts
 var IDENTIFIER = /^[A-Za-z][A-Za-z0-9_]*$/;
@@ -19,7 +19,7 @@ var CAPABILITIES_BY_ENVIRONMENT = {
 var ALLOWED = CAPABILITIES_BY_ENVIRONMENT;
 var fields = (names) => new Set(names.split(" "));
 var TOP_FIELDS = fields(
-  "apiVersion runsOn container capabilities source label description icon inputs outputs props"
+  "apiVersion runsOn container capabilities gpuLimits source label description icon inputs outputs props"
 );
 var DATA_FIELDS = fields(
   "kind type default description variadic min max step accept control options schema fields"
@@ -111,6 +111,16 @@ function validateNodeDefinition(value) {
       add("duplicate-capability", `${String(capability)} is duplicated`, path);
     seen.add(capability);
   }
+  if (value.gpuLimits !== void 0) {
+    if (!seen.has("gpu"))
+      add("gpu-limits-without-gpu", "gpuLimits needs the gpu capability", "gpuLimits");
+    if (!isRecord(value.gpuLimits))
+      add("invalid-gpu-limits", "gpuLimits must be an object of WebGPU limit names to numbers", "gpuLimits");
+    else
+      for (const [name, limit] of Object.entries(value.gpuLimits))
+        if (typeof limit !== "number" || !Number.isFinite(limit) || limit < 0)
+          add("invalid-gpu-limits", `gpuLimits.${name} must be a non-negative number`, `gpuLimits.${name}`);
+  }
   const inward = /* @__PURE__ */ new Map();
   const outward = /* @__PURE__ */ new Map();
   for (const section of ["inputs", "outputs", "props"]) {
@@ -307,4 +317,4 @@ export {
   CAPABILITIES_BY_ENVIRONMENT,
   validateNodeDefinition
 };
-//# sourceMappingURL=chunk-A4OAMOZH.js.map
+//# sourceMappingURL=chunk-NJFMDXHR.js.map

package/dist/cli/{chunk-DUIUFVU2.js → chunk-OBZAP3GG.js}

@@ -1,53 +1,60 @@
-import {
-  RunTrace,
-  captureNodeConsole
-} from "./chunk-4UDFYF5G.js";
-import {
-  installProjectStages
-} from "./chunk-QBBKRNGY.js";
 import {
   setEmbeddedCompiler,
   setProjectModuleCompiler
 } from "./chunk-2KXB47FP.js";
+import {
+  installHeadlessCanvas
+} from "./chunk-EZRWJ4G2.js";
 import {
   parseFrameSpec
 } from "./chunk-BP7UKF36.js";
 import {
   encodeMp4,
   timelineFrameSpec
-} from "./chunk-YAT5Y25U.js";
+} from "./chunk-7QE2ZNSN.js";
 import {
   applyEnv
 } from "./chunk-ZL4JTG5Y.js";
 import {
-  cascadeVersion,
-  compileEmbedded,
-  compileProjectModule,
-  formatStageTrace
-} from "./chunk-MIIEFUGG.js";
-import {
+  RunTrace,
+  captureNodeConsole,
   checkProjectGraph,
+  cookingNode,
   inspectProjectGraph,
   installProjectIo,
+  installProjectStages,
   renderDeterministicProjectFrames,
   runDeterministicProjectGraph,
   saveStillImages,
   validateProjectGraph
-} from "./chunk-EUIAC3U3.js";
+} from "./chunk-QKL7CCRS.js";
 import {
   graphSeed
-} from "./chunk-GFS6W3C5.js";
+} from "./chunk-L6B6FUQP.js";
 import {
-  ProjectRoot
-} from "./chunk-RQZ4SX5R.js";
+  frameRange
+} from "./chunk-CO22XHNG.js";
 import {
-  installHeadlessCanvas
-} from "./chunk-WIH4TEIS.js";
+  compileEmbedded,
+  compileProjectModule
+} from "./chunk-W7OUAT7J.js";
+import {
+  cascadeVersion,
+  formatStageTrace
+} from "./chunk-5ORUQ6ES.js";
+import {
+  ProjectRoot
+} from "./chunk-W5PJ5RMP.js";
 
 // src/cli/runner.ts
 import * as fs from "fs/promises";
 import * as path from "path";
 import { existsSync } from "node:fs";
+var RENDER_SUGGESTION_FRAMES = 30;
+function renderSuggestion(file, frames, count) {
+  if (count < RENDER_SUGGESTION_FRAMES) return null;
+  return `${count} frames in one process. cascade render ${file} --frames ${frames} renders them across worker processes (and encodes a preview mp4; --no-video for frames only).`;
+}
 async function runGraph(options) {
   const { file, entryNode, nodes, validateOnly, checkOnly, inspectOnly, strict, verbose, frames, fps, out } = options;
   if (verbose) {
@@ -98,6 +105,10 @@ async function runGraph(options) {
     setEmbeddedCompiler(async (code) => (await compileEmbedded(project, code)).code);
     disposeStageBridge = installProjectStages(project, {
       verbose,
+      // A render worker starts Python while the probe frames run.
+      prewarm: Boolean(options.worker),
+      // A render worker is already one of several processes: one Python each.
+      ...options.worker ? { poolSize: 1 } : {},
       onTrace: (stage) => {
         trace.recordStage(stage);
         if (verbose) console.log(`[stage] ${formatStageTrace(stage)}`);
@@ -108,10 +119,11 @@ async function runGraph(options) {
       onOutput: (stage, stream, line) => {
         const text = `[${stage ?? "stage-worker"}] ${line}`;
         if (verbose) (stream === "stderr" ? console.warn : console.log)(text);
+        else if (stage === null) cookingNode.exit(() => trace.recordLog(stream, text));
         else trace.recordLog(stream, text);
       }
     });
-    disposeIoBridge = installProjectIo(project);
+    disposeIoBridge = installProjectIo(project, { resident: true });
   } catch (error) {
     if (verbose) console.warn(`No project context for ${file}: ${error instanceof Error ? error.message : error}`);
   }
@@ -123,6 +135,10 @@ async function runGraph(options) {
     if (verbose) console.warn(canvasError.message);
   }
   const frameSpec = frames ? frames === "timeline" ? timelineFrameSpec(graphData) : parseFrameSpec(frames) : null;
+  if (frameSpec && frames && !options.worker) {
+    const hint = renderSuggestion(file, frames, frameRange(frameSpec.start, frameSpec.end, frameSpec.step ?? 1).length);
+    if (hint) (options.json ? console.error : console.log)(hint);
+  }
   const restoreConsole = captureNodeConsole(trace);
   const restoreEnv = applyEnv(options.env);
   if (options.env) trace.setEnvNames(Object.keys(options.env));
@@ -159,7 +175,11 @@ async function runGraph(options) {
         ...options.outNodes?.length ? { outNodes: options.outNodes } : {},
         ...verbose ? { verbose } : {},
         ...options.fresh ? { fresh: true } : {},
-        ...options.worker ? { frameSource: options.worker.frameSource, onFrame: options.worker.onFrame } : {},
+        ...options.worker ? { frameSource: options.worker.frameSource } : {},
+        onFrame: async (frame) => {
+          trace.recordSaved(frame.durationMs);
+          await options.worker?.onFrame(frame);
+        },
         observe
       });
       if (rendered && options.worker) {
@@ -194,11 +214,15 @@ async function runGraph(options) {
       const target = options.outNodes?.length || (nodes?.length ?? 0) > 1 ? void 0 : nodes?.[0] ?? entryNode;
       const saveImages = async (graph) => {
         if (!project) return;
+        const saving = performance.now();
         images = await saveStillImages(graph, project, {
           ...out ? { out } : {},
           ...nodes?.length ? { nodes } : entryNode ? { nodes: [entryNode] } : {},
           ...options.outNodes?.length ? { extra: options.outNodes } : {}
         });
+        const runs = trace.toJSON().runs;
+        const cook = runs[runs.length - 1]?.ms;
+        if (cook !== void 0) trace.recordSaved(cook + performance.now() - saving);
       };
       if (await runDeterministicProjectGraph(file, graphData, target, observe, saveImages)) {
         if (verbose) console.log("Graph execution completed");
@@ -236,6 +260,8 @@ Run trace: ${tracePath}`;
 }
 
 export {
+  RENDER_SUGGESTION_FRAMES,
+  renderSuggestion,
   runGraph
 };
-//# sourceMappingURL=chunk-DUIUFVU2.js.map
+//# sourceMappingURL=chunk-OBZAP3GG.js.map

package/dist/cli/chunk-QAGATJGE.js

@@ -0,0 +1,336 @@
+import {
+  installHeadlessCanvas
+} from "./chunk-EZRWJ4G2.js";
+import {
+  applyScene,
+  exportEditor,
+  formatPlan,
+  fromBase64,
+  parseScene
+} from "./chunk-JEW5MPGI.js";
+import {
+  cookProjectGraph,
+  installProjectIo
+} from "./chunk-QKL7CCRS.js";
+import {
+  ProjectRoot
+} from "./chunk-W5PJ5RMP.js";
+
+// src/cli/editorCommands.ts
+import fs from "node:fs/promises";
+import path from "node:path";
+var EDITOR_COMMANDS = ["export", "share", "freeze", "publish", "scene"];
+var EDITOR_HELP = `
+Shareable editors (see doc/EDITOR_EXPORT.md):
+  cascade export <graph> --plan                 Print what would ship, build nothing
+  cascade export <graph> --out <dir> [--deploy vercel [--project <name>] [--scope <team>] [--public]]
+  cascade share <graph | site-dir> [--name <slug>] [--scope <team>] [--protected]   Deploy as cascade-<slug>, print the link
+  cascade publish <graph> <node>.<prop> [--id <id>] [--label <text>] [--group <name>]
+                  [--control <kind>] [--min n] [--max n] [--step n] [--help <text>] [--remove]
+  cascade freeze <graph> <node> --fields <a,b.c> [--output <port>] [--personal <a,..>]
+  cascade scene <graph> <scene.json> --out <new-graph.cascade>
+  cascade run <graph> --scene <scene.json> [--write <node>.<port>=<file>]...
+`;
+async function runEditorCommand(args) {
+  const [command, graph] = args;
+  if (command === "share") {
+    const { runShareCommand } = await import("./share-B7HTCOJX.js");
+    return runShareCommand(args);
+  }
+  if (!graph || graph.startsWith("-")) throw new Error(`cascade ${command} requires a graph file`);
+  const flags = parseFlags(args.slice(2));
+  switch (command) {
+    case "export":
+      return exportCommand(graph, flags);
+    case "publish":
+      return publishCommand(graph, flags);
+    case "freeze":
+      return freezeCommand(graph, flags);
+    case "scene":
+      return sceneCommand(graph, flags);
+    case "run":
+      return runWithScene(graph, flags);
+    default:
+      throw new Error(`Unknown command ${command}`);
+  }
+}
+var SWITCHES = /* @__PURE__ */ new Set(["--plan", "--remove", "--json", "--public"]);
+function parseFlags(args) {
+  const positional = [];
+  const values = /* @__PURE__ */ new Map();
+  const switches = /* @__PURE__ */ new Set();
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index];
+    if (!arg.startsWith("--")) {
+      positional.push(arg);
+      continue;
+    }
+    if (SWITCHES.has(arg)) {
+      switches.add(arg);
+      continue;
+    }
+    const value = args[index + 1];
+    if (value === void 0 || value.startsWith("--") && !/^--?\d/.test(value)) throw new Error(`${arg} needs a value`);
+    values.set(arg, [...values.get(arg) ?? [], value]);
+    index++;
+  }
+  return { positional, values, switches };
+}
+var one = (flags, name) => {
+  const list = flags.values.get(name);
+  return list?.[list.length - 1];
+};
+async function exportCommand(graph, flags) {
+  const deploy = one(flags, "--deploy");
+  if (deploy && deploy !== "vercel") throw new Error("--deploy supports vercel only");
+  const result = await exportEditor(graph, {
+    plan: flags.switches.has("--plan"),
+    out: one(flags, "--out"),
+    ...deploy ? { deploy: "vercel" } : {},
+    project: one(flags, "--project"),
+    scope: one(flags, "--scope"),
+    ...flags.switches.has("--public") ? { public: true } : {}
+  });
+  if (flags.switches.has("--json")) console.log(JSON.stringify(result.plan, null, 2));
+  else console.log(formatPlan(result.plan));
+  if (result.directory) console.log(`
+Editor exported: ${result.directory}
+Manifest: ${path.join(result.directory, "export-manifest.json")}`);
+  if (result.url) console.log(`Deployed: ${result.url}`);
+}
+async function readGraph(file) {
+  return JSON.parse(await fs.readFile(file, "utf8"));
+}
+async function writeEditor(file, document, editor) {
+  const next = { ...document, editor };
+  await fs.writeFile(file, `${JSON.stringify(next, null, 2)}
+`);
+}
+async function publishCommand(graph, flags) {
+  const target = flags.positional[0];
+  const match = target ? /^([^.]+)\.(.+)$/.exec(target) : null;
+  if (!match) throw new Error("cascade publish needs <node>.<prop>");
+  const [, node, prop] = match;
+  const document = await readGraph(graph);
+  if (!document.nodes.some((item) => item.id === node)) throw new Error(`No node ${node} in ${graph}`);
+  const editor = document.editor ?? { id: path.basename(graph).replace(/\.cascade$/, "") };
+  const parameters = [...editor.parameters ?? []];
+  const id = one(flags, "--id") ?? prop;
+  const existing = parameters.findIndex((item) => item.node === node && item.prop === prop);
+  if (flags.switches.has("--remove")) {
+    if (existing < 0) throw new Error(`${node}.${prop} is not published`);
+    parameters.splice(existing, 1);
+    await writeEditor(graph, document, { ...editor, parameters });
+    console.log(`Unpublished ${node}.${prop}`);
+    return;
+  }
+  const number = (name) => {
+    const value = one(flags, name);
+    if (value === void 0) return void 0;
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed)) throw new Error(`${name} must be a number`);
+    return parsed;
+  };
+  const previous = existing >= 0 ? parameters[existing] : void 0;
+  const parameter = {
+    ...previous,
+    id: previous?.id ?? id,
+    node,
+    prop,
+    ...one(flags, "--label") ? { label: one(flags, "--label") } : {},
+    ...one(flags, "--group") ? { group: one(flags, "--group") } : {},
+    ...one(flags, "--control") ? { control: one(flags, "--control") } : {},
+    ...number("--min") !== void 0 ? { min: number("--min") } : {},
+    ...number("--max") !== void 0 ? { max: number("--max") } : {},
+    ...number("--step") !== void 0 ? { step: number("--step") } : {},
+    ...number("--order") !== void 0 ? { order: number("--order") } : {},
+    ...one(flags, "--help") ? { help: one(flags, "--help") } : {},
+    ...one(flags, "--unit") ? { unit: one(flags, "--unit") } : {}
+  };
+  if (existing >= 0) parameters[existing] = parameter;
+  else {
+    if (parameters.some((item) => item.id === parameter.id)) throw new Error(`Parameter id ${parameter.id} is taken; pass --id`);
+    parameters.push(parameter);
+  }
+  await writeEditor(graph, document, { ...editor, parameters });
+  console.log(`${existing >= 0 ? "Updated" : "Published"} ${node}.${prop} as "${parameter.id}"`);
+}
+async function freezeCommand(graph, flags) {
+  const node = flags.positional[0];
+  if (!node) throw new Error("cascade freeze needs a node id");
+  const fields = (one(flags, "--fields") ?? "").split(",").map((item) => item.trim()).filter(Boolean);
+  if (!fields.length) throw new Error("cascade freeze needs --fields: name exactly the values to keep");
+  const personal = (one(flags, "--personal") ?? "").split(",").map((item) => item.trim()).filter(Boolean);
+  const document = await readGraph(graph);
+  if (!document.nodes.some((item) => item.id === node)) throw new Error(`No node ${node} in ${graph}`);
+  const graphFile = path.resolve(graph);
+  const project = new ProjectRoot(path.dirname(graphFile));
+  await installHeadlessCanvas().catch(() => void 0);
+  const removeIo = installProjectIo(project);
+  const { outputs } = await cookProjectGraph(graphFile, document, node).finally(removeIo);
+  const produced = outputs.get(node);
+  if (!produced) throw new Error(`${node} produced nothing`);
+  const output = one(flags, "--output") ?? [...produced.keys()][0];
+  if (!produced.has(output)) throw new Error(`${node} has no output ${output}; it has ${[...produced.keys()].join(", ")}`);
+  const full = toJson(produced.get(output));
+  const directory = path.join("frozen", node);
+  await fs.mkdir(project.resolve(directory), { recursive: true });
+  const files = [];
+  const pick = async (value) => {
+    if (value && typeof value === "object" && !Array.isArray(value) && typeof value.path === "string") {
+      const from = value.path;
+      const source = project.resolve(from.replace(/^\.\//, ""));
+      const name = `${directory}/${path.basename(from)}`;
+      await fs.copyFile(source, project.resolve(name));
+      files.push(name);
+      return { ...value, path: name };
+    }
+    if (Array.isArray(value)) return Promise.all(value.map(pick));
+    if (value && typeof value === "object")
+      return Object.fromEntries(await Promise.all(Object.entries(value).map(async ([key, item]) => [key, await pick(item)])));
+    return value;
+  };
+  const chosen = {};
+  for (const field of fields) {
+    const value = getPath(full, field);
+    if (value === void 0) throw new Error(`${node}.${output} has no field ${field}`);
+    setPath(chosen, field, await pick(value));
+  }
+  if (fields.includes("path") && typeof chosen.path === "string" && full && typeof full === "object" && !Array.isArray(full)) {
+    const { path: copied } = await pick({ path: chosen.path });
+    chosen.path = copied;
+  }
+  const snapshot = {
+    format: "cascade.frozen",
+    version: 1,
+    node,
+    output,
+    fields,
+    ...personal.length ? { personal } : {},
+    value: chosen,
+    ...files.length ? { files } : {},
+    frozenAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  const snapshotFile = `${directory}.json`;
+  await fs.writeFile(project.resolve(snapshotFile), `${JSON.stringify(snapshot, null, 2)}
+`);
+  const editor = document.editor ?? { id: path.basename(graph).replace(/\.cascade$/, "") };
+  const freeze = (editor.freeze ?? []).filter((item) => item.node !== node);
+  freeze.push({ node, output, snapshot: snapshotFile });
+  await writeEditor(graph, document, { ...editor, freeze });
+  console.log(`Froze ${node}.${output}: ${fields.join(", ")} \u2192 ${snapshotFile}${files.length ? ` (+${files.length} file${files.length > 1 ? "s" : ""})` : ""}`);
+}
+async function sceneCommand(graph, flags) {
+  const sceneFile = flags.positional[0];
+  const out = one(flags, "--out");
+  if (!sceneFile || !out) throw new Error("cascade scene needs <scene.json> --out <new-graph.cascade>");
+  if (path.resolve(out) === path.resolve(graph)) throw new Error("--out must be a new file; the source graph is never overwritten");
+  const { document, warnings } = await sceneDocument(graph, sceneFile);
+  await fs.writeFile(out, `${JSON.stringify(document, null, 2)}
+`);
+  for (const warning of warnings) console.warn(`Warning: ${warning}`);
+  console.log(`Scene applied: ${out}`);
+}
+async function sceneDocument(graph, sceneFile) {
+  const document = await readGraph(graph);
+  const scene = parseScene(await fs.readFile(sceneFile, "utf8"));
+  const project = new ProjectRoot(path.dirname(path.resolve(graph)));
+  const located = /* @__PURE__ */ new Map();
+  for (const [id, file] of Object.entries(scene.files ?? {})) {
+    const found = await locateSceneFile(project, file);
+    if (found) located.set(id, { path: found, ...file.mediaType ? { mediaType: file.mediaType } : {} });
+  }
+  return applyScene(document, scene, { resolveFile: (parameter) => located.get(parameter.id) });
+}
+async function locateSceneFile(project, file) {
+  const { createHash } = await import("node:crypto");
+  const safe = path.basename(file.name).replace(/[^A-Za-z0-9._-]/g, "_");
+  if (file.data) {
+    const bytes = fromBase64(file.data);
+    const digest = createHash("sha256").update(bytes).digest("hex");
+    if (digest !== file.sha256) throw new Error(`Scene file ${file.name} does not match its hash`);
+    const name = `assets/scenes/${digest.slice(0, 12)}-${safe}`;
+    await fs.mkdir(path.dirname(project.resolve(name)), { recursive: true });
+    await fs.writeFile(project.resolve(name), bytes);
+    return name;
+  }
+  for (const candidate of await filesNamed(project.root, path.basename(file.name))) {
+    const digest = createHash("sha256").update(await fs.readFile(candidate)).digest("hex");
+    if (digest === file.sha256) return path.relative(project.root, candidate).split(path.sep).join("/");
+  }
+  return void 0;
+}
+async function filesNamed(root, name) {
+  const found = [];
+  const walk = async (directory, depth) => {
+    if (depth > 6) return;
+    for (const entry of await fs.readdir(directory, { withFileTypes: true }).catch(() => [])) {
+      if (entry.name === "node_modules" || entry.name === ".git" || entry.name === ".cascade-cache") continue;
+      const file = path.join(directory, entry.name);
+      if (entry.isDirectory()) await walk(file, depth + 1);
+      else if (entry.name === name) found.push(file);
+    }
+  };
+  await walk(path.join(root, "assets"), 0);
+  await walk(path.join(root, "licensed"), 0);
+  return found;
+}
+async function runWithScene(graph, flags) {
+  const graphFile = path.resolve(graph);
+  let document = await readGraph(graph);
+  const scene = one(flags, "--scene");
+  if (scene) {
+    const applied = await sceneDocument(graph, scene);
+    document = applied.document;
+    for (const warning of applied.warnings) console.warn(`Warning: ${warning}`);
+  }
+  await installHeadlessCanvas().catch(() => void 0);
+  const project = new ProjectRoot(path.dirname(graphFile));
+  const removeIo = installProjectIo(project);
+  const { outputs } = await cookProjectGraph(graphFile, document).finally(removeIo);
+  for (const spec of flags.values.get("--write") ?? []) {
+    const match = /^([^.=]+)\.([^=]+)=(.+)$/.exec(spec);
+    if (!match) throw new Error(`--write expects <node>.<port>=<file>, got ${spec}`);
+    const [, node, port, file] = match;
+    const value = outputs.get(node)?.get(port);
+    if (value === void 0) throw new Error(`${node}.${port} produced nothing`);
+    if (typeof value === "string") await fs.writeFile(file, value);
+    else if (value && typeof value === "object" && typeof value.path === "string")
+      await fs.copyFile(project.resolve(value.path.replace(/^\.\//, "")), file);
+    else await fs.writeFile(file, JSON.stringify(toJson(value)));
+    console.log(`Wrote ${node}.${port} \u2192 ${file}`);
+  }
+}
+function toJson(value) {
+  return JSON.parse(JSON.stringify(value, (_key, item) => ArrayBuffer.isView(item) ? Array.from(item) : item) ?? "null");
+}
+function getPath(value, field) {
+  let current = value;
+  for (const part of field.split(".").flatMap((item) => item.split(/\[(\d+)\]/).filter(Boolean))) {
+    if (current === null || typeof current !== "object") return void 0;
+    current = current[part];
+  }
+  return current;
+}
+function setPath(target, field, value) {
+  const parts = field.split(".").flatMap((item) => item.split(/\[(\d+)\]/).filter(Boolean));
+  let current = target;
+  parts.forEach((part, index) => {
+    const last = index === parts.length - 1;
+    const container = current;
+    if (last) {
+      container[part] = value;
+      return;
+    }
+    if (container[part] === void 0) container[part] = /^\d+$/.test(parts[index + 1]) ? [] : {};
+    current = container[part];
+  });
+}
+
+export {
+  EDITOR_COMMANDS,
+  EDITOR_HELP,
+  runEditorCommand,
+  sceneDocument
+};
+//# sourceMappingURL=chunk-QAGATJGE.js.map