@field/cascade 0.10.0 → 0.12.0

package/dist/cli/chunk-BP7UKF36.js

@@ -0,0 +1,376 @@
+import {
+  expressionEngine
+} from "./chunk-RUU3YWXU.js";
+import {
+  imagePath,
+  sequenceFileName,
+  sequenceWidth
+} from "./chunk-ICH7N5PN.js";
+import {
+  TimeState,
+  runFrameRange
+} from "./chunk-CO22XHNG.js";
+
+// src/cli/frames.ts
+import fs from "node:fs/promises";
+import path from "node:path";
+
+// src/engine/cascade.ts
+var CascadeContext = class {
+  constructor() {
+    this._graph = null;
+    this._pwd = null;
+    /**
+     * Time state. Frames are stored as real numbers: `frame()` reports the
+     * integer frame ($F) and `fframe()` the fractional one ($FF), so sub-frame
+     * time exists rather than being floored away at the door.
+     */
+    this._time = new TimeState();
+    this._selectedNodes = /* @__PURE__ */ new Set();
+  }
+  /**
+   * Initialize with a graph reference
+   */
+  setGraph(graph) {
+    this._graph = graph;
+    expressionEngine.setGraph(graph);
+  }
+  /**
+   * Get the current graph
+   */
+  getGraph() {
+    return this._graph;
+  }
+  // ============ Node Access ============
+  /**
+   * Find a node by path (absolute or relative to pwd)
+   */
+  node(path2) {
+    if (!this._graph) return null;
+    if (path2.startsWith("/")) {
+      return this.resolveAbsolutePath(path2);
+    }
+    if (this._pwd) {
+      return this._pwd.node(path2);
+    }
+    return this.resolveAbsolutePath("/" + path2);
+  }
+  /**
+   * Find a parameter by path (e.g., "/node1/radius")
+   */
+  parm(path2) {
+    const lastSlash = path2.lastIndexOf("/");
+    if (lastSlash === -1) return null;
+    const nodePath = path2.substring(0, lastSlash) || "/";
+    const parmName = path2.substring(lastSlash + 1);
+    const node = this.node(nodePath);
+    return node?.parm(parmName) ?? null;
+  }
+  /**
+   * Get the root node (virtual - returns null, represents "/")
+   * In Cascade, root is not a real node but the graph itself
+   */
+  root() {
+    return null;
+  }
+  /**
+   * Get current working directory/network
+   */
+  pwd() {
+    return this._pwd;
+  }
+  /**
+   * Set current working directory/network
+   */
+  setPwd(node) {
+    this._pwd = node;
+  }
+  /**
+   * Navigate to a path (like cd command)
+   */
+  cd(path2) {
+    if (path2 === "/") {
+      this._pwd = null;
+      return;
+    }
+    const target = this.node(path2);
+    if (target && target.isNetwork()) {
+      this._pwd = target;
+    }
+  }
+  // ============ Selection ============
+  /**
+   * Get all selected nodes
+   */
+  selectedNodes() {
+    if (!this._graph) return [];
+    return Array.from(this._selectedNodes).map((id) => this._graph.getNode(id)).filter((n) => n !== null);
+  }
+  /**
+   * Get selected node IDs
+   */
+  selectedNodeIds() {
+    return Array.from(this._selectedNodes);
+  }
+  /**
+   * Set selection (internal use by editor)
+   */
+  setSelection(nodeIds) {
+    this._selectedNodes = new Set(nodeIds);
+    this.onSelectionChange?.(nodeIds);
+  }
+  /**
+   * Clear all selection
+   */
+  clearAllSelected() {
+    this._selectedNodes.clear();
+    this.onSelectionChange?.([]);
+  }
+  // ============ Time/Playback ============
+  /**
+   * Get current frame number (integer) — $F
+   */
+  frame() {
+    return this._time.frame;
+  }
+  /**
+   * Get current frame as a fractional value — $FF
+   */
+  fframe() {
+    return this._time.frameFraction;
+  }
+  /**
+   * Get current time in seconds — $T
+   */
+  time() {
+    return this._time.time;
+  }
+  /**
+   * Get frames per second — $FPS
+   */
+  fps() {
+    return this._time.fps;
+  }
+  /**
+   * Set current frame. Fractional frames are preserved; `frame()` still
+   * reports the floored integer frame.
+   */
+  setFrame(frame) {
+    this._time.setFrame(frame);
+    expressionEngine.setFrame(this._time.frameFraction);
+  }
+  /**
+   * Set current time in seconds, keeping the sub-frame remainder
+   */
+  setTime(time) {
+    this._time.setTime(time);
+    expressionEngine.setFrame(this._time.frameFraction);
+  }
+  /**
+   * Set FPS
+   */
+  setFps(fps) {
+    this._time.setFps(fps);
+    expressionEngine.setFps(this._time.fps);
+  }
+  /**
+   * The clock a frame-range loop drives. Nothing here reads a wall clock —
+   * the caller owns time, which is what keeps a cook deterministic.
+   */
+  clock() {
+    return {
+      setFrame: (frame) => this.setFrame(frame),
+      markTimeDependentDirty: () => this.markTimeDependentDirty(),
+      getFrame: () => this.frame(),
+      getFrameFraction: () => this.fframe(),
+      getTime: () => this.time(),
+      getFps: () => this.fps()
+    };
+  }
+  // ============ Channel Shortcuts ============
+  /**
+   * Get parameter value as number (shorthand)
+   */
+  ch(path2) {
+    const p = this.parm(path2);
+    return p?.evalAsFloat() ?? 0;
+  }
+  /**
+   * Get parameter value as string (shorthand)
+   */
+  chs(path2) {
+    const p = this.parm(path2);
+    return p?.evalAsString() ?? "";
+  }
+  /**
+   * Get parameter value as vector (shorthand)
+   */
+  chv(path2) {
+    const p = this.parm(path2);
+    const val = p?.eval();
+    if (Array.isArray(val)) return val;
+    if (typeof val === "number") return [val];
+    return [];
+  }
+  // ============ Time-Dependent Updates ============
+  /**
+   * Mark all time-dependent nodes as dirty
+   * Call this at the start of each frame in the animation loop
+   */
+  markTimeDependentDirty() {
+    if (!this._graph) return;
+    for (const node of this._graph.nodes) {
+      if (node.isTimeDependent) {
+        node.markDirty();
+      }
+    }
+  }
+  /**
+   * Get all time-dependent nodes in the graph
+   */
+  getTimeDependentNodes() {
+    if (!this._graph) return [];
+    return this._graph.nodes.filter((n) => n.isTimeDependent);
+  }
+  /**
+   * Advance the frame and mark time-dependent nodes dirty.
+   * Convenience method for animation loops; `step` may be fractional.
+   * Returns the new fractional frame.
+   */
+  nextFrame(step = 1) {
+    this.setFrame(this.fframe() + step);
+    this.markTimeDependentDirty();
+    return this.fframe();
+  }
+  // ============ Internal Helpers ============
+  resolveAbsolutePath(path2) {
+    if (!this._graph) return null;
+    const segments = path2.replace(/^\//, "").split("/").filter((s) => s.length > 0);
+    if (segments.length === 0) {
+      return null;
+    }
+    let current = null;
+    const rootNodes = this._graph.nodes.filter((n) => !n.parent);
+    for (let i = 0; i < segments.length; i++) {
+      const segment = segments[i];
+      const searchIn = current ? current.children() : rootNodes;
+      const found = searchIn.find((n) => n.id === segment);
+      if (!found) return null;
+      current = found;
+    }
+    return current;
+  }
+};
+var cascade = new CascadeContext();
+
+// src/engine/animation/frameRange.ts
+async function evaluateFrameRange(options) {
+  const { fps, context = cascade, ...rest } = options;
+  const previousFps = context.fps();
+  if (fps !== void 0) context.setFps(fps);
+  try {
+    return await runFrameRange(context.clock(), rest);
+  } finally {
+    if (fps !== void 0) context.setFps(previousFps);
+  }
+}
+
+// src/cli/frames.ts
+function parseFrameSpec(spec) {
+  const text = String(spec ?? "").trim();
+  const match = /^(-?\d+(?:\.\d+)?)(?:\s*[-:]\s*(-?\d+(?:\.\d+)?))?(?:\s*x\s*(\d+(?:\.\d+)?))?$/i.exec(text);
+  if (!match) {
+    throw new Error(`--frames expects a range like 1-100, 1-100x2, or a single frame like 42 (got "${spec}")`);
+  }
+  const start = Number(match[1]);
+  const end = match[2] === void 0 ? start : Number(match[2]);
+  const step = match[3] === void 0 ? void 0 : Number(match[3]);
+  if (end < start) throw new Error(`--frames: end (${end}) must not be before start (${start})`);
+  if (step !== void 0 && !(step > 0)) throw new Error(`--frames: step must be greater than 0 (got ${step})`);
+  return step === void 0 ? { start, end } : { start, end, step };
+}
+function outputPorts(graph, entryNode) {
+  const nodes = entryNode ? [entryNode] : graph.nodes;
+  const found = [];
+  for (const node of nodes) {
+    for (const port of node.outputs) {
+      if (port.dataType !== "image") continue;
+      if (!entryNode && port.connections.length > 0) continue;
+      found.push({ node, port });
+    }
+  }
+  return found;
+}
+function outputSnapshot(graph) {
+  return JSON.stringify(graph.nodes.map((node) => [node.id, node.outputs.map((port) => port.value ?? null)]));
+}
+async function cookUntilSettled(graph, entryNode, options = {}) {
+  const { fixpoint = false, passes = 8 } = options;
+  const dirtyAll = () => {
+    for (const node of graph.nodes) node.markDirty?.();
+  };
+  let previous = fixpoint ? outputSnapshot(graph) : null;
+  for (let pass = 0; pass < passes; pass++) {
+    await graph.execute(entryNode);
+    await graph.scheduler?.whenIdle?.();
+    if (graph.nodes.some((node) => node.error !== null)) return;
+    const stale = graph.nodes.some((node) => node.cookState === "stale" || node.cookState === "queued");
+    if (!fixpoint) {
+      if (!stale) return;
+      continue;
+    }
+    const snapshot = outputSnapshot(graph);
+    const settled = !stale && snapshot === previous;
+    previous = snapshot;
+    if (settled) return;
+    dirtyAll();
+  }
+  throw new Error(`graph did not settle after ${passes} cook passes`);
+}
+async function renderFrameRange(options) {
+  const { graph, project, out, start, end, step, fps, entryNode, verbose, signal } = options;
+  cascade.setGraph(graph);
+  const outDirectory = project.resolve(out);
+  await fs.mkdir(outDirectory, { recursive: true });
+  const files = [];
+  const width = sequenceWidth(end);
+  const result = await evaluateFrameRange({
+    start,
+    end,
+    step,
+    fps,
+    signal,
+    onFrame: async ({ frame, index, total }) => {
+      if (index === 0) for (const node of graph.nodes) node.markDirty();
+      await cookUntilSettled(graph, entryNode, { fixpoint: index === 0 });
+      const failed = graph.nodes.filter((node) => node.error !== null);
+      if (failed.length) {
+        const detail = failed.map((node) => `${node.id}: ${node.error?.message ?? "unknown cook error"}`).join("; ");
+        throw new Error(`frame ${frame} failed \u2014 ${detail}`);
+      }
+      const ports = outputPorts(graph, entryNode);
+      if (!ports.length) {
+        throw new Error(
+          "No image output to save: the graph has no unconsumed image port. Name the node to render with --entry-node."
+        );
+      }
+      for (const { node, port } of ports) {
+        const source = imagePath(port.value);
+        if (!source) continue;
+        const name = sequenceFileName(node.id, frame, source, width);
+        await fs.copyFile(project.resolveMedia(source), path.join(outDirectory, name));
+        files.push(path.posix.join(out, name));
+      }
+      if (verbose) console.log(`  frame ${frame} (${index + 1}/${total})`);
+    }
+  });
+  return { frames: result.frames, files, aborted: result.aborted };
+}
+
+export {
+  parseFrameSpec,
+  outputPorts,
+  cookUntilSettled,
+  renderFrameRange
+};
+//# sourceMappingURL=chunk-BP7UKF36.js.map

package/dist/cli/chunk-BPODRH52.js

@@ -0,0 +1,201 @@
+import {
+  Node,
+  packagePathToType,
+  registerNodeClasses,
+  registerNodeMetadata
+} from "./chunk-CTPLRSWF.js";
+import {
+  bundleValueProblem,
+  gpuLimitShortfall,
+  graphSeed,
+  isGpuHost,
+  nodeSeed,
+  seededRandom,
+  selectBundleFields
+} from "./chunk-L6B6FUQP.js";
+
+// src/nodes/definition/DefinitionNode.ts
+var silentProgress = { report: () => {
+} };
+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 ? {
+      // 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
+  };
+}
+function bundlePortOptions(port) {
+  if (port.type !== "bundle") return {};
+  return {
+    ...port.schema ? { schema: port.schema } : {},
+    ...Array.isArray(port.fields) ? { fieldSelection: port.fields } : port.fields ? { bundleFields: port.fields } : {}
+  };
+}
+function attachDefinition(node, registration, capabilities) {
+  const definition = registration.definition;
+  const pendingTriggers = /* @__PURE__ */ new Map();
+  let triggerSequence = 0;
+  const container = definition.container;
+  if (container === "subnet" || container === "array") {
+    node.declaredContainer = container;
+  }
+  for (const [name, input] of Object.entries(definition.inputs ?? {})) {
+    if (input.kind === "trigger") {
+      const port = node.in(name, void 0, {
+        type: "any",
+        ...input.description ? { description: input.description } : {}
+      });
+      port.portType = "trigger";
+      port.onTrigger = async (payload) => {
+        const sequence = triggerSequence++;
+        pendingTriggers.set(name, {
+          id: `${node.id}:${sequence}`,
+          runId: `studio:${node.id}:${sequence}`,
+          sequence,
+          ...payload === void 0 ? {} : { payload },
+          source: { kind: "external" }
+        });
+        node.markDirty();
+        await node.execute();
+      };
+      continue;
+    }
+    if (input.variadic) {
+      node.setVariadic(void 0, { type: input.type });
+      continue;
+    }
+    node.in(name, input.default, {
+      type: input.type,
+      ...input.min === void 0 ? {} : { min: input.min },
+      ...input.max === void 0 ? {} : { max: input.max },
+      ...input.step === void 0 ? {} : { step: input.step },
+      ...input.options ? {
+        choices: input.options.map((value) => ({ value, label: String(value) }))
+      } : {},
+      ...input.description ? { description: input.description } : {},
+      ...bundlePortOptions(input)
+    });
+  }
+  for (const [name, output] of Object.entries(definition.outputs ?? {})) {
+    node.out(
+      name,
+      output.kind === "trigger" ? "trigger" : "param",
+      output.kind === "data" ? { type: output.type, description: output.description, ...bundlePortOptions(output) } : { description: output.description }
+    );
+  }
+  for (const [name, prop] of Object.entries(definition.props ?? {})) {
+    const parameter = node.param(name, prop.default, {
+      type: prop.type,
+      ...parameterOptions(prop)
+    });
+    parameter.documentField = "props";
+  }
+  const hasTriggerInputs = Object.values(definition.inputs ?? {}).some((input) => input.kind === "trigger");
+  let executePromise;
+  return async () => {
+    if (hasTriggerInputs && pendingTriggers.size === 0) return;
+    for (const name of definition.capabilities ?? []) {
+      if (!capabilities[name]) {
+        throw new Error(`${registration.moduleId} requires the Studio ${name} capability`);
+      }
+    }
+    const execute = await (executePromise ??= registration.loadExecute("browser"));
+    const inputValues = {};
+    for (const [name, input] of Object.entries(definition.inputs ?? {})) {
+      inputValues[name] = input.kind === "trigger" ? pendingTriggers.get(name) : input.variadic ? node.getVariadicInputs().map((port) => port.value ?? void 0) : input.type === "bundle" && input.fields ? selectBundleFields(node.inputs.find((port) => port.name === name)?.value, input.fields) : node.inputs.find((port) => port.name === name)?.value;
+    }
+    pendingTriggers.clear();
+    const outputs = Object.fromEntries(Object.entries(definition.outputs ?? {}).map(([name, output]) => {
+      const port = node.outputs.find((candidate) => candidate.name === name);
+      if (!port) throw new Error(`Missing output ${registration.moduleId}.${name}`);
+      return [name, output.kind === "trigger" ? { trigger: (payload) => port.trigger(payload) } : {
+        set: (value) => {
+          if (output.type === "bundle") {
+            const problem = bundleValueProblem(value, output.fields);
+            if (problem) throw new Error(`${node.id}.${name} ${problem}`);
+          }
+          port.setValue(value);
+        }
+      }];
+    }));
+    let nodeCapabilities = capabilities;
+    const gpuHost = (definition.capabilities ?? []).includes("gpu") && isGpuHost(capabilities.gpu) ? capabilities.gpu : null;
+    if (gpuHost) {
+      await gpuHost.ensure();
+      const gpu = gpuHost.forNode(node.id);
+      const shortfall = gpuLimitShortfall(node.id, definition.gpuLimits, gpu);
+      if (shortfall) throw new Error(shortfall);
+      nodeCapabilities = { ...capabilities, gpu };
+    }
+    const seed = nodeSeed(graphSeed({ seed: node.documentSeed }), node.id);
+    const context = {
+      nodeId: node.id,
+      inputs: inputValues,
+      outputs,
+      props: Object.fromEntries(node.parameters.map((parameter) => [parameter.name, parameter.value])),
+      capabilities: nodeCapabilities,
+      // The node's own cook signal, not a fresh one that nobody aborts. See
+      // `Node.cookSignal` for what that cost.
+      signal: node.cookSignal ?? new AbortController().signal,
+      progress: silentProgress,
+      // The same derivation as the headless runtime, so a seeded node draws
+      // the same thing in both hosts.
+      seed,
+      random: seededRandom(seed)
+    };
+    await execute(context);
+  };
+}
+function configureNode(node, registration, capabilities) {
+  node.setFunction(attachDefinition(node, registration, capabilities));
+}
+function registerDefinitionNodes(registrations, capabilities = {}) {
+  const libraries = /* @__PURE__ */ new Map();
+  for (const registration of registrations) {
+    const parts = registration.moduleId.split(".");
+    if (parts.length !== 3 || parts[0] !== "cascade") {
+      throw new Error(`Studio built-ins require cascade.<library>.<node>: ${registration.moduleId}`);
+    }
+    const libraryId = parts[1];
+    const nodeType = packagePathToType(registration.moduleId);
+    const classes = libraries.get(libraryId) ?? {};
+    classes[nodeType] = class extends Node {
+      constructor(id, graph) {
+        super(id, nodeType, graph);
+      }
+      setup() {
+        configureNode(this, registration, capabilities);
+      }
+    };
+    libraries.set(libraryId, classes);
+    registerNodeMetadata({
+      type: registration.moduleId,
+      name: registration.definition.label ?? nodeType,
+      icon: registration.definition.icon,
+      description: registration.definition.description,
+      category: libraryId
+    });
+  }
+  for (const [libraryId, classes] of libraries) registerNodeClasses(libraryId, classes);
+}
+
+export {
+  attachDefinition,
+  registerDefinitionNodes
+};
+//# sourceMappingURL=chunk-BPODRH52.js.map