@marlinjai/studio-mcp 0.1.0 → 0.2.0

package/dist/cli.js

@@ -213,8 +213,8 @@ var StudioClient = class {
   }
   /** S9: a rendered diagram of a saved workflow's document, so an agent can
    * see the graph it just built. */
-  getWorkflowScreenshot(savedId2) {
-    return this.json("GET", `/api/v1/workflows/${encodeURIComponent(savedId2)}/screenshot`);
+  getWorkflowScreenshot(savedId2, opts = {}) {
+    return this.json("GET", `/api/v1/workflows/${encodeURIComponent(savedId2)}/screenshot${projectQuery(opts.projectId)}`);
   }
   // ── Recipes (S10): published workflow + closed post-run effect list ──
   publishWorkflow(savedId2, body) {
@@ -239,9 +239,10 @@ var StudioClient = class {
   describeNodeTypes() {
     return this.json("GET", "/api/v1/node-types");
   }
-  /** `savedId` carries a `saved:` prefix; the colon is URL-encoded. */
-  getWorkflowDocument(savedId2) {
-    return this.json("GET", `/api/v1/workflows/${encodeURIComponent(savedId2)}`);
+  /** `savedId` carries a `saved:` prefix; the colon is URL-encoded. `projectId`
+   * names the project the workflow lives in; absent, the Studio's default. */
+  getWorkflowDocument(savedId2, opts = {}) {
+    return this.json("GET", `/api/v1/workflows/${encodeURIComponent(savedId2)}${projectQuery(opts.projectId)}`);
   }
   /** Create a document by applying `ops` to an empty one (the same code path as apply). */
   createWorkflow(body) {
@@ -412,6 +413,9 @@ function mimeForFilename(name) {
       return "application/octet-stream";
   }
 }
+function projectQuery(projectId) {
+  return projectId === void 0 ? "" : `?projectId=${encodeURIComponent(projectId)}`;
+}
 
 // src/tools.ts
 import { z as z8 } from "zod";
@@ -444,6 +448,10 @@ var MODEL_TASKS = [
   "speech-to-speech",
   "image-to-text",
   "image-to-json",
+  // Camera-motion record (2026-09-13): a video in, a prompt-ready description
+  // of its camera motion out, measured from the frames by Studio's own code
+  // (model `studio/motion-record`, no paid provider).
+  "video-to-text",
   // A human decision gate over candidate images (P3 J1). Still a model task,
   // not a new node kind: WorkflowNode already requires task + model, and the
   // ranking call underneath is the same image-to-json vision model
@@ -488,6 +496,8 @@ var TASK_PORTS = {
   // VISION + LANGUAGE.
   "image-to-text": { inputs: ["image", "text"], output: "text" },
   "image-to-json": { inputs: ["image", "text"], output: "json" },
+  // Camera-motion record: the wired clip is the whole input, no prompt.
+  "video-to-text": { inputs: ["video"], output: "text" },
   // Judge (P3 J1): one candidate wire in (the several results of ONE
   // upstream node-run, not fan-in), the approved candidate out. Both sides
   // are typed 'image' so an approved candidate can feed straight into any
@@ -551,11 +561,21 @@ var RefBindingSchema = z2.object({
   // the "no array-of-refs" gap without widening the binding grammar itself.
   wrap: z2.literal("array").optional()
 });
-var BindingSchema = z2.discriminatedUnion("kind", [
+var ListItemBindingSchema = z2.discriminatedUnion("kind", [
   LiteralBindingSchema,
   ParamBindingSchema,
   RefBindingSchema
 ]);
+var ListBindingSchema = z2.object({
+  kind: z2.literal("list"),
+  items: z2.array(ListItemBindingSchema)
+});
+var BindingSchema = z2.discriminatedUnion("kind", [
+  LiteralBindingSchema,
+  ParamBindingSchema,
+  RefBindingSchema,
+  ListBindingSchema
+]);
 var WorkflowTaskSchema = z2.enum(MODEL_TASKS);
 var RetryPolicySchema = z2.object({
   maxAttempts: z2.number().int().positive(),
@@ -634,6 +654,7 @@ var AssetIdSchema = z3.string().max(128);
 var PortTypeSchema = z3.enum(PORT_TYPES);
 var InputTypeSchema = z3.enum(INPUT_PORT_TYPES);
 var PositionSchema = z3.object({ x: z3.number().finite(), y: z3.number().finite() });
+var CollapsedSchema = z3.boolean();
 var TaskNodeSchema = z3.object({
   id: IdSchema,
   kind: z3.literal("task"),
@@ -654,13 +675,15 @@ var TaskNodeSchema = z3.object({
   bakedInputs: z3.record(KeySchema, LiteralBindingSchema).default({}),
   /** The generation id that feeds downstream. Absent = latest (D4). */
   activeGeneration: IdSchema.optional(),
-  label: LabelSchema.optional()
+  label: LabelSchema.optional(),
+  collapsed: CollapsedSchema.optional()
 });
 var PromptSourceNodeSchema = z3.object({
   id: IdSchema,
   kind: z3.literal("prompt-source"),
   text: PromptTextSchema.default(""),
-  label: LabelSchema.optional()
+  label: LabelSchema.optional(),
+  collapsed: CollapsedSchema.optional()
 });
 var ImageSourceNodeSchema = z3.object({
   id: IdSchema,
@@ -671,7 +694,18 @@ var ImageSourceNodeSchema = z3.object({
   /** The Storage Brain asset id, when known (E18: every image input resolves to
    * an asset id). */
   assetId: AssetIdSchema.optional(),
-  label: LabelSchema.optional()
+  label: LabelSchema.optional(),
+  collapsed: CollapsedSchema.optional()
+});
+var VideoSourceNodeSchema = z3.object({
+  id: IdSchema,
+  kind: z3.literal("video-source"),
+  videoUrl: UrlSchema.default(""),
+  /** The Storage Brain asset id, when known, so the clip can be re-signed and
+   * attributed the way an image source's asset is. */
+  assetId: AssetIdSchema.optional(),
+  label: LabelSchema.optional(),
+  collapsed: CollapsedSchema.optional()
 });
 var InputNodeSchema = z3.object({
   id: IdSchema,
@@ -686,12 +720,14 @@ var InputNodeSchema = z3.object({
   /** Used when a run omits the input. Never null: absent means no default. */
   default: JsonNonNullValueSchema.optional(),
   label: LabelSchema.optional(),
-  description: DescriptionSchema.optional()
+  description: DescriptionSchema.optional(),
+  collapsed: CollapsedSchema.optional()
 });
 var DocNodeSchema = z3.discriminatedUnion("kind", [
   TaskNodeSchema,
   PromptSourceNodeSchema,
   ImageSourceNodeSchema,
+  VideoSourceNodeSchema,
   InputNodeSchema
 ]);
 var DocEdgeSchema = z3.object({
@@ -704,6 +740,18 @@ var DocGroupSchema = z3.object({
   label: LabelSchema.optional(),
   nodeIds: z3.array(IdSchema).min(1)
 });
+var EDGE_ROUTINGS = ["curved", "orthogonal"];
+var EdgeRoutingSchema = z3.enum(EDGE_ROUTINGS);
+var WireRouteSchema = z3.object({
+  from: PositionSchema,
+  to: PositionSchema,
+  points: z3.array(PositionSchema).max(64)
+});
+var DocumentViewSchema = z3.object({
+  edgeRouting: EdgeRoutingSchema.optional(),
+  /** Routed wires from the last Arrange, keyed by `edgeKey`. */
+  wires: z3.record(z3.string().max(512), WireRouteSchema).optional()
+});
 var WorkflowDocumentSchema = z3.object({
   schema: z3.number().int().positive(),
   id: IdSchema,
@@ -711,7 +759,10 @@ var WorkflowDocumentSchema = z3.object({
   nodes: z3.array(DocNodeSchema).max(2e3),
   edges: z3.array(DocEdgeSchema).max(8e3),
   layout: z3.record(IdSchema, PositionSchema).default({}),
-  groups: z3.array(DocGroupSchema).max(500).default([])
+  groups: z3.array(DocGroupSchema).max(500).default([]),
+  /** Display preferences; absent on every document written before they
+   * existed (additive, so `DOCUMENT_SCHEMA_VERSION` is unchanged). */
+  view: DocumentViewSchema.optional()
 });
 function edgeKey(e) {
   return JSON.stringify([e.source, e.target, e.port]);
@@ -963,7 +1014,7 @@ var MODEL_CATALOG = [
     label: "Kling 2.5 Turbo Pro (image-to-video)",
     description: "Kuaishou Kling 2.5 Turbo Pro via fal. Cinematic image-to-video; $0.35 base (5s) plus $0.07 per extra second. Default image-to-video.",
     cost: { usd: 0.35 },
-    capabilities: { needsImageInput: true, maxInputImages: 1 },
+    capabilities: { needsImageInput: true, maxInputImages: 1, acceptsEndFrame: true },
     isDefault: true
   },
   {
@@ -984,7 +1035,7 @@ var MODEL_CATALOG = [
     label: "Seedance 2.5 (image-to-video)",
     description: "ByteDance Seedance 2.5 via fal. Accepts a start frame AND an end frame (end_image_url), selectable duration 4-30s, up to 1080p, with synchronised audio (generate_audio, on by default). Token-billed: (w*h*s*24)/1024 at $0.0214 per 1000 tokens, so roughly $1.89 for 4s at 720p and $4.16 at 1080p. CAUTION: ByteDance partner moderation on 2.5 rejected even fal's own robot test image with content_policy_violation (observed 2026-08-21), so it may refuse input that 2.0 accepts. Try 2.0 first for photographic input.",
     cost: { usd: 1.89 },
-    capabilities: { needsImageInput: true, maxInputImages: 1 }
+    capabilities: { needsImageInput: true, maxInputImages: 1, acceptsEndFrame: true }
   },
   {
     id: "fal/seedance-2-0-image-to-video",
@@ -994,7 +1045,7 @@ var MODEL_CATALOG = [
     label: "Seedance 2.0 (image-to-video)",
     description: "ByteDance Seedance 2.0 via fal. Start frame plus optional end frame (end_image_url), duration 4-15s, up to 4k, and it accepts seven explicit aspect ratios where 2.5 is fixed to auto. Not simply superseded by 2.5: 2.0 generated from photographic input that 2.5 refused on content policy (observed 2026-08-21), and it is the only one offering 4k. Token-billed identically to 2.5.",
     cost: { usd: 1.89 },
-    capabilities: { needsImageInput: true, maxInputImages: 1 }
+    capabilities: { needsImageInput: true, maxInputImages: 1, acceptsEndFrame: true }
   },
   // ── FLUX.3 (Black Forest Labs) ───────────────────────────────────────────
   // One model, three tiers of the same three input shapes:
@@ -1029,7 +1080,7 @@ var MODEL_CATALOG = [
     label: "FLUX.3 draft (first + last frame)",
     description: "Black Forest Labs FLUX.3 draft tier via fal. Start AND end keyframe, duration 5-20s, fixed 720p, audio ON by default. $0.06 per second of draft, roughly a third of Kling 2.5 for the same two-keyframe shot. Note it names the start frame start_image_url, not image_url. Minimum 5s, so a 4s cut means rendering 5s and trimming. PREVIEW QUALITY: enhance before shipping.",
     cost: { usd: 0.3 },
-    capabilities: { needsImageInput: true, maxInputImages: 2, emitsDraftCache: true }
+    capabilities: { needsImageInput: true, maxInputImages: 2, emitsDraftCache: true, acceptsEndFrame: true }
   },
   {
     id: "fal/flux-3-keyframes-to-video-draft",
@@ -1059,7 +1110,7 @@ var MODEL_CATALOG = [
     label: "FLUX.3 (first + last frame)",
     description: "Black Forest Labs FLUX.3 direct tier via fal. Start AND end keyframe (start_image_url / end_image_url), duration 5-20s, resolution 720p (default) or 1080p, audio ON by default. $0.17 per second at 720p, $0.29 at 1080p; the catalog usd anchors 5s at 720p. Minimum 5s, so a 4s cut means rendering 5s and trimming. Finished quality, returns the seed.",
     cost: { usd: 0.85 },
-    capabilities: { needsImageInput: true, maxInputImages: 2 }
+    capabilities: { needsImageInput: true, maxInputImages: 2, acceptsEndFrame: true }
   },
   {
     id: "fal/flux-3-keyframes-to-video",
@@ -1129,6 +1180,19 @@ var MODEL_CATALOG = [
     capabilities: { needsImageInput: true, maxInputImages: 1 },
     isDefault: true
   },
+  // Camera-motion record (2026-09-13): Studio's own analysis, no paid provider.
+  // A video in, a prompt-ready description of its camera motion out
+  // (job.output.text), with the measured record beside it (job.output.json).
+  {
+    id: "studio/motion-record",
+    provider: "studio",
+    modality: "text",
+    task: "video-to-text",
+    label: "Motion record (Studio)",
+    description: "Measures a clip's camera motion from its frames (phase correlation every 0.1 s: pan, tilt, dolly, steadiness, subject motion) and writes a deterministic description to job.output.text plus the full record to job.output.json. Runs in Studio, costs nothing. Default video-to-text.",
+    cost: { usd: 0 },
+    isDefault: true
+  },
   {
     id: "fal/moondream-next-vqa",
     provider: "fal",
@@ -1320,6 +1384,9 @@ function portBinding(task, port) {
   if (port === "mesh3d" && (task === "remesh" || task === "texture")) {
     return { key: "parentAssetId", path: "assetId" };
   }
+  if (port === "video" && task === "video-to-text") {
+    return { key: "inputVideoUrl", path: "url" };
+  }
   if (port === "video" && task === "video-to-video") {
     return { key: "inputVideoUrl", path: "url" };
   }
@@ -1350,6 +1417,30 @@ function canConnect(sourceOut, targetTask, targetPort) {
   if (sourceOut !== targetPort) return false;
   return portBinding(targetTask, targetPort) !== null;
 }
+function portCardinality(task, port) {
+  if (portBinding(task, port) === null) return "none";
+  if (port === "image" && task === "image-edit") return "many";
+  if (port === "image" && task === "image-to-video") return "two";
+  return "one";
+}
+function cardinalityLimit(cardinality) {
+  switch (cardinality) {
+    case "none":
+      return 0;
+    case "one":
+      return 1;
+    case "two":
+      return 2;
+    case "many":
+      return Number.POSITIVE_INFINITY;
+  }
+}
+function orderedPortKey(task, port, ordinal) {
+  const canonical = portBinding(task, port);
+  if (!canonical) return null;
+  if (portCardinality(task, port) === "two" && ordinal === 1) return "endImageUrl";
+  return canonical.key;
+}
 function sourcePortOf(node) {
   switch (node.kind) {
     case "task":
@@ -1358,10 +1449,28 @@ function sourcePortOf(node) {
       return "text";
     case "image-source":
       return "image";
+    case "video-source":
+      return "video";
     case "input":
       return node.type;
   }
 }
+function targetCardinality(node, port) {
+  if (node.kind !== "task") return "none";
+  return portCardinality(node.task, port);
+}
+function slotRefusal(node, port, wired) {
+  const cardinality = targetCardinality(node, port);
+  let limit = cardinalityLimit(cardinality);
+  if (cardinality === "many" && node.kind === "task" && node.model) {
+    const cap = tryGetModel(node.model)?.capabilities?.maxInputImages;
+    if (typeof cap === "number" && cap > 0) limit = Math.min(limit, cap);
+  }
+  if (wired < limit) return null;
+  if (cardinality === "one") return `node "${node.id}" accepts one ${port} wire, got more`;
+  if (cardinality === "two") return `node "${node.id}" takes two ${port} wires (start frame, end frame), got more`;
+  return `node "${node.id}" (${node.kind === "task" ? node.model : node.kind}) takes at most ${limit} ${port} wires`;
+}
 function wireLegality(source, target, port) {
   if (source.id === target.id) return { ok: false, code: "cycle", message: `node "${source.id}" cannot wire into itself` };
   const produced = sourcePortOf(source);
@@ -1428,7 +1537,7 @@ function validateDocument(doc) {
     inputNames.add(node.name);
   }
   const edgeKeys = /* @__PURE__ */ new Set();
-  const slots = /* @__PURE__ */ new Set();
+  const slots = /* @__PURE__ */ new Map();
   for (const e of doc.edges) {
     const key = edgeKey(e);
     if (edgeKeys.has(key)) return { ok: false, code: "conflict", message: `duplicate edge ${key}` };
@@ -1440,14 +1549,24 @@ function validateDocument(doc) {
     const legal = wireLegality(source, target, e.port);
     if (!legal.ok) return legal;
     const slot = slotKey(e.target, e.port);
-    if (slots.has(slot)) {
+    const wired = slots.get(slot) ?? 0;
+    const refusal = slotRefusal(target, e.port, wired);
+    if (refusal) return { ok: false, code: "cardinality", message: refusal };
+    slots.set(slot, wired + 1);
+  }
+  for (const [slot, wired] of slots) {
+    if (wired < 2) continue;
+    const [targetId, port] = JSON.parse(slot);
+    const target = byId.get(targetId);
+    if (!target || target.kind !== "task" || port !== "image" || portCardinality(target.task, port) !== "two" || !target.model) continue;
+    const model = tryGetModel(target.model);
+    if (model && !model.capabilities?.acceptsEndFrame) {
       return {
         ok: false,
-        code: "cardinality",
-        message: `node "${e.target}" accepts one ${e.port} wire, got more`
+        code: "invalid_port",
+        message: `"${target.id}" (${target.model}) takes no end frame, so its second image wire has nowhere to bind. Pick a model with start and end frame support (Kling 2.5, Seedance 2.x, FLUX.3 first-last) or disconnect it.`
       };
     }
-    slots.add(slot);
   }
   if (documentTopologicalOrder(doc) === null) {
     return { ok: false, code: "cycle", message: `document "${doc.id}" has a cycle in its wires` };
@@ -1480,16 +1599,25 @@ var TaskNodePropsSchema = z4.object({
   task: z4.enum(MODEL_TASKS),
   model: ModelIdSchema,
   prompt: PromptTextSchema,
-  label: LabelSchema.nullable()
+  label: LabelSchema.nullable(),
+  collapsed: CollapsedSchema.nullable()
 }).partial().strict();
 var PromptSourcePropsSchema = z4.object({
   text: PromptTextSchema,
-  label: LabelSchema.nullable()
+  label: LabelSchema.nullable(),
+  collapsed: CollapsedSchema.nullable()
 }).partial().strict();
 var ImageSourcePropsSchema = z4.object({
   imageUrl: UrlSchema,
   assetId: AssetIdSchema.nullable(),
-  label: LabelSchema.nullable()
+  label: LabelSchema.nullable(),
+  collapsed: CollapsedSchema.nullable()
+}).partial().strict();
+var VideoSourcePropsSchema = z4.object({
+  videoUrl: UrlSchema,
+  assetId: AssetIdSchema.nullable(),
+  label: LabelSchema.nullable(),
+  collapsed: CollapsedSchema.nullable()
 }).partial().strict();
 var InputNodePropsSchema = z4.object({
   name: InputNameSchema,
@@ -1498,14 +1626,19 @@ var InputNodePropsSchema = z4.object({
   cardinality: z4.enum(["one", "many"]).nullable(),
   default: JsonNonNullValueSchema.nullable(),
   label: LabelSchema.nullable(),
-  description: DescriptionSchema.nullable()
+  description: DescriptionSchema.nullable(),
+  collapsed: CollapsedSchema.nullable()
 }).partial().strict();
 var GroupPropsSchema = z4.object({
   label: LabelSchema.nullable(),
   nodeIds: z4.array(IdSchema).min(1)
 }).partial().strict();
 var DocumentPropsSchema = z4.object({
-  label: LabelSchema
+  label: LabelSchema,
+  /** Display preferences (`view.edgeRouting`); null clears the whole
+   * object. The object is replaced, not merged: pass every field you want
+   * kept. */
+  view: DocumentViewSchema.strict().nullable()
 }).partial().strict();
 var AddNodeOpSchema = z4.object({
   type: z4.literal("addNode"),
@@ -1523,6 +1656,7 @@ var SetNodePropsOpSchema = z4.discriminatedUnion("kind", [
   z4.object({ type: z4.literal("setNodeProps"), kind: z4.literal("task"), id: IdSchema, props: TaskNodePropsSchema }),
   z4.object({ type: z4.literal("setNodeProps"), kind: z4.literal("prompt-source"), id: IdSchema, props: PromptSourcePropsSchema }),
   z4.object({ type: z4.literal("setNodeProps"), kind: z4.literal("image-source"), id: IdSchema, props: ImageSourcePropsSchema }),
+  z4.object({ type: z4.literal("setNodeProps"), kind: z4.literal("video-source"), id: IdSchema, props: VideoSourcePropsSchema }),
   z4.object({ type: z4.literal("setNodeProps"), kind: z4.literal("input"), id: IdSchema, props: InputNodePropsSchema })
 ]);
 var SetNodeSettingOpSchema = z4.object({
@@ -1554,8 +1688,8 @@ var DisconnectOpSchema = z4.object({
 });
 var ExposeAsInputOpSchema = z4.object({
   type: z4.literal("exposeAsInput"),
-  /** A prompt-source or image-source node; it becomes an input node IN PLACE
-   * (same id, same produced port type), so its wires survive. */
+  /** A prompt-source, image-source or video-source node; it becomes an input
+   * node IN PLACE (same id, same produced port type), so its wires survive. */
   id: IdSchema,
   name: InputNameSchema,
   required: z4.boolean().optional(),
@@ -1568,8 +1702,9 @@ var ExposeAsInputOpSchema = z4.object({
 });
 var FreezeInputOpSchema = z4.object({
   type: z4.literal("freezeInput"),
-  /** A text or image input node; it becomes a prompt-source / image-source IN
-   * PLACE carrying `value` (a chosen run's resolved value, or any literal). */
+  /** A text, image or video input node; it becomes a prompt-source /
+   * image-source / video-source IN PLACE carrying `value` (a chosen run's
+   * resolved value, or any literal). */
   id: IdSchema,
   value: PromptTextSchema,
   assetId: AssetIdSchema.optional(),
@@ -1778,6 +1913,8 @@ var TASK_TO_KIND = {
   // vision (text/json output, no binary asset)
   "image-to-text": "analyze_image",
   "image-to-json": "analyze_image",
+  // camera-motion record (text + json output, no binary asset), Studio's own worker
+  "video-to-text": "analyze_video",
   // utility (new Image asset off the source)
   upscale: "transform_image",
   "background-remove": "transform_image",
@@ -1801,7 +1938,7 @@ function taskExecution(task) {
 function paramTypeForInput(type) {
   return type === "json" ? "json" : "string";
 }
-function isUsableImageUrl(url) {
+function isUsableSourceUrl(url) {
   return url.length > 0 && !url.startsWith("data:");
 }
 function documentToDefinition(doc, opts = {}) {
@@ -1859,22 +1996,50 @@ function documentToDefinition(doc, opts = {}) {
         issues.push({ code: "prompt_required", nodeId: node.id, message: `Node "${node.id}" (${task}) needs a prompt.` });
       }
     }
+    const byPort = /* @__PURE__ */ new Map();
     for (const e of wires) {
       if (e.port === "text") continue;
-      const b = portBinding(task, e.port);
-      const source = byId.get(e.source);
-      if (source.kind === "image-source") {
-        const url = source.imageUrl.trim();
-        if (!isUsableImageUrl(url)) {
-          issues.push({ code: "source_uploading", nodeId: node.id, message: `Image source for "${node.id}" is still uploading; wait for it to finish.` });
-          continue;
+      const list = byPort.get(e.port);
+      if (list) list.push(e);
+      else byPort.set(e.port, [e]);
+    }
+    for (const [port, portWires] of byPort) {
+      const b = portBinding(task, port);
+      const cardinality = portCardinality(task, port);
+      const items = [];
+      let uploading = false;
+      for (const [ordinal, e] of portWires.entries()) {
+        const source = byId.get(e.source);
+        const single = cardinality !== "many" || portWires.length === 1;
+        const key = orderedPortKey(task, port, ordinal) ?? b.key;
+        const wrap = single && b.wrap === "array";
+        let item = null;
+        if (source.kind === "image-source") {
+          const url = source.imageUrl.trim();
+          if (!isUsableSourceUrl(url)) {
+            issues.push({ code: "source_uploading", nodeId: node.id, message: `Image source for "${node.id}" is still uploading; wait for it to finish.` });
+            uploading = true;
+            continue;
+          }
+          item = { kind: "literal", value: wrap ? [url] : url };
+        } else if (source.kind === "video-source") {
+          const clip = source.videoUrl.trim();
+          if (!isUsableSourceUrl(clip)) {
+            issues.push({ code: "source_uploading", nodeId: node.id, message: `Video source for "${node.id}" is still uploading; wait for it to finish.` });
+            uploading = true;
+            continue;
+          }
+          item = { kind: "literal", value: wrap ? [clip] : clip };
+        } else if (source.kind === "input") {
+          item = wrap && source.cardinality !== "many" ? { kind: "param", name: source.name, wrap: "array" } : { kind: "param", name: source.name };
+        } else if (source.kind === "task") {
+          item = wrap ? { kind: "ref", node: source.id, path: b.path, wrap: "array" } : { kind: "ref", node: source.id, path: b.path };
         }
-        inputs[b.key] = { kind: "literal", value: b.wrap === "array" ? [url] : url };
-      } else if (source.kind === "input") {
-        inputs[b.key] = b.wrap === "array" && source.cardinality !== "many" ? { kind: "param", name: source.name, wrap: "array" } : { kind: "param", name: source.name };
-      } else if (source.kind === "task") {
-        inputs[b.key] = b.wrap === "array" ? { kind: "ref", node: source.id, path: b.path, wrap: "array" } : { kind: "ref", node: source.id, path: b.path };
+        if (!item) continue;
+        if (single) inputs[key] = item;
+        else items.push(item);
       }
+      if (!uploading && items.length > 0) inputs[b.key] = { kind: "list", items };
     }
     for (const [key, binding] of Object.entries(node.bakedInputs)) if (!(key in inputs)) inputs[key] = binding;
     if (Object.keys(inputs).length === 0 && !promptMissing) {
@@ -2076,7 +2241,7 @@ async function pollUntil(what, fetchState, isDone, opts = {}) {
   }
 }
 var TERMINAL_JOB_STATUSES = /* @__PURE__ */ new Set(["succeeded", "failed", "canceled"]);
-var TERMINAL_RUN_STATUSES = /* @__PURE__ */ new Set(["succeeded", "failed", "partial"]);
+var TERMINAL_RUN_STATUSES = /* @__PURE__ */ new Set(["succeeded", "failed", "partial", "cancelled"]);
 function isJobTerminal(res) {
   return TERMINAL_JOB_STATUSES.has(res.job.status);
 }
@@ -2109,8 +2274,24 @@ function runFailureSummary(res) {
 var DEFAULT_SWAP_EDIT_MODEL = "fal/nano-banana-2-edit";
 var DEFAULT_SWAP_VIDEO_MODEL = "fal/seedance-pro-image-to-video";
 var KEYFRAME_SWAP_VIDEO_MODEL = "fal/kling-v2-5-image-to-video";
-var DEFAULT_SWAP_PROMPT = "Replace the person in the first image with the person from the second image. Keep the pose, framing, camera angle, clothing fit, lighting, background, and every other pixel of the scene identical. Match the face, hair, and body of the second image exactly. Photorealistic, no artifacts.";
-var DEFAULT_MOTION_PROMPT = "Natural, subtle motion that continues the scene: gentle camera movement, realistic body motion, consistent lighting. Keep the person identical to the still.";
+var SWAP_SCOPES = ["identity", "full_body"];
+function composeSwapPrompt(options = {}) {
+  const scope = options.scope ?? "identity";
+  const taken = scope === "full_body" ? "take the face, head, hair and body proportions from the second image" : "take the face, head and hair from the second image";
+  const kept = scope === "full_body" ? "Keep the first image's clothing, pose, expression, gaze and hand placement." : "Keep the first image's body, clothing, pose, expression, gaze and hand placement.";
+  const sentences = [
+    `Replace the person in the first image with the person in the second image: ${taken}.`,
+    kept,
+    "Match the first image's lighting, focus and colour, and keep its framing and background."
+  ];
+  for (const raw of options.preserve ?? []) {
+    const constraint = raw.trim().replace(/[.\s]+$/, "");
+    if (constraint) sentences.push(`${constraint.charAt(0).toUpperCase()}${constraint.slice(1)}.`);
+  }
+  return sentences.join(" ");
+}
+var DEFAULT_SWAP_PROMPT = composeSwapPrompt();
+var DEFAULT_MOTION_PROMPT = "Continue the scene as photographed: keep the camera position and framing of the still, move the person naturally and continuously, and keep the lighting consistent. Add no camera movement.";
 var SWAP_EDIT_NODE_ID = "edit";
 var SWAP_VIDEO_NODE_ID = "video";
 function defaultVideoModelFor(input) {
@@ -2130,7 +2311,7 @@ function buildCharacterSwapDefinition(input) {
         task: "image-edit",
         model: input.editModel ?? DEFAULT_SWAP_EDIT_MODEL,
         inputs: {
-          prompt: { kind: "literal", value: input.swapPrompt ?? DEFAULT_SWAP_PROMPT },
+          prompt: { kind: "literal", value: input.swapPrompt ?? composeSwapPrompt({ scope: input.scope, preserve: input.preserve }) },
           inputImages: { kind: "literal", value: [input.sceneFrameUrl, input.characterImageUrl] },
           aspectRatio: { kind: "literal", value: input.aspectRatio ?? "16:9" }
         }
@@ -2239,6 +2420,9 @@ function summarizeNode(node, wires) {
     case "image-source":
       base.imageUrl = clipText(node.imageUrl);
       break;
+    case "video-source":
+      base.videoUrl = clipText(node.videoUrl);
+      break;
     case "input":
       base.name = node.name;
       base.type = node.type;
@@ -2409,11 +2593,12 @@ var studioWorkflowGet = defineTool({
   description: "Read a saved workflow. By default returns a summary: { savedId, revision, label, readOnly, nodes: [{ id, kind, label?, task?, model?, prompt? (first 80 chars, plus promptLength), imageUrl?, name?, type?, required?, wires: { in, out } }], edgeCount, groupCount, projection: { ok, issues } } where revision is the baseRevision for studio_workflow_apply and projection says whether the workflow can run and why not. A workflow the canvas cannot represent comes back as { readOnly: true, definitionNodeCount, projection, hint } with no nodes: it is readable and runnable (studio_run_workflow with its savedId) but not patchable. needsLossyAcknowledgement: true means its first patch must carry acknowledgeLossy: true. full: true returns the whole response instead; use it only when you need every field.",
   inputSchema: {
     savedId,
+    projectId: z7.string().min(1).optional().describe("Project id from studio_list_projects the workflow lives in; omit for the default project."),
     full: z7.boolean().default(false).describe("Return the whole response (the full document, or the stored definition of a read-only workflow) instead of the summary.")
   },
   annotations: { readOnlyHint: true },
   handler: async (args, ctx) => {
-    const res = await ctx.client.getWorkflowDocument(args.savedId);
+    const res = await ctx.client.getWorkflowDocument(args.savedId, args.projectId !== void 0 ? { projectId: args.projectId } : {});
     if (args.full) return res;
     if (res.readOnly === true || res.document === null) {
       const definition = isRecord(res.definition) ? res.definition : null;
@@ -2486,6 +2671,7 @@ var studioWorkflowApply = defineTool({
   description: 'Change a saved workflow atomically: the ops are applied all-or-nothing on top of baseRevision (the revision from studio_workflow_get, studio_workflow_create or your last apply). Success returns { ok: true, savedId, revision, appliedCount, inverseCount, affectedNodes (summaries of the nodes the patch touched, removed ones as { id, removed: true }), projection: { ok, issues }, idempotencyKey, replayed }. Every refusal comes back as { ok: false, code, hint } you can act on rather than an error: "stale_revision" (re-read, rebase your ops, apply again on the revision returned), "invalid_patch" (error.opIndex names the offending op), "forbidden" (opIndex plus the missingScope your credential needs), "not_editable" (this workflow is readable and runnable but cannot be patched), "lossy_import" (read notes, then resend with acknowledgeLossy: true and a NEW idempotencyKey), "idempotency_mismatch" (that key belongs to a different patch: use a fresh one), and "network_error" / "server_error" which you retry with the SAME idempotencyKey so the patch can never apply twice.',
   inputSchema: {
     savedId,
+    projectId: z7.string().min(1).optional().describe("Project id from studio_list_projects the workflow lives in; omit for the default project."),
     baseRevision: PatchSchema.shape.baseRevision.describe("The revision the ops were written against. The Studio refuses a stale one with stale_revision."),
     ops: opsSchema,
     idempotencyKey: PatchSchema.shape.idempotencyKey.describe(
@@ -2500,6 +2686,7 @@ var studioWorkflowApply = defineTool({
     let res;
     try {
       res = await ctx.client.applyWorkflowPatch(args.savedId, {
+        ...args.projectId !== void 0 ? { projectId: args.projectId } : {},
         baseRevision: args.baseRevision,
         ops: args.ops,
         idempotencyKey,
@@ -2534,16 +2721,18 @@ var studioWorkflowValidate = defineTool({
   inputSchema: {
     document: WorkflowDocumentSchema.optional().describe("The document to validate. Either this or savedId."),
     savedId: savedId.optional().describe("Fetch this saved workflow first and validate against its current document. Either this or document, not both."),
+    projectId: z7.string().min(1).optional().describe("Project id from studio_list_projects the saved workflow lives in (only with savedId); omit for the default project."),
     ops: PatchSchema.shape.ops.optional().describe("Ops to apply to the document before projecting it (the same vocabulary and limits as studio_workflow_apply)."),
     params: paramsSchema.optional()
   },
   annotations: { readOnlyHint: true },
   handler: async (args, ctx) => {
     if (args.document && args.savedId) throw new ToolInputError("pass either `document` or `savedId`, not both");
+    if (args.projectId !== void 0 && !args.savedId) throw new ToolInputError("`projectId` only applies when fetching by `savedId`");
     let document = args.document;
     if (!document) {
       if (!args.savedId) throw new ToolInputError("provide a `document` or a `savedId` to validate");
-      const saved = await ctx.client.getWorkflowDocument(args.savedId);
+      const saved = await ctx.client.getWorkflowDocument(args.savedId, args.projectId !== void 0 ? { projectId: args.projectId } : {});
       if (saved.readOnly === true || saved.document === null) {
         throw new ToolInputError(
           `workflow ${args.savedId} has no document to validate: the canvas cannot represent its stored definition (studio_workflow_get shows readOnly: true and why). It is still runnable with studio_run_workflow.`
@@ -2562,11 +2751,12 @@ var studioWorkflowScreenshot = defineTool({
   name: "studio_workflow_screenshot",
   description: "Render a saved workflow's document as a diagram (labelled boxes and wires, positioned by the document's own layout) so you can see the graph you just built, the Figma get_screenshot equivalent. NOT a pixel-exact preview of the real canvas: a plain diagnostic diagram for checking topology (is everything wired the way I meant, did that addNode land where I expected). Returns { url, width, height }; the url is a signed Storage Brain link, valid for 24h. Free, read-only.",
   inputSchema: {
-    savedId
+    savedId,
+    projectId: z7.string().min(1).optional().describe("Project id from studio_list_projects the workflow lives in; omit for the default project.")
   },
   annotations: { readOnlyHint: true },
   handler: async (args, ctx) => {
-    return ctx.client.getWorkflowScreenshot(args.savedId);
+    return ctx.client.getWorkflowScreenshot(args.savedId, args.projectId !== void 0 ? { projectId: args.projectId } : {});
   }
 });
 var WORKFLOW_TOOLS = [
@@ -2599,6 +2789,8 @@ function projectJob(res) {
 function projectNodeRun(nr) {
   return {
     nodeId: nr.nodeId,
+    // The node-run (generation) id: what `upstreamGenerations` pins.
+    id: nr.id ?? null,
     status: nr.status,
     url: nr.resultUrl ?? nr.results?.[0]?.url ?? null,
     kind: nr.results?.[0]?.kind ?? null,
@@ -2852,17 +3044,20 @@ var studioUploadBrandReference = defineTool({
   }
 });
 var workflowDefinitionSchema = WorkflowDefinitionSchema.describe(
-  'Inline workflow DAG: { id, label?, params?: [{ name, type: string|number|boolean|json, required?, label?, description?, inputType?, cardinality?: one|many, default? }], nodes: [{ id, task (one of the model tasks listed), model (catalog id, e.g. fal/nano-banana-2-edit), inputs, retry? }] }. Node inputs are bindings: {kind:"literal",value}, {kind:"param",name,wrap?:"array"} or {kind:"ref",node,path:"url",wrap?:"array"}. Image-edit nodes take inputImages (array, use wrap:"array" on a ref or param); image-to-video nodes take inputImageUrl (string).'
+  'Inline workflow DAG: { id, label?, params?: [{ name, type: string|number|boolean|json, required?, label?, description?, inputType?, cardinality?: one|many, default? }], nodes: [{ id, task (one of the model tasks listed), model (catalog id, e.g. fal/nano-banana-2-edit), inputs, retry? }] }. Node inputs are bindings: {kind:"literal",value}, {kind:"param",name,wrap?:"array"}, {kind:"ref",node,path:"url",wrap?:"array"} or an ordered {kind:"list",items:[...]} of those. Image-edit nodes take inputImages (an array: one wrapped ref/param, or a list in reference order, scene frame first); image-to-video nodes take inputImageUrl (start frame) and optionally endImageUrl (end frame, on models that accept one).'
 );
 var studioRunWorkflow = defineTool({
   name: "studio_run_workflow",
-  description: `Run a generation workflow DAG. Pass an inline definition (nodes of provider calls wired by ref bindings; this is what the hosted Studio accepts) or the savedId of a workflow saved in the Studio (the Studio runs that workflow's current document, exactly what the canvas would run). Params fill {kind:"param"} bindings. Returns the runId plus per-node status, URLs and cost; with wait=true (default) it blocks until the run is terminal (succeeded, failed, partial). Each node becomes a paid job.`,
+  description: `Run a generation workflow DAG. Pass an inline definition (nodes of provider calls wired by ref bindings; this is what the hosted Studio accepts) or the savedId of a workflow saved in the Studio (the Studio runs that workflow's current document, exactly what the canvas would run). Params fill {kind:"param"} bindings. Returns the runId plus per-node status, URLs and cost; with wait=true (default) it blocks until the run is terminal (succeeded, failed, partial, cancelled). Each node becomes a paid job. Use an inline definition ONLY for the first batch of a new deliverable (one workflow, a node per item, a stable label); a follow-up on an existing item belongs in that saved workflow as a new node (studio_workflow_apply: addNode plus connect from the node it refines) run here with savedId and nodeIds, because every listed inline run is saved as its own workflow.`,
   inputSchema: {
     projectId: z8.string().min(1).describe("Project id from studio_list_projects."),
     definition: workflowDefinitionSchema.optional(),
     savedId: z8.string().optional().describe("Id of a saved workflow (from studio_workflow_create, studio_workflow_get or a listed run) to run instead of an inline definition. An unknown id is a 404 naming it; a workflow that is not runnable yet comes back as not_runnable with per-node issues."),
     params: z8.record(z8.string(), z8.unknown()).optional().describe("Values for the definition's params."),
     nodeIds: z8.array(z8.string()).optional().describe("Run only this subset of nodes (requires an inline `definition` or a `savedId`)."),
+    upstreamGenerations: z8.record(z8.string(), z8.string()).optional().describe(
+      'Pin WHICH generation of an upstream node feeds this subset run: { "<upstream node id>": "<node-run id>" } (the per-node `id` that studio_get_run returns). A verified pin is reused even when the planner has no matching cache key for it (an inline first batch, or a node edited and reverted), so a follow-up node wired from an earlier generation runs against exactly that image. An unknown id is refused naming the node, never silently replaced by the latest.'
+    ),
     runs: z8.number().int().min(1).max(8).optional().describe("Repeat a node subset N times (1 to 8)."),
     visibility: z8.enum(["listed", "unlisted"]).optional().describe("Whether the run shows in the Studio workflow list."),
     budgetUsd: z8.number().nonnegative().optional().describe(
@@ -2886,6 +3081,7 @@ var studioRunWorkflow = defineTool({
       ...args.definition ? { definition: args.definition } : {},
       ...args.params ? { params: args.params } : {},
       ...args.nodeIds && args.nodeIds.length > 0 ? { nodeIds: args.nodeIds } : {},
+      ...args.upstreamGenerations ? { upstreamGenerations: args.upstreamGenerations } : {},
       ...args.runs !== void 0 ? { runs: args.runs } : {},
       ...args.savedId ? { savedId: args.savedId } : {},
       ...args.visibility ? { visibility: args.visibility } : {},
@@ -2899,7 +3095,7 @@ var studioRunWorkflow = defineTool({
 });
 var studioGetRun = defineTool({
   name: "studio_get_run",
-  description: "Fetch a workflow run by runId: overall status (pending, running, succeeded, failed, partial, awaiting_decision), total cost, and per-node status, result URL, cost and error message. Set wait=true to block until the run settles. A run at awaiting_decision is parked on a person at a judge node: waiting returns immediately with a `waiting` block naming the node and its candidates, because polling can never clear it; ask the user to choose and submit their answer with studio_decide_judge.",
+  description: "Fetch a workflow run by runId: overall status (pending, running, succeeded, failed, partial, awaiting_decision, cancelled; cancelled means somebody stopped it), total cost, and per-node status, result URL, cost and error message. Set wait=true to block until the run settles. A run at awaiting_decision is parked on a person at a judge node: waiting returns immediately with a `waiting` block naming the node and its candidates, because polling can never clear it; ask the user to choose and submit their answer with studio_decide_judge.",
   inputSchema: {
     runId: z8.string().min(1),
     wait: z8.boolean().default(false),
@@ -2946,14 +3142,16 @@ var studioGetRunOutput = defineTool({
 });
 var studioReplaceCharacterInVideo = defineTool({
   name: "studio_replace_character_in_video",
-  description: "Put a minted character into a video shot using the proven still-swap recipe: (1) an image-edit node (fal/nano-banana-2-edit) replaces the person in a scene FRAME with the character, keeping everything else identical (16:9); (2) an image-to-video node animates that still (default fal/seedance-pro-image-to-video; with endFrameUrl it switches to fal/kling-v2-5-image-to-video and binds the end keyframe so the clip lands on it). Give the character as characterSlug (its full-body reference is used, falling back to three-quarter then face) or as an explicit characterReferenceUrl. Requires a frame URL: extract a representative frame from the video yourself first (this tool does not decode video). Waits for both nodes and returns stillUrl, videoUrl, runId and costUsd (about $0.70 per take). Keep generated cuts under 5 seconds and budget 2 to 3 takes per shot. Do not use video-to-video swap models on dark or handheld footage; this recipe replaces that.",
+  description: 'Put a minted character into a video shot through the still-swap route: (1) an image-edit node (fal/nano-banana-2-edit) replaces the person in a scene FRAME with the character; (2) an image-to-video node animates that still (default fal/seedance-pro-image-to-video; with endFrameUrl it switches to fal/kling-v2-5-image-to-video and binds the end keyframe so the clip lands on it). Be honest with the user about what this route is: the video step REGENERATES the motion from the stills, so the original performance, timing and background are recreated rather than preserved; when the original motion must survive exactly, say so before spending. Declare scope: identity (default) takes face, head and hair and keeps the footage body; full_body also takes the character body proportions, which changes the silhouette. Pass preserve with the two or three shot-specific constraints most likely to fail, from looking at the frame (e.g. "keep the open door in front of his body", "match the face soft focus"), or a complete swapPrompt of your own. Never add a realism suffix like "photorealistic" or a promise that every pixel stays identical; the model cannot keep either and the suffix sharpens deliberately soft subjects. Give the character as characterSlug (its full-body reference is used, falling back to three-quarter then face) or as an explicit characterReferenceUrl. Requires a frame URL: extract a representative frame from the video yourself first (this tool does not decode video). Waits for both nodes and returns stillUrl, videoUrl, runId and costUsd (about $0.70 per take). Inspect the still before paying for more takes, keep generated cuts under 5 seconds, and budget one take plus two retries per shot. Do not use video-to-video swap models on dark or handheld footage.',
   inputSchema: {
     projectId: z8.string().min(1).describe("Project id from studio_list_projects."),
     sceneFrameUrl: httpUrl.describe("Public or signed URL of ONE frame of the target shot (png/jpg)."),
     characterSlug: slug.optional().describe("Minted character to insert; its full-body reference (fallback three-quarter, face) is resolved automatically."),
     characterReferenceUrl: httpUrl.optional().describe("Explicit character reference image URL (use instead of characterSlug)."),
     endFrameUrl: httpUrl.optional().describe("Optional second approved keyframe for the END of the clip. Switches the video model to Kling (start + end frame) unless videoModel is set explicitly."),
-    swapPrompt: z8.string().optional().describe("Override the still-swap edit prompt."),
+    scope: z8.enum(SWAP_SCOPES).optional().describe("How much of the person to replace. identity (default): face, head and hair from the character, the footage keeps its body. full_body: also the character body proportions; the silhouette changes, so the background behind the old body and every contact point must be re-derived."),
+    preserve: z8.array(z8.string().min(1).max(200)).max(6).optional().describe('Shot-specific constraints most likely to fail, as concrete relationships seen in the frame, one per entry (e.g. "keep the open door in front of his body"). Appended to the composed prompt.'),
+    swapPrompt: z8.string().optional().describe("A complete still-swap edit prompt of your own; replaces the composed one, so scope and preserve are then ignored."),
     motionPrompt: z8.string().optional().describe("Override the motion description for the video node."),
     videoModel: z8.string().optional().describe(`Image-to-video model id. Default ${DEFAULT_SWAP_VIDEO_MODEL}, or ${KEYFRAME_SWAP_VIDEO_MODEL} when endFrameUrl is given.`),
     editModel: z8.string().default(DEFAULT_SWAP_EDIT_MODEL).describe("Image-edit model id for the still swap."),
@@ -2984,6 +3182,8 @@ var studioReplaceCharacterInVideo = defineTool({
       characterImageUrl,
       ...args.endFrameUrl ? { endFrameUrl: args.endFrameUrl } : {},
       ...args.swapPrompt ? { swapPrompt: args.swapPrompt } : {},
+      ...args.scope ? { scope: args.scope } : {},
+      ...args.preserve ? { preserve: args.preserve } : {},
       ...args.motionPrompt ? { motionPrompt: args.motionPrompt } : {},
       editModel: args.editModel,
       videoModel,
@@ -3146,7 +3346,7 @@ function registerTools(server, ctx) {
 
 // src/server.ts
 var SERVER_NAME = "lumitra-studio";
-var SERVER_VERSION = "0.1.0";
+var SERVER_VERSION = "0.2.0";
 function createStudioMcpServer(opts = {}) {
   const config = opts.config ?? resolveConfig(opts.env ?? process.env);
   const client = new StudioClient(config, {
@@ -3160,7 +3360,8 @@ function createStudioMcpServer(opts = {}) {
         "Lumitra Studio: brand-consistent image generation, character minting, workflow runs and the still-swap video recipe over the hosted Studio API.",
         "Start with studio_list_projects to get a projectId. Every generation costs real money (roughly $0.04 per image, $0.30 per character mint, $0.70 per video take); check studio_get_spend when in doubt.",
         "Long jobs: tools wait by default (up to timeoutSeconds, 600 by default) and return ids you can poll with studio_get_job / studio_get_run if they time out.",
-        "Authoring a workflow is free and revisioned: studio_workflow_describe for the vocabulary, studio_workflow_create to build one from ops, studio_workflow_apply to change it on top of a baseRevision (a stale_revision result means re-read, rebase, retry), studio_workflow_validate to dry-run before spending, then studio_run_workflow with its savedId."
+        "Authoring a workflow is free and revisioned: studio_workflow_describe for the vocabulary, studio_workflow_create to build one from ops, studio_workflow_apply to change it on top of a baseRevision (a stale_revision result means re-read, rebase, retry), studio_workflow_validate to dry-run before spending, then studio_run_workflow with its savedId.",
+        "Workflow hygiene: one deliverable is ONE saved workflow with a node per item, and a refinement of an item (edit, upscale, variation) is a NEW NODE appended to that workflow with studio_workflow_apply (addNode plus a connect from the node it refines, so the earlier generation is its input), then studio_run_workflow with savedId and nodeIds limited to the new node. Never send a fresh inline definition for a follow-up: every listed inline run is saved as its own workflow, which scatters one deliverable across duplicates."
       ].join(" ")
     }
   );