@marlinjai/studio-mcp 0.1.1 → 0.2.0

package/dist/cli.js

@@ -448,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
@@ -492,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
@@ -555,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(),
@@ -681,6 +697,16 @@ var ImageSourceNodeSchema = z3.object({
   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,
   kind: z3.literal("input"),
@@ -701,6 +727,7 @@ var DocNodeSchema = z3.discriminatedUnion("kind", [
   TaskNodeSchema,
   PromptSourceNodeSchema,
   ImageSourceNodeSchema,
+  VideoSourceNodeSchema,
   InputNodeSchema
 ]);
 var DocEdgeSchema = z3.object({
@@ -987,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
   },
   {
@@ -1008,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",
@@ -1018,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:
@@ -1053,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",
@@ -1083,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",
@@ -1153,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",
@@ -1344,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" };
   }
@@ -1374,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":
@@ -1382,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);
@@ -1452,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}` };
@@ -1464,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` };
@@ -1518,6 +1613,12 @@ var ImageSourcePropsSchema = z4.object({
   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,
   type: InputTypeSchema,
@@ -1555,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({
@@ -1586,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(),
@@ -1600,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(),
@@ -1810,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",
@@ -1833,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 = {}) {
@@ -1891,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) {
@@ -2141,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) {
@@ -2162,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" }
         }
@@ -2271,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;
@@ -2892,7 +3044,7 @@ 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",
@@ -2990,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."),
@@ -3028,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,
@@ -3190,7 +3346,7 @@ function registerTools(server, ctx) {
 
 // src/server.ts
 var SERVER_NAME = "lumitra-studio";
-var SERVER_VERSION = "0.1.1";
+var SERVER_VERSION = "0.2.0";
 function createStudioMcpServer(opts = {}) {
   const config = opts.config ?? resolveConfig(opts.env ?? process.env);
   const client = new StudioClient(config, {