@koda-sl/baker-cli 0.125.0 → 0.129.1-dev.972f3c9aa

package/dist/{chunk-4EPKHOTF.js → chunk-J2LYFDVC.js}

@@ -3,9 +3,9 @@ import {
   __toESM
 } from "./chunk-5WRI5ZAA.js";
 
-// ../../node_modules/.pnpm/safe-stable-stringify@2.5.0/node_modules/safe-stable-stringify/index.js
+// ../../.pnpm-store/v10/links/@/safe-stable-stringify/2.5.0/810146e81bae4e3a061fe487864f2fde80c4b03b886877dc0f1fffbc6480b67e/node_modules/safe-stable-stringify/index.js
 var require_safe_stable_stringify = __commonJS({
-  "../../node_modules/.pnpm/safe-stable-stringify@2.5.0/node_modules/safe-stable-stringify/index.js"(exports, module) {
+  "../../.pnpm-store/v10/links/@/safe-stable-stringify/2.5.0/810146e81bae4e3a061fe487864f2fde80c4b03b886877dc0f1fffbc6480b67e/node_modules/safe-stable-stringify/index.js"(exports, module) {
     "use strict";
     var { hasOwnProperty } = Object.prototype;
     var stringify = configure2();
@@ -138,9 +138,9 @@ var require_safe_stable_stringify = __commonJS({
         }
         if (value) {
           return (value2) => {
-            let message = `Object can not safely be stringified. Received type ${typeof value2}`;
-            if (typeof value2 !== "function") message += ` (${value2.toString()})`;
-            throw new Error(message);
+            let message2 = `Object can not safely be stringified. Received type ${typeof value2}`;
+            if (typeof value2 !== "function") message2 += ` (${value2.toString()})`;
+            throw new Error(message2);
           };
         }
       }
@@ -600,7 +600,7 @@ ${originalIndentation}`;
 });
 
 // src/engine/index.ts
-import path15 from "path";
+import path16 from "path";
 
 // src/engine/client/http.ts
 var CONTENT_POLICY_CODE = "content_policy_blocked";
@@ -649,14 +649,17 @@ var HttpClient = class {
     this.fetchFn = opts.fetchFn ?? fetch;
     this.sleepFn = opts.sleepFn ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
   }
-  async postJson(path16, body, signal) {
-    return await this.requestJson("POST", path16, body, signal);
+  async postJson(path17, body, signal) {
+    return await this.requestJson("POST", path17, body, signal);
+  }
+  async putJson(path17, body, signal) {
+    return await this.requestJson("PUT", path17, body, signal);
   }
-  async getJson(path16, signal) {
-    return await this.requestJson("GET", path16, void 0, signal);
+  async getJson(path17, signal) {
+    return await this.requestJson("GET", path17, void 0, signal);
   }
-  async requestJson(method, path16, body, signal) {
-    const url = `${this.baseUrl}${path16.startsWith("/") ? path16 : `/${path16}`}`;
+  async requestJson(method, path17, body, signal) {
+    const url = `${this.baseUrl}${path17.startsWith("/") ? path17 : `/${path17}`}`;
     for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
       const outcome = await this.attempt(method, url, body, attempt, signal);
       if (outcome.kind === "value") return outcome.value;
@@ -679,8 +682,8 @@ var HttpClient = class {
     try {
       const res = await this.fetchFn(url, {
         method,
-        headers: method === "POST" ? { "Content-Type": "application/json", Authorization: `Bearer ${this.apiKey}` } : { Authorization: `Bearer ${this.apiKey}` },
-        body: method === "POST" ? JSON.stringify(body) : void 0,
+        headers: method === "GET" ? { Authorization: `Bearer ${this.apiKey}` } : { "Content-Type": "application/json", Authorization: `Bearer ${this.apiKey}` },
+        body: method === "GET" ? void 0 : JSON.stringify(body),
         signal: controller.signal
       });
       if (res.ok) return { kind: "value", value: await res.json() };
@@ -717,33 +720,33 @@ async function parseErrorBody(res) {
   const errObj = body.error ?? {};
   return classifyHttpError(res.status, errObj, errObj.message ?? `HTTP ${res.status}`);
 }
-function classifyHttpError(status, errObj, message) {
+function classifyHttpError(status, errObj, message2) {
   if (errObj.code === CONTENT_POLICY_CODE) {
-    return { kind: "content_policy", status, provider: errObj.provider, message };
+    return { kind: "content_policy", status, provider: errObj.provider, message: message2 };
   }
   if (status === 401 || status === 403) {
-    return { kind: "unauthorized", status, message };
+    return { kind: "unauthorized", status, message: message2 };
   }
   if (status === 400 || status === 422) {
-    return { kind: "validation", status, message, details: errObj.details };
+    return { kind: "validation", status, message: message2, details: errObj.details };
   }
   if (status === 502 || status === 504) {
     if (errObj.code === "provider_timeout" || status === 504) {
-      return { kind: "timeout", provider: errObj.provider, message };
+      return { kind: "timeout", provider: errObj.provider, message: message2 };
     }
     return {
       kind: "provider",
       status,
       provider: errObj.provider,
       code: errObj.code ?? "provider_error",
-      message,
+      message: message2,
       retryable: errObj.retryable ?? true
     };
   }
   if (status >= 500 || status === 429) {
-    return { kind: "server", status, message };
+    return { kind: "server", status, message: message2 };
   }
-  return { kind: "validation", status, message, details: errObj.details };
+  return { kind: "validation", status, message: message2, details: errObj.details };
 }
 function backoffMs(attempt) {
   return 1e3 * 2 ** attempt;
@@ -777,7 +780,9 @@ function failedJobError(error) {
     retryable: error.retryable ?? false
   });
 }
-var JOB_POLL_INTERVAL_MS = 3e3;
+function pollInterval(attempt) {
+  return attempt < 15 ? 1e3 : 3e3;
+}
 var JOB_POLL_MAX_MS = 20 * 60 * 1e3;
 var BackendClient = class {
   http;
@@ -793,30 +798,92 @@ var BackendClient = class {
   }
   async pollJob(jobId, signal) {
     const deadline = Date.now() + JOB_POLL_MAX_MS;
-    const path16 = `/api/canvas/jobs/${encodeURIComponent(jobId)}`;
-    while (true) {
+    const path17 = `/api/canvas/jobs/${encodeURIComponent(jobId)}`;
+    for (let attempt = 0; ; attempt++) {
       if (signal?.aborted) {
         throw new BackendHttpError({ kind: "network", cause: signal.reason ?? new Error("aborted") });
       }
-      const job = await this.http.getJson(path16, signal);
+      const job = await this.http.getJson(path17, signal);
       if (job.status === "completed") return job.result;
       if (job.status === "failed") throw failedJobError(job.error);
       if (Date.now() > deadline) {
         throw new BackendHttpError({ kind: "timeout", message: `job ${jobId} did not finish in time` });
       }
-      await sleep(JOB_POLL_INTERVAL_MS);
+      await sleep(pollInterval(attempt));
     }
   }
-  presignAssetUpload(sha256, mime, signal) {
+  presignAssetUpload(sha256, mime, signal, purpose) {
     return this.http.postJson(
       "/api/canvas/assets/presign",
-      { sha256, mime },
+      { sha256, mime, purpose },
       signal
     );
   }
+  /** Remote cache lookup. A miss (404) — or an old backend without the route — returns null. */
+  async getCacheEntry(cacheKey, signal) {
+    try {
+      const res = await this.http.getJson(`/api/canvas/cache/${encodeURIComponent(cacheKey)}`, signal);
+      return res.entry;
+    } catch (e) {
+      if (e instanceof BackendHttpError && "status" in e.detail && e.detail.status === 404) return null;
+      throw e;
+    }
+  }
+  async putCacheEntry(entry, signal) {
+    await this.http.putJson(
+      `/api/canvas/cache/${encodeURIComponent(entry.cacheKey)}`,
+      entry,
+      signal
+    );
+  }
+  /** Durable run-history record — POST /api/canvas/runs (idempotent server-side on runId). */
+  async recordRun(payload, signal) {
+    await this.http.postJson("/api/canvas/runs", payload, signal);
+  }
+  /**
+   * Resumable-run lookup — GET /api/canvas/runs/active. Returns the newest
+   * still-running/interrupted run for the creative (pinned to the exact canvas
+   * sha), so a fresh sandbox can adopt its run id and re-attach billed
+   * in-flight jobs. Null on no active run — or an older backend without the
+   * route (both 404).
+   */
+  async getActiveRun(creativeSlug, canvasSha, signal) {
+    const params = new URLSearchParams({ slug: creativeSlug });
+    if (canvasSha) params.set("sha", canvasSha);
+    try {
+      const res = await this.http.getJson(`/api/canvas/runs/active?${params}`, signal);
+      return res.run;
+    } catch (e) {
+      if (e instanceof BackendHttpError && "status" in e.detail && e.detail.status === 404) return null;
+      throw e;
+    }
+  }
+  /**
+   * Portable-rerun lookup — GET /api/canvas/runs/latest. The newest run for
+   * the creative that recorded a canvas snapshot manifest; null when none
+   * exists (or the backend predates the route — both 404).
+   */
+  async getLatestSnapshotRun(creativeSlug, signal) {
+    const params = new URLSearchParams({ slug: creativeSlug });
+    try {
+      const res = await this.http.getJson(`/api/canvas/runs/latest?${params}`, signal);
+      return res.run;
+    } catch (e) {
+      if (e instanceof BackendHttpError && "status" in e.detail && e.detail.status === 404) return null;
+      throw e;
+    }
+  }
+  /**
+   * Chat-scoped blueprint sync — POST /api/creatives/definition. Lets the
+   * dashboard draw a scaffolded creative's workflow graph BEFORE the first run.
+   * Additive on the backend (never archives siblings, never sets definitionPath).
+   */
+  async syncCreativeDefinition(payload, signal) {
+    await this.http.postJson("/api/creatives/definition", payload, signal);
+  }
   getArtifact(kind, name, version, signal) {
-    const path16 = version ? `/api/canvas/artifacts/${encodeURIComponent(kind)}/${encodeURIComponent(name)}/${encodeURIComponent(version)}` : `/api/canvas/artifacts/${encodeURIComponent(kind)}/${encodeURIComponent(name)}`;
-    return this.http.getJson(path16, signal);
+    const path17 = version ? `/api/canvas/artifacts/${encodeURIComponent(kind)}/${encodeURIComponent(name)}/${encodeURIComponent(version)}` : `/api/canvas/artifacts/${encodeURIComponent(kind)}/${encodeURIComponent(name)}`;
+    return this.http.getJson(path17, signal);
   }
 };
 
@@ -837,14 +904,17 @@ function requireCredentialsFromEnv(env = process.env) {
   }
   return c;
 }
+function remoteCacheEnabledFromEnv(env = process.env) {
+  return env.BAKER_CANVAS_REMOTE_CACHE !== "off";
+}
 
 // src/engine/engine/errors.ts
 function isBlocking(issue) {
   return issue.severity !== "warning";
 }
 var CanvasError = class extends Error {
-  constructor(message) {
-    super(message);
+  constructor(message2) {
+    super(message2);
     this.name = "CanvasError";
   }
 };
@@ -870,6 +940,14 @@ var NodeExecutionError = class extends CanvasError {
     this.cause = cause;
   }
 };
+var RunAbortedError = class extends CanvasError {
+  reason;
+  constructor(reason, message2) {
+    super(message2);
+    this.name = "RunAbortedError";
+    this.reason = reason;
+  }
+};
 var LayerExecutionError = class extends CanvasError {
   failures;
   constructor(failures) {
@@ -901,7 +979,7 @@ function describeCause(c) {
   }
 }
 
-// ../../node_modules/.pnpm/safe-stable-stringify@2.5.0/node_modules/safe-stable-stringify/esm/wrapper.js
+// ../../.pnpm-store/v10/links/@/safe-stable-stringify/2.5.0/810146e81bae4e3a061fe487864f2fde80c4b03b886877dc0f1fffbc6480b67e/node_modules/safe-stable-stringify/esm/wrapper.js
 var import__ = __toESM(require_safe_stable_stringify(), 1);
 var configure = import__.default.configure;
 var wrapper_default = import__.default;
@@ -947,6 +1025,7 @@ var OPENROUTER_IMAGE_AR = ["1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:1
 var OPENROUTER_IMAGE_AR_EXTREME = [...OPENROUTER_IMAGE_AR, "1:4", "4:1", "1:8", "8:1"];
 var OPENROUTER_IMAGE_SIZE = ["1K", "2K", "4K"];
 var OPENROUTER_IMAGE_SIZE_EXTENDED = ["0.5K", ...OPENROUTER_IMAGE_SIZE];
+var OPENROUTER_IMAGE_QUALITY = ["auto", "low", "medium", "high"];
 var SEEDANCE_DURATIONS = [4, 5, 6, 8, 10, 12, 15];
 var ELEVENLABS_OUTPUT_FORMATS = [
   "mp3_22050_32",
@@ -959,10 +1038,10 @@ var ELEVENLABS_OUTPUT_FORMATS = [
 var ELEVENLABS_MAX_TEXT_CHARS = 45454;
 var ELEVENLABS_MAX_MUSIC_LENGTH_MS = 454545;
 var OPENROUTER_IMAGE_MIMES = ["image/png", "image/jpeg", "image/webp", "image/gif"];
-var FAL_IMAGE_MIMES = ["image/png", "image/jpeg", "image/webp"];
-var FAL_VIDEO_MIMES = ["video/mp4", "video/webm", "video/quicktime"];
+var REPLICATE_IMAGE_MIMES = ["image/png", "image/jpeg", "image/webp"];
+var REPLICATE_VIDEO_MIMES = ["video/mp4", "video/webm", "video/quicktime"];
 var DECONSTRUCT_VIDEO_MIMES = ["video/mp4", "video/webm", "video/quicktime"];
-var FAL_AUDIO_MIMES = ["audio/wav", "audio/mpeg", "audio/mp3"];
+var REPLICATE_AUDIO_MIMES = ["audio/wav", "audio/mpeg", "audio/mp3"];
 var IMAGE_GENERATE_MODELS = [
   "openai/gpt-5.4-image-2",
   "google/gemini-3.5-flash",
@@ -970,6 +1049,13 @@ var IMAGE_GENERATE_MODELS = [
   "google/gemini-3-pro-image-preview",
   "recraft/recraft-v4.1-pro-vector"
 ];
+var VIDEO_GENERATE_MODELS = [
+  "bytedance/seedance-2.0",
+  "google/veo-3.1",
+  "google/veo-3.1-fast",
+  "kwaivgi/kling-v3.0-pro"
+];
+var DEFAULT_VIDEO_GENERATE_MODEL = "bytedance/seedance-2.0";
 var MODEL_REGISTRY = {
   text_generate: {
     "~google/gemini-flash-latest": {
@@ -1065,7 +1151,8 @@ var MODEL_REGISTRY = {
       params: {
         prompt: { kind: "string" },
         aspect_ratio: { kind: "string", enum: OPENROUTER_IMAGE_AR },
-        image_size: { kind: "string", enum: OPENROUTER_IMAGE_SIZE }
+        image_size: { kind: "string", enum: OPENROUTER_IMAGE_SIZE },
+        quality: { kind: "string", enum: OPENROUTER_IMAGE_QUALITY }
       }
     },
     "google/gemini-3.5-flash": {
@@ -1077,7 +1164,8 @@ var MODEL_REGISTRY = {
       params: {
         prompt: { kind: "string" },
         aspect_ratio: { kind: "string", enum: OPENROUTER_IMAGE_AR_EXTREME },
-        image_size: { kind: "string", enum: OPENROUTER_IMAGE_SIZE_EXTENDED }
+        image_size: { kind: "string", enum: OPENROUTER_IMAGE_SIZE_EXTENDED },
+        quality: { kind: "string", enum: OPENROUTER_IMAGE_QUALITY }
       }
     },
     "google/gemini-3.1-flash-image-preview": {
@@ -1099,7 +1187,8 @@ var MODEL_REGISTRY = {
       params: {
         prompt: { kind: "string" },
         aspect_ratio: { kind: "string", enum: OPENROUTER_IMAGE_AR },
-        image_size: { kind: "string", enum: OPENROUTER_IMAGE_SIZE }
+        image_size: { kind: "string", enum: OPENROUTER_IMAGE_SIZE },
+        quality: { kind: "string", enum: OPENROUTER_IMAGE_QUALITY }
       }
     },
     "recraft/recraft-v4.1-pro-vector": {
@@ -1180,25 +1269,75 @@ var MODEL_REGISTRY = {
   },
   video_generate: {
     "bytedance/seedance-2.0": {
-      // Routed via fal.ai (not OpenRouter) because OpenRouter's Seedance
-      // passthrough rejects photorealistic human reference frames via
-      // ByteDance's "real person" safety filter.
+      // Routed via Replicate's official `bytedance/seedance-2.0` model. NOTE:
+      // ByteDance's upstream "real person" likeness filter still blocks photoreal
+      // human reference frames on ANY reseller — the escape is a synthetic/AI
+      // presenter face or routing real faces to Veo, not the provider choice.
       label: "ByteDance Seedance 2.0",
       inputs: [],
-      optional_inputs: [{ kind: "image", mimes: FAL_IMAGE_MIMES }],
+      optional_inputs: [{ kind: "image", mimes: REPLICATE_IMAGE_MIMES }],
       required: ["prompt"],
       params: {
-        prompt: { kind: "string" },
+        // Replicate's Seedance wrapper hard-caps the prompt at 4000 chars; gate
+        // it here so an over-length prompt fails validate (free) not the billed call.
+        prompt: { kind: "string", maxLength: 4e3 },
         aspect_ratio: {
           kind: "string",
           enum: ["1:1", "3:4", "9:16", "4:3", "16:9", "21:9", "9:21"]
         },
-        resolution: { kind: "string", enum: ["480p", "720p", "1080p"] },
+        resolution: { kind: "string", enum: ["480p", "720p", "1080p", "4k"] },
         duration: { kind: "number", enum: SEEDANCE_DURATIONS },
         seed: { kind: "number" },
         generate_audio: { kind: "boolean" }
       }
     },
+    "google/veo-3.1": {
+      // Photoreal CINE CEILING + the real-face fallback (Veo generates adult
+      // humans from a keyframe, dodging ByteDance's real-person filter). Same
+      // OpenRouter google-vertex routing as the fast tier; the quality dial is
+      // `resolution: 1080p` + `generate_audio` + a real `negative_prompt`, not a
+      // separate provider knob. Reach for this for hero beats and any clip that
+      // must carry a real human likeness.
+      label: "Google Veo 3.1",
+      inputs: [],
+      optional_inputs: [{ kind: "image", mimes: OPENROUTER_IMAGE_MIMES }],
+      required: ["prompt"],
+      params: {
+        prompt: { kind: "string" },
+        negative_prompt: { kind: "string" },
+        aspect_ratio: { kind: "string", enum: ["16:9", "9:16"] },
+        resolution: { kind: "string", enum: ["720p", "1080p"] },
+        duration: { kind: "number", enum: [4, 6, 8] },
+        seed: { kind: "number" },
+        generate_audio: { kind: "boolean" },
+        person_generation: { kind: "string", enum: ["allow_all", "allow_adult"] },
+        enhance_prompt: { kind: "boolean" },
+        conditioning_scale: { kind: "number" }
+      }
+    },
+    "kwaivgi/kling-v3.0-pro": {
+      // Motion-transfer / dynamic multi-shot beats. Reachable through the default
+      // OpenRouter gateway (generic video body — no google-vertex block), so it
+      // needs no direct-provider exception. Cost is usage-based (known from the
+      // provider response), so it has no pre-flight cost estimate. `cfg_scale`
+      // trades prompt adherence vs motion freedom; higher = closer to prompt.
+      label: "Kling 3.0",
+      inputs: [],
+      optional_inputs: [{ kind: "image", mimes: OPENROUTER_IMAGE_MIMES }],
+      required: ["prompt"],
+      params: {
+        // Kling caps the prompt shorter than Seedance; gate it here so an
+        // over-length prompt fails validate (free) not the billed call.
+        prompt: { kind: "string", maxLength: 2500 },
+        negative_prompt: { kind: "string" },
+        aspect_ratio: { kind: "string", enum: ["1:1", "16:9", "9:16"] },
+        resolution: { kind: "string", enum: ["720p", "1080p"] },
+        duration: { kind: "number", enum: [5, 10] },
+        seed: { kind: "number" },
+        generate_audio: { kind: "boolean" },
+        cfg_scale: { kind: "number", min: 0, max: 1 }
+      }
+    },
     "google/veo-3.1-fast": {
       // Cheap test/iteration model. Forwarded by the backend via
       // `provider.options.google-vertex.parameters` (camelCased on the wire).
@@ -1214,7 +1353,10 @@ var MODEL_REGISTRY = {
         duration: { kind: "number", enum: [4, 6, 8] },
         seed: { kind: "number" },
         generate_audio: { kind: "boolean" },
-        person_generation: { kind: "string", enum: ["allow_all"] },
+        // Image-to-video and EU/UK/CH/MENA regions cap this at `allow_adult`;
+        // `allow_all` is text-to-video only. Allow both so an image-conditioned
+        // Veo clip (the real-face fallback) validates.
+        person_generation: { kind: "string", enum: ["allow_all", "allow_adult"] },
         enhance_prompt: { kind: "boolean" },
         conditioning_scale: { kind: "number" }
       }
@@ -1265,8 +1407,8 @@ var MODEL_REGISTRY = {
     "fal/veed-lipsync": {
       label: "VEED Lipsync (fal.ai)",
       inputs: [
-        { kind: "video", mimes: FAL_VIDEO_MIMES },
-        { kind: "audio", mimes: FAL_AUDIO_MIMES }
+        { kind: "video", mimes: REPLICATE_VIDEO_MIMES },
+        { kind: "audio", mimes: REPLICATE_AUDIO_MIMES }
       ],
       required: [],
       params: {}
@@ -1302,7 +1444,7 @@ var MODEL_REGISTRY = {
       // TARGET voice, preserving timing/prosody. Used to normalize a talking-head
       // clip's native (generator-chosen) voice into ONE consistent brand voice.
       label: "ElevenLabs Voice Changer (multilingual STS v2)",
-      inputs: [{ kind: "audio", mimes: FAL_AUDIO_MIMES }],
+      inputs: [{ kind: "audio", mimes: REPLICATE_AUDIO_MIMES }],
       required: ["voice"],
       params: {
         voice: { kind: "string" },
@@ -1329,7 +1471,7 @@ var MODEL_REGISTRY = {
     },
     "elevenlabs/video-background-music-v1": {
       label: "ElevenLabs Video Background Music v1",
-      inputs: [{ kind: "video", mimes: FAL_VIDEO_MIMES }],
+      inputs: [{ kind: "video", mimes: REPLICATE_VIDEO_MIMES }],
       required: [],
       params: {
         description: { kind: "string" },
@@ -1500,7 +1642,7 @@ function validateValue(key, value, schema, model) {
 }
 
 // src/engine/lib/concurrency.ts
-var DEFAULT_CONCURRENCY = 5;
+var DEFAULT_CONCURRENCY = 8;
 function resolveConcurrency(...candidates) {
   for (const candidate of candidates) {
     if (candidate === void 0 || candidate === "") continue;
@@ -1562,6 +1704,185 @@ function encodeRandom() {
   return out;
 }
 
+// src/engine/storage/remote-cache-store.ts
+var CANVAS_ASSETS_URL_SEGMENT = "/canvas-assets/";
+function isPersistedAssetRef(ref) {
+  const { url, sha256 } = ref;
+  if (typeof url !== "string" || typeof sha256 !== "string") return false;
+  return url.includes(`${CANVAS_ASSETS_URL_SEGMENT}${sha256.slice(0, 2)}/${sha256}`) || url.includes(`${CANVAS_ASSETS_URL_SEGMENT}${sha256}`);
+}
+function isAssetRefLike(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && typeof value.sha256 === "string" && typeof value.mime === "string";
+}
+function collectAssetRefLikes(value, out = []) {
+  if (Array.isArray(value)) {
+    for (const item of value) collectAssetRefLikes(item, out);
+    return out;
+  }
+  if (typeof value !== "object" || value === null) return out;
+  if (isAssetRefLike(value)) {
+    out.push(value);
+  }
+  for (const item of Object.values(value)) collectAssetRefLikes(item, out);
+  return out;
+}
+function entryFullyPersisted(entry) {
+  return collectAssetRefLikes(entry.outputs).every((ref) => isPersistedAssetRef(ref));
+}
+function stripLocalFields(entry) {
+  const clone = JSON.parse(JSON.stringify(entry));
+  for (const ref of collectAssetRefLikes(clone.outputs)) {
+    delete ref.path;
+    delete ref.bytes;
+  }
+  return clone;
+}
+var RemoteCacheStore = class {
+  client;
+  log;
+  constructor(client, log) {
+    this.client = client;
+    this.log = log ?? (() => void 0);
+  }
+  async get(cacheKey) {
+    return await this.client.getCacheEntry(cacheKey);
+  }
+  async put(entry) {
+    if (!entryFullyPersisted(entry)) {
+      this.log(`[cache   ] ${entry.cacheKey.slice(0, 12)}\u2026 has local-only assets, kept local`);
+      return;
+    }
+    const stripped = stripLocalFields(entry);
+    if (stripped.refs.length > MAX_REMOTE_REFS) {
+      stripped.refs = stripped.refs.slice(0, MAX_REMOTE_REFS);
+    }
+    await this.client.putCacheEntry(stripped);
+  }
+};
+var MAX_REMOTE_REFS = 512;
+var LayeredCacheStore = class {
+  rootDir;
+  local;
+  remote;
+  assets;
+  log;
+  constructor(opts) {
+    this.local = opts.local;
+    this.remote = opts.remote;
+    this.assets = opts.assets;
+    this.rootDir = opts.local.rootDir;
+    this.log = opts.log ?? (() => void 0);
+  }
+  async get(cacheKey) {
+    const localHit = await this.local.get(cacheKey);
+    if (localHit) return localHit;
+    let remoteEntry;
+    try {
+      remoteEntry = await this.remote.get(cacheKey);
+    } catch (e) {
+      this.log(`[cache   ] remote lookup failed (${message(e)}) \u2014 treating as miss`);
+      return null;
+    }
+    if (!remoteEntry) return null;
+    let rehydrated;
+    try {
+      rehydrated = await this.rehydrate(remoteEntry);
+    } catch (e) {
+      this.log(`[cache   ] ${cacheKey.slice(0, 12)}\u2026 rehydration failed (${message(e)}) \u2014 treating as miss`);
+      return null;
+    }
+    await this.local.put(rehydrated);
+    return rehydrated;
+  }
+  async put(entry) {
+    await this.local.put(entry);
+    try {
+      await this.remote.put(entry);
+    } catch (e) {
+      this.log(`[cache   ] remote write failed (${message(e)}) \u2014 entry kept local`);
+    }
+  }
+  /**
+   * Download every referenced asset into the local content-addressed store
+   * (sha-verified) and stamp fresh local paths. Any ref that cannot be
+   * rehydrated fails the WHOLE entry — a partially-hydrated cache hit would
+   * crash materialization later with a far less actionable error.
+   */
+  async rehydrate(entry) {
+    const clone = JSON.parse(JSON.stringify(entry));
+    for (const ref of collectAssetRefLikes(clone.outputs)) {
+      if (!isPersistedAssetRef(ref)) {
+        throw new Error(`ref ${ref.sha256.slice(0, 12)}\u2026 has no persisted url`);
+      }
+      const ingested = await this.assets.ingestRemote({
+        kind: typeof ref.kind === "string" ? ref.kind : "json",
+        url: ref.url,
+        sha256: ref.sha256,
+        mime: ref.mime,
+        metadata: ref.metadata ?? void 0
+      });
+      ref.path = ingested.path;
+    }
+    return clone;
+  }
+};
+function message(e) {
+  return e instanceof Error ? e.message : String(e);
+}
+
+// src/engine/nodes/remote/upload.ts
+var PUT_MAX_ATTEMPTS = 4;
+var sleep2 = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function presignAndPut(args) {
+  let lastFailure = null;
+  for (let attempt = 0; attempt < PUT_MAX_ATTEMPTS; attempt++) {
+    if (args.ctx.signal?.aborted) break;
+    if (attempt > 0) await sleep2(500 * 2 ** (attempt - 1) * (1 + Math.random() * 0.25));
+    const result = await attemptPresignedPut(args);
+    if (result.ok) return result.url;
+    lastFailure = result.failure;
+    if (!result.retryable) break;
+  }
+  throw lastFailure ?? new Error("upload: aborted before the PUT could start");
+}
+async function attemptPresignedPut(args) {
+  try {
+    const { putUrl, publicUrl } = await args.ctx.client.presignAssetUpload(args.sha256, args.mime, args.ctx.signal);
+    const putRes = await fetch(putUrl, {
+      method: "PUT",
+      body: new Uint8Array(args.bytes),
+      headers: { "Content-Type": args.mime },
+      signal: args.ctx.signal
+    });
+    if (putRes.ok) return { ok: true, url: publicUrl };
+    return {
+      ok: false,
+      failure: new Error(`upload: presigned PUT failed ${putRes.status} ${putRes.statusText}`),
+      // Only transient statuses warrant a replay — a 400/403 fails identically every attempt.
+      retryable: putRes.status >= 500 || putRes.status === 429 || putRes.status === 408
+    };
+  } catch (e) {
+    return {
+      ok: false,
+      failure: e instanceof Error ? e : new Error(String(e)),
+      retryable: args.ctx.signal?.aborted !== true
+    };
+  }
+}
+async function ensureUploaded(ref, ctx) {
+  if (ref.url) return ref;
+  const bytes = await ctx.assets.readBytes(ref.sha256, ref.mime);
+  const url = await presignAndPut({ bytes, sha256: ref.sha256, mime: ref.mime, ctx });
+  return { ...ref, url };
+}
+async function persistOutputAssetUrls(outputs, ctx) {
+  for (const ref of collectAssetRefLikes(outputs)) {
+    if (isPersistedAssetRef(ref)) continue;
+    const bytes = await ctx.assets.readBytes(ref.sha256, ref.mime);
+    ref.url = await presignAndPut({ bytes, sha256: ref.sha256, mime: ref.mime, ctx });
+  }
+}
+
 // src/engine/schema/canvas.ts
 import { z } from "zod";
 var REF_PREFIX = "$ref:";
@@ -1591,7 +1912,14 @@ var NodeDecl = z.object({
   version: z.string().min(1).optional(),
   inputs: z.record(z.string(), z.unknown()).optional(),
   params: z.record(z.string(), z.unknown()).optional(),
-  when: z.unknown().optional()
+  when: z.unknown().optional(),
+  // Regenerate knob. The engine is content-addressed: identical params + inputs
+  // return the cached render, so re-running an unchanged node NEVER re-bills or
+  // produces a new result. Bump this token (any string/number — a `2`, a `"v3"`,
+  // a note) and re-run to force THIS node to render fresh; because its new output
+  // changes downstream input hashes, everything depending on it regenerates too.
+  // This is the declarative "change a value, re-run, get a new render" affordance.
+  regenerate: z.union([z.string(), z.number()]).optional()
 }).strict();
 var OutputRef = z.object({
   node: z.string(),
@@ -1599,6 +1927,16 @@ var OutputRef = z.object({
 }).strict();
 var VideoMeta = z.object({
   duration_s: z.number(),
+  // The one-clock contract: the spine's summed clip lengths and every audio
+  // timeline reachable from the final mux must equal `expected_total_s` — the
+  // validator recomputes both from the LIVE graph (`-shortest` at the final mux
+  // silently truncates the longer stream on any mismatch). Emitted by
+  // scaffold-video; optional so hand-authored canvases still parse.
+  timeline: z.object({
+    spine_node: z.string(),
+    expected_total_s: z.number(),
+    audio_mix_node: z.string().optional()
+  }).strict().optional(),
   // Each sequenced voiceover turn on the absolute timeline.
   vo_segments: z.array(
     z.object({
@@ -2076,8 +2414,111 @@ function dfsCycle(u, color, stack, reverseAdj) {
 }
 
 // src/engine/engine/validator.ts
+import { readFile as readFile2 } from "fs/promises";
+import path3 from "path";
 import { z as z2 } from "zod";
 
+// src/engine/scaffold/lib/prompt-profiles.ts
+var VEO_PERSON_GENERATION = "allow_adult";
+var VEO_NEGATIVE_PROMPT = "subtitles, captions, on-screen text, watermark, logo, warped face, distorted hands, extra fingers, low quality";
+var VEO_DURATIONS = [4, 6, 8];
+var KLING_DURATIONS = [5, 10];
+var KLING_NEGATIVE_PROMPT = "warped face, distorted hands, extra fingers, morphing, flicker, on-screen text, watermark, low quality";
+var KLING_CFG_SCALE = 0.7;
+var SPEAKS_PROSE = (line) => `The person speaks to camera; lip-sync follows the dialogue verbatim, with delivery and emotion carried in the wording itself (no bracketed cues). Dialogue: "${line}"`;
+var SEEDANCE_PROFILE = {
+  id: "seedance",
+  dialogueDirective: SPEAKS_PROSE,
+  extraDirectives: [],
+  // Seedance has no negative_prompt field. Phrase the anti-artifact intent as the POSITIVE
+  // state we want (crisp hands, one stable face, smooth coherent motion, locked identity) —
+  // an "Avoid: warped fingers, morphing faces" list tends to plant those very artifacts.
+  stabilityDirectives: [
+    "hands and fingers crisp and anatomically correct",
+    "one consistent face and identity across every frame",
+    "smooth, temporally coherent motion that holds steady frame to frame"
+  ],
+  keyframeInstruction: "Preserve the composition and colors of the first frame; change only the motion described.",
+  // ~120 words is the Seedance quality sweet spot: past it the model starts dropping beats and
+  // the attention budget dilutes. The validator warns above this; composite scenes that stack
+  // many brief `parts` are the usual offenders.
+  wordBudget: 120,
+  durationSet: SEEDANCE_DURATIONS,
+  paramDefaults: {}
+};
+var VEO_PROFILE = {
+  id: "veo",
+  dialogueDirective: SPEAKS_PROSE,
+  // Veo's known failure mode: quoted dialogue triggers burned-in subtitles. Belt
+  // (inline) and braces (the negative_prompt param, below) — the param is the real lever.
+  extraDirectives: ["No subtitles, no captions, no on-screen text of any kind."],
+  stabilityDirectives: [],
+  // Veo takes a negative_prompt PARAM instead (paramDefaults).
+  keyframeInstruction: "Describe the transition and camera move between the frames; the frames fix the content.",
+  wordBudget: 200,
+  durationSet: VEO_DURATIONS,
+  paramDefaults: { person_generation: VEO_PERSON_GENERATION, negative_prompt: VEO_NEGATIVE_PROMPT }
+};
+var KLING_PROFILE = {
+  id: "kling",
+  dialogueDirective: SPEAKS_PROSE,
+  // Belt (inline) and braces (the negative_prompt param) — the param is the real lever.
+  extraDirectives: ["Single, deliberate camera move \u2014 no whip pans or rapid cuts within the clip."],
+  stabilityDirectives: [],
+  // Kling takes a negative_prompt PARAM instead (paramDefaults).
+  keyframeInstruction: "Preserve the composition and colors of the first frame; animate the motion described.",
+  wordBudget: 200,
+  durationSet: KLING_DURATIONS,
+  paramDefaults: { negative_prompt: KLING_NEGATIVE_PROMPT, cfg_scale: KLING_CFG_SCALE }
+};
+function clipProfileFor(modelId) {
+  if (/^bytedance\/seedance/.test(modelId)) return SEEDANCE_PROFILE;
+  if (/^google\/veo/.test(modelId)) return VEO_PROFILE;
+  if (/^kwaivgi\/kling|^kling\//.test(modelId)) return KLING_PROFILE;
+  return void 0;
+}
+function clipParamRecipe(profile, intent) {
+  const out = {};
+  if (intent === "hero") {
+    out.resolution = "1080p";
+  }
+  if (intent === "hook" && profile.id === "kling") {
+    out.cfg_scale = 0.85;
+  }
+  return out;
+}
+function nativeDialogueOf(prompt) {
+  if (typeof prompt !== "string") return void 0;
+  const m = prompt.match(/Dialogue: "(.*)"/);
+  return m?.[1]?.trim() || void 0;
+}
+var GPT_IMAGE_PROFILE = {
+  id: "gpt-image",
+  constraintPlacement: "last",
+  photorealCue: true,
+  // OpenRouter forwards `quality`; gpt-image-2 already processes inputs at high
+  // fidelity automatically, so we deliberately do NOT send `input_fidelity`.
+  paramDefaults: { quality: "high" }
+};
+var GEMINI_IMAGE_PROFILE = {
+  id: "gemini",
+  constraintPlacement: "inline",
+  photorealCue: true,
+  paramDefaults: { quality: "high" }
+};
+var RECRAFT_IMAGE_PROFILE = {
+  id: "recraft",
+  constraintPlacement: "inline",
+  photorealCue: false,
+  paramDefaults: {}
+};
+function imageProfileFor(modelId) {
+  if (/^openai\/gpt-.*image/.test(modelId)) return GPT_IMAGE_PROFILE;
+  if (/^google\/gemini/.test(modelId)) return GEMINI_IMAGE_PROFILE;
+  if (/^recraft\//.test(modelId)) return RECRAFT_IMAGE_PROFILE;
+  return void 0;
+}
+
 // src/engine/engine/define.ts
 function resolveOutputKinds(spec, params) {
   if (!spec) return {};
@@ -2159,16 +2600,62 @@ var STAGE_CODES = {
   REFERENCE_MISSING: "VIDEO_REFERENCE_MISSING",
   SPAN_EXCEEDS_MODEL: "VIDEO_SPAN_EXCEEDS_MODEL",
   UI_IN_PROMPT: "VIDEO_UI_IN_PROMPT",
-  BRANDMARK_IN_PROMPT: "VIDEO_BRANDMARK_IN_PROMPT"
+  BRANDMARK_IN_PROMPT: "VIDEO_BRANDMARK_IN_PROMPT",
+  SPEECH_EXCEEDS_EXTRACT: "VIDEO_SPEECH_EXCEEDS_EXTRACT",
+  PROMPT_PROFILE_MISSING: "VIDEO_PROMPT_PROFILE_MISSING",
+  PROMPT_DECISION_MISSING: "VIDEO_PROMPT_DECISION_MISSING",
+  HOOK_LAYER_MISSING: "VIDEO_HOOK_LAYER_MISSING",
+  IMAGE_PROFILE_MISSING: "IMAGE_PROMPT_PROFILE_MISSING",
+  PROMPT_OVER_BUDGET: "VIDEO_PROMPT_OVER_BUDGET",
+  PERSON_GENERATION_MISSING: "VIDEO_PERSON_GENERATION_MISSING",
+  RAW_FACE_KEYFRAME: "VIDEO_RAW_FACE_KEYFRAME",
+  TIMELINE_TOTAL: "VIDEO_TIMELINE_TOTAL_MISMATCH",
+  NATIVE_SEG_OVERLAP: "VIDEO_NATIVE_SEG_OVERLAP",
+  SPINE_UNNORMALIZED: "VIDEO_SPINE_UNNORMALIZED",
+  ODD_DIMENSIONS: "VIDEO_ODD_DIMENSIONS",
+  REGION_DROPPED: "VIDEO_REGION_DROPPED",
+  OVERLAY_OUT_OF_BOUNDS: "VIDEO_OVERLAY_OUT_OF_BOUNDS"
 };
 var SPAN_MODEL_SLACK_S = 0.25;
 var VIDEO_TIME_SLACK_S = 0.75;
 var SPEECH_WORDS_PER_SECOND = 2.5;
 var SPEECH_OVERRUN_RATIO = 1.6;
-function nativeDialogueOf(prompt) {
-  if (typeof prompt !== "string") return void 0;
-  const m = prompt.match(/Dialogue: "(.*)"/);
-  return m?.[1]?.trim() || void 0;
+function ffmpegTrimSeconds(node) {
+  const args = node.params?.args;
+  if (!Array.isArray(args)) return null;
+  let t = null;
+  for (let i = 0; i < args.length - 1; i++) {
+    if (args[i] === "-t") {
+      const v = Number(args[i + 1]);
+      if (Number.isFinite(v)) t = v;
+    }
+  }
+  return t;
+}
+function refNodeOf(ctx, value) {
+  if (typeof value !== "string" || !value.startsWith(REF_PREFIX)) return null;
+  const parsed = parseRefExpr(value);
+  if (!parsed) return null;
+  const idx = ctx.idToIndex.get(parsed.nodeId);
+  return idx === void 0 ? null : ctx.canvas.nodes[idx];
+}
+function liveNodeDurationS(ctx, node, depth = 0) {
+  if (!node || depth > 3) return null;
+  if (node.type === "video_generate") {
+    const d = node.params?.duration;
+    return typeof d === "number" ? d : null;
+  }
+  if (node.type === "ffmpeg") {
+    const t = ffmpegTrimSeconds(node);
+    if (t !== null) return t;
+    for (const v of Object.values(node.inputs ?? {})) {
+      const upstream = refNodeOf(ctx, v);
+      const d = liveNodeDurationS(ctx, upstream, depth + 1);
+      if (d !== null) return d;
+    }
+    return null;
+  }
+  return null;
 }
 function validateCanvas(input, registry) {
   const issues = [];
@@ -2230,6 +2717,7 @@ async function validateCanvasDeep(input, registry) {
       });
     }
   }
+  await checkOverlayTimingBounds(canvas, issues);
   const hasBlocking = issues.some(isBlocking);
   if (hasBlocking) return { ok: false, issues };
   const warnings = [...shallow.warnings ?? [], ...issues.filter((i) => !isBlocking(i))];
@@ -2471,6 +2959,38 @@ function estimateCredits(ctx) {
   }
   return total;
 }
+function overlayTimingIssues(html, durationS) {
+  const out = [];
+  for (const m of html.matchAll(/<[^>]*\bdata-start="([\d.]+)"[^>]*\bdata-dur="([\d.]+)"[^>]*>/g)) {
+    const start = Number(m[1]);
+    const dur = Number(m[2]);
+    if (!Number.isFinite(start) || !Number.isFinite(dur)) continue;
+    if (start >= durationS || start + dur > durationS + 0.25) out.push({ start, dur });
+  }
+  return out;
+}
+async function checkOverlayTimingBounds(canvas, issues) {
+  const durationS = canvas.metadata?.video?.duration_s;
+  if (typeof durationS !== "number") return;
+  for (let i = 0; i < canvas.nodes.length; i++) {
+    const n = canvas.nodes[i];
+    if (n?.type !== "hyperframe_render") continue;
+    const composition = n.params?.composition;
+    if (typeof composition !== "string" || !path3.isAbsolute(composition)) continue;
+    const html = await readFile2(path3.join(composition, "index.html"), "utf8").catch(() => null);
+    if (!html) continue;
+    for (const w of overlayTimingIssues(html, durationS)) {
+      issues.push({
+        path: `nodes[${i}].params.composition`,
+        code: STAGE_CODES.OVERLAY_OUT_OF_BOUNDS,
+        severity: "warning",
+        node_id: n.id,
+        node_type: n.type,
+        message: `an overlay in ${path3.basename(composition)}/index.html runs [${w.start}s, ${w.start + w.dur}s] but the video ends at ${durationS}s \u2014 it never hides on screen. Re-time its data-start/data-dur to fit the video`
+      });
+    }
+  }
+}
 function nativeAudioReachesMix(ctx, scene) {
   const wanted = [
     `$ref:s${scene}_voextract.audio`,
@@ -2503,6 +3023,13 @@ function talkingSceneSatisfied(ctx, entry, scene) {
   });
 }
 function checkVideoInvariants(ctx) {
+  checkPromptProfile(ctx);
+  checkImageProfile(ctx);
+  checkPersonGeneration(ctx);
+  checkPromptBudget(ctx);
+  checkRawFaceKeyframe(ctx);
+  checkPromptDecisions(ctx);
+  checkHookLayers(ctx);
   const meta = ctx.canvas.metadata?.video;
   if (!meta) return;
   const segments = [...meta.vo_segments].sort((a, b) => a.start_s - b.start_s);
@@ -2542,6 +3069,286 @@ function checkVideoInvariants(ctx) {
   checkBrandmarkInPrompt(ctx);
   checkReferenceCompleteness(ctx, meta);
   checkClipSpanFitsModel(ctx, meta);
+  checkTimelineContract(ctx, meta);
+  checkNativeSegOverlap(ctx);
+  checkSpineNormalized(ctx, meta);
+  checkOddDimensions(ctx);
+  checkRegionDropped(ctx);
+}
+function checkPromptProfile(ctx) {
+  for (const n of ctx.canvas.nodes) {
+    if (n.type !== "video_generate") continue;
+    const model = n.params?.model;
+    if (typeof model !== "string" || clipProfileFor(model)) continue;
+    ctx.issues.push({
+      path: `nodes[${ctx.idToIndex.get(n.id) ?? -1}].params.model`,
+      code: STAGE_CODES.PROMPT_PROFILE_MISSING,
+      severity: "warning",
+      node_id: n.id,
+      message: `"${n.id}" runs on "${model}", a model with no clip-prompt profile \u2014 its prompt was authored with the default Seedance syntax. Review the dialogue/emotion markup for this model before billing`
+    });
+  }
+}
+var TECHNIQUE_CUE = /\b(camera|push[- ]?in|pull[- ]?out|pan|dolly|zoom|tilt|track|handheld|locked|orbit|crane|whip|motion|move)\b/i;
+var NEGATIVES_CUE = /\bavoid:|\bno subtitles|\bnegative\b|keep it clean and stable/i;
+var VIBE_CUE = /\b(light|lighting|golden|moody|warm|cool|tone|grade|contrast|shadow|glow|rim|backlit|neon|soft|harsh)\b/i;
+function checkPromptDecisions(ctx) {
+  for (const n of ctx.canvas.nodes) {
+    if (n.type !== "video_generate") continue;
+    const params = n.params;
+    const prompt = typeof params?.prompt === "string" ? params.prompt : "";
+    if (!prompt) continue;
+    const hasTechnique = TECHNIQUE_CUE.test(prompt);
+    const hasNegatives = NEGATIVES_CUE.test(prompt) || typeof params?.negative_prompt === "string";
+    if (hasTechnique || hasNegatives) continue;
+    ctx.issues.push({
+      path: `nodes[${ctx.idToIndex.get(n.id) ?? -1}].params.prompt`,
+      code: STAGE_CODES.PROMPT_DECISION_MISSING,
+      severity: "warning",
+      node_id: n.id,
+      message: `"${n.id}" is a thin clip prompt \u2014 it names no camera/motion move (TECHNIQUE) and no constraints (NEGATIVES: an affirmative "Keep it clean and stable" line, a negative_prompt param, or an "Avoid:" tail). Make the six decisions (route / spec / beats / copy / technique / negatives) so the model doesn't fill the gaps with drift. See prompt-anatomy.md`
+    });
+  }
+}
+function checkHookLayers(ctx) {
+  const scene0 = ctx.canvas.nodes.filter((n) => /^s0(?:[_a-z0-9])*_/.test(n.id) || n.id === "s0");
+  const hookClip = scene0.find((n) => n.type === "video_generate");
+  if (!hookClip) return;
+  const scene0Text = scene0.map((n) => {
+    const p = n.params?.prompt;
+    return typeof p === "string" ? p : "";
+  }).join("\n");
+  const hookParams = hookClip.params;
+  const hasOverlayLayer = ctx.canvas.nodes.some((n) => /hyperframe/.test(n.type));
+  const hasSound = hookParams?.generate_audio === true || /Dialogue:|Audio:/.test(scene0Text) || ctx.canvas.nodes.some((n) => n.type === "tts" || n.type === "dialogue" || n.type === "music");
+  const hasVisual = scene0Text.trim().length > 40;
+  const hasVibe = VIBE_CUE.test(scene0Text);
+  const missing = [];
+  if (!hasOverlayLayer) missing.push("text (overlay)");
+  if (!hasSound) missing.push("sound (line/SFX)");
+  if (!hasVisual) missing.push("visual (the frame)");
+  if (!hasVibe) missing.push("vibe (lighting/tone)");
+  if (missing.length < 2) return;
+  ctx.issues.push({
+    path: `nodes[${ctx.idToIndex.get(hookClip.id) ?? -1}]`,
+    code: STAGE_CODES.HOOK_LAYER_MISSING,
+    severity: "warning",
+    node_id: hookClip.id,
+    message: `the hook (scene 0) is thin across layers \u2014 missing ${missing.join(", ")}. A scroll-stopping hook works on all four layers (text / sound / visual / vibe); strengthen the missing ones. See hook-craft.md`
+  });
+}
+function checkImageProfile(ctx) {
+  for (const n of ctx.canvas.nodes) {
+    if (n.type !== "image_generate") continue;
+    const model = n.params?.model;
+    if (typeof model !== "string" || imageProfileFor(model)) continue;
+    ctx.issues.push({
+      path: `nodes[${ctx.idToIndex.get(n.id) ?? -1}].params.model`,
+      code: STAGE_CODES.IMAGE_PROFILE_MISSING,
+      severity: "warning",
+      node_id: n.id,
+      message: `"${n.id}" renders on "${model}", an image model with no frame-prompt profile \u2014 it got the generic template (constraint placement / photoreal cue not tuned). Add an ImageModelProfile for this model`
+    });
+  }
+}
+function checkPersonGeneration(ctx) {
+  for (const n of ctx.canvas.nodes) {
+    if (n.type !== "video_generate") continue;
+    const params = n.params;
+    const model = params?.model;
+    if (clipProfileFor(typeof model === "string" ? model : "")?.id !== "veo") continue;
+    const hasKeyframe = Boolean(n.inputs?.first_frame ?? n.inputs?.reference);
+    if (!hasKeyframe || params?.person_generation) continue;
+    ctx.issues.push({
+      path: `nodes[${ctx.idToIndex.get(n.id) ?? -1}].params`,
+      code: STAGE_CODES.PERSON_GENERATION_MISSING,
+      severity: "warning",
+      node_id: n.id,
+      message: `Veo clip "${n.id}" drives from a keyframe but sets no person_generation \u2014 set "allow_adult" (the only legal value for image-to-video, and the only one allowed in the EU/UK)`
+    });
+  }
+}
+function checkPromptBudget(ctx) {
+  for (const n of ctx.canvas.nodes) {
+    if (n.type !== "video_generate") continue;
+    const params = n.params;
+    const model = params?.model;
+    const prompt = params?.prompt;
+    const profile = typeof model === "string" ? clipProfileFor(model) : void 0;
+    if (!profile || typeof prompt !== "string") continue;
+    const words = prompt.trim().split(/\s+/).filter(Boolean).length;
+    if (words <= profile.wordBudget) continue;
+    ctx.issues.push({
+      path: `nodes[${ctx.idToIndex.get(n.id) ?? -1}].params.prompt`,
+      code: STAGE_CODES.PROMPT_OVER_BUDGET,
+      severity: "warning",
+      node_id: n.id,
+      message: `"${n.id}" prompt is ${words} words \u2014 over ${model}'s ~${profile.wordBudget}-word budget; trim it (the frames carry the content, so keep the clip prompt to motion + audio)`
+    });
+  }
+}
+function checkRawFaceKeyframe(ctx) {
+  for (const n of ctx.canvas.nodes) {
+    if (n.type !== "video_generate") continue;
+    const model = n.params?.model;
+    if (clipProfileFor(typeof model === "string" ? model : "")?.id !== "seedance") continue;
+    const src = refNodeOf(ctx, n.inputs?.first_frame ?? n.inputs?.reference);
+    if (!src || src.type !== "ingest") continue;
+    ctx.issues.push({
+      path: `nodes[${ctx.idToIndex.get(n.id) ?? -1}].inputs.first_frame`,
+      code: STAGE_CODES.RAW_FACE_KEYFRAME,
+      severity: "warning",
+      node_id: n.id,
+      message: `Seedance clip "${n.id}" animates a RAW ingested image ("${src.id}"), not a generated frame \u2014 if it shows a real human face, ByteDance's real-person filter rejects it (422). Anchor on an AI-generated portrait (recast), or route this clip to Veo`
+    });
+  }
+}
+function spineTotalS(ctx, spine) {
+  let total = 0;
+  const inputs = Object.entries(spine.inputs ?? {}).filter(([k]) => /^c\d+$/.test(k));
+  if (inputs.length === 0) return null;
+  for (const [, v] of inputs) {
+    const d = liveNodeDurationS(ctx, refNodeOf(ctx, v));
+    if (d === null) return null;
+    total += d;
+  }
+  const graph = spine.params.args?.join?.(" ") ?? "";
+  for (const m of String(graph).matchAll(/xfade=transition=[^:]+:duration=([\d.]+)/g)) {
+    total -= Number(m[1]);
+  }
+  return total;
+}
+function checkTimelineContract(ctx, meta) {
+  const stamp = meta.timeline;
+  const spineId = stamp?.spine_node ?? (ctx.idToIndex.has("spine") ? "spine" : null);
+  if (!spineId) return;
+  const expected = stamp?.expected_total_s ?? meta.duration_s;
+  checkSpineTotal(ctx, spineId, expected);
+  checkAudioTimelineTotals(ctx, stamp?.audio_mix_node, expected);
+}
+function checkSpineTotal(ctx, spineId, expected) {
+  const spineIdx = ctx.idToIndex.get(spineId);
+  const spine = spineIdx === void 0 ? null : ctx.canvas.nodes[spineIdx];
+  const spineLen = spine ? spineTotalS(ctx, spine) : null;
+  if (spineLen === null || Math.abs(spineLen - expected) <= VIDEO_TIME_SLACK_S) return;
+  ctx.issues.push({
+    path: `nodes[${spineIdx}].params.args`,
+    code: STAGE_CODES.TIMELINE_TOTAL,
+    node_id: spineId,
+    message: `the picture sums to ${round2(spineLen)}s but the timeline is pinned to ${expected}s \u2014 \`-shortest\` at the final mux will silently cut the longer stream. Re-time the seg trims (or the audio total_ms) so both match`
+  });
+}
+function checkAudioTimelineTotals(ctx, audioMixNode, expected) {
+  const mustBeFullLength = /* @__PURE__ */ new Set();
+  if (audioMixNode) mustBeFullLength.add(audioMixNode);
+  ctx.canvas.nodes.forEach((n) => {
+    if (n.type !== "audio_voice_convert") return;
+    const track = refNodeOf(ctx, (n.inputs ?? {}).audio);
+    if (track?.type === "audio_timeline") mustBeFullLength.add(track.id);
+  });
+  for (const id of mustBeFullLength) {
+    const idx = ctx.idToIndex.get(id);
+    const node = idx === void 0 ? null : ctx.canvas.nodes[idx];
+    const totalMs = node?.params?.total_ms;
+    if (typeof totalMs !== "number") continue;
+    if (Math.abs(totalMs / 1e3 - expected) > VIDEO_TIME_SLACK_S) {
+      ctx.issues.push({
+        path: `nodes[${idx}].params.total_ms`,
+        code: STAGE_CODES.TIMELINE_TOTAL,
+        node_id: id,
+        message: `audio timeline "${id}" is pinned to ${totalMs}ms but the picture timeline is ${expected}s \u2014 \`-shortest\` at the final mux will silently cut the longer stream. Pin total_ms to ${Math.round(expected * 1e3)}`
+      });
+    }
+  }
+}
+function checkNativeSegOverlap(ctx) {
+  for (const conv of ctx.canvas.nodes) {
+    if (conv.type !== "audio_voice_convert") continue;
+    const track = refNodeOf(ctx, (conv.inputs ?? {}).audio);
+    if (track?.type !== "audio_timeline") continue;
+    const params = track.params;
+    const windows = (params.tracks ?? []).map((t) => {
+      const extract = refNodeOf(ctx, (track.inputs ?? {})[t.slot]);
+      const len = t.duration_s ?? (extract ? ffmpegTrimSeconds(extract) : null);
+      return len === null ? null : { slot: t.slot, start: t.start_s, end: t.start_s + len };
+    }).filter((w) => w !== null).sort((a, b) => a.start - b.start);
+    for (let i = 1; i < windows.length; i++) {
+      const prev = windows[i - 1];
+      const cur = windows[i];
+      if (!prev || !cur || cur.start >= prev.end - 0.01) continue;
+      const trackIdx = ctx.idToIndex.get(track.id);
+      ctx.issues.push({
+        path: `nodes[${trackIdx}].params.tracks`,
+        code: STAGE_CODES.NATIVE_SEG_OVERLAP,
+        node_id: track.id,
+        message: `voice track "${track.id}": "${prev.slot}" runs to ${round2(prev.end)}s but "${cur.slot}" starts at ${cur.start}s \u2014 both play at once (echo). Cap the first with duration_s: ${round2(cur.start - prev.start)} or re-time the windows`
+      });
+    }
+  }
+}
+function checkSpineNormalized(ctx, meta) {
+  const spineId = meta.timeline?.spine_node ?? "spine";
+  const idx = ctx.idToIndex.get(spineId);
+  const spine = idx === void 0 ? null : ctx.canvas.nodes[idx];
+  if (!spine || spine.type !== "ffmpeg") return;
+  const args = spine.params.args;
+  const graph = Array.isArray(args) ? args.join(" ") : "";
+  if (!graph.includes("concat=n=")) return;
+  if (/\[\d+:v\](?:\[|concat)/.test(graph)) {
+    ctx.issues.push({
+      path: `nodes[${idx}].params.args`,
+      code: STAGE_CODES.SPINE_UNNORMALIZED,
+      severity: "warning",
+      node_id: spineId,
+      message: `the spine concat feeds raw input labels \u2014 generated clips carry no fps/SAR guarantee, and one 24fps clip silently stretches the picture off the audio/overlay clock. Chain \`format=yuv420p,fps=30,setsar=1,settb=AVTB\` on every input before the concat`
+    });
+  }
+}
+function checkOddDimensions(ctx) {
+  ctx.canvas.nodes.forEach((node, idx) => {
+    if (node.type !== "ffmpeg") return;
+    const args = node.params.args;
+    const blob = Array.isArray(args) ? args.join(" ") : "";
+    for (const m of blob.matchAll(/(?:scale|crop|pad)=(\d+):(\d+)/g)) {
+      const w = Number(m[1]);
+      const h = Number(m[2]);
+      if (w % 2 === 0 && h % 2 === 0) continue;
+      ctx.issues.push({
+        path: `nodes[${idx}].params.args`,
+        code: STAGE_CODES.ODD_DIMENSIONS,
+        severity: "warning",
+        node_id: node.id,
+        message: `"${m[0]}" produces an odd dimension \u2014 libx264 yuv420p rejects odd sizes, so this node fails at render time. Round both to even numbers`
+      });
+      return;
+    }
+  });
+}
+function checkRegionDropped(ctx) {
+  const regionClips = /* @__PURE__ */ new Map();
+  for (const node of ctx.canvas.nodes) {
+    const m = /^s(\d+)_r\d+_clip$/.exec(node.id);
+    if (m && node.type === "video_generate")
+      regionClips.set(m[1], (regionClips.get(m[1]) ?? 0) + 1);
+  }
+  for (const [scene, billed] of regionClips) {
+    const idx = ctx.idToIndex.get(`s${scene}_composite`);
+    if (idx === void 0) continue;
+    const composite = ctx.canvas.nodes[idx];
+    const consumed = Object.keys(composite.inputs ?? {}).filter((k) => /^c\d+$/.test(k)).length;
+    if (billed > consumed) {
+      ctx.issues.push({
+        path: `nodes[${idx}].inputs`,
+        code: STAGE_CODES.REGION_DROPPED,
+        severity: "warning",
+        node_id: composite.id,
+        message: `scene s${scene} bills ${billed} region clips but its composite consumes ${consumed} \u2014 the extra generation is paid for and never reaches the frame. Wire every region into the composite or delete the unused clip node`
+      });
+    }
+  }
+}
+function round2(n) {
+  return Math.round(n * 100) / 100;
 }
 var ELEMENT_TYPE_KEYWORDS = {
   animal: ["dog", "puppy", "pup", "cat", "kitten", "kitty", "pet", "canine", "feline"],
@@ -2669,15 +3476,37 @@ function checkSpeechOverrun(ctx, talkingScenes) {
     for (const n of ctx.canvas.nodes) {
       if (!nativeClipRe.test(n.id) || n.type !== "video_generate") continue;
       const overrun = speechOverrunOf(n, secondsPerWord(entry));
-      if (!overrun) continue;
-      ctx.issues.push({
-        path: `nodes[${ctx.idToIndex.get(n.id) ?? -1}].params.prompt`,
-        code: STAGE_CODES.SPEECH_OVERRUN,
-        message: `"${n.id}" asks Seedance to speak ~${Math.round(overrun.estSpeechS * 10) / 10}s of dialogue inside a ${overrun.duration}s clip \u2014 the line cannot fit (>${SPEECH_OVERRUN_RATIO}\xD7 the clip). Shorten the line, split the scene, or lengthen the clip duration`
-      });
+      if (overrun) {
+        ctx.issues.push({
+          path: `nodes[${ctx.idToIndex.get(n.id) ?? -1}].params.prompt`,
+          code: STAGE_CODES.SPEECH_OVERRUN,
+          message: `"${n.id}" asks Seedance to speak ~${Math.round(overrun.estSpeechS * 10) / 10}s of dialogue inside a ${overrun.duration}s clip \u2014 the line cannot fit (>${SPEECH_OVERRUN_RATIO}\xD7 the clip). Shorten the line, split the scene, or lengthen the clip duration`
+        });
+        continue;
+      }
+      checkSpeechExceedsExtract(ctx, n, entry);
     }
   }
 }
+function checkSpeechExceedsExtract(ctx, clip, entry) {
+  const params = clip.params;
+  if (params?.generate_audio !== true) return;
+  const line = nativeDialogueOf(params.prompt);
+  if (!line) return;
+  const regionTag = /^s\d+(_r\d+)?_clip$/.exec(clip.id)?.[1] ?? "";
+  const extractIdx = ctx.idToIndex.get(`s${entry.scene}${regionTag}_voextract`) ?? ctx.idToIndex.get(`s${entry.scene}_voextract`);
+  const extract = extractIdx === void 0 ? null : ctx.canvas.nodes[extractIdx];
+  const windowS = extract ? ffmpegTrimSeconds(extract) : null;
+  if (windowS === null) return;
+  const estSpeechS = line.split(/\s+/).filter(Boolean).length * secondsPerWord(entry);
+  if (estSpeechS <= windowS * SPEECH_OVERRUN_RATIO) return;
+  ctx.issues.push({
+    path: `nodes[${ctx.idToIndex.get(clip.id) ?? -1}].params.prompt`,
+    code: STAGE_CODES.SPEECH_EXCEEDS_EXTRACT,
+    node_id: clip.id,
+    message: `"${clip.id}"'s line is ~${Math.round(estSpeechS * 10) / 10}s of speech but its extract window (s${entry.scene}_voextract) is ${windowS}s \u2014 the read gets cut mid-word on the spine. Shorten the Dialogue line, lengthen the scene in prompt.json and re-scaffold, or raise the voextract \`-t\` when the read should carry over the next cutaway`
+  });
+}
 var UI_IN_PROMPT_RE = /\bscreen[- ]?(?:recording|capture|grab|share)\b|\bapp (?:interface|screen)\b|\bphone screen overlay\b/i;
 function checkUiInPrompt(ctx) {
   for (const n of ctx.canvas.nodes) {
@@ -2750,9 +3579,9 @@ function checkOutputRef(ctx) {
 function pushZodIssues(issues, err, pathPrefix, code, nodeId, nodeType) {
   for (const issue of err.issues) {
     const tail2 = pathToString(issue.path);
-    const path16 = pathPrefix ? tail2 ? `${pathPrefix}.${tail2}` : pathPrefix : tail2;
+    const path17 = pathPrefix ? tail2 ? `${pathPrefix}.${tail2}` : pathPrefix : tail2;
     issues.push({
-      path: path16,
+      path: path17,
       code,
       message: issue.message,
       received: issue.code === "invalid_type" ? issue.received : void 0,
@@ -2761,8 +3590,8 @@ function pushZodIssues(issues, err, pathPrefix, code, nodeId, nodeType) {
     });
   }
 }
-function pathToString(path16) {
-  return path16.map((p) => typeof p === "number" ? `[${p}]` : `.${String(p)}`).join("").replace(/^\./, "");
+function pathToString(path17) {
+  return path17.map((p) => typeof p === "number" ? `[${p}]` : `.${String(p)}`).join("").replace(/^\./, "");
 }
 function buildDepGraph(canvas) {
   const graph = /* @__PURE__ */ new Map();
@@ -2841,6 +3670,7 @@ var Engine = class {
   cache;
   outputsDir;
   log;
+  persistAssets;
   constructor(opts) {
     this.registry = opts.registry;
     this.client = opts.client;
@@ -2848,6 +3678,7 @@ var Engine = class {
     this.cache = opts.cache;
     this.outputsDir = opts.outputsDir;
     this.log = opts.log ?? (() => void 0);
+    this.persistAssets = opts.persistAssets ?? false;
   }
   validate(canvas) {
     return validateCanvas(canvas, this.registry);
@@ -2859,6 +3690,12 @@ var Engine = class {
   async run(input, opts = {}) {
     const validation = await this.validateDeep(input);
     if (!validation.ok) throw new ValidationError(validation.issues);
+    if (opts.max_credits !== void 0 && validation.estimatedCredits > opts.max_credits) {
+      throw new RunAbortedError(
+        "cost_cap",
+        `estimated ${validation.estimatedCredits} credits exceeds the ${opts.max_credits}-credit cap \u2014 nothing was billed; raise --max-credits or shrink the canvas`
+      );
+    }
     const canvas = validation.canvas;
     const runId = opts.run_id ?? `r_${ulid()}`;
     const writer = new OutputWriter({ outputsDir: this.outputsDir, runId });
@@ -2871,7 +3708,16 @@ var Engine = class {
     const outputs = {};
     const counters = { cachedNodes: 0, totalCredits: 0 };
     const nodeRuns = [];
-    await this.runLayers(canvas, outputs, runId, writer, opts, counters, nodeRuns);
+    const graph = this.pruneToOutput(canvas, buildGraph(canvas));
+    const needsBytes = computeNeedsLocalBytes(canvas, graph, this.registry);
+    this.emitProgress(opts, {
+      kind: "plan",
+      nodes: [...graph.entries()].map(([id, deps]) => {
+        const node = canvas.nodes.find((n) => n.id === id);
+        return { node_id: id, node_type: node?.type ?? "unknown", deps: [...deps], params: node?.params };
+      })
+    });
+    await this.runLayers(canvas, graph, outputs, runId, writer, opts, counters, nodeRuns, needsBytes);
     const output = pickFinalOutput(canvas, outputs);
     const stats = {
       total_nodes: canvas.nodes.length,
@@ -2894,39 +3740,63 @@ var Engine = class {
       `[done    ] ${stats.cached_nodes}/${stats.total_nodes} cached, ${stats.total_credits} credits, ${stats.duration_ms}ms`
     );
     this.log(`outputs in: ${writer.runDir}`);
-    return { run_id: runId, output, outputs_by_node: outputs, stats, outputs_dir: writer.runDir };
+    return { run_id: runId, output, outputs_by_node: outputs, stats, outputs_dir: writer.runDir, node_runs: nodeRuns };
   }
-  async runLayers(canvas, outputs, runId, writer, opts, counters, nodeRuns) {
-    const layers = topologicalLayers(this.pruneToOutput(canvas, buildGraph(canvas)));
+  async runLayers(canvas, graph, outputs, runId, writer, opts, counters, nodeRuns, needsBytes) {
+    const layers = topologicalLayers(graph);
     const limit = resolveConcurrency(opts.concurrency);
     for (const layer of layers) {
-      const settled = await mapWithConcurrency(
-        layer,
-        limit,
-        (nodeId) => this.executeOne(canvas, nodeId, outputs, runId, writer, opts).then((r) => {
+      if (opts.signal?.aborted) throw new RunAbortedError("signal", "run aborted before layer dispatch");
+      if (opts.max_credits !== void 0 && counters.totalCredits > opts.max_credits) {
+        throw new RunAbortedError(
+          "cost_cap",
+          `spent ${counters.totalCredits} credits, over the ${opts.max_credits}-credit cap \u2014 completed nodes are cached; raise --max-credits to continue where this stopped`
+        );
+      }
+      const settled = await mapWithConcurrency(layer, limit, (nodeId) => {
+        if (opts.signal?.aborted) {
+          return Promise.reject(new RunAbortedError("signal", "run aborted before node dispatch"));
+        }
+        this.emitProgress(opts, { kind: "node_start", node_id: nodeId });
+        return this.executeOne(canvas, nodeId, outputs, runId, writer, opts, needsBytes.has(nodeId)).then((r) => {
           if (r.cached) counters.cachedNodes++;
           counters.totalCredits += r.credits;
           const node = canvas.nodes.find((n) => n.id === nodeId);
           if (node) {
-            nodeRuns.push({
+            const run = {
               node_id: nodeId,
               node_type: node.type,
               cached: r.cached,
               duration_ms: r.durationMs,
               credits: r.credits
-            });
+            };
+            nodeRuns.push(run);
+            this.emitProgress(opts, { kind: "node_settled", run, outputs: outputs[nodeId] ?? {} });
           }
-        })
-      );
+        });
+      });
       const failures = [];
       settled.forEach((result, i) => {
         const nodeId = layer[i];
-        if (result.status === "rejected" && nodeId) failures.push({ nodeId, reason: result.reason });
+        if (result.status === "rejected" && nodeId) {
+          if (result.reason instanceof RunAbortedError) return;
+          failures.push({ nodeId, reason: result.reason });
+          this.emitProgress(opts, { kind: "node_failed", node_id: nodeId });
+        }
       });
+      if (opts.signal?.aborted) throw new RunAbortedError("signal", "run aborted by signal");
       if (failures.length === 1 && failures[0]) throw failures[0].reason;
       if (failures.length > 1) throw new LayerExecutionError(failures);
     }
   }
+  /** Progress consumers are observers only — an exception there must never fail the run. */
+  emitProgress(opts, event) {
+    if (!opts.onProgress) return;
+    try {
+      opts.onProgress(event);
+    } catch {
+    }
+  }
   /**
    * Dead-node elimination: when the canvas declares an `output`, execute only the
    * nodes that output transitively depends on. Orphaned nodes (left by an edit or
@@ -2957,12 +3827,13 @@ var Engine = class {
     }
     await writer.writeManifest("_final", output);
   }
-  async executeOne(canvas, nodeId, outputs, runId, writer, opts) {
+  async executeOne(canvas, nodeId, outputs, runId, writer, opts, downloadOutputs) {
     const node = canvas.nodes.find((n) => n.id === nodeId);
     if (!node) throw new Error(`executor: missing node ${nodeId}`);
     const def = this.registry.get(node.type);
     if (!def) throw new Error(`executor: missing registry entry for type ${node.type}`);
-    const prepared = await prepareForExecution(node, outputs, def, canvas.cache_salt, this.assets);
+    const regenerateToken = resolveRegenerateToken(node, opts.regenerate, runId);
+    const prepared = await prepareForExecution(node, outputs, def, canvas.cache_salt, regenerateToken, this.assets);
     const policy = opts.cache_policy ?? "read_write";
     if (policy !== "bypass") {
       const cacheT0 = Date.now();
@@ -2980,17 +3851,27 @@ var Engine = class {
       nodeId: node.id,
       nodeType: node.type,
       cacheKey: prepared.cacheKey,
+      downloadOutputs,
       client: this.client,
       assets: this.assets,
       log: this.log,
       signal: opts.signal
     };
-    const { parsedInputs, parsedParams } = parseNodeArgs(def, prepared, node.id, node.type);
+    const preparedForExec = needsLocalMaterialization(def) ? { ...prepared, resolvedInputs: await this.materializeLocalInputs(prepared.resolvedInputs) } : prepared;
+    const { parsedInputs, parsedParams } = parseNodeArgs(def, preparedForExec, node.id, node.type);
     const result = await invokeExecute(def, parsedInputs, parsedParams, ctx, node.id, node.type);
     const elapsed = Date.now() - t0;
     const credits = def.cost ? def.cost({ params: parsedParams }).credits : 0;
     const outputsObj = result;
     outputs[node.id] = outputsObj;
+    if (this.persistAssets) {
+      try {
+        await persistOutputAssetUrls(outputsObj, ctx);
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        this.log(`[warn    ] ${node.id}: asset persistence failed (${msg}) \u2014 outputs stay local-only`);
+      }
+    }
     if (policy === "read_write") {
       await this.cache.put({
         cacheKey: prepared.cacheKey,
@@ -3019,8 +3900,42 @@ var Engine = class {
       }
     }
   }
+  /**
+   * Download any URL-only asset ref reachable in a local node's inputs so the
+   * bytes are on disk before the local runner stages them. Returns a copy —
+   * refs are replaced, never mutated in place, so the producer's cached output
+   * (shared object) keeps its URL-only shape.
+   */
+  async materializeLocalInputs(inputs) {
+    const fix = async (value) => {
+      if (Array.isArray(value)) return Promise.all(value.map(fix));
+      if (value && typeof value === "object") {
+        const v = value;
+        if (typeof v.kind === "string" && typeof v.url === "string" && typeof v.sha256 === "string" && typeof v.mime === "string" && typeof v.path !== "string") {
+          this.log(`[warn    ] materializing URL-only input on demand (${v.kind}/${v.mime}) \u2014 missed graph edge`);
+          return this.assets.ingestRemote({
+            kind: v.kind,
+            url: v.url,
+            sha256: v.sha256,
+            mime: v.mime,
+            metadata: v.metadata
+          });
+        }
+        const out = {};
+        for (const [k, val] of Object.entries(v)) out[k] = await fix(val);
+        return out;
+      }
+      return value;
+    };
+    return await fix(inputs);
+  }
 };
-async function prepareForExecution(node, outputs, def, cacheSalt, assets) {
+function resolveRegenerateToken(node, forced, runId) {
+  if (forced?.has(node.id)) return `run:${runId}`;
+  if (node.regenerate !== void 0) return `node:${String(node.regenerate)}`;
+  return void 0;
+}
+async function prepareForExecution(node, outputs, def, cacheSalt, regenerateToken, assets) {
   const resolvedInputs = resolveRefs(node.inputs ?? {}, { outputs }) ?? {};
   const resolvedParams = resolveRefs(node.params ?? {}, { outputs }) ?? {};
   const slotValues = await hydrateTextSlots(resolvedInputs, assets, node.id, node.type);
@@ -3033,6 +3948,9 @@ async function prepareForExecution(node, outputs, def, cacheSalt, assets) {
       throw new NodeExecutionError(node.id, node.type, { kind: "local", cause: e });
     }
   }
+  if (regenerateToken !== void 0) {
+    extras = { ...extras ?? {}, __regenerate__: regenerateToken };
+  }
   const cacheKey = computeCacheKey({
     node_id: node.type,
     node_version: def.version,
@@ -3061,6 +3979,9 @@ async function invokeExecute(def, parsedInputs, parsedParams, ctx, nodeId, nodeT
     throw new NodeExecutionError(nodeId, nodeType, { kind: "local", cause: e });
   }
 }
+function needsLocalMaterialization(def) {
+  return def.location === "local" && !def.passthroughRefs;
+}
 function pickFinalOutput(canvas, outputs) {
   if (canvas.output) {
     const node = outputs[canvas.output.node];
@@ -3071,6 +3992,16 @@ function pickFinalOutput(canvas, outputs) {
   const lastOut = outputs[last.id];
   return lastOut ? Object.values(lastOut)[0] : void 0;
 }
+function computeNeedsLocalBytes(canvas, graph, registry) {
+  const typeById = new Map(canvas.nodes.map((n) => [n.id, n.type]));
+  const needs = /* @__PURE__ */ new Set();
+  for (const [consumerId, deps] of graph) {
+    const def = registry.get(typeById.get(consumerId) ?? "");
+    if (def?.location !== "local" || def.passthroughRefs) continue;
+    for (const dep of deps) needs.add(dep);
+  }
+  return needs;
+}
 function buildGraph(canvas) {
   const graph = /* @__PURE__ */ new Map();
   for (const n of canvas.nodes) graph.set(n.id, /* @__PURE__ */ new Set());
@@ -3105,11 +4036,11 @@ function hashInputs(inputs) {
   const out = {};
   for (const [k, v] of Object.entries(inputs)) {
     if (Array.isArray(v)) {
-      out[k] = v.map((el) => extractSha(el) ?? canonicalLiteral(el));
+      out[k] = v.map((el) => extractSha(el) ?? canonicalLiteral(normalizeParamsForCacheKey(el)));
     } else {
       const s = extractSha(v);
       if (s !== null) out[k] = s;
-      else out[k] = canonicalLiteral(v);
+      else out[k] = canonicalLiteral(normalizeParamsForCacheKey(v));
     }
   }
   return out;
@@ -3201,7 +4132,16 @@ async function hydrateSlotValue(value, assets, nodeId, nodeType) {
   try {
     bytes = await assets.readBytes(value.sha256, value.mime);
   } catch (e) {
-    throw new NodeExecutionError(nodeId, nodeType, { kind: "local", cause: e });
+    if (value.url) {
+      try {
+        await assets.ingestRemote({ kind: value.kind, url: value.url, sha256: value.sha256, mime: value.mime });
+        bytes = await assets.readBytes(value.sha256, value.mime);
+      } catch (e2) {
+        throw new NodeExecutionError(nodeId, nodeType, { kind: "local", cause: e2 });
+      }
+    } else {
+      throw new NodeExecutionError(nodeId, nodeType, { kind: "local", cause: e });
+    }
   }
   if (bytes.length > MAX_INLINE_TEXT_BYTES) {
     throw new NodeExecutionError(nodeId, nodeType, {
@@ -3261,9 +4201,9 @@ var NodeRegistry = class {
 
 // src/engine/nodes/ingest.ts
 import { execFile as execFileCb, spawn } from "child_process";
-import { mkdtemp, readdir, readFile as readFile2, rm, stat as stat2 } from "fs/promises";
+import { mkdtemp, readdir, readFile as readFile3, rm, stat as stat2 } from "fs/promises";
 import { tmpdir } from "os";
-import path3 from "path";
+import path4 from "path";
 import { promisify } from "util";
 import { z as z5 } from "zod";
 
@@ -3309,27 +4249,6 @@ var FontRef = BaseAssetRef.extend({
 });
 var AssetRef = z4.discriminatedUnion("kind", [ImageRef, VideoRef, AudioRef, JsonRef, TextRef, FontRef]);
 
-// src/engine/nodes/remote/upload.ts
-async function presignAndPut(args) {
-  const { putUrl, publicUrl } = await args.ctx.client.presignAssetUpload(args.sha256, args.mime, args.ctx.signal);
-  const putRes = await fetch(putUrl, {
-    method: "PUT",
-    body: new Uint8Array(args.bytes),
-    headers: { "Content-Type": args.mime },
-    signal: args.ctx.signal
-  });
-  if (!putRes.ok) {
-    throw new Error(`upload: presigned PUT failed ${putRes.status} ${putRes.statusText}`);
-  }
-  return publicUrl;
-}
-async function ensureUploaded(ref, ctx) {
-  if (ref.url) return ref;
-  const bytes = await ctx.assets.readBytes(ref.sha256, ref.mime);
-  const url = await presignAndPut({ bytes, sha256: ref.sha256, mime: ref.mime, ctx });
-  return { ...ref, url };
-}
-
 // src/engine/nodes/remote/delegate.ts
 function delegated(spec) {
   return {
@@ -3357,7 +4276,9 @@ async function callBackendExec(args) {
         nodeVersion: args.nodeVersion,
         params: args.params,
         inputs: serialized,
-        idempotency_key: idempotencyKey
+        idempotency_key: idempotencyKey,
+        canvas_run_id: args.ctx.canvasRunId,
+        node_id: args.ctx.nodeId
       },
       args.ctx.signal
     );
@@ -3409,6 +4330,9 @@ async function ingestValue(value, ctx, declaredKind) {
   }
   if (isRawAsset(value)) {
     const kind = value.kind ?? declaredKind ?? "json";
+    if (ctx.downloadOutputs === false) {
+      return buildRef({ kind, sha: value.sha256, mime: value.mime, url: value.url, metadata: value.metadata });
+    }
     return ctx.assets.ingestRemote({
       kind,
       url: value.url,
@@ -3523,7 +4447,7 @@ function safePathname(rawUrl) {
 }
 var ingestNode = defineNode({
   id: "ingest",
-  version: "1.1.0",
+  version: "1.2.0",
   category: "io",
   location: "local",
   summary: "Ingest an external URL or a local file into the asset store. Declare the kind you expect (image/video/audio/text/json/font); the node picks the strategy. For source=url: yt-dlp for video/audio (YouTube/TikTok/Vimeo/etc. and direct file URLs), Handinger for HTML/PDF pages \u2192 markdown, direct HTTP fetch for binary URLs (images, fonts) and raw .txt/.md. For source=path: read from the local filesystem and upload to R2.",
@@ -3566,6 +4490,9 @@ function runStrategy(strategy, params, ctx) {
   }
 }
 async function execDirectFetch(params, ctx) {
+  if (params.expect === "image") {
+    return ingestImageUrl(params.url, ctx);
+  }
   const result = await callBackendExec({
     nodeType: "ingest",
     nodeVersion: ingestNode.version,
@@ -3576,6 +4503,37 @@ async function execDirectFetch(params, ctx) {
   });
   return assertAssetOutput(result, params.expect);
 }
+async function ingestImageUrl(url, ctx) {
+  const res = await fetch(url);
+  if (!res.ok) {
+    throw localExecError(ctx, `fetch ${url} \u2192 ${res.status}`);
+  }
+  const ab = await res.arrayBuffer();
+  if (ab.byteLength > MAX_ASSET_BYTES) {
+    throw localExecError(ctx, `file_too_large: ${url} is ${ab.byteLength} bytes (limit ${MAX_ASSET_BYTES})`);
+  }
+  let normalized;
+  try {
+    normalized = await toModelSafeImage(Buffer.from(ab));
+  } catch (e) {
+    throw localExecError(ctx, `${url}: ${e.message}`);
+  }
+  if (normalized.rasterizedFrom) {
+    ctx.log(`ingest: normalized ${normalized.rasterizedFrom} URL -> PNG (${normalized.bytes.length}B)`);
+  }
+  return uploadAndIngest({
+    bytes: normalized.bytes,
+    kind: "image",
+    mime: normalized.mime,
+    metadata: {
+      source_url: url,
+      strategy: "direct_fetch",
+      ingested_at: (/* @__PURE__ */ new Date()).toISOString(),
+      ...normalized.rasterizedFrom ? { rasterized_from: normalized.rasterizedFrom } : {}
+    },
+    ctx
+  });
+}
 async function execHandinger(params, ctx) {
   const result = await callBackendExec({
     nodeType: "ingest",
@@ -3603,8 +4561,8 @@ function resolveLocalPath(input) {
       `ingest: ~ path expansion is not supported (got "${input}"). Use an absolute path or a cwd-relative path.`
     );
   }
-  if (path3.isAbsolute(input)) return input;
-  return path3.resolve(process.cwd(), input);
+  if (path4.isAbsolute(input)) return input;
+  return path4.resolve(process.cwd(), input);
 }
 var EXT_TO_MIME = {
   png: "image/png",
@@ -3612,7 +4570,15 @@ var EXT_TO_MIME = {
   jpeg: "image/jpeg",
   webp: "image/webp",
   gif: "image/gif",
+  // Non-model-safe rasters `toModelSafeImage` transcodes to PNG at ingest — they
+  // must resolve to an image mime here or the kind-check rejects the local file
+  // before normalization ever runs.
   avif: "image/avif",
+  heic: "image/heic",
+  heif: "image/heif",
+  tif: "image/tiff",
+  tiff: "image/tiff",
+  bmp: "image/bmp",
   mp4: "video/mp4",
   webm: "video/webm",
   mov: "video/quicktime",
@@ -3644,7 +4610,7 @@ function sniffSvg(buf) {
   return head.startsWith("<?xml") ? head.includes("<svg") : head.startsWith("<svg");
 }
 function inferMimeFromPath(absPath, sniffBytes) {
-  const ext = path3.extname(absPath).slice(1).toLowerCase();
+  const ext = path4.extname(absPath).slice(1).toLowerCase();
   const fromExt = EXT_TO_MIME[ext];
   if (fromExt) return fromExt;
   const fromBytes = sniffImageMime(sniffBytes);
@@ -3663,15 +4629,45 @@ async function rasterizeSvgToPng(bytes) {
   }
   return await sharp(bytes, { density }).png({ force: true, palette: false }).toBuffer();
 }
+var MODEL_SAFE_IMAGE_MIMES = /* @__PURE__ */ new Set(["image/jpeg", "image/png", "image/gif", "image/webp"]);
+async function toModelSafeImage(bytes) {
+  const safe = sniffImageMime(bytes);
+  if (safe && MODEL_SAFE_IMAGE_MIMES.has(safe)) {
+    return { bytes, mime: safe };
+  }
+  if (sniffSvg(bytes)) {
+    return { bytes: await rasterizeSvgToPng(bytes), mime: "image/png", rasterizedFrom: "svg" };
+  }
+  const { default: sharp } = await import("sharp");
+  try {
+    const img = sharp(bytes);
+    const format = (await img.metadata()).format;
+    const png = await img.png({ force: true }).toBuffer();
+    return { bytes: png, mime: "image/png", rasterizedFrom: format ?? "unknown" };
+  } catch (e) {
+    throw new Error(`bytes are not a decodable image (${e.message})`);
+  }
+}
+function hasAscii(buf, offset, sig) {
+  return buf.length >= offset + sig.length && buf.toString("ascii", offset, offset + sig.length) === sig;
+}
+var HEIC_BRANDS = /* @__PURE__ */ new Set(["heic", "heix", "heim", "heis", "hevc", "hevx", "mif1", "msf1", "heif"]);
+function sniffIsoBmff(buf) {
+  if (!hasAscii(buf, 4, "ftyp")) return null;
+  const brand = buf.subarray(8, 12).toString("ascii");
+  if (brand === "avif" || brand === "avis") return "image/avif";
+  if (HEIC_BRANDS.has(brand)) return "image/heic";
+  return null;
+}
 function sniffImageMime(buf) {
   if (buf.length < 4) return null;
-  if (buf[0] === 137 && buf[1] === 80 && buf[2] === 78 && buf[3] === 71) return "image/png";
+  if (buf[0] === 137 && hasAscii(buf, 1, "PNG")) return "image/png";
   if (buf[0] === 255 && buf[1] === 216 && buf[2] === 255) return "image/jpeg";
-  if (buf[0] === 71 && buf[1] === 73 && buf[2] === 70) return "image/gif";
-  if (buf.length >= 12 && buf[0] === 82 && buf[1] === 73 && buf[2] === 70 && buf[3] === 70 && buf[8] === 87 && buf[9] === 69 && buf[10] === 66 && buf[11] === 80) {
-    return "image/webp";
-  }
-  return null;
+  if (hasAscii(buf, 0, "GIF")) return "image/gif";
+  if (hasAscii(buf, 0, "RIFF") && hasAscii(buf, 8, "WEBP")) return "image/webp";
+  if (hasAscii(buf, 0, "II*\0") || hasAscii(buf, 0, "MM\0*")) return "image/tiff";
+  if (hasAscii(buf, 0, "BM")) return "image/bmp";
+  return sniffIsoBmff(buf);
 }
 function findBoxPayload(buf, start, end, type) {
   let offset = start;
@@ -3724,10 +4720,10 @@ function inferKindFromMime(mime) {
   if (mime.startsWith("font/")) return "font";
   return null;
 }
-function localExecError(ctx, message) {
+function localExecError(ctx, message2) {
   return new NodeExecutionError(ctx.nodeId, ctx.nodeType, {
     kind: "local",
-    cause: new Error(`ingest: ${message}`)
+    cause: new Error(`ingest: ${message2}`)
   });
 }
 async function execLocalFile(params, ctx) {
@@ -3753,7 +4749,7 @@ async function execLocalFile(params, ctx) {
   }
   let bytes;
   try {
-    bytes = await readFile2(absPath);
+    bytes = await readFile3(absPath);
   } catch (e) {
     if (e.code === "EACCES") {
       throw localExecError(ctx, `permission_denied: ${absPath}`);
@@ -3774,17 +4770,20 @@ async function execLocalFile(params, ctx) {
   ctx.log(`ingest: local file ${stats.size}B mime=${mime}`);
   let outBytes = bytes;
   let outMime = mime;
-  if (mime === SVG_MIME) {
-    outBytes = await rasterizeSvgToPng(bytes);
-    outMime = "image/png";
-    ctx.log(`ingest: rasterized SVG -> PNG (${outBytes.length}B)`);
+  let rasterizedFrom;
+  if (kind === "image") {
+    const normalized = await toModelSafeImage(bytes);
+    outBytes = normalized.bytes;
+    outMime = normalized.mime;
+    rasterizedFrom = normalized.rasterizedFrom;
+    if (rasterizedFrom) ctx.log(`ingest: normalized ${rasterizedFrom} -> PNG (${outBytes.length}B)`);
   }
   const durationMs = probeVideoDurationMs(params.expect, outBytes, ctx);
   const ref = await uploadAndIngest({
     bytes: outBytes,
     kind: params.expect,
     mime: outMime,
-    metadata: localFileMetadata({ absPath, fileSize: stats.size, mime, durationMs }),
+    metadata: localFileMetadata({ absPath, fileSize: stats.size, mime, durationMs, rasterizedFrom }),
     ctx
   });
   return withProbedDuration(ref, durationMs);
@@ -3801,8 +4800,8 @@ function localFileMetadata(args) {
     strategy: "local_file",
     ingested_at: (/* @__PURE__ */ new Date()).toISOString(),
     file_size: args.fileSize,
-    original_filename: path3.basename(args.absPath),
-    ...args.mime === SVG_MIME ? { rasterized_from: "svg" } : {},
+    original_filename: path4.basename(args.absPath),
+    ...args.rasterizedFrom ? { rasterized_from: args.rasterizedFrom } : {},
     ...args.durationMs !== void 0 ? { duration_ms: args.durationMs } : {}
   };
 }
@@ -3825,7 +4824,7 @@ async function execYtDlp(params, ctx) {
   if (params.expect !== "video" && params.expect !== "audio") {
     throw new Error(`ingest: yt_dlp only handles video/audio, got expect=${params.expect}`);
   }
-  const workDir = await mkdtemp(path3.join(tmpdir(), "ingest-yt-"));
+  const workDir = await mkdtemp(path4.join(tmpdir(), "ingest-yt-"));
   try {
     const { filePath, info } = await runYtDlp({
       url: params.url,
@@ -3840,7 +4839,7 @@ async function execYtDlp(params, ctx) {
         `file_too_large: yt-dlp output for ${params.url} is ${downloadedStats.size} bytes (limit ${MAX_ASSET_BYTES})`
       );
     }
-    const bytes = await readFile2(filePath);
+    const bytes = await readFile3(filePath);
     const kind = params.expect;
     const mime = YT_DLP_MIME[kind];
     const metadata = buildYtDlpMetadata(params.url, info);
@@ -3852,8 +4851,8 @@ async function execYtDlp(params, ctx) {
   }
 }
 async function runYtDlp(args) {
-  const outTemplate = path3.join(args.workDir, "out.%(ext)s");
-  const infoPath = path3.join(args.workDir, "out.info.json");
+  const outTemplate = path4.join(args.workDir, "out.%(ext)s");
+  const infoPath = path4.join(args.workDir, "out.info.json");
   const argv = [
     args.url,
     "--no-playlist",
@@ -3886,11 +4885,11 @@ ${tail(stderr, 40)}`)
   }
   let info = {};
   try {
-    const raw = await readFile2(infoPath, "utf-8");
+    const raw = await readFile3(infoPath, "utf-8");
     info = JSON.parse(raw);
   } catch {
   }
-  return { filePath: path3.join(args.workDir, downloaded), info };
+  return { filePath: path4.join(args.workDir, downloaded), info };
 }
 function buildYtDlpMetadata(sourceUrl, info) {
   const out = {
@@ -3979,9 +4978,9 @@ import { z as z6 } from "zod";
 
 // src/engine/nodes/local/lib/cli-runner.ts
 import { execFile as execFileCb2, spawn as spawn2 } from "child_process";
-import { copyFile as copyFile2, mkdtemp as mkdtemp2, readFile as readFile3, rm as rm2, stat as stat3 } from "fs/promises";
+import { copyFile as copyFile2, mkdtemp as mkdtemp2, readFile as readFile4, rm as rm2, stat as stat3 } from "fs/promises";
 import { tmpdir as tmpdir2 } from "os";
-import path4 from "path";
+import path5 from "path";
 import { promisify as promisify2 } from "util";
 var execFile2 = promisify2(execFileCb2);
 var DEFAULT_TIMEOUT_MS = 10 * 60 * 1e3;
@@ -4008,7 +5007,7 @@ function mimeForExt(ext) {
 }
 function extForAssetRef(ref) {
   if (ref.path) {
-    const e = path4.extname(ref.path);
+    const e = path5.extname(ref.path);
     if (e) return e;
   }
   const reverse = {
@@ -4030,14 +5029,14 @@ function planArrayInputSlot(tmpDir, slot, values, lookup, stagedInputs) {
     const ref = values[i];
     if (!ref) continue;
     if (!ref.path) throw new Error(`cli-runner: inputs.${slot}[${i}] has no local path`);
-    const dest = path4.join(tmpDir, `in_${slot}_${i}${extForAssetRef(ref)}`);
+    const dest = path5.join(tmpDir, `in_${slot}_${i}${extForAssetRef(ref)}`);
     stagedInputs.push({ srcPath: ref.path, destPath: dest });
     lookup.set(`in.${slot}.${i}`, dest);
   }
 }
 function planSingleInputSlot(tmpDir, slot, ref, lookup, stagedInputs) {
   if (!ref.path) throw new Error(`cli-runner: inputs.${slot} has no local path`);
-  const dest = path4.join(tmpDir, `in_${slot}${extForAssetRef(ref)}`);
+  const dest = path5.join(tmpDir, `in_${slot}${extForAssetRef(ref)}`);
   stagedInputs.push({ srcPath: ref.path, destPath: dest });
   lookup.set(`in.${slot}`, dest);
 }
@@ -4045,7 +5044,7 @@ function planOutputs(tmpDir, outputs, lookup) {
   const outputPaths = [];
   for (const [name, spec] of Object.entries(outputs)) {
     const ext = spec.ext.startsWith(".") ? spec.ext : `.${spec.ext}`;
-    const absPath = path4.join(tmpDir, `out_${name}${ext}`);
+    const absPath = path5.join(tmpDir, `out_${name}${ext}`);
     outputPaths.push({ name, absPath, spec });
     lookup.set(`out.${name}`, absPath);
   }
@@ -4086,8 +5085,8 @@ function rejectRawPaths(substituted, original, stagingDir) {
     throw new Error(`cli-runner: home-relative path "${original}" not allowed in args.`);
   }
   if (substituted.startsWith("/")) {
-    const resolved = path4.resolve(substituted);
-    if (!resolved.startsWith(`${stagingDir}${path4.sep}`) && resolved !== stagingDir) {
+    const resolved = path5.resolve(substituted);
+    if (!resolved.startsWith(`${stagingDir}${path5.sep}`) && resolved !== stagingDir) {
       throw new Error(
         `cli-runner: raw filesystem path "${original}" not allowed \u2014 declare an input slot and use {{in.<slot>}} instead.`
       );
@@ -4137,7 +5136,7 @@ function tailLines(text, maxLines) {
 }
 async function runCli(opts) {
   const { bin, args, inputs, outputs, ctx, timeoutMs = DEFAULT_TIMEOUT_MS } = opts;
-  const tmpDir = await mkdtemp2(path4.join(tmpdir2(), `cli-${bin.replace(/[^a-z0-9]/gi, "")}-`));
+  const tmpDir = await mkdtemp2(path5.join(tmpdir2(), `cli-${bin.replace(/[^a-z0-9]/gi, "")}-`));
   try {
     const { lookup, stagedInputs, outputPaths } = planPlaceholders(tmpDir, inputs, outputs);
     await stageInputs(stagedInputs);
@@ -4159,7 +5158,7 @@ ${tailLines(stderr, 40)}`);
       if (!s?.isFile() || s.size === 0) {
         throw new Error(`cli-runner: declared output "${name}" missing or empty at ${absPath}`);
       }
-      const bytes = await readFile3(absPath);
+      const bytes = await readFile4(absPath);
       const ref = await ctx.assets.ingestBytes({
         bytes: Buffer.from(bytes),
         kind: spec.kind,
@@ -4199,6 +5198,12 @@ var Track = z6.object({
   slot: z6.string().min(1),
   /** When this track starts on the timeline, seconds from 0. */
   start_s: z6.number().min(0),
+  /**
+   * Optional hard cap on this track's length, seconds. The clip is trimmed BEFORE
+   * placement, so a source that runs long (an over-long voice extract, a converted
+   * track that came back oversized) cannot bleed into the next track's window.
+   */
+  duration_s: z6.number().positive().optional(),
   /** Optional level adjustment in dB (negative ducks, e.g. a music bed at -12). */
   gain_db: z6.number().optional()
 }).strict();
@@ -4255,7 +5260,10 @@ function buildAudioTimelineArgs(params) {
   params.tracks.forEach((track, i) => {
     inputArgs.push("-i", `{{in.${track.slot}}}`);
     const delayMs = Math.round(track.start_s * 1e3);
-    const steps = [`adelay=${delayMs}:all=1`];
+    const steps = [
+      ...track.duration_s !== void 0 ? [`atrim=0:${track.duration_s}`] : [],
+      `adelay=${delayMs}:all=1`
+    ];
     if (track.gain_db !== void 0) steps.push(`volume=${track.gain_db}dB`);
     const label = `a${i}`;
     filterChains.push(`[${i}:a]${steps.join(",")}[${label}]`);
@@ -4273,11 +5281,11 @@ function buildAudioTimelineArgs(params) {
 }
 var audioTimelineNode = defineNode({
   id: "audio_timeline",
-  version: "1.1.0",
+  version: "1.2.0",
   category: "audio",
   location: "local",
   summary: "Place and mix several audio clips onto one timeline: each track starts at a given second (optionally level-adjusted in dB), then they're combined into a single track. Built for laying a music bed plus timed voiceover lines and sound effects under a video.",
-  when_to_use: "Use to assemble a full audio bed from separately-generated clips \u2014 e.g. a `music` bed at 0 (ducked via `gain_db: -12`), each scene's `tts` voiceover at its scene start, and `sound_effect` hits at their timestamps. Wire each clip as `inputs.<slot>` (audio AssetRef) and list it in `params.tracks` with `{slot, start_s, gain_db?}`. Set `total_ms` to pin the final length to the video. Requires `ffmpeg` on PATH.",
+  when_to_use: "Use to assemble a full audio bed from separately-generated clips \u2014 e.g. a `music` bed at 0 (ducked via `gain_db: -12`), each scene's `tts` voiceover at its scene start, and `sound_effect` hits at their timestamps. Wire each clip as `inputs.<slot>` (audio AssetRef) and list it in `params.tracks` with `{slot, start_s, duration_s?, gain_db?}` (`duration_s` hard-caps a clip so it can't bleed into the next track's window). Set `total_ms` to pin the final length to the video. Requires `ffmpeg` on PATH.",
   inputs: AudioTimelineInputs,
   params: AudioTimelineParams,
   outputs: AudioTimelineOutputs,
@@ -4329,19 +5337,56 @@ var audioTimelineNode = defineNode({
   }
 });
 
-// src/engine/nodes/local/ffmpeg.ts
+// src/engine/nodes/local/collect.ts
 import { z as z7 } from "zod";
+var collectNode = defineNode({
+  id: "collect",
+  version: "1.0.0",
+  category: "data",
+  location: "local",
+  passthroughRefs: true,
+  summary: "Gather images from multiple upstream nodes into one ordered array \u2014 the standard terminal for multi-variant canvases whose final output is several images.",
+  when_to_use: "Point the canvas `output` at this node when several independent branches (e.g. one image_generate per scene/variant) must ALL be finals. Wire `inputs.images` as an array of refs like `$ref:gen_billboard_03.images#0` \u2014 each final inherits its producer node id as its label (or set `params.labels` to override), so variants stay identifiable in the dashboard and selection.",
+  inputs: z7.object({ images: z7.array(ImageRef).min(1) }).strict(),
+  params: z7.object({ labels: z7.array(z7.string().min(1)).min(1).optional() }).strict(),
+  outputs: z7.object({ images: z7.array(ImageRef).min(1) }).strict(),
+  outputKinds: { images: "image" },
+  cost: () => ({ credits: 0, seconds_estimate: 0 }),
+  // Arity is only knowable at validate time when `images` is a literal array;
+  // a single `$ref:` string to an upstream array output defers to runtime.
+  validateExtra: ({ rawParams, rawInputs }) => {
+    const labels = rawParams?.labels;
+    if (!Array.isArray(labels)) return [];
+    if (new Set(labels).size !== labels.length) {
+      return [{ path: "params.labels", message: "labels must be unique \u2014 each names one output variant" }];
+    }
+    const images = rawInputs?.images;
+    if (Array.isArray(images) && labels.length !== images.length) {
+      return [
+        {
+          path: "params.labels",
+          message: `labels has ${labels.length} entries but ${images.length} images are wired \u2014 provide one label per image`
+        }
+      ];
+    }
+    return [];
+  },
+  execute: ({ inputs }) => Promise.resolve({ images: inputs.images })
+});
+
+// src/engine/nodes/local/ffmpeg.ts
+import { z as z8 } from "zod";
 var FFMPEG_BIN2 = "ffmpeg";
-var OutputDecl = z7.object({
-  kind: z7.enum(["image", "video", "audio"]),
-  ext: z7.string().min(1).max(8)
+var OutputDecl = z8.object({
+  kind: z8.enum(["image", "video", "audio"]),
+  ext: z8.string().min(1).max(8)
 }).strict();
-var FfmpegParams = z7.object({
-  args: z7.array(z7.string()).min(1),
-  outputs: z7.record(z7.string(), OutputDecl).default({})
+var FfmpegParams = z8.object({
+  args: z8.array(z8.string()).min(1),
+  outputs: z8.record(z8.string(), OutputDecl).default({})
 }).strict();
-var FfmpegInputs = z7.record(z7.string(), z7.unknown());
-var FfmpegOutputs = z7.record(z7.string(), z7.custom());
+var FfmpegInputs = z8.record(z8.string(), z8.unknown());
+var FfmpegOutputs = z8.record(z8.string(), z8.custom());
 var ffmpegNode = defineNode({
   id: "ffmpeg",
   version: "2.0.0",
@@ -4371,17 +5416,17 @@ var ffmpegNode = defineNode({
 import { mkdtemp as mkdtemp3, rm as rm3, writeFile as writeFile3 } from "fs/promises";
 import { createRequire } from "module";
 import { tmpdir as tmpdir3 } from "os";
-import path6 from "path";
-import { z as z8 } from "zod";
+import path7 from "path";
+import { z as z9 } from "zod";
 
 // src/engine/nodes/local/lib/assets.ts
-import { copyFile as copyFile3, readFile as readFile4 } from "fs/promises";
-import path5 from "path";
+import { copyFile as copyFile3, readFile as readFile5 } from "fs/promises";
+import path6 from "path";
 async function stageAsset(ref, destDir, filename) {
   if (!ref.path) {
     throw new Error(`stageAsset: ref (${ref.kind}/${ref.mime}) has no local path`);
   }
-  const dest = path5.join(destDir, filename);
+  const dest = path6.join(destDir, filename);
   await copyFile3(ref.path, dest);
   return dest;
 }
@@ -4390,11 +5435,11 @@ async function refToUrl(ref) {
   if (!ref.path) {
     throw new Error("refToUrl: AssetRef has neither url nor path");
   }
-  const bytes = await readFile4(ref.path);
+  const bytes = await readFile5(ref.path);
   return `data:${ref.mime};base64,${bytes.toString("base64")}`;
 }
 var ASSET_KINDS = /* @__PURE__ */ new Set(["image", "video", "audio", "json", "text", "font"]);
-function isAssetRefLike(value) {
+function isAssetRefLike2(value) {
   if (!value || typeof value !== "object") return false;
   const v = value;
   return typeof v.kind === "string" && ASSET_KINDS.has(v.kind) && typeof v.mime === "string" && typeof v.sha256 === "string" && (typeof v.url === "string" || typeof v.path === "string");
@@ -4408,15 +5453,15 @@ var DEFAULT_SPECIMEN = [
   "abcdefghijklmnopqrstuvwxyz",
   `0123456789 !?&@#$%().,:;'"-`
 ].join("\n");
-var FontSpecimenParams = z8.object({
-  text: z8.string().min(1).max(2e3).optional().default(DEFAULT_SPECIMEN),
-  font_size: z8.number().int().min(8).max(512).optional().default(72),
-  padding: z8.number().int().min(0).max(512).optional().default(64),
-  line_height: z8.number().min(0.8).max(3).optional().default(1.35),
-  max_width: z8.number().int().min(256).max(4096).optional()
+var FontSpecimenParams = z9.object({
+  text: z9.string().min(1).max(2e3).optional().default(DEFAULT_SPECIMEN),
+  font_size: z9.number().int().min(8).max(512).optional().default(72),
+  padding: z9.number().int().min(0).max(512).optional().default(64),
+  line_height: z9.number().min(0.8).max(3).optional().default(1.35),
+  max_width: z9.number().int().min(256).max(4096).optional()
 }).strict();
-var FontSpecimenInputs = z8.object({ font: FontRef }).loose();
-var FontSpecimenOutputs = z8.object({ image: ImageRef }).strict();
+var FontSpecimenInputs = z9.object({ font: FontRef }).loose();
+var FontSpecimenOutputs = z9.object({ image: ImageRef }).strict();
 var DEVICE_SCALE_FACTOR = 2;
 var PAGE_TIMEOUT_MS = 3e4;
 function escapeHtml(text) {
@@ -4464,11 +5509,11 @@ var fontSpecimenNode = defineNode({
   outputKinds: { image: "image" },
   cost: () => ({ credits: 0, seconds_estimate: 5 }),
   async execute({ inputs, params, ctx }) {
-    const tmp = await mkdtemp3(path6.join(tmpdir3(), "font-specimen-"));
+    const tmp = await mkdtemp3(path7.join(tmpdir3(), "font-specimen-"));
     try {
       const fontFilename = `font.${extForMime(inputs.font.mime)}`;
       await stageAsset(inputs.font, tmp, fontFilename);
-      const entryPath = path6.join(tmp, "index.html");
+      const entryPath = path7.join(tmp, "index.html");
       await writeFile3(entryPath, buildSpecimenHtml(params, fontFilename), "utf-8");
       ctx.log(`rendering specimen (${params.font_size}px, ${params.text.split("\n").length} lines)`);
       const pwSpecifier = ["play", "wright"].join("");
@@ -4552,16 +5597,16 @@ var fontSpecimenNode = defineNode({
 
 // src/engine/nodes/local/hyperframe.ts
 import { execFile as execFile4 } from "child_process";
-import { copyFile as copyFile4, mkdtemp as mkdtemp4, readFile as readFile8, rm as rm4, stat as stat5, writeFile as writeFile5 } from "fs/promises";
+import { copyFile as copyFile4, mkdtemp as mkdtemp4, readFile as readFile9, rm as rm4, stat as stat5, writeFile as writeFile5 } from "fs/promises";
 import { createRequire as createRequire2 } from "module";
 import { cpus, tmpdir as tmpdir4 } from "os";
-import path11 from "path";
+import path12 from "path";
 import { promisify as promisify4 } from "util";
-import { z as z10 } from "zod";
+import { z as z11 } from "zod";
 
 // src/engine/engine/composition-hash.ts
-import { readdir as readdir2, readFile as readFile5, stat as stat4 } from "fs/promises";
-import path7 from "path";
+import { readdir as readdir2, readFile as readFile6, stat as stat4 } from "fs/promises";
+import path8 from "path";
 var SKIP_DIRS = /* @__PURE__ */ new Set([".cache", ".git", "node_modules", "dist", "build", ".next", ".turbo"]);
 function isSkippedName(name) {
   if (name.startsWith(".")) return true;
@@ -4578,79 +5623,79 @@ async function collectFiles(root, current) {
   const names = await readdir2(current);
   for (const name of names) {
     if (isSkippedName(name)) continue;
-    const abs = path7.join(current, name);
+    const abs = path8.join(current, name);
     const s = await stat4(abs);
     if (s.isDirectory()) {
       out.push(...await collectFiles(root, abs));
       continue;
     }
     if (!s.isFile()) continue;
-    const bytes = await readFile5(abs);
-    const relPath = path7.relative(root, abs).split(path7.sep).join("/");
+    const bytes = await readFile6(abs);
+    const relPath = path8.relative(root, abs).split(path8.sep).join("/");
     out.push({ relPath, contentSha: sha256Hex(bytes) });
   }
   return out;
 }
 
 // src/engine/engine/composition-meta.ts
-import { readFile as readFile6 } from "fs/promises";
-import path8 from "path";
-import { z as z9 } from "zod";
-var InputKind = z9.enum(["video", "image", "audio", "json"]);
-var InputSpec = z9.object({
+import { readFile as readFile7 } from "fs/promises";
+import path9 from "path";
+import { z as z10 } from "zod";
+var InputKind = z10.enum(["video", "image", "audio", "json"]);
+var InputSpec = z10.object({
   kind: InputKind,
-  required: z9.boolean().optional().default(false),
+  required: z10.boolean().optional().default(false),
   // Filename the composition's HTML references (e.g. `input.mp4`, `logo.png`).
   // Defaults to `<key><ext>` derived from the kind.
-  staged_as: z9.string().min(1).optional(),
-  description: z9.string().optional()
+  staged_as: z10.string().min(1).optional(),
+  description: z10.string().optional()
 }).strict();
 var ParamSpecBase = {
-  required: z9.boolean().optional().default(false),
-  description: z9.string().optional()
+  required: z10.boolean().optional().default(false),
+  description: z10.string().optional()
 };
-var StringParam = z9.object({
+var StringParam = z10.object({
   ...ParamSpecBase,
-  kind: z9.literal("string"),
-  default: z9.string().optional(),
-  enum: z9.array(z9.string()).optional()
+  kind: z10.literal("string"),
+  default: z10.string().optional(),
+  enum: z10.array(z10.string()).optional()
 }).strict();
-var IntegerParam = z9.object({
+var IntegerParam = z10.object({
   ...ParamSpecBase,
-  kind: z9.literal("integer"),
-  default: z9.number().int().optional(),
-  min: z9.number().int().optional(),
-  max: z9.number().int().optional()
+  kind: z10.literal("integer"),
+  default: z10.number().int().optional(),
+  min: z10.number().int().optional(),
+  max: z10.number().int().optional()
 }).strict();
-var NumberParam = z9.object({
+var NumberParam = z10.object({
   ...ParamSpecBase,
-  kind: z9.literal("number"),
-  default: z9.number().optional(),
-  min: z9.number().optional(),
-  max: z9.number().optional()
+  kind: z10.literal("number"),
+  default: z10.number().optional(),
+  min: z10.number().optional(),
+  max: z10.number().optional()
 }).strict();
-var BooleanParam = z9.object({
+var BooleanParam = z10.object({
   ...ParamSpecBase,
-  kind: z9.literal("boolean"),
-  default: z9.boolean().optional()
+  kind: z10.literal("boolean"),
+  default: z10.boolean().optional()
 }).strict();
-var ColorParam = z9.object({
+var ColorParam = z10.object({
   ...ParamSpecBase,
-  kind: z9.literal("color"),
-  default: z9.string().optional()
+  kind: z10.literal("color"),
+  default: z10.string().optional()
 }).strict();
-var ImageParam = z9.object({
+var ImageParam = z10.object({
   ...ParamSpecBase,
-  kind: z9.literal("image"),
-  default: z9.string().optional()
+  kind: z10.literal("image"),
+  default: z10.string().optional()
 }).strict();
-var JsonParam = z9.object({
+var JsonParam = z10.object({
   ...ParamSpecBase,
-  kind: z9.literal("json"),
-  schema: z9.unknown().optional(),
-  default: z9.unknown().optional()
+  kind: z10.literal("json"),
+  schema: z10.unknown().optional(),
+  default: z10.unknown().optional()
 }).strict();
-var ParamSpec = z9.discriminatedUnion("kind", [
+var ParamSpec = z10.discriminatedUnion("kind", [
   StringParam,
   IntegerParam,
   NumberParam,
@@ -4659,22 +5704,22 @@ var ParamSpec = z9.discriminatedUnion("kind", [
   ImageParam,
   JsonParam
 ]);
-var CompositionMetaSchema = z9.object({
-  id: z9.string().min(1),
-  title: z9.string().min(1),
-  description: z9.string().optional(),
-  width: z9.number().int().positive(),
-  height: z9.number().int().positive(),
-  fps: z9.number().int().positive().default(30),
-  default_duration: z9.number().positive().default(10),
-  inputs: z9.record(z9.string(), InputSpec).default({}),
-  params: z9.record(z9.string(), ParamSpec).default({})
+var CompositionMetaSchema = z10.object({
+  id: z10.string().min(1),
+  title: z10.string().min(1),
+  description: z10.string().optional(),
+  width: z10.number().int().positive(),
+  height: z10.number().int().positive(),
+  fps: z10.number().int().positive().default(30),
+  default_duration: z10.number().positive().default(10),
+  inputs: z10.record(z10.string(), InputSpec).default({}),
+  params: z10.record(z10.string(), ParamSpec).default({})
 }).strict();
 async function loadCompositionMeta(compositionDir) {
-  const metaPath = path8.join(compositionDir, "meta.json");
+  const metaPath = path9.join(compositionDir, "meta.json");
   let raw;
   try {
-    raw = await readFile6(metaPath, "utf-8");
+    raw = await readFile7(metaPath, "utf-8");
   } catch (e) {
     throw new Error(`composition meta: cannot read ${metaPath} (${e.message})`);
   }
@@ -4696,39 +5741,39 @@ function buildParamsSchema(meta) {
   for (const [name, spec] of Object.entries(meta.params)) {
     shape[name] = buildParamFieldSchema(name, spec);
   }
-  return z9.object(shape).strict();
+  return z10.object(shape).strict();
 }
 function buildParamFieldSchema(name, spec) {
   switch (spec.kind) {
     case "string": {
-      const s = spec.enum && spec.enum.length > 0 ? z9.enum(spec.enum) : z9.string();
+      const s = spec.enum && spec.enum.length > 0 ? z10.enum(spec.enum) : z10.string();
       return finalize(s, spec.default, spec.required);
     }
     case "integer": {
-      let s = z9.number().int();
+      let s = z10.number().int();
       if (spec.min !== void 0) s = s.min(spec.min);
       if (spec.max !== void 0) s = s.max(spec.max);
       return finalize(s, spec.default, spec.required);
     }
     case "number": {
-      let s = z9.number();
+      let s = z10.number();
       if (spec.min !== void 0) s = s.min(spec.min);
       if (spec.max !== void 0) s = s.max(spec.max);
       return finalize(s, spec.default, spec.required);
     }
     case "boolean":
-      return finalize(z9.boolean(), spec.default, spec.required);
+      return finalize(z10.boolean(), spec.default, spec.required);
     case "color": {
-      const s = z9.string().regex(/^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/, {
+      const s = z10.string().regex(/^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/, {
         message: `param "${name}": must be a 3/6/8-digit hex color (e.g. "#ff0066")`
       });
       return finalize(s, spec.default, spec.required);
     }
     case "image":
-      return finalize(z9.union([z9.string().min(1), z9.record(z9.string(), z9.unknown())]), spec.default, spec.required);
+      return finalize(z10.union([z10.string().min(1), z10.record(z10.string(), z10.unknown())]), spec.default, spec.required);
     case "json":
       return finalize(
-        z9.unknown().refine((v) => v !== void 0, { message: `param "${name}" is required` }),
+        z10.unknown().refine((v) => v !== void 0, { message: `param "${name}" is required` }),
         spec.default,
         spec.required
       );
@@ -4752,8 +5797,8 @@ function defaultFilenameForInput(key, kind) {
 
 // src/engine/nodes/local/lib/hyperframe-check.ts
 import { execFile as execFile3 } from "child_process";
-import { readFile as readFile7 } from "fs/promises";
-import path9 from "path";
+import { readFile as readFile8 } from "fs/promises";
+import path10 from "path";
 import { promisify as promisify3 } from "util";
 var execFileAsync = promisify3(execFile3);
 var NEVER_BLOCK = [
@@ -4766,8 +5811,8 @@ var NEVER_BLOCK = [
   /text[_-]?occluded/i
 ];
 var UNAVAILABLE = /unknown command|command not found|not found|Did you mean|Unknown argument|ENOENT/i;
-function isAdvisory(code, message) {
-  const hay = `${code} ${message}`;
+function isAdvisory(code, message2) {
+  const hay = `${code} ${message2}`;
   return NEVER_BLOCK.some((re) => re.test(hay));
 }
 function parseCheckJson(raw) {
@@ -4795,10 +5840,10 @@ function classifyLint(json) {
   for (const f of findings) {
     const rec = f;
     const code = String(rec?.code ?? "");
-    const message = String(rec?.message ?? "");
+    const message2 = String(rec?.message ?? "");
     const severity = String(rec?.severity ?? "info");
-    const blocking = severity === "error" && !isAdvisory(code, message);
-    out.push({ source: "lint", code, message, severity: blocking ? "blocking" : "warning" });
+    const blocking = severity === "error" && !isAdvisory(code, message2);
+    out.push({ source: "lint", code, message: message2, severity: blocking ? "blocking" : "warning" });
   }
   return out;
 }
@@ -4810,9 +5855,9 @@ function classifyInspect(json) {
   for (const iss of issues) {
     const rec = iss;
     const code = String(rec?.code ?? rec?.type ?? "overflow");
-    const message = String(rec?.message ?? rec?.detail ?? JSON.stringify(iss));
+    const message2 = String(rec?.message ?? rec?.detail ?? JSON.stringify(iss));
     const severity = rec?.severity ? String(rec.severity) : obj?.ok === false ? "error" : "warning";
-    out.push({ source: "inspect", code, message, severity: severity === "error" ? "blocking" : "warning" });
+    out.push({ source: "inspect", code, message: message2, severity: severity === "error" ? "blocking" : "warning" });
   }
   return out;
 }
@@ -4905,7 +5950,7 @@ ${detail}`);
   }
   let indexHtml = "";
   try {
-    indexHtml = await readFile7(path9.join(dir, "index.html"), "utf-8");
+    indexHtml = await readFile8(path10.join(dir, "index.html"), "utf-8");
   } catch {
     indexHtml = "";
   }
@@ -4970,9 +6015,9 @@ ${stderr.slice(0, 1500)}`;
 
 // src/engine/nodes/local/lib/hyperframe-meta.ts
 import { writeFile as writeFile4 } from "fs/promises";
-import path10 from "path";
+import path11 from "path";
 async function ensureHyperframesMetaJson(tmp, nodeId, meta, duration) {
-  const metaPath = path10.join(tmp, "meta.json");
+  const metaPath = path11.join(tmp, "meta.json");
   await writeFile4(
     metaPath,
     JSON.stringify(
@@ -5028,17 +6073,17 @@ function literalize(value) {
 // src/engine/nodes/local/hyperframe.ts
 var execFileAsync2 = promisify4(execFile4);
 var require_2 = createRequire2(import.meta.url);
-var HyperframeParams = z10.object({
-  composition: z10.string().min(1),
+var HyperframeParams = z11.object({
+  composition: z11.string().min(1),
   // Output container. mp4 (default) for delivery; webm/mov render WITH
   // transparency (alpha) when the composition background is transparent —
   // use for motion-graphic overlays dropped into Premiere/AE/Nuke.
-  format: z10.enum(["mp4", "webm", "mov"]).optional().default("mp4"),
-  timeout_ms: z10.number().int().positive().optional().default(10 * 60 * 1e3)
-}).catchall(z10.unknown());
-var HyperframeInputs = z10.record(z10.string(), z10.custom()).optional().default({});
-var HyperframeOutputs = z10.object({
-  video: z10.custom()
+  format: z11.enum(["mp4", "webm", "mov"]).optional().default("mp4"),
+  timeout_ms: z11.number().int().positive().optional().default(10 * 60 * 1e3)
+}).catchall(z11.unknown());
+var HyperframeInputs = z11.record(z11.string(), z11.custom()).optional().default({});
+var HyperframeOutputs = z11.object({
+  video: z11.custom()
 }).strict();
 var NODE_OWNED_PARAM_KEYS = /* @__PURE__ */ new Set(["composition", "format", "timeout_ms"]);
 var MIME_BY_FORMAT = {
@@ -5072,7 +6117,7 @@ var hyperframeRenderNode = defineNode({
     const compositionDir = await resolveCompositionDir(params.composition);
     const meta = await loadCompositionMeta(compositionDir);
     const compositionParams = validateAndParseDynamicParams(meta, params);
-    const tmp = await mkdtemp4(path11.join(tmpdir4(), "hf-render-"));
+    const tmp = await mkdtemp4(path12.join(tmpdir4(), "hf-render-"));
     try {
       await copyComposition(compositionDir, tmp);
       await vendorGsap(tmp, ctx);
@@ -5082,9 +6127,9 @@ var hyperframeRenderNode = defineNode({
       await substituteCompositionFiles(tmp, substitutionValues);
       await ensureHyperframesMetaJson(tmp, ctx.nodeId, meta, duration);
       await runHyperframesCheck({ dir: tmp, nodeId: "hyperframe_render", ctx, timeoutMs: params.timeout_ms });
-      const outputPath = path11.join(tmp, `output.${params.format}`);
+      const outputPath = path12.join(tmp, `output.${params.format}`);
       await runRender({ tmp, outputPath, params, meta, ctx });
-      const bytes = await readFile8(outputPath);
+      const bytes = await readFile9(outputPath);
       ctx.log(`rendered ${bytes.length} bytes`);
       const ref = await ctx.assets.ingestBytes({
         bytes: Buffer.from(bytes),
@@ -5106,10 +6151,10 @@ var hyperframeRenderNode = defineNode({
   }
 });
 async function resolveCompositionDir(composition) {
-  const compositionPath = path11.isAbsolute(composition) ? composition : path11.resolve(process.cwd(), composition);
+  const compositionPath = path12.isAbsolute(composition) ? composition : path12.resolve(process.cwd(), composition);
   const s = await stat5(compositionPath);
   if (s.isDirectory()) return compositionPath;
-  return path11.dirname(compositionPath);
+  return path12.dirname(compositionPath);
 }
 async function validateComposition(rawParams) {
   const issues = await validateCompositionParams(rawParams);
@@ -5191,7 +6236,7 @@ async function copyComposition(srcDir, destDir) {
   await cp(srcDir, destDir, {
     recursive: true,
     filter: (src) => {
-      const name = path11.basename(src);
+      const name = path12.basename(src);
       if (name === ".cache" || name === "node_modules" || name === ".git") return false;
       return true;
     }
@@ -5200,7 +6245,7 @@ async function copyComposition(srcDir, destDir) {
 async function vendorGsap(tmp, ctx) {
   try {
     const gsapMin = require_2.resolve("gsap/dist/gsap.min.js");
-    await copyFile4(gsapMin, path11.join(tmp, "gsap.min.js"));
+    await copyFile4(gsapMin, path12.join(tmp, "gsap.min.js"));
   } catch (e) {
     ctx.log(`warning: could not vendor gsap.min.js (${e.message}); compositions must self-supply`);
   }
@@ -5215,7 +6260,7 @@ async function stageInputs2(tmp, inputs, meta, ctx) {
     await stageAsset(ref, tmp, filename);
     ctx.log(`staged ${spec.kind} \u2192 ${filename}`);
     if (spec.kind === "video" && primaryDuration === null) {
-      primaryDuration = await probeDurationSeconds(path11.join(tmp, filename));
+      primaryDuration = await probeDurationSeconds(path12.join(tmp, filename));
     }
   }
   return primaryDuration;
@@ -5257,12 +6302,12 @@ async function buildSubstitutionValues(compositionParams, meta, duration) {
 }
 function coerceImageParam(value) {
   if (typeof value === "string") return Promise.resolve(value);
-  if (isAssetRefLike(value)) return refToUrl(value);
+  if (isAssetRefLike2(value)) return refToUrl(value);
   throw new Error("hyperframe_render: image param must be a URL string or AssetRef");
 }
 async function substituteCompositionFiles(tmp, values) {
-  const entryPath = path11.join(tmp, "index.html");
-  const original = await readFile8(entryPath, "utf-8");
+  const entryPath = path12.join(tmp, "index.html");
+  const original = await readFile9(entryPath, "utf-8");
   const { output, missing } = substituteVariables(original, values);
   if (missing.length > 0) {
     throw new Error(
@@ -5278,7 +6323,7 @@ function workerCount() {
 async function runRender(opts) {
   const { tmp, outputPath, params, meta, ctx } = opts;
   const args = buildRenderArgs(tmp, outputPath, meta, params.format);
-  ctx.log(`rendering ${meta.width}x${meta.height}@${meta.fps}fps ${params.format} from ${path11.basename(tmp)}`);
+  ctx.log(`rendering ${meta.width}x${meta.height}@${meta.fps}fps ${params.format} from ${path12.basename(tmp)}`);
   try {
     await execFileAsync2("npx", args, { timeout: params.timeout_ms, maxBuffer: 64 * 1024 * 1024 });
   } catch (e) {
@@ -5322,28 +6367,28 @@ async function probeDurationSeconds(filePath) {
 
 // src/engine/nodes/local/hyperframe-snapshot.ts
 import { execFile as execFile5 } from "child_process";
-import { copyFile as copyFile5, mkdtemp as mkdtemp5, readFile as readFile9, rm as rm5, writeFile as writeFile6 } from "fs/promises";
+import { copyFile as copyFile5, mkdtemp as mkdtemp5, readFile as readFile10, rm as rm5, writeFile as writeFile6 } from "fs/promises";
 import { createRequire as createRequire3 } from "module";
 import { tmpdir as tmpdir5 } from "os";
-import path12 from "path";
+import path13 from "path";
 import { promisify as promisify5 } from "util";
-import { z as z11 } from "zod";
+import { z as z12 } from "zod";
 var _execFileAsync = promisify5(execFile5);
 var require_3 = createRequire3(import.meta.url);
-var WaitForSpec = z11.discriminatedUnion("kind", [
-  z11.object({ kind: z11.literal("auto") }),
-  z11.object({ kind: z11.literal("selector"), value: z11.string().min(1) }),
-  z11.object({ kind: z11.literal("function"), value: z11.string().min(1) }),
-  z11.object({ kind: z11.literal("timeout"), ms: z11.number().int().min(0).max(6e4) })
+var WaitForSpec = z12.discriminatedUnion("kind", [
+  z12.object({ kind: z12.literal("auto") }),
+  z12.object({ kind: z12.literal("selector"), value: z12.string().min(1) }),
+  z12.object({ kind: z12.literal("function"), value: z12.string().min(1) }),
+  z12.object({ kind: z12.literal("timeout"), ms: z12.number().int().min(0).max(6e4) })
 ]);
-var HyperframeSnapshotParams = z11.object({
-  composition: z11.string().min(1),
+var HyperframeSnapshotParams = z12.object({
+  composition: z12.string().min(1),
   wait_for: WaitForSpec.optional().default({ kind: "auto" }),
-  timeout_ms: z11.number().int().positive().optional().default(6e4)
-}).catchall(z11.unknown());
-var HyperframeSnapshotInputs = z11.record(z11.string(), z11.custom()).optional().default({});
-var HyperframeSnapshotOutputs = z11.object({
-  image: z11.custom()
+  timeout_ms: z12.number().int().positive().optional().default(6e4)
+}).catchall(z12.unknown());
+var HyperframeSnapshotInputs = z12.record(z12.string(), z12.custom()).optional().default({});
+var HyperframeSnapshotOutputs = z12.object({
+  image: z12.custom()
 }).strict();
 var NODE_OWNED_PARAM_KEYS2 = /* @__PURE__ */ new Set(["composition", "wait_for", "timeout_ms"]);
 var DEVICE_SCALE_FACTOR2 = 2;
@@ -5372,7 +6417,7 @@ var hyperframeSnapshotNode = defineNode({
     const compositionDir = await resolveCompositionDir(params.composition);
     const meta = await loadCompositionMeta(compositionDir);
     const compositionParams = validateAndParseDynamicParams2(meta, params);
-    const tmp = await mkdtemp5(path12.join(tmpdir5(), "hf-snap-"));
+    const tmp = await mkdtemp5(path13.join(tmpdir5(), "hf-snap-"));
     try {
       await copyComposition2(compositionDir, tmp);
       await vendorGsap2(tmp, ctx);
@@ -5387,7 +6432,7 @@ var hyperframeSnapshotNode = defineNode({
         timeoutMs: params.timeout_ms,
         samples: 1
       });
-      const entryPath = path12.join(tmp, "index.html");
+      const entryPath = path13.join(tmp, "index.html");
       const entryUrl = `file://${entryPath}`;
       ctx.log(`snapshotting ${meta.width}x${meta.height}@${DEVICE_SCALE_FACTOR2}x wait=${params.wait_for.kind}`);
       const pwSpecifier = ["play", "wright"].join("");
@@ -5448,7 +6493,7 @@ async function copyComposition2(srcDir, destDir) {
   await cp(srcDir, destDir, {
     recursive: true,
     filter: (src) => {
-      const name = path12.basename(src);
+      const name = path13.basename(src);
       if (name === ".cache" || name === "node_modules" || name === ".git") return false;
       return true;
     }
@@ -5457,7 +6502,7 @@ async function copyComposition2(srcDir, destDir) {
 async function vendorGsap2(tmp, ctx) {
   try {
     const gsapMin = require_3.resolve("gsap/dist/gsap.min.js");
-    await copyFile5(gsapMin, path12.join(tmp, "gsap.min.js"));
+    await copyFile5(gsapMin, path13.join(tmp, "gsap.min.js"));
   } catch (e) {
     ctx.log(`warning: could not vendor gsap.min.js (${e.message}); compositions must self-supply`);
   }
@@ -5487,12 +6532,12 @@ async function buildSubstitutionValues2(compositionParams, meta) {
 }
 function coerceImageParam2(value) {
   if (typeof value === "string") return Promise.resolve(value);
-  if (isAssetRefLike(value)) return refToUrl(value);
+  if (isAssetRefLike2(value)) return refToUrl(value);
   throw new Error("hyperframe_snapshot: image param must be a URL string or AssetRef");
 }
 async function substituteCompositionFiles2(tmp, values) {
-  const entryPath = path12.join(tmp, "index.html");
-  const original = await readFile9(entryPath, "utf-8");
+  const entryPath = path13.join(tmp, "index.html");
+  const original = await readFile10(entryPath, "utf-8");
   const { output, missing } = substituteVariables(original, values);
   if (missing.length > 0) {
     throw new Error(
@@ -5535,18 +6580,18 @@ async function waitForReady(page, waitFor, timeoutMs) {
 // src/engine/nodes/local/imagemagick.ts
 import { execFile as execFile6 } from "child_process";
 import { promisify as promisify6 } from "util";
-import { z as z12 } from "zod";
+import { z as z13 } from "zod";
 var execFileAsync3 = promisify6(execFile6);
-var OutputDecl2 = z12.object({
-  kind: z12.enum(["image", "video", "audio"]),
-  ext: z12.string().min(1).max(8)
+var OutputDecl2 = z13.object({
+  kind: z13.enum(["image", "video", "audio"]),
+  ext: z13.string().min(1).max(8)
 }).strict();
-var ImageMagickParams = z12.object({
-  args: z12.array(z12.string()).min(1),
-  outputs: z12.record(z12.string(), OutputDecl2).default({})
+var ImageMagickParams = z13.object({
+  args: z13.array(z13.string()).min(1),
+  outputs: z13.record(z13.string(), OutputDecl2).default({})
 }).strict();
-var ImageMagickInputs = z12.record(z12.string(), z12.unknown());
-var ImageMagickOutputs = z12.record(z12.string(), z12.custom());
+var ImageMagickInputs = z13.record(z13.string(), z13.unknown());
+var ImageMagickOutputs = z13.record(z13.string(), z13.custom());
 var resolvedBin;
 async function resolveBin() {
   if (resolvedBin) return resolvedBin;
@@ -5588,29 +6633,29 @@ var imagemagickNode = defineNode({
 });
 
 // src/engine/nodes/local/text.ts
-import { z as z13 } from "zod";
+import { z as z14 } from "zod";
 var textNode = defineNode({
   id: "text",
   version: "1.0.0",
   category: "data",
   location: "local",
   summary: "A literal text value. Use for prompts, descriptions, copy.",
-  inputs: z13.object({}).strict(),
-  params: z13.object({ value: z13.string() }).strict(),
-  outputs: z13.object({ text: z13.string() }).strict(),
+  inputs: z14.object({}).strict(),
+  params: z14.object({ value: z14.string() }).strict(),
+  outputs: z14.object({ text: z14.string() }).strict(),
   cost: () => ({ credits: 0, seconds_estimate: 0 }),
   execute: ({ params }) => Promise.resolve({ text: params.value })
 });
 
 // src/engine/nodes/remote/audioVoiceConvert.ts
-import { z as z14 } from "zod";
-var AudioVoiceConvertParams = z14.object({
-  model: z14.literal("elevenlabs/eleven_multilingual_sts_v2"),
+import { z as z15 } from "zod";
+var AudioVoiceConvertParams = z15.object({
+  model: z15.literal("elevenlabs/eleven_multilingual_sts_v2"),
   /** Target voice id. Splice an upstream `voice_select` via `"{{voice_ref}}"`. */
-  voice: z14.string().min(1),
-  output_format: z14.string().optional(),
+  voice: z15.string().min(1),
+  output_format: z15.string().optional(),
   /** Strip the source clip's background noise before re-voicing. */
-  remove_background_noise: z14.boolean().optional()
+  remove_background_noise: z15.boolean().optional()
 }).strict();
 var audioVoiceConvertNode = delegated({
   id: "audio_voice_convert",
@@ -5618,44 +6663,44 @@ var audioVoiceConvertNode = delegated({
   category: "audio",
   summary: "Voice Changer / speech-to-speech via ElevenLabs (eleven_multilingual_sts_v2). Re-voices an existing audio clip in a TARGET voice while preserving timing/prosody.",
   when_to_use: 'Use to normalize a generator-chosen voice (e.g. a Seedance talking-head clip\'s native audio) into ONE consistent brand voice across every scene \u2014 the cadence is preserved so any lip-sync stays valid. Wire `inputs.voice_ref: $ref:<voice_select>.voice_id` and set `params.voice: "{{voice_ref}}"`.',
-  inputs: z14.object({
+  inputs: z15.object({
     audio: AudioRef,
     voice_ref: TextRef.optional()
   }).strict(),
   params: AudioVoiceConvertParams,
-  outputs: z14.object({ audio: AudioRef }).strict(),
+  outputs: z15.object({ audio: AudioRef }).strict(),
   outputKinds: { audio: "audio" },
   cost: () => ({ credits: 1, seconds_estimate: 20 })
 });
 
 // src/engine/nodes/remote/dialogue.ts
-import { z as z15 } from "zod";
-var DialogueInput = z15.object({
-  text: z15.string().min(1),
-  voice_id: z15.string().min(1)
+import { z as z16 } from "zod";
+var DialogueInput = z16.object({
+  text: z16.string().min(1),
+  voice_id: z16.string().min(1)
 });
 var DIALOGUE_MODELS = ["elevenlabs/eleven_v3"];
-var DialogueParams = z15.object({
-  model: z15.enum(DIALOGUE_MODELS),
+var DialogueParams = z16.object({
+  model: z16.enum(DIALOGUE_MODELS),
   /**
    * Ordered list of lines, each tagged with the voice that should speak it.
    * Up to 10 unique voice_ids; total text across all lines should stay under
    * ~2000 characters for best quality (ElevenLabs guidance).
    */
-  inputs: z15.array(DialogueInput).min(1).max(50),
-  language_code: z15.string().optional(),
+  inputs: z16.array(DialogueInput).min(1).max(50),
+  language_code: z16.string().optional(),
   /** ElevenLabs voice/model settings passthrough (e.g. `{ stability: 0.5 }`). */
-  settings: z15.record(z15.string(), z15.unknown()).optional(),
-  seed: z15.number().int().min(0).max(4294967295).optional(),
-  apply_text_normalization: z15.enum(["auto", "on", "off"]).optional(),
+  settings: z16.record(z16.string(), z16.unknown()).optional(),
+  seed: z16.number().int().min(0).max(4294967295).optional(),
+  apply_text_normalization: z16.enum(["auto", "on", "off"]).optional(),
   /**
    * When true, hits `/v1/text-to-dialogue/with-timestamps` and emits a
    * separate `timestamps` output — character-level alignment plus
    * per-voice segment markers usable for captions, lipsync, or
    * beat-matched cuts in ad creatives.
    */
-  with_timestamps: z15.boolean().optional(),
-  output_format: z15.enum(ELEVENLABS_OUTPUT_FORMATS).optional()
+  with_timestamps: z16.boolean().optional(),
+  output_format: z16.enum(ELEVENLABS_OUTPUT_FORMATS).optional()
 }).strict().refine((p) => p.inputs.reduce((sum, line) => sum + line.text.length, 0) <= ELEVENLABS_MAX_TEXT_CHARS, {
   message: `total dialogue text exceeds ${ELEVENLABS_MAX_TEXT_CHARS} characters`,
   path: ["inputs"]
@@ -5666,9 +6711,9 @@ var dialogueNode = delegated({
   category: "audio",
   summary: "Multi-voice dialogue / VO with ElevenLabs Eleven v3. Each line is tagged with a `voice_id`, so you can render two-character scripts (e.g. ad VO + customer testimonial reaction) in a single call. Setting `with_timestamps: true` adds character-level alignment for caption rendering and lipsync-friendly cuts.",
   when_to_use: "Use for any ad creative or website video VO that needs more than narration \u2014 interviews, two-actor scripts, character ads, testimonial reads. For single-voice flat reads the existing `tts` node is cheaper and simpler; reach for `dialogue` when you need multiple speakers in one stitched track or word-level timing for downstream lipsync / captions.",
-  inputs: z15.object({}).loose(),
+  inputs: z16.object({}).loose(),
   params: DialogueParams,
-  outputs: z15.object({ audio: AudioRef, timestamps: JsonRef.optional() }).strict(),
+  outputs: z16.object({ audio: AudioRef, timestamps: JsonRef.optional() }).strict(),
   outputKinds: { audio: "audio", timestamps: "json" },
   cost: ({ params }) => {
     const chars = params.inputs.reduce((sum, line) => sum + line.text.length, 0);
@@ -5677,7 +6722,7 @@ var dialogueNode = delegated({
 });
 
 // src/engine/nodes/remote/image.ts
-import { z as z16 } from "zod";
+import { z as z17 } from "zod";
 var IMAGE_GENERATE_MODELS2 = [
   "openai/gpt-5.4-image-2",
   "google/gemini-3.5-flash",
@@ -5685,41 +6730,44 @@ var IMAGE_GENERATE_MODELS2 = [
   "google/gemini-3-pro-image-preview",
   "recraft/recraft-v4.1-pro-vector"
 ];
-var ImageGenerateParams = z16.object({
-  model: z16.enum(IMAGE_GENERATE_MODELS2),
-  prompt: z16.string().min(1),
-  aspect_ratio: z16.enum(["1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3", "4:5", "5:4", "21:9", "1:4", "4:1", "1:8", "8:1"]).optional(),
-  image_size: z16.enum(["0.5K", "1K", "2K", "4K"]).optional(),
+var ImageGenerateParams = z17.object({
+  model: z17.enum(IMAGE_GENERATE_MODELS2),
+  prompt: z17.string().min(1),
+  aspect_ratio: z17.enum(["1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3", "4:5", "5:4", "21:9", "1:4", "4:1", "1:8", "8:1"]).optional(),
+  image_size: z17.enum(["0.5K", "1K", "2K", "4K"]).optional(),
+  // Rendering quality — forwarded into `image_config`. OpenRouter models without a
+  // quality knob ignore it; the registry gates which models accept it (gpt-image, Gemini).
+  quality: z17.enum(["auto", "low", "medium", "high"]).optional(),
   // Recraft v4 vector controls — forwarded into `image_config`. Registry
   // rejects them on non-Recraft models.
-  strength: z16.number().min(0).max(1).optional(),
-  rgb_colors: z16.array(z16.array(z16.number().int().min(0).max(255))).optional(),
-  background_rgb_color: z16.array(z16.number().int().min(0).max(255)).optional()
+  strength: z17.number().min(0).max(1).optional(),
+  rgb_colors: z17.array(z17.array(z17.number().int().min(0).max(255))).optional(),
+  background_rgb_color: z17.array(z17.number().int().min(0).max(255)).optional()
 }).strict();
 var imageGenerateNode = delegated({
   id: "image_generate",
-  version: "2.1.0",
+  version: "2.2.0",
   category: "image",
   summary: "Generate images for ad creatives. Curated model set: GPT-5.4 Image, Gemini 3.5 Flash, Gemini 3.1 Flash Image Preview, Gemini 3 Pro Image, Recraft v4.1 Pro Vector. Per-model param support comes from the canvas-engine model registry.",
   when_to_use: "Use for hero shots, product photography, illustrations, and vector logos. `recraft/recraft-v4.1-pro-vector` for crisp vector / logo work; `openai/gpt-5.4-image-2` for photorealistic; Gemini variants for fast iteration and editing via the `reference` input. `reference` accepts ONE image or an ARRAY of images \u2014 wire several to combine references in a single generation (e.g. a subject sheet + a font specimen + the original ad). Every reference is forwarded to the model in array order.",
   // `reference` is one image or an ordered array of images. The backend forwards
   // each as a separate `image_url` to the provider (OpenRouter accepts many).
-  inputs: z16.object({ reference: z16.union([ImageRef, z16.array(ImageRef).min(1)]).optional() }).loose(),
+  inputs: z17.object({ reference: z17.union([ImageRef, z17.array(ImageRef).min(1)]).optional() }).loose(),
   params: ImageGenerateParams,
-  outputs: z16.object({ images: z16.array(ImageRef).min(1) }).strict(),
+  outputs: z17.object({ images: z17.array(ImageRef).min(1) }).strict(),
   outputKinds: { images: "image" },
   cost: () => ({ credits: 5, seconds_estimate: 10 })
 });
 
 // src/engine/nodes/remote/imageAspectAdapt.ts
-import { z as z17 } from "zod";
+import { z as z18 } from "zod";
 var ASPECT_ADAPT_MODELS = ["google/gemini-3-pro-image-preview", "google/gemini-3.1-flash-image-preview"];
 var ASPECT_ADAPT_FORMATS = ["1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9"];
-var ImageAspectAdaptParams = z17.object({
-  model: z17.enum(ASPECT_ADAPT_MODELS),
-  formats: z17.array(z17.enum(ASPECT_ADAPT_FORMATS)).min(1).max(6).refine((formats) => new Set(formats).size === formats.length, { message: "formats must be unique" }),
-  guidance: z17.string().min(1).optional(),
-  image_size: z17.enum(["0.5K", "1K", "2K", "4K"]).optional()
+var ImageAspectAdaptParams = z18.object({
+  model: z18.enum(ASPECT_ADAPT_MODELS),
+  formats: z18.array(z18.enum(ASPECT_ADAPT_FORMATS)).min(1).max(6).refine((formats) => new Set(formats).size === formats.length, { message: "formats must be unique" }),
+  guidance: z18.string().min(1).optional(),
+  image_size: z18.enum(["0.5K", "1K", "2K", "4K"]).optional()
 }).strict();
 var imageAspectAdaptNode = delegated({
   id: "image_aspect_adapt",
@@ -5727,9 +6775,9 @@ var imageAspectAdaptNode = delegated({
   category: "image",
   summary: "Adapt ONE creative into multiple aspect ratios (Meta: 9:16 stories, 1:1 feed, 4:5, 16:9\u2026) in a single step. AI recomposes the layout per format \u2014 identical subject, text, logos, colors, and style; the scene is extended/restructured, never stretched or cropped. Formats that already match the source ratio pass through unchanged at zero cost. Outputs are ordered exactly as `formats`.",
   when_to_use: "Use after a hero creative exists (image_generate, ingest, image_search) to fan it out to every placement format \u2014 wire the creative into `source` and list the target ratios in `formats`. Cost is estimated per format; formats matching the source ratio are free pass-throughs. Pick `google/gemini-3.1-flash-image-preview` (Nano Banana flash) while iterating, `google/gemini-3-pro-image-preview` (Nano Banana Pro) for final-quality adaptation.",
-  inputs: z17.object({ source: ImageRef }).loose(),
+  inputs: z18.object({ source: ImageRef }).loose(),
   params: ImageAspectAdaptParams,
-  outputs: z17.object({ images: z17.array(ImageRef).min(1) }).strict(),
+  outputs: z18.object({ images: z18.array(ImageRef).min(1) }).strict(),
   outputKinds: { images: "image" },
   cost: ({ params }) => {
     const p = params;
@@ -5742,12 +6790,12 @@ var imageAspectAdaptNode = delegated({
 });
 
 // src/engine/nodes/remote/imageBackgroundRemove.ts
-import { z as z18 } from "zod";
-var ImageBackgroundRemoveParams = z18.object({
-  model: z18.literal("fal/birefnet-v2").optional().default("fal/birefnet-v2"),
-  model_variant: z18.enum(["General Use (Light)", "General Use (Heavy)", "Matting", "Portrait", "DIS", "HRSOD", "COD"]).optional().default("General Use (Light)"),
-  operating_resolution: z18.enum(["1024x1024", "2048x2048", "2304x2304"]).optional(),
-  mask_only: z18.boolean().optional().default(false)
+import { z as z19 } from "zod";
+var ImageBackgroundRemoveParams = z19.object({
+  model: z19.literal("fal/birefnet-v2").optional().default("fal/birefnet-v2"),
+  model_variant: z19.enum(["General Use (Light)", "General Use (Heavy)", "Matting", "Portrait", "DIS", "HRSOD", "COD"]).optional().default("General Use (Light)"),
+  operating_resolution: z19.enum(["1024x1024", "2048x2048", "2304x2304"]).optional(),
+  mask_only: z19.boolean().optional().default(false)
 }).strict();
 var imageBackgroundRemoveNode = delegated({
   id: "image_background_remove",
@@ -5755,11 +6803,11 @@ var imageBackgroundRemoveNode = delegated({
   category: "image",
   summary: "Remove the background from an image and return a transparent PNG (or the segmentation mask). Powered by fal.ai `fal-ai/birefnet/v2`.",
   when_to_use: "Use to extract subjects from photos for use as overlays in hyperframe compositions, product shots, or compositing pipelines. Set `mask_only:true` to return the binary mask instead of the alpha-cut image.",
-  inputs: z18.object({
+  inputs: z19.object({
     image: ImageRef
   }).strict(),
   params: ImageBackgroundRemoveParams,
-  outputs: z18.object({
+  outputs: z19.object({
     image: ImageRef,
     mask: ImageRef.optional()
   }).strict(),
@@ -5768,7 +6816,7 @@ var imageBackgroundRemoveNode = delegated({
 });
 
 // src/engine/nodes/remote/imageDescribe.ts
-import { z as z19 } from "zod";
+import { z as z20 } from "zod";
 var IMAGE_DESCRIBE_MODELS = ["~google/gemini-pro-latest", "~google/gemini-flash-latest"];
 var imageDescribeNode = delegated({
   id: "image_describe",
@@ -5776,33 +6824,33 @@ var imageDescribeNode = delegated({
   category: "vision",
   summary: "Reverse-engineer an image into an exhaustive, replication-grade JSON description: who the advertiser is and what they sell (source_context), composition, non-person subjects with expression/treatment, deeply detailed people, brand-identified logos (named by brand, not appearance), camera optics, lighting, color palette WITH per-color brand-ownership (brand vs borrowed-functional) and purpose, materials, visible text, ad signals (proof badges/CTA/price), the persuasion engine (ad_intent), style, post-processing.",
   when_to_use: 'Use to turn a reference image into a structured blueprint you can inject into downstream prompts via `{{slot}}` \u2014 e.g. restyle a competitor ad onto your own product, lock a look across a series, or feed exact palette/lighting into image_generate. Purpose-built for market adaptation: logos are identified by brand ("Trustpilot", never "green star"), people and animals carry expression/emotion/intent detail, and each color is tagged brand vs borrowed-functional so a recolor can keep the reds/yellows that do a job. The extraction prompt is baked in; use `focus` to emphasise aspects and `context` to pass known provenance (advertiser, category, market) so source_context and color ownership are grounded. Pick `~google/gemini-pro-latest` for the densest extraction (recommended for ad / market-adaptation passes), `~google/gemini-flash-latest` for cheap/fast passes. The output is rich \u2014 raise `max_tokens` (e.g. 8000+) for dense ads so the JSON isn\'t truncated.',
-  inputs: z19.object({ image: ImageRef }).loose(),
-  params: z19.object({
-    model: z19.enum(IMAGE_DESCRIBE_MODELS),
-    focus: z19.string().optional(),
-    context: z19.string().optional(),
-    temperature: z19.number().min(0).max(2).optional(),
-    max_tokens: z19.number().int().positive().optional()
+  inputs: z20.object({ image: ImageRef }).loose(),
+  params: z20.object({
+    model: z20.enum(IMAGE_DESCRIBE_MODELS),
+    focus: z20.string().optional(),
+    context: z20.string().optional(),
+    temperature: z20.number().min(0).max(2).optional(),
+    max_tokens: z20.number().int().positive().optional()
   }).strict(),
-  outputs: z19.object({ description: JsonRef }).strict(),
+  outputs: z20.object({ description: JsonRef }).strict(),
   outputKinds: { description: "json" },
   cost: () => ({ credits: 2, seconds_estimate: 10 })
 });
 
 // src/engine/nodes/remote/imageReferenceSheet.ts
-import { z as z20 } from "zod";
+import { z as z21 } from "zod";
 var REFERENCE_SHEET_MODELS = ["google/gemini-3-pro-image-preview", "google/gemini-3.1-flash-image-preview"];
-var ImageReferenceSheetParams = z20.object({
-  model: z20.enum(REFERENCE_SHEET_MODELS),
-  subject_description: z20.string().min(1),
+var ImageReferenceSheetParams = z21.object({
+  model: z21.enum(REFERENCE_SHEET_MODELS),
+  subject_description: z21.string().min(1),
   // `location` = a set/room shown from several camera ANGLES (not a rotated subject),
   // so a multi-scene shoot keeps one consistent set.
-  subject_type: z20.enum(["character", "person", "product", "location"]),
-  views: z20.array(z20.string().min(1)).min(2).max(8).optional(),
-  style: z20.string().optional(),
-  prompt_override: z20.string().min(1).optional(),
-  aspect_ratio: z20.enum(["1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3", "4:5", "5:4", "21:9", "1:4", "4:1", "1:8", "8:1"]).optional(),
-  image_size: z20.enum(["0.5K", "1K", "2K", "4K"]).optional()
+  subject_type: z21.enum(["character", "person", "product", "location"]),
+  views: z21.array(z21.string().min(1)).min(2).max(8).optional(),
+  style: z21.string().optional(),
+  prompt_override: z21.string().min(1).optional(),
+  aspect_ratio: z21.enum(["1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3", "4:5", "5:4", "21:9", "1:4", "4:1", "1:8", "8:1"]).optional(),
+  image_size: z21.enum(["0.5K", "1K", "2K", "4K"]).optional()
 }).strict();
 var imageReferenceSheetNode = delegated({
   id: "image_reference_sheet",
@@ -5810,9 +6858,9 @@ var imageReferenceSheetNode = delegated({
   category: "image",
   summary: "Fuse 1\u20136 images of a single subject (person, character, product, or location/set) into ONE multi-view reference sheet \u2014 a labeled grid in consistent style and lighting: a turnaround (FRONT / SIDE / BACK\u2026) for a person/character/product, or several camera angles of the same room (WIDE / REVERSE / DETAIL\u2026) for a location. Curated models: Gemini 3 Pro Image (best fusion + labels), Gemini 3.1 Flash Image (cheap iteration).",
   when_to_use: "Use before image_generate / video_generate when a subject must stay consistent across many creatives \u2014 wire the `sheet` output into their `reference` input instead of re-describing the subject per prompt. `subject_description` should be the exact wording you reuse downstream. Pick `google/gemini-3-pro-image-preview` for final 6-view sheets at 2K+, `google/gemini-3.1-flash-image-preview` while iterating.",
-  inputs: z20.object({ references: z20.array(ImageRef).min(1).max(6) }).loose(),
+  inputs: z21.object({ references: z21.array(ImageRef).min(1).max(6) }).loose(),
   params: ImageReferenceSheetParams,
-  outputs: z20.object({ sheet: ImageRef }).strict(),
+  outputs: z21.object({ sheet: ImageRef }).strict(),
   outputKinds: { sheet: "image" },
   cost: ({ params }) => ({
     credits: params?.model === "google/gemini-3-pro-image-preview" ? 20 : 5,
@@ -5821,10 +6869,10 @@ var imageReferenceSheetNode = delegated({
 });
 
 // src/engine/nodes/remote/imageSearch.ts
-import { z as z21 } from "zod";
-var ImageSearchParams = z21.object({
-  prompt: z21.string().min(1),
-  count: z21.number().int().min(1).max(20).default(5)
+import { z as z22 } from "zod";
+var ImageSearchParams = z22.object({
+  prompt: z22.string().min(1),
+  count: z22.number().int().min(1).max(20).default(5)
 }).strict();
 var imageSearchNode = delegated({
   id: "image_search",
@@ -5832,15 +6880,15 @@ var imageSearchNode = delegated({
   category: "image",
   summary: "Agentic image search across Google Images, stock photography (Freepik), and Pinterest. An LLM agent picks the search tools and queries, selects the best matches, and the results are downloaded into canvas assets.",
   when_to_use: "Use to gather real-world reference or inspiration images for a prompt (e.g. several photos of an australian shepherd) so a later step or the user can pick the best one. Not for creating new imagery \u2014 use image_generate for that.",
-  inputs: z21.object({}).loose(),
+  inputs: z22.object({}).loose(),
   params: ImageSearchParams,
-  outputs: z21.object({ images: z21.array(ImageRef).min(1) }).strict(),
+  outputs: z22.object({ images: z22.array(ImageRef).min(1) }).strict(),
   outputKinds: { images: "image" },
   cost: ({ params }) => ({ credits: Math.ceil(2 + params.count / 2), seconds_estimate: 30 })
 });
 
 // src/engine/nodes/remote/imageSelect.ts
-import { z as z22 } from "zod";
+import { z as z23 } from "zod";
 var IMAGE_SELECT_MODELS = ["~google/gemini-flash-latest", "~google/gemini-pro-latest"];
 var imageSelectNode = delegated({
   id: "image_select",
@@ -5848,15 +6896,15 @@ var imageSelectNode = delegated({
   category: "vision",
   summary: "Pick the best `count` images out of 2+ candidates with a vision LLM, judged against a prompt. Outputs a passthrough subset of the input refs (no new pixels) plus the model's comparative reasoning.",
   when_to_use: "Use after fanning out several image_generate variants (or any pool of 2+ images) to keep only the strongest before expensive downstream steps \u2014 video generation, reference sheets, final delivery. `count` fixes the output size, so `images#0`\u2026`images#count-1` are always safe to wire. Pick `~google/gemini-flash-latest` for cheap/fast picks and `~google/gemini-pro-latest` for harder aesthetic judgement.",
-  inputs: z22.object({ images: z22.array(ImageRef).min(2) }).loose(),
-  params: z22.object({
-    model: z22.enum(IMAGE_SELECT_MODELS),
-    prompt: z22.string().min(1),
-    count: z22.number().int().min(1).default(1),
-    temperature: z22.number().min(0).max(2).optional(),
-    max_tokens: z22.number().int().positive().optional()
+  inputs: z23.object({ images: z23.array(ImageRef).min(2) }).loose(),
+  params: z23.object({
+    model: z23.enum(IMAGE_SELECT_MODELS),
+    prompt: z23.string().min(1),
+    count: z23.number().int().min(1).default(1),
+    temperature: z23.number().min(0).max(2).optional(),
+    max_tokens: z23.number().int().positive().optional()
   }).strict(),
-  outputs: z22.object({ images: z22.array(ImageRef).min(1), reasoning: TextRef }).strict(),
+  outputs: z23.object({ images: z23.array(ImageRef).min(1), reasoning: TextRef }).strict(),
   outputKinds: { images: "image", reasoning: "text" },
   cost: () => ({ credits: 1, seconds_estimate: 5 }),
   // Arity is only knowable at validate time when `images` is a literal array
@@ -5881,34 +6929,34 @@ var imageSelectNode = delegated({
 });
 
 // src/engine/nodes/remote/music.ts
-import { z as z23 } from "zod";
+import { z as z24 } from "zod";
 var MUSIC_MODELS = ["elevenlabs/music-v1", "elevenlabs/video-background-music-v1"];
-var MusicParams = z23.object({
-  model: z23.enum(MUSIC_MODELS),
+var MusicParams = z24.object({
+  model: z24.enum(MUSIC_MODELS),
   /** Free-form prompt. Used by `elevenlabs/music-v1` (compose-detailed). */
-  prompt: z23.string().optional(),
+  prompt: z24.string().optional(),
   /**
    * Structured composition plan (intro / hook / verse / outro sections with
    * per-section styles + durations). Mutually exclusive with `prompt`.
    */
-  composition_plan: z23.record(z23.string(), z23.unknown()).optional(),
+  composition_plan: z24.record(z24.string(), z24.unknown()).optional(),
   /** Target length when using `prompt`. 3000–454545ms (capped by the $10 per-node cost limit). */
-  music_length_ms: z23.number().int().min(3e3).max(ELEVENLABS_MAX_MUSIC_LENGTH_MS).optional(),
-  seed: z23.number().int().optional(),
+  music_length_ms: z24.number().int().min(3e3).max(ELEVENLABS_MAX_MUSIC_LENGTH_MS).optional(),
+  seed: z24.number().int().optional(),
   /** Prompt mode only — forces an instrumental (no vocals) track. */
-  force_instrumental: z23.boolean().optional(),
+  force_instrumental: z24.boolean().optional(),
   /** composition_plan only — honor exact section durations. */
-  respect_sections_durations: z23.boolean().optional(),
+  respect_sections_durations: z24.boolean().optional(),
   /** Emit word-level timestamps alongside the audio. */
-  with_timestamps: z23.boolean().optional(),
+  with_timestamps: z24.boolean().optional(),
   /**
    * video-to-music only — short description of the desired score
    * ("upbeat synth, fast cuts, 80s") used to bias the model.
    */
-  description: z23.string().max(1e3).optional(),
+  description: z24.string().max(1e3).optional(),
   /** video-to-music only — up to 10 style tags. */
-  tags: z23.array(z23.string()).max(10).optional(),
-  output_format: z23.enum(ELEVENLABS_OUTPUT_FORMATS).optional()
+  tags: z24.array(z24.string()).max(10).optional(),
+  output_format: z24.enum(ELEVENLABS_OUTPUT_FORMATS).optional()
 }).strict();
 var musicNode = delegated({
   id: "music",
@@ -5916,9 +6964,9 @@ var musicNode = delegated({
   category: "audio",
   summary: "Generate music for ad creatives and website video content. `elevenlabs/music-v1` composes from a text prompt or structured composition plan; `elevenlabs/video-background-music-v1` scores an existing video clip provided via `inputs.video`.",
   when_to_use: "Use to produce background music or a full score for video ads, hero-section reels, or any motion content. Prefer the video-to-music model when you already have a cut and want music timed to it; use compose-detailed when you have only a brief or want section-level control (intro / hook / outro). Pair the resulting audio with `video_generate` or `video_lipsync` at compose time.",
-  inputs: z23.object({ video: VideoRef.optional() }).loose(),
+  inputs: z24.object({ video: VideoRef.optional() }).loose(),
   params: MusicParams,
-  outputs: z23.object({ audio: AudioRef, timestamps: JsonRef.optional() }).strict(),
+  outputs: z24.object({ audio: AudioRef, timestamps: JsonRef.optional() }).strict(),
   outputKinds: { audio: "audio", timestamps: "json" },
   cost: ({ params }) => {
     const seconds = params.music_length_ms ? Math.ceil(params.music_length_ms / 1e3) : 30;
@@ -5949,25 +6997,25 @@ var musicNode = delegated({
 });
 
 // src/engine/nodes/remote/soundEffect.ts
-import { z as z24 } from "zod";
+import { z as z25 } from "zod";
 var SOUND_EFFECT_MODELS = ["elevenlabs/eleven_text_to_sound_v2"];
-var SoundEffectParams = z24.object({
-  model: z24.enum(SOUND_EFFECT_MODELS),
+var SoundEffectParams = z25.object({
+  model: z25.enum(SOUND_EFFECT_MODELS),
   /** Prompt describing the SFX ("metal door slam", "soft UI tap", "ocean waves"). */
-  text: z24.string().min(1),
+  text: z25.string().min(1),
   /**
    * Target length in seconds. 0.5–30. Leave unset to let the model pick the
    * natural length for the described effect.
    */
-  duration_seconds: z24.number().min(0.5).max(30).optional(),
+  duration_seconds: z25.number().min(0.5).max(30).optional(),
   /**
    * 0–1. Higher = stick closer to the prompt at the cost of variety; lower
    * = let the model interpret more freely. Defaults to 0.3 on the provider.
    */
-  prompt_influence: z24.number().min(0).max(1).optional(),
+  prompt_influence: z25.number().min(0).max(1).optional(),
   /** Only valid on `eleven_text_to_sound_v2` — produce a seamless loop. */
-  loop: z24.boolean().optional(),
-  output_format: z24.enum(ELEVENLABS_OUTPUT_FORMATS).optional()
+  loop: z25.boolean().optional(),
+  output_format: z25.enum(ELEVENLABS_OUTPUT_FORMATS).optional()
 }).strict();
 var soundEffectNode = delegated({
   id: "sound_effect",
@@ -5975,9 +7023,9 @@ var soundEffectNode = delegated({
   category: "audio",
   summary: "Generate short sound effects from a text prompt via ElevenLabs Text-to-Sound. Use for whooshes, impacts, UI clicks, ambient beds, or signature stingers in ad creatives and product videos.",
   when_to_use: "Reach for this when you need a punch-in SFX layered against `video_generate` or `hyperframe_render` output \u2014 e.g. a logo whoosh on a hero shot, a click on a CTA cut, a swelling ambient bed under VO. Set `loop: true` for atmospheric beds that need to tile under longer footage; leave `duration_seconds` unset and the model picks a natural length.",
-  inputs: z24.object({}).loose(),
+  inputs: z25.object({}).loose(),
   params: SoundEffectParams,
-  outputs: z24.object({ audio: AudioRef }).strict(),
+  outputs: z25.object({ audio: AudioRef }).strict(),
   outputKinds: { audio: "audio" },
   cost: ({ params }) => {
     const seconds = params.duration_seconds ?? 5;
@@ -5986,7 +7034,7 @@ var soundEffectNode = delegated({
 });
 
 // src/engine/nodes/remote/textGenerate.ts
-import { z as z25 } from "zod";
+import { z as z26 } from "zod";
 var TEXT_GENERATE_MODELS = ["~google/gemini-flash-latest", "~google/gemini-pro-latest"];
 var textGenerateNode = delegated({
   id: "text_generate",
@@ -5994,58 +7042,58 @@ var textGenerateNode = delegated({
   category: "language",
   summary: "Single-turn LLM text generation via OpenRouter. Returns a text response.",
   when_to_use: 'Use for any short text generation step in a canvas \u2014 ad copy, hooks, headlines, JSON outputs for downstream nodes. Pick `~google/gemini-flash-latest` for cheap/fast work and `~google/gemini-pro-latest` for harder reasoning. When the output must be JSON for a downstream `{{slot}}` (e.g. the ad-blueprint transform), set `response_format: "json_object"` so the model returns clean JSON with no markdown fences or prose. Set `web_search: true` to let the model search the live web first (OpenRouter `:online`) \u2014 useful when the transform must adapt copy to the target brand\'s real facts (current pricing, the trust signals it actually has) rather than guess.',
-  inputs: z25.object({}).loose(),
-  params: z25.object({
-    model: z25.enum(TEXT_GENERATE_MODELS),
-    prompt: z25.string().min(1),
-    system: z25.string().optional(),
-    response_format: z25.enum(["text", "json_object"]).optional(),
-    web_search: z25.boolean().optional(),
-    temperature: z25.number().min(0).max(2).optional(),
-    max_tokens: z25.number().int().positive().optional()
+  inputs: z26.object({}).loose(),
+  params: z26.object({
+    model: z26.enum(TEXT_GENERATE_MODELS),
+    prompt: z26.string().min(1),
+    system: z26.string().optional(),
+    response_format: z26.enum(["text", "json_object"]).optional(),
+    web_search: z26.boolean().optional(),
+    temperature: z26.number().min(0).max(2).optional(),
+    max_tokens: z26.number().int().positive().optional()
   }).strict(),
-  outputs: z25.object({ text: TextRef }).strict(),
+  outputs: z26.object({ text: TextRef }).strict(),
   outputKinds: { text: "text" },
   cost: () => ({ credits: 1, seconds_estimate: 3 })
 });
 
 // src/engine/nodes/remote/tts.ts
-import { z as z26 } from "zod";
+import { z as z27 } from "zod";
 var TTS_MODELS = ["elevenlabs/eleven_v3"];
-var TtsVoiceSettings = z26.object({
-  stability: z26.number().min(0).max(1).optional(),
-  similarity_boost: z26.number().min(0).max(1).optional(),
-  style: z26.number().min(0).max(1).optional(),
-  use_speaker_boost: z26.boolean().optional(),
-  speed: z26.number().min(0.25).max(4).optional()
+var TtsVoiceSettings = z27.object({
+  stability: z27.number().min(0).max(1).optional(),
+  similarity_boost: z27.number().min(0).max(1).optional(),
+  style: z27.number().min(0).max(1).optional(),
+  use_speaker_boost: z27.boolean().optional(),
+  speed: z27.number().min(0.25).max(4).optional()
 }).strict();
-var TtsPronunciationLocator = z26.object({
-  pronunciation_dictionary_id: z26.string().min(1),
-  version_id: z26.string().nullable().optional()
+var TtsPronunciationLocator = z27.object({
+  pronunciation_dictionary_id: z27.string().min(1),
+  version_id: z27.string().nullable().optional()
 }).strict();
-var TtsParams = z26.object({
-  model: z26.enum(TTS_MODELS),
-  text: z26.string().min(1).max(ELEVENLABS_MAX_TEXT_CHARS),
-  voice: z26.string().min(1),
+var TtsParams = z27.object({
+  model: z27.enum(TTS_MODELS),
+  text: z27.string().min(1).max(ELEVENLABS_MAX_TEXT_CHARS),
+  voice: z27.string().min(1),
   /** Provider output_format (mp3 family only — assets are stored as audio/mpeg). */
-  output_format: z26.enum(ELEVENLABS_OUTPUT_FORMATS).optional(),
-  seed: z26.number().int().min(0).max(4294967295).optional(),
+  output_format: z27.enum(ELEVENLABS_OUTPUT_FORMATS).optional(),
+  seed: z27.number().int().min(0).max(4294967295).optional(),
   // Top-level shortcuts; structured form is `voice_settings`.
-  stability: z26.number().min(0).max(1).optional(),
-  similarity_boost: z26.number().min(0).max(1).optional(),
+  stability: z27.number().min(0).max(1).optional(),
+  similarity_boost: z27.number().min(0).max(1).optional(),
   voice_settings: TtsVoiceSettings.optional(),
   /** ISO 639-1 language code. eleven_v3 supports language hints. */
-  language_code: z26.string().optional(),
-  pronunciation_dictionary_locators: z26.array(TtsPronunciationLocator).max(3).optional(),
-  apply_text_normalization: z26.enum(["auto", "on", "off"]).optional(),
+  language_code: z27.string().optional(),
+  pronunciation_dictionary_locators: z27.array(TtsPronunciationLocator).max(3).optional(),
+  apply_text_normalization: z27.enum(["auto", "on", "off"]).optional(),
   /** Currently Japanese-only. Adds latency. */
-  apply_language_text_normalization: z26.boolean().optional(),
+  apply_language_text_normalization: z27.boolean().optional(),
   /**
    * When true, hits `/v1/text-to-speech/{voice_id}/with-timestamps` and
    * adds a `timestamps` output (character-level alignment) for caption
    * rendering, lipsync, and beat-matched cuts.
    */
-  with_timestamps: z26.boolean().optional()
+  with_timestamps: z27.boolean().optional()
 }).strict();
 var ttsNode = delegated({
   id: "tts",
@@ -6053,9 +7101,9 @@ var ttsNode = delegated({
   category: "audio",
   summary: "Single-voice text-to-speech via ElevenLabs Eleven v3. Optional character-level timestamps for caption rendering and beat-matched cuts.",
   when_to_use: "Use for single-speaker VO \u2014 ad reads, hero-section narration, product walkthroughs. Reach for `dialogue` when you need multiple voices in one stitched track. Set `with_timestamps: true` when downstream needs character-level alignment (captions, lipsync).",
-  inputs: z26.object({}).loose(),
+  inputs: z27.object({}).loose(),
   params: TtsParams,
-  outputs: z26.object({ audio: AudioRef, timestamps: JsonRef.optional() }).strict(),
+  outputs: z27.object({ audio: AudioRef, timestamps: JsonRef.optional() }).strict(),
   outputKinds: { audio: "audio", timestamps: "json" },
   cost: ({ params }) => ({
     credits: Math.max(1, Math.ceil(params.text.length * 15e-4)),
@@ -6064,47 +7112,49 @@ var ttsNode = delegated({
 });
 
 // src/engine/nodes/remote/video.ts
-import { z as z27 } from "zod";
-var VIDEO_GENERATE_MODELS = ["bytedance/seedance-2.0", "google/veo-3.1-fast"];
-var VideoGenerateParams = z27.object({
-  model: z27.enum(VIDEO_GENERATE_MODELS),
-  prompt: z27.string().min(1),
-  duration: z27.number().int().positive().optional(),
-  resolution: z27.string().optional(),
+import { z as z28 } from "zod";
+var videoModelEnum = z28.enum(VIDEO_GENERATE_MODELS);
+var VideoGenerateParams = z28.object({
+  model: videoModelEnum,
+  prompt: z28.string().min(1),
+  duration: z28.number().int().positive().optional(),
+  resolution: z28.string().optional(),
   // Union of ratios accepted by at least one curated model (registry gates
   // per-model). 3:2/2:3 are deliberately absent: no registered model takes them.
-  aspect_ratio: z27.enum(["16:9", "9:16", "1:1", "4:3", "3:4", "21:9", "9:21"]).optional(),
-  generate_audio: z27.boolean().optional(),
-  seed: z27.number().int().nonnegative().optional(),
+  aspect_ratio: z28.enum(["16:9", "9:16", "1:1", "4:3", "3:4", "21:9", "9:21"]).optional(),
+  generate_audio: z28.boolean().optional(),
+  seed: z28.number().int().nonnegative().optional(),
   // Veo-only passthroughs (routed via `provider.options.google-vertex.parameters`).
-  negative_prompt: z27.string().optional(),
-  person_generation: z27.string().optional(),
-  enhance_prompt: z27.boolean().optional(),
-  conditioning_scale: z27.number().optional()
+  negative_prompt: z28.string().optional(),
+  person_generation: z28.string().optional(),
+  enhance_prompt: z28.boolean().optional(),
+  conditioning_scale: z28.number().optional(),
+  // Kling-only passthrough (prompt-adherence dial, sent top-level).
+  cfg_scale: z28.number().optional()
 }).strict();
 var videoGenerateNode = delegated({
   id: "video_generate",
   version: "2.0.0",
   category: "video",
-  summary: "Generate video for ad creatives. Two curated models: `bytedance/seedance-2.0` (production quality, photorealistic humans via fal.ai) and `google/veo-3.1-fast` (cheap/fast for iteration and tests). Async with polling.",
-  when_to_use: "Use `bytedance/seedance-2.0` for final ad output (photoreal subjects, image-to-video with first/last frames). Use `google/veo-3.1-fast` while iterating to keep cost low. Each model has different supported durations, resolutions, and aspect ratios \u2014 see the README per-model section.",
-  inputs: z27.object({
+  summary: "Generate video for ad creatives. Curated roster: `bytedance/seedance-2.0` (identity/product workhorse), `google/veo-3.1` (photoreal cine ceiling + real-face fallback), `google/veo-3.1-fast` (cheap Veo iteration), `kwaivgi/kling-3.0` (motion-transfer/dynamic). Async with polling.",
+  when_to_use: "Use `bytedance/seedance-2.0` for identity/product output. Route real human likenesses to `google/veo-3.1` (dodges the ByteDance real-person filter); use `google/veo-3.1-fast` while iterating to keep cost low; `kwaivgi/kling-3.0` for motion-transfer/hyper-dynamic beats. The scaffolder's scored router picks for you. Each model gates its own durations/resolutions/aspect ratios in the registry \u2014 see the README per-model section.",
+  inputs: z28.object({
     first_frame: ImageRef.optional(),
     last_frame: ImageRef.optional(),
     reference: ImageRef.optional()
   }).loose(),
   params: VideoGenerateParams,
-  outputs: z27.object({ video: VideoRef }).strict(),
+  outputs: z28.object({ video: VideoRef }).strict(),
   outputKinds: { video: "video" },
   cost: () => ({ credits: 50, seconds_estimate: 120 })
 });
 
 // src/engine/nodes/remote/videoBackgroundRemove.ts
-import { z as z28 } from "zod";
-var VideoBackgroundRemoveParams = z28.object({
-  model: z28.literal("fal/veed-video-background-removal").optional().default("fal/veed-video-background-removal"),
-  edge_refinement: z28.boolean().optional().default(true),
-  output_codec: z28.enum(["vp9", "h264"]).optional().default("vp9")
+import { z as z29 } from "zod";
+var VideoBackgroundRemoveParams = z29.object({
+  model: z29.literal("fal/veed-video-background-removal").optional().default("fal/veed-video-background-removal"),
+  edge_refinement: z29.boolean().optional().default(true),
+  output_codec: z29.enum(["vp9", "h264"]).optional().default("vp9")
 }).strict();
 var videoBackgroundRemoveNode = delegated({
   id: "video_background_remove",
@@ -6112,18 +7162,18 @@ var videoBackgroundRemoveNode = delegated({
   category: "video",
   summary: "Remove the background from a video and return a transparent VP9-with-alpha WebM (or H264 RGB+alpha pair). Drops directly into a hyperframe composition as `<video src='...'>` for chroma-keyed picture-in-picture overlays. Powered by fal.ai `veed/video-background-removal/fast`.",
   when_to_use: "Use when you need a talking-head or subject to float over a custom background in a hyperframe composition. Pair with hyperframe_render(composition: screencast-with-talker) for screencast-with-narrator videos. Output is `video/webm` with alpha \u2014 feed straight into `<video src>` in a composition.",
-  inputs: z28.object({
+  inputs: z29.object({
     video: VideoRef
   }).strict(),
   params: VideoBackgroundRemoveParams,
-  outputs: z28.object({ video: VideoRef }).strict(),
+  outputs: z29.object({ video: VideoRef }).strict(),
   outputKinds: { video: "video" },
   // $0.012 per 30 frames (edge refinement on) — assume ~30fps; refine via fal dashboard.
   cost: () => ({ credits: 50, seconds_estimate: 60 })
 });
 
 // src/engine/nodes/remote/videoDeconstruct.ts
-import { z as z29 } from "zod";
+import { z as z30 } from "zod";
 var VIDEO_DECONSTRUCT_MODELS = ["~google/gemini-flash-latest", "~google/gemini-pro-latest"];
 var videoDeconstructNode = delegated({
   id: "video_deconstruct",
@@ -6131,34 +7181,34 @@ var videoDeconstructNode = delegated({
   category: "video",
   summary: 'Deconstruct a video into a replication-grade blueprint: scene boundaries, the real start/end frame of every scene (extracted from the video as images), and an exhaustive JSON analysis \u2014 per-scene action detail, camera motion, generation-ready frame/motion prompts, overlay text with full typographic style, floating elements, deeply detailed cast (perceived demographics, ethnicity/skin-tone, styling, market-recasting notes), brand-identified logos (named by brand and what they signal, not by appearance, with on-screen timestamps), dialogue with voice descriptions, music spec, SFX list, plus a word-level transcript. `mode:"index"` is the cheap structure-first pass: scene boundaries + global blueprint only (one LLM call, no frames).',
   when_to_use: 'Use to reverse-engineer a reference video (e.g. a competitor ad) so a new canvas can reproduce or remix it scene by scene. Agent loop: (1) optionally run `mode:"index"` to see the structure cheaply (scene count, boundaries, transcript) before planning; (2) run the full deconstruct; (3) read `analysis` and author the reproduction canvas. The blueprint maps 1:1 onto generation nodes: `analysis.scenes[i]` aligns positionally with `start_frames#i`/`end_frames#i`; per scene, `start_frame_prompt`/`end_frame_prompt` feed image_generate (overlay text is excluded from them by contract \u2014 recomposite it from `overlays`), `motion_prompt` + the two frames feed video_generate (first_frame/last_frame), `dialogue[].voice_description` casts tts/dialogue voices, `global.music.music_prompt` feeds music, `sfx[].sound_effect_prompt` feeds sound_effect, and `overlays`/`floating_elements` drive an ffmpeg/hyperframe overlay pass. Long videos (over ~8 min single-shot): run `mode:"index"` first, then several full nodes IN PARALLEL each with a `start_s`/`end_s` window (\u2264480s, snap edges to index scene boundaries), and merge by concatenating `analysis.scenes`; over-length errors include suggested windows. Inject fields into downstream prompts via `{{slot}}`. Pick `~google/gemini-pro-latest` for the densest extraction, `~google/gemini-flash-latest` for cheap/fast passes.',
-  inputs: z29.object({ video: VideoRef }).loose(),
-  params: z29.object({
-    model: z29.enum(VIDEO_DECONSTRUCT_MODELS),
-    mode: z29.enum(["full", "index"]).optional(),
-    language: z29.string().min(2).max(8).optional(),
-    max_scenes: z29.number().int().min(1).max(60).optional(),
-    focus: z29.string().optional(),
-    start_s: z29.number().min(0).optional(),
-    end_s: z29.number().positive().optional(),
+  inputs: z30.object({ video: VideoRef }).loose(),
+  params: z30.object({
+    model: z30.enum(VIDEO_DECONSTRUCT_MODELS),
+    mode: z30.enum(["full", "index"]).optional(),
+    language: z30.string().min(2).max(8).optional(),
+    max_scenes: z30.number().int().min(1).max(60).optional(),
+    focus: z30.string().optional(),
+    start_s: z30.number().min(0).optional(),
+    end_s: z30.number().positive().optional(),
     // Real visual shot-cut timestamps (absolute seconds), detected locally with
     // ffmpeg before the deconstruct. The backend SNAPS its LLM scene boundaries
     // onto these and SPLITS any scene that spans one, so a scene's frames never
     // straddle a hard cut. `scaffold-video` populates this; omit for LLM-only cuts.
-    shot_cuts: z29.array(z29.number().min(0)).max(200).optional(),
+    shot_cuts: z30.array(z30.number().min(0)).max(200).optional(),
     // The video model's per-clip ceiling (seconds). A shot longer than this is
     // split into seamless continuation sub-scenes (shared splice frame), so long
     // shots reproduce in full instead of being truncated. `scaffold-video` sets
     // the Seedance ceiling (15); omit to disable length splitting.
-    max_clip_s: z29.number().positive().max(60).optional(),
+    max_clip_s: z30.number().positive().max(60).optional(),
     // Transcript provider for the blueprint's dialogue/transcript. Default
     // Groq Whisper; "deepgram" routes to Nova-3 so words carry punctuation.
-    transcriber: z29.enum(["groq", "deepgram"]).optional()
+    transcriber: z30.enum(["groq", "deepgram"]).optional()
   }).strict(),
-  outputs: z29.object({
+  outputs: z30.object({
     analysis: JsonRef,
     // Absent in mode:"index" (structure only, no Mux frame extraction).
-    start_frames: z29.array(ImageRef).min(1).optional(),
-    end_frames: z29.array(ImageRef).min(1).optional(),
+    start_frames: z30.array(ImageRef).min(1).optional(),
+    end_frames: z30.array(ImageRef).min(1).optional(),
     transcript: JsonRef
   }).strict(),
   outputKinds: { analysis: "json", start_frames: "image", end_frames: "image", transcript: "json" },
@@ -6166,31 +7216,31 @@ var videoDeconstructNode = delegated({
 });
 
 // src/engine/nodes/remote/videoLipsync.ts
-import { z as z30 } from "zod";
-var FalLipsyncParams = z30.object({
-  model: z30.literal("fal/veed-lipsync")
+import { z as z31 } from "zod";
+var FalLipsyncParams = z31.object({
+  model: z31.literal("fal/veed-lipsync")
 }).strict();
-var VideoLipsyncParams = z30.discriminatedUnion("model", [FalLipsyncParams]);
+var VideoLipsyncParams = z31.discriminatedUnion("model", [FalLipsyncParams]);
 var videoLipsyncNode = delegated({
   id: "video_lipsync",
   version: "1.0.0",
   category: "video",
   summary: "Lip-sync a video to an audio track. Currently backed by VEED via fal.ai (`fal/veed-lipsync`). $0.40/min of output.",
-  inputs: z30.object({
+  inputs: z31.object({
     video: VideoRef,
     audio: AudioRef
   }).strict(),
   params: VideoLipsyncParams,
-  outputs: z30.object({ video: VideoRef }).strict(),
+  outputs: z31.object({ video: VideoRef }).strict(),
   outputKinds: { video: "video" },
   cost: () => ({ credits: 20, seconds_estimate: 120 })
 });
 
 // src/engine/nodes/remote/videoTranscribe.ts
-import { mkdtemp as mkdtemp6, readFile as readFile10, rm as rm6 } from "fs/promises";
+import { mkdtemp as mkdtemp6, readFile as readFile11, rm as rm6 } from "fs/promises";
 import { tmpdir as tmpdir6 } from "os";
-import path13 from "path";
-import { z as z31 } from "zod";
+import path14 from "path";
+import { z as z32 } from "zod";
 
 // src/engine/nodes/local/lib/ffmpeg.ts
 import { execFile as execFile7 } from "child_process";
@@ -6269,29 +7319,32 @@ ${detail.slice(-4e3)}`);
 }
 
 // src/engine/nodes/remote/videoTranscribe.ts
-var VideoTranscribeParams = z31.object({
-  language: z31.string().min(2).max(8).optional(),
+var VideoTranscribeParams = z32.object({
+  language: z32.string().min(2).max(8).optional(),
   // Provider choice is explicit (no env-based silent branching). Default Groq
   // Whisper; "deepgram" routes to Deepgram Nova-3, which additionally emits a
   // `rich` JSON output with punctuated words + paragraph/sentence grouping.
-  transcriber: z31.enum(["groq", "deepgram"]).optional()
+  transcriber: z32.enum(["groq", "deepgram"]).optional()
 }).strict();
-var VideoTranscribeInputs = z31.object({
-  video: VideoRef
+var VideoTranscribeInputs = z32.object({
+  // A video (audio auto-extracted locally) OR a bare audio track. The key stays
+  // `video` for back-compat; the backend already accepts audio-kind refs on it —
+  // the local extraction path has been shipping one for every video input.
+  video: z32.union([VideoRef, AudioRef])
 }).strict();
-var VideoTranscribeOutputs = z31.object({
-  transcript: z31.custom(),
+var VideoTranscribeOutputs = z32.object({
+  transcript: z32.custom(),
   // Only emitted by the Deepgram path: full punctuated words + paragraph /
   // sentence grouping with speaker indices. Absent for the default Groq path.
-  rich: z31.custom().optional()
+  rich: z32.custom().optional()
 }).strict();
 var AUDIO_EXTRACT_TIMEOUT_MS = 6e4;
 var videoTranscribeNode = defineNode({
   id: "video_transcribe",
-  version: "2.2.0",
+  version: "2.3.0",
   category: "language",
   location: "local",
-  summary: 'Transcribe a video\'s audio to a word-level JSON transcript. Default `transcriber:"groq"` uses Groq Whisper Large v3 Turbo ($0.04/hr, 10s min); `transcriber:"deepgram"` uses Deepgram Nova-3 ($0.0043/min) and additionally emits a `rich` JSON output with punctuated words + paragraph/sentence grouping (and speaker indices). Automatically extracts audio locally (mono 16 kHz MP3) before uploading \u2014 reduces payload ~100\xD7 and lifts the effective duration limit well beyond Groq\'s 100 MB file cap. The `transcript` output is always an array of {text, start, end} entries ready to feed Hyperframes caption compositions (Deepgram prefers the punctuated word form).',
+  summary: 'Transcribe a video or audio track to a word-level JSON transcript. Default `transcriber:"groq"` uses Groq Whisper Large v3 Turbo ($0.04/hr, 10s min); `transcriber:"deepgram"` uses Deepgram Nova-3 ($0.0043/min) and additionally emits a `rich` JSON output with punctuated words + paragraph/sentence grouping (and speaker indices). Automatically extracts audio locally (mono 16 kHz MP3) before uploading \u2014 reduces payload ~100\xD7 and lifts the effective duration limit well beyond Groq\'s 100 MB file cap. The `transcript` output is always an array of {text, start, end} entries ready to feed Hyperframes caption compositions (Deepgram prefers the punctuated word form).',
   when_to_use: 'Use to generate burned-in captions for a stitched video. Pair with `hyperframe_render` and a captions composition (e.g. `tiktok-captions`) by passing the transcript JSON through `params.variables.transcript`. Pick `params.language` to filter out non-target speech (e.g. "es" for Spanish). Pick `transcriber:"deepgram"` when you want punctuation/paragraphs (read them from the `rich` output) or speaker grouping. Requires ffmpeg on PATH for audio extraction (falls back to full video upload if unavailable).',
   inputs: VideoTranscribeInputs,
   params: VideoTranscribeParams,
@@ -6303,7 +7356,7 @@ var videoTranscribeNode = defineNode({
     const effectiveInputs = audioInput ?? inputs;
     return await callBackendExec({
       nodeType: "video_transcribe",
-      nodeVersion: "2.2.0",
+      nodeVersion: "2.3.0",
       params,
       inputs: effectiveInputs,
       outputKinds: { transcript: "json", rich: "json" },
@@ -6321,14 +7374,14 @@ async function tryExtractAudio(inputs, ctx) {
       ctx.log("video_transcribe: no audio track detected, sending full video");
       return null;
     }
-    tmpDir = await mkdtemp6(path13.join(tmpdir6(), "vtx-"));
-    const audioPath = path13.join(tmpDir, "audio.mp3");
+    tmpDir = await mkdtemp6(path14.join(tmpdir6(), "vtx-"));
+    const audioPath = path14.join(tmpDir, "audio.mp3");
     ctx.log("video_transcribe: extracting audio (mono 16kHz mp3)");
     await runFfmpeg(
       ["-i", video.path, "-vn", "-ac", "1", "-ar", "16000", "-b:a", "64k", "-f", "mp3", "-y", audioPath],
       { timeout_ms: AUDIO_EXTRACT_TIMEOUT_MS }
     );
-    const bytes = await readFile10(audioPath);
+    const bytes = await readFile11(audioPath);
     if (bytes.byteLength === 0) {
       ctx.log("video_transcribe: extracted audio is empty, sending full video");
       return null;
@@ -6368,29 +7421,29 @@ async function tryExtractAudio(inputs, ctx) {
 }
 
 // src/engine/nodes/remote/voiceSelect.ts
-import { z as z32 } from "zod";
+import { z as z33 } from "zod";
 var voiceSelectNode = delegated({
   id: "voice_select",
   version: "1.0.0",
   category: "audio",
   summary: 'Cast an ElevenLabs voice from a natural-language description (e.g. "warm, authoritative female narrator, American accent"). Lists the account\'s voices and ranks them against the brief, emitting the best `voice_id` as a bare-string text asset plus a ranked `candidates` JSON.',
   when_to_use: 'Use to turn a voice description (e.g. from a `video_deconstruct` blueprint\'s `voice_description`) into a usable ElevenLabs voice id, then feed it into a `tts` node by wiring `inputs.voice_ref: $ref:<this>.voice_id` and setting `params.voice: "{{voice_ref}}"` \u2014 the engine splices the id in at run time. Review `candidates` (json) to pick a different voice. Optional `gender`/`age`/`accent`/`language` hints sharpen the ranking.',
-  inputs: z32.object({}).loose(),
-  params: z32.object({
-    description: z32.string().min(1),
-    gender: z32.string().optional(),
-    age: z32.string().optional(),
-    accent: z32.string().optional(),
-    language: z32.string().optional(),
-    limit: z32.number().int().min(1).max(20).optional()
+  inputs: z33.object({}).loose(),
+  params: z33.object({
+    description: z33.string().min(1),
+    gender: z33.string().optional(),
+    age: z33.string().optional(),
+    accent: z33.string().optional(),
+    language: z33.string().optional(),
+    limit: z33.number().int().min(1).max(20).optional()
   }).strict(),
-  outputs: z32.object({ voice_id: TextRef, candidates: JsonRef }).strict(),
+  outputs: z33.object({ voice_id: TextRef, candidates: JsonRef }).strict(),
   outputKinds: { voice_id: "text", candidates: "json" },
   cost: () => ({ credits: 0, seconds_estimate: 5 })
 });
 
 // src/engine/schema/catalog.ts
-import { z as z33 } from "zod";
+import { z as z34 } from "zod";
 function generateCatalog(registry, opts = {}) {
   const entries = registry.all().map((def) => {
     const cost = def.cost ? safeCost(def) : void 0;
@@ -6401,9 +7454,9 @@ function generateCatalog(registry, opts = {}) {
       summary: def.summary,
       when_to_use: def.when_to_use,
       location: def.location,
-      inputs: z33.toJSONSchema(def.inputs, { unrepresentable: "any" }),
-      params: z33.toJSONSchema(def.params, { unrepresentable: "any" }),
-      outputs: z33.toJSONSchema(def.outputs, { unrepresentable: "any" }),
+      inputs: z34.toJSONSchema(def.inputs, { unrepresentable: "any" }),
+      params: z34.toJSONSchema(def.params, { unrepresentable: "any" }),
+      outputs: z34.toJSONSchema(def.outputs, { unrepresentable: "any" }),
       cost_estimate_credits: cost?.credits,
       runtime_estimate_seconds: cost?.seconds_estimate
     };
@@ -6435,19 +7488,19 @@ function safeCost(def) {
 
 // src/engine/storage/cache-store.ts
 import { randomUUID as randomUUID2 } from "crypto";
-import { mkdir as mkdir3, readFile as readFile11, rename as rename2, writeFile as writeFile7 } from "fs/promises";
-import path14 from "path";
+import { mkdir as mkdir3, readFile as readFile12, rename as rename2, writeFile as writeFile7 } from "fs/promises";
+import path15 from "path";
 var LocalCacheStore = class {
   rootDir;
   constructor(rootDir) {
     this.rootDir = rootDir;
   }
   filePath(cacheKey) {
-    return path14.join(this.rootDir, `${cacheKey}.json`);
+    return path15.join(this.rootDir, `${cacheKey}.json`);
   }
   async get(cacheKey) {
     try {
-      const buf = await readFile11(this.filePath(cacheKey), "utf8");
+      const buf = await readFile12(this.filePath(cacheKey), "utf8");
       return JSON.parse(buf);
     } catch (e) {
       if (e.code === "ENOENT") return null;
@@ -6456,7 +7509,7 @@ var LocalCacheStore = class {
   }
   async put(entry) {
     const dest = this.filePath(entry.cacheKey);
-    await mkdir3(path14.dirname(dest), { recursive: true });
+    await mkdir3(path15.dirname(dest), { recursive: true });
     const tmp = `${dest}.tmp-${process.pid}-${randomUUID2()}`;
     await writeFile7(tmp, JSON.stringify(entry, null, 0));
     await rename2(tmp, dest);
@@ -6480,7 +7533,8 @@ var LOCAL_NODES = [
   imagemagickNode,
   videoTranscribeNode,
   fontSpecimenNode,
-  audioTimelineNode
+  audioTimelineNode,
+  collectNode
 ];
 var REMOTE_NODES = [
   textGenerateNode,
@@ -6510,29 +7564,55 @@ function defaultRegistry() {
 }
 function createEngineFromEnv(opts = {}) {
   const cwd = opts.cwd ?? process.cwd();
-  const cacheDir = opts.cacheDir ?? path15.join(cwd, "canvas", ".cache");
-  const outputsDir = opts.outputsDir ?? path15.join(cwd, "canvas");
+  const cacheDir = opts.cacheDir ?? path16.join(cwd, "canvas", ".cache");
+  const outputsDir = opts.outputsDir ?? path16.join(cwd, "canvas");
   const creds = requireCredentialsFromEnv();
+  const client = new BackendClient({ baseUrl: creds.url, apiKey: creds.apiKey });
+  const assets = new LocalAssetStore(path16.join(cacheDir, "assets"));
+  const localCache = new LocalCacheStore(path16.join(cacheDir, "index"));
+  const remoteCacheEnabled = opts.remoteCache ?? remoteCacheEnabledFromEnv();
+  const cache = remoteCacheEnabled ? new LayeredCacheStore({
+    local: localCache,
+    remote: new RemoteCacheStore(client, opts.log),
+    assets,
+    log: opts.log
+  }) : localCache;
   return new Engine({
     registry: defaultRegistry(),
-    client: new BackendClient({ baseUrl: creds.url, apiKey: creds.apiKey }),
-    assets: new LocalAssetStore(path15.join(cacheDir, "assets")),
-    cache: new LocalCacheStore(path15.join(cacheDir, "index")),
+    client,
+    assets,
+    cache,
     outputsDir,
-    log: opts.log
+    log: opts.log,
+    persistAssets: remoteCacheEnabled
   });
 }
 
 export {
+  BackendClient,
+  requireCredentialsFromEnv,
+  RunAbortedError,
   LayerExecutionError,
   describeFailureReason,
   SEEDANCE_DURATIONS,
   ELEVENLABS_MAX_MUSIC_LENGTH_MS,
   IMAGE_GENERATE_MODELS,
+  DEFAULT_VIDEO_GENERATE_MODEL,
   MODEL_REGISTRY,
   resolveConcurrency,
+  ulid,
+  isPersistedAssetRef,
+  collectAssetRefLikes,
+  REF_PREFIX,
+  parseRefExpr,
+  sha256Hex,
+  SEEDANCE_PROFILE,
+  clipProfileFor,
+  clipParamRecipe,
+  imageProfileFor,
   elementMentionKeywords,
-  BackendClient2 as BackendClient,
+  toModelSafeImage,
+  BackendClient2,
   Engine2 as Engine,
   LocalAssetStore2 as LocalAssetStore,
   LocalCacheStore2 as LocalCacheStore,
@@ -6542,4 +7622,4 @@ export {
   defaultRegistry,
   createEngineFromEnv
 };
-//# sourceMappingURL=chunk-4EPKHOTF.js.map
+//# sourceMappingURL=chunk-J2LYFDVC.js.map