@pinepaper.studio/mcp-server 1.6.3 → 1.6.5

package/dist/types/code-generator.js

@@ -192,16 +192,28 @@ app.historyManager.saveState();
 function generateDeleteItemCode(itemId) {
     return `
 // Delete item ${itemId}
-const item = app.getItemById('${itemId}');
-if (!item) {
-  throw new Error('Item not found: ${itemId}');
-}
-item.remove();
-app.itemRegistry.remove('${itemId}');
-app.historyManager.saveState();
-
-// Return success
-({ success: true, itemId: '${itemId}' });
+//
+// Delegate to app.deleteItem rather than hand-rolling the removal. The old
+// inline version called \`app.itemRegistry.remove(...)\`, which does not exist —
+// the method is \`unregister\` — so the Paper item left the canvas while its
+// REGISTRY ROW SURVIVED, pointing at a detached object. The scene then reported
+// nodes that were not on screen, agents could still address them, and relations
+// to them looked alive. It also skipped the identity-keyed trackers
+// (animatedItems / keyframeItems / selectedItems), so a deleted item that was
+// animating kept being ticked every frame.
+//
+// app.deleteItem does all of that, plus the redraw, the history snapshot and
+// the collaboration mutation event, and it resolves any ref form.
+(function () {
+  if (typeof app.deleteItem !== 'function') {
+    return { success: false, error: 'app.deleteItem unavailable — update FxTool' };
+  }
+  const ok = app.deleteItem('${itemId}');
+  if (!ok) {
+    return { success: false, error: 'Item not found: ${itemId}' };
+  }
+  return { success: true, itemId: '${itemId}' };
+})();
 `.trim();
 }
 /**
@@ -247,7 +259,11 @@ const relations = app.getRelations('${itemId}', ${typeArg});
 // Format results
 const formatted = relations.map(r => ({
   sourceId: r.sourceId || '${itemId}',
-  targetId: r.targetId,
+  // RelationRegistry.getAssociations returns { relation, target, params } —
+  // there is no \`targetId\` on it. Reading the wrong field made EVERY edge come
+  // back with an undefined destination, so the graph was unreadable through
+  // this tool even though it was wired correctly on the canvas.
+  targetId: r.target ?? r.targetId ?? null,
   relationType: r.relation || r.type,
   params: r.params || {}
 }));
@@ -265,7 +281,10 @@ const results = app.queryByRelationTarget('${itemId}', ${typeArg});
 const relations = results.map(r => ({
   sourceId: r.itemId,
   targetId: '${itemId}',
-  relationType: '${relationType || 'unknown'}',
+  // queryByTarget returns the real relation name on each result. Hardcoding
+  // the filter string labelled every edge 'unknown' on an unfiltered query —
+  // which is exactly the query you make when exploring an unfamiliar graph.
+  relationType: r.relation || ${relationType ? `'${relationType}'` : "'unknown'"},
   params: r.params || {}
 }));
 
@@ -869,19 +888,38 @@ export class PinePaperCodeGenerator {
     /**
      * Generate code for importing SVG
      */
-    generateImportSVG(svgString, url, position = { x: 400, y: 300 }, scale = 1.0) {
+    generateImportSVG(svgString, url, position = { x: 400, y: 300 }, scale = 1.0, source) {
+        // Figma is an OPTION on this tool rather than a tool of its own: it is the
+        // same import with a normalisation pass in front, and the tool count is
+        // already the thing the consolidation backlog objects to.
+        //
+        // The pass is not cosmetic. Figma's "Copy as SVG" carries a root
+        // fill="none" that INHERITS (everything renders invisible — the classic "I
+        // pasted my icon and got nothing"), frequently no viewBox, and global ids
+        // like `clip0` that make a second import silently adopt the first one's
+        // clipPath.
+        const importExpr = (varName) => source === 'figma'
+            ? `(function () {
+  if (typeof app.importFigmaSVG !== 'function') {
+    return { item: app.importSVG(${varName}), changes: ['figma normalisation unavailable — update PinePaper Studio'] };
+  }
+  const r = app.importFigmaSVG(${varName});
+  return { item: r.item || null, changes: r.changes || [] };
+})()`
+            : `{ item: app.importSVG(${varName}), changes: [] }`;
         if (url) {
             return `
-// Import SVG from URL
+// Import SVG from URL${source === 'figma' ? ' (Figma-normalised)' : ''}
 const response = await fetch('${url}');
 const svgText = await response.text();
-const imported = app.importSVG(svgText);
+const _r = ${importExpr('svgText')};
+const imported = _r.item;
 if (imported) {
   imported.position = new paper.Point(${position.x}, ${position.y});
   imported.scale(${scale});
   const itemId = app.registerItem(imported, 'svg-import', { source: 'mcp' });
   app.historyManager.saveState();
-  ({ success: true, itemId, position: { x: ${position.x}, y: ${position.y} } });
+  ({ success: true, itemId, changes: _r.changes, position: { x: ${position.x}, y: ${position.y} } });
 } else {
   throw new Error('Failed to import SVG from URL');
 }
@@ -891,15 +929,16 @@ if (imported) {
             // Escape the SVG string for embedding in code
             const escapedSvg = svgString.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$/g, '\\$');
             return `
-// Import SVG string
+// Import SVG string${source === 'figma' ? ' (Figma-normalised)' : ''}
 const svgString = \`${escapedSvg}\`;
-const imported = app.importSVG(svgString);
+const _r = ${importExpr('svgString')};
+const imported = _r.item;
 if (imported) {
   imported.position = new paper.Point(${position.x}, ${position.y});
   imported.scale(${scale});
   const itemId = app.registerItem(imported, 'svg-import', { source: 'mcp' });
   app.historyManager.saveState();
-  ({ success: true, itemId, position: { x: ${position.x}, y: ${position.y} } });
+  ({ success: true, itemId, changes: _r.changes, position: { x: ${position.x}, y: ${position.y} } });
 } else {
   throw new Error('Failed to import SVG');
 }
@@ -1354,7 +1393,10 @@ results;
         const styleStr = style ? JSON.stringify(style) : '{}';
         const widthVal = width || 120;
         const heightVal = height || 60;
-        const labelStr = label ? `'${label.replace(/'/g, "\\'")}'` : 'null';
+        // JSON.stringify emits a complete escaped literal — hand-rolled quote
+        // escaping missed backslashes (CodeQL js/incomplete-sanitization: an input
+        // ending in \ escapes the closing quote; 'x\\'; evil()' breaks out).
+        const labelStr = label ? JSON.stringify(label) : 'null';
         return `
 // Create diagram shape: ${shapeType}
 const shapeConfig = {
@@ -1505,7 +1547,7 @@ const shapes = app.diagramManager.getAvailableShapes(category);
             updates.push(`style: ${JSON.stringify(style)}`);
         }
         if (label !== undefined) {
-            updates.push(`label: '${label.replace(/'/g, "\\'")}'`);
+            updates.push(`label: ${JSON.stringify(label)}`);
         }
         if (labelPosition !== undefined) {
             updates.push(`labelPosition: ${labelPosition}`);
@@ -1589,7 +1631,7 @@ throw new Error('Unknown diagram mode action: ${action}');
     generateAgentStartJob(input) {
         const validated = AgentStartJobInputSchema.parse(input);
         const { name, screenshotPolicy, canvasPreset, clearCanvas, includeOntology } = validated;
-        const nameStr = name ? `'${name.replace(/'/g, "\\'")}'` : 'null';
+        const nameStr = name ? JSON.stringify(name) : 'null';
         const policyStr = screenshotPolicy || 'on_complete';
         const shouldClear = clearCanvas !== false;
         const wantOntology = includeOntology !== false;
@@ -2121,7 +2163,7 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
      */
     generateAgentExport(input) {
         const validated = AgentExportInputSchema.parse(input);
-        const { platform, format, quality, framing, duration } = validated;
+        const { platform, format, quality, framing, duration, estimateOnly } = validated;
         const qualityLevel = quality || 'standard';
         const videoDuration = duration ?? 5;
         // Quality settings (bitrate in bps for VideoEncoder)
@@ -2156,6 +2198,33 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
   const settings = ${JSON.stringify(qualitySettings)};
   const dimensions = ${JSON.stringify({ width: preset.width, height: preset.height })};
 
+  // Preflight: same resolved settings as the real export, but render nothing.
+  // Branching HERE rather than in a separate tool is deliberate — the estimate
+  // has to see the same platform dimensions, fps and quality the export would
+  // use, and a parallel tool would re-derive them and drift.
+  if (${estimateOnly ? 'true' : 'false'}) {
+    if (typeof app.estimateExportSize !== 'function') {
+      return { success: false, estimateOnly: true, error: 'This PinePaper build has no estimateExportSize() — update the editor to preflight export size.' };
+    }
+    const est = await app.estimateExportSize({
+      format,
+      duration: ${videoDuration},
+      fps: settings.fps,
+      quality,
+      width: dimensions.width,
+      height: dimensions.height,
+    });
+    return {
+      success: true,
+      estimateOnly: true,
+      platform, format, quality,
+      duration: ${videoDuration},
+      fps: settings.fps,
+      dimensions: dimensions.width + 'x' + dimensions.height,
+      estimate: est,
+    };
+  }
+
   // Resolve camera-view framing dims when requested. Reads the first
   // camera_animates keyframe's zoom and divides the canvas dims by it
   // (mirrors FxTool ExportEngine.js:466-485). Camera animation still
@@ -3243,12 +3312,20 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
     const relations = [];
     const decorative = [];
 
-    // Collect items from registry
-    if (app.itemRegistry) {
-      for (const [id, item] of app.itemRegistry.entries()) {
+    // Collect items from registry.
+    //
+    // ItemRegistry exposes get/getAll — never \`entries()\`. Iterating a
+    // non-existent method threw on EVERY call, so this tool has never once
+    // returned a scene. getAll() yields registry ENTRIES
+    // ({ itemId, item, type, properties }), not bare Paper items, so the
+    // geometry has to be read off entry.item.
+    if (app.itemRegistry && typeof app.itemRegistry.getAll === 'function') {
+      for (const entry of app.itemRegistry.getAll()) {
+        const item = entry.item;
+        if (!item) continue;
         const itemData = {
-          id: id,
-          type: item.data?.type || item.className?.toLowerCase() || 'unknown',
+          id: entry.itemId,
+          type: entry.type || item.data?.type || item.className?.toLowerCase() || 'unknown',
           position: item.position ? { x: item.position.x, y: item.position.y } : null,
           bounds: item.bounds ? {
             x: item.bounds.x,
@@ -3266,6 +3343,30 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
         if (item.opacity !== undefined) itemData.properties.opacity = item.opacity;
         if (item.rotation) itemData.properties.rotation = item.rotation;
         if (item.data?.content) itemData.properties.content = item.data.content;
+        if (item.visible === false) itemData.properties.visible = false;
+
+        // THE SECOND TIMELINE. A video/audio item carries its own clip window
+        // (media-time in/out) plus where that window sits on the project
+        // timeline. Without it a consumer sees "there is a video here" and has
+        // no idea which 5 seconds of it play, or when.
+        const p = entry.properties || {};
+        if (p.inPoint !== undefined || p.outPoint !== undefined || p.clipStartTime !== undefined) {
+          itemData.clip = {
+            clipStartTime: p.clipStartTime ?? 0,   // project-timeline start, s
+            inPoint: p.inPoint ?? 0,               // media-time in, s
+            outPoint: p.outPoint ?? null           // media-time out, s
+          };
+        }
+
+        // When this item is on screen at all, merged across keyframe clip
+        // window / loop / mask / relation windows / effects / media clip.
+        // null end = open-ended. Static items report null.
+        if (typeof app.activeWindowOf === 'function') {
+          try {
+            const w = app.activeWindowOf(entry.itemId);
+            if (w) itemData.activeWindow = w;
+          } catch (_) { /* non-fatal — an item without a window is just static */ }
+        }
 
         if (item.data?.isDecorative) {
           decorative.push(itemData);
@@ -3275,14 +3376,19 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
       }
     }
 
-    // Collect relations
-    if (app.getRelations) {
-      const activeRelations = app.getRelations();
-      for (const rel of activeRelations) {
+    // Collect relations — the EDGE LIST, which with the items above is the
+    // scene DAG.
+    //
+    // \`app.getRelations()\` takes an itemId; called bare it returns [], so the
+    // old code emitted an empty edge list for every scene. exportForSave() is
+    // the canonical whole-graph dump (the same one history persistence uses)
+    // and returns { fromId, toId, relation, params }.
+    if (app.relationRegistry && typeof app.relationRegistry.exportForSave === 'function') {
+      for (const rel of app.relationRegistry.exportForSave()) {
         relations.push({
-          sourceId: rel.sourceId,
-          targetId: rel.targetId,
-          type: rel.type,
+          sourceId: rel.fromId,
+          targetId: rel.toId ?? null,   // null = self-relation, not a missing edge
+          type: rel.relation,
           params: rel.params
         });
       }
@@ -3698,9 +3804,18 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
     }
     generateImportImage(input) {
         const { url, position, maxWidth, maxHeight, mask } = input;
-        const positionOpts = position ? `, position: { x: ${position.x}, y: ${position.y} }` : '';
-        const maxWidthOpt = maxWidth !== undefined ? `, maxWidth: ${maxWidth}` : '';
-        const maxHeightOpt = maxHeight !== undefined ? `, maxHeight: ${maxHeight}` : '';
+        // Each fragment used to be written with a LEADING comma, as if it followed
+        // an entry that no longer exists — so the first one opened the object with
+        // `{, position: …}` and the emitted code was a syntax error. Passing any
+        // option at all therefore failed 100% of the time, which is why imported
+        // images could never be positioned, sized or masked. Join instead, so the
+        // separators come from the number of options rather than from each one.
+        const optParts = [
+            position ? `position: { x: ${position.x}, y: ${position.y} }` : '',
+            maxWidth !== undefined ? `maxWidth: ${maxWidth}` : '',
+            maxHeight !== undefined ? `maxHeight: ${maxHeight}` : '',
+        ].filter(Boolean);
+        const optsLiteral = optParts.length ? `{ ${optParts.join(', ')} }` : '{}';
         return `
 // Import image from URL
 (async function() {
@@ -3709,9 +3824,20 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
   }
   try {
     const entry = await app.imageTools.uploadFromURL('${url}');
-    const opts = {${positionOpts}${maxWidthOpt}${maxHeightOpt} };
+    const opts = ${optsLiteral};
     const raster = await app.imageTools.placeImage(entry.id, Object.keys(opts).length > 0 ? opts : undefined);
-${mask ? `    app.imageTools.applyMask(raster, '${mask}');\n` : ''}    const itemId = raster.data?.itemId || raster.name || raster.id;
+${mask ? `    app.imageTools.applyMask(raster, '${mask}');\n` : ''}    // The REGISTRY id is \`data.id\`. \`data.itemId\` has never existed, so this
+    // fell through to \`raster.id\` — a Paper.js NUMBER — and the handle the tool
+    // returned could not be used as a relation endpoint or with modify/animate.
+    // Register the raster if placeImage somehow left it unregistered, so the
+    // caller always gets a usable id rather than a number that looks like one.
+    let itemId = raster.data?.id;
+    if (!itemId && typeof app.registerItem === 'function') {
+      itemId = app.registerItem(raster, 'image', { source: 'mcp-import' });
+    }
+    if (!itemId) {
+      return { error: 'Image placed but not registered — no usable item id. This is a bug; report the scene.' };
+    }
     return {
       success: true,
       itemId: itemId,
@@ -3990,8 +4116,210 @@ ${mask ? `    app.imageTools.applyMask(raster, '${mask}');\n` : ''}    const ite
                 return `(function() { return { error: 'Unknown selection action: ${input.action}' }; })();`;
         }
     }
+    /**
+     * @private Guard + call one PinePaper facade, uniformly.
+     *
+     * Every one of the 1.6.4 tools wraps a facade that a given editor build may
+     * not have yet — the server ships independently of the app. A missing method
+     * has to come back as a NAMED error, not a TypeError inside runGenerated:
+     * this repo has shipped three emitters that called methods which never
+     * existed (`imageTools.applyFilter`, `itemRegistry.entries`,
+     * `itemRegistry.remove`) and each reported success or an opaque throw.
+     */
+    _facadeCall(method, args, label) {
+        return `
+// ${label}
+(async function() {
+  if (typeof app.${method} !== 'function') {
+    return { success: false, error: 'app.${method}() unavailable — update PinePaper Studio to a build that has it.' };
+  }
+  const r = await app.${method}(${args});
+  // Facades report { ok } — normalise to { success } so every tool result reads
+  // the same way, while keeping the original payload intact.
+  if (r && typeof r === 'object' && 'ok' in r) {
+    return { success: r.ok !== false, ...r };
+  }
+  return { success: true, result: r };
+})();`.trim();
+    }
+    generateBrandKit(input) {
+        const opts = JSON.stringify({ ...(input.selectionOnly ? { selectionOnly: true } : {}) });
+        const method = input.action === 'plan' ? 'planBrandKit' : 'applyBrandKit';
+        return this._facadeCall(method, `${JSON.stringify(input.kit)}, ${opts}`, `Brand kit: ${input.action}`);
+    }
+    generateComponent(input) {
+        const ids = JSON.stringify(input.itemIds || []);
+        switch (input.action) {
+            case 'define':
+                // defineComponent takes ITEMS, not ids — resolve through the registry
+                // here so the tool can speak the id space every other tool speaks.
+                return `
+// Component: define
+(function() {
+  if (typeof app.defineComponent !== 'function') {
+    return { success: false, error: 'app.defineComponent() unavailable — update PinePaper Studio.' };
+  }
+  const items = ${ids}.map((id) => app.itemRegistry.get(id)?.item).filter(Boolean);
+  if (!items.length) return { success: false, error: 'no live items for the given ids' };
+  const r = app.defineComponent(items, ${JSON.stringify({ name: input.name })});
+  return { success: r.ok !== false, ...r };
+})();`.trim();
+            case 'list':
+                return this._facadeCall('listComponents', '', 'Component: list');
+            case 'instantiate':
+                return this._facadeCall('instantiateComponent', `${JSON.stringify(input.componentId || '')}, ${JSON.stringify({
+                    ...(input.position ? { position: input.position } : {}),
+                    ...(input.overrides ? { overrides: input.overrides } : {}),
+                })}`, 'Component: instantiate');
+            case 'set_override':
+                return this._facadeCall('setComponentOverride', `${JSON.stringify(input.instanceId || '')}, ${JSON.stringify(input.componentKey || '')}, ${JSON.stringify(input.prop || '')}, ${JSON.stringify(input.value ?? null)}`, 'Component: set override');
+            case 'sync':
+                return this._facadeCall('syncComponent', JSON.stringify(input.componentId || ''), 'Component: sync');
+            case 'update_from_instance':
+                return this._facadeCall('updateComponentFromInstance', JSON.stringify(input.instanceId || ''), 'Component: update from instance');
+            case 'detach':
+                return this._facadeCall('detachComponentInstance', JSON.stringify(input.instanceId || ''), 'Component: detach');
+        }
+    }
+    generateArtboard(input) {
+        switch (input.action) {
+            case 'list_presets':
+                return this._facadeCall('listArtboardPresets', '', 'Artboard: list presets');
+            case 'set': {
+                const target = input.preset
+                    ? JSON.stringify(input.preset)
+                    : JSON.stringify({ width: input.width, height: input.height });
+                return this._facadeCall('setArtboard', target, 'Artboard: set');
+            }
+            case 'set_constraints':
+                return this._facadeCall('setItemConstraints', `${JSON.stringify(input.itemId || '')}, ${JSON.stringify({
+                    ...(input.horizontal ? { horizontal: input.horizontal } : {}),
+                    ...(input.vertical ? { vertical: input.vertical } : {}),
+                })}`, 'Artboard: set constraints');
+        }
+    }
+    generateComment(input) {
+        switch (input.action) {
+            case 'add':
+                return this._facadeCall('addComment', JSON.stringify({
+                    text: input.text,
+                    ...(input.author ? { author: input.author } : {}),
+                    ...(input.itemId ? { itemId: input.itemId } : {}),
+                    ...(input.x !== undefined ? { x: input.x } : {}),
+                    ...(input.y !== undefined ? { y: input.y } : {}),
+                    ...(input.time !== undefined ? { time: input.time } : {}),
+                }), 'Comment: add');
+            case 'list':
+                return this._facadeCall('listComments', JSON.stringify({
+                    ...(input.time !== undefined ? { time: input.time } : {}),
+                    ...(input.includeResolved ? { includeResolved: true } : {}),
+                }), 'Comment: list');
+            case 'resolve':
+                return this._facadeCall('resolveComment', `${JSON.stringify(input.id || '')}, ${input.resolved === false ? 'false' : 'true'}`, 'Comment: resolve');
+            case 'delete':
+                return this._facadeCall('deleteComment', JSON.stringify(input.id || ''), 'Comment: delete');
+        }
+    }
+    generateProvenance(input) {
+        const id = JSON.stringify(input.itemId);
+        switch (input.action) {
+            case 'get': return this._facadeCall('getItemProvenance', id, 'Provenance: get');
+            case 'lineage': return this._facadeCall('getLineage', id, 'Provenance: lineage');
+            case 'dependents': return this._facadeCall('getDependents', id, 'Provenance: dependents');
+            case 'record':
+                return this._facadeCall('recordLineage', `${id}, ${JSON.stringify(input.kind || 'derived')}, ${JSON.stringify(input.sourceRef || '')}, ${JSON.stringify(input.meta || {})}`, 'Provenance: record lineage');
+        }
+    }
+    generateCompose(input) {
+        switch (input.action) {
+            case 'list_patterns':
+                return this._facadeCall('listCollagePatterns', '', 'Compose: list patterns');
+            case 'list_treatments':
+                return this._facadeCall('listCameraTreatments', '', 'Compose: list treatments');
+            case 'list_reveals':
+                return this._facadeCall('listReveals', '', 'Compose: list reveals');
+            case 'list_styles':
+                return this._facadeCall('listStyles', '', 'Compose: list styles');
+            case 'set_treatment':
+                return this._facadeCall('setCollageTreatment', `${JSON.stringify(input.rootId || '')}, ${JSON.stringify(input.treatment || '')}, ${JSON.stringify({ ...(input.loop ? { loop: true } : {}) })}`, 'Compose: set treatment');
+            case 'apply':
+            default:
+                // Forward the WHOLE surface. The first version forwarded only
+                // treatment/camera/loop/craft — the temporal (reveal), style, text,
+                // vector and audio halves of composeCollage were unreachable through
+                // MCP, so agents converged on the four static patterns the description
+                // happened to name. A capability gap reads as model bias from outside.
+                return this._facadeCall('composeCollage', `${JSON.stringify(input.pattern || '')}, ${JSON.stringify(input.itemIds || [])}, ${JSON.stringify({
+                    ...(input.treatment ? { treatment: input.treatment } : {}),
+                    ...(input.applyCamera === false ? { applyCamera: false } : {}),
+                    ...(input.loop ? { loop: true } : {}),
+                    ...(input.craft ? { craft: input.craft } : {}),
+                    ...(input.reveal !== undefined ? { reveal: input.reveal } : {}),
+                    ...(input.revealOptions ? { revealOptions: input.revealOptions } : {}),
+                    ...(input.style ? { style: input.style } : {}),
+                    ...(input.text ? { text: input.text } : {}),
+                    ...(input.assets ? { assets: input.assets } : {}),
+                    ...(input.audio ? { audio: input.audio } : {}),
+                    ...(input.grid ? { grid: true } : {}),
+                })}`, 'Compose: apply pattern');
+        }
+    }
+    generateAudioBeats(input) {
+        if (input.action === 'analyze') {
+            return this._facadeCall('analyzeAudio', `${JSON.stringify(input.source || '')}, ${JSON.stringify({
+                ...(input.sensitivity !== undefined ? { sensitivity: input.sensitivity } : {}),
+                ...(input.minGap !== undefined ? { minGap: input.minGap } : {}),
+            })}`, 'Audio: analyze beats');
+        }
+        return this._facadeCall('animateToBeat', `${JSON.stringify(input.itemId || '')}, ${JSON.stringify({
+            ...(input.source ? { source: input.source } : {}),
+            ...(input.beats ? { beats: input.beats } : {}),
+            ...(input.grid ? { grid: true } : {}),
+            ...(input.property ? { property: input.property } : {}),
+            ...(input.base !== undefined ? { base: input.base } : {}),
+            ...(input.accent !== undefined ? { accent: input.accent } : {}),
+            ...(input.decay !== undefined ? { decay: input.decay } : {}),
+            ...(input.sensitivity !== undefined ? { sensitivity: input.sensitivity } : {}),
+        })}`, 'Audio: animate to beat');
+    }
+    generateTemplateParams(input) {
+        if (input.action === 'get') {
+            return this._facadeCall('getTemplateParams', JSON.stringify(input.templateId), 'Template params: get');
+        }
+        return this._facadeCall('applyTemplateWithParams', `${JSON.stringify(input.templateId)}, ${JSON.stringify(input.params || {})}`, 'Template params: apply');
+    }
+    generateSceneDiff(input) {
+        if (input.action === 'version') {
+            return this._facadeCall('diffAgainstVersion', JSON.stringify(input.versionId || ''), 'Scene diff: vs version');
+        }
+        return this._facadeCall('diffHistoryStates', `${input.indexA ?? 0}, ${input.indexB ?? 0}`, 'Scene diff: history');
+    }
     generateTransform(input) {
         switch (input.action) {
+            case 'fit': {
+                const mode = input.mode || 'contain';
+                return `
+// Fit item to the export frame (${mode})
+(function() {
+  // Route through the agent facade, not app.fitToFrame directly: an agent that
+  // just called upload_video holds a MEDIA id (vraster_…), which is a different
+  // id space from canvas item ids. PinePaperAgent.fitToFrame resolves either.
+  const A = (typeof window !== 'undefined') && window.PinePaperAgent;
+  if (A && typeof A.fitToFrame === 'function') {
+    const ok = A.fitToFrame(${JSON.stringify(input.itemId || '')}, '${mode}');
+    return ok
+      ? { success: true, action: 'fit', itemId: '${input.itemId}', mode: '${mode}' }
+      : { success: false, error: 'Item not found or not fittable: ${input.itemId}' };
+  }
+  if (typeof app.fitToFrame !== 'function') {
+    return { success: false, error: 'fitToFrame unavailable — update FxTool' };
+  }
+  const ok = app.fitToFrame(${JSON.stringify(input.itemId || '')}, '${mode}');
+  return ok
+    ? { success: true, action: 'fit', itemId: '${input.itemId}', mode: '${mode}' }
+    : { success: false, error: 'Item not found: ${input.itemId}' };
+})();`.trim();
+            }
             case 'nudge': {
                 const dx = input.dx ?? 0;
                 const dy = input.dy ?? 0;
@@ -4123,6 +4451,32 @@ ${resolve}
 })();`.trim();
             default:
                 return `(function() { return { error: 'Unknown image_filter action: ${input.action}' }; })();`;
+            case 'analyze_palette':
+                return `
+// Analyze palette: the dominant colours, largest area first (GPU path)
+(async function() {
+  if (typeof app.analyzePalette !== 'function') { return { success: false, error: 'app.analyzePalette unavailable — update FxTool to a palette-capable build' }; }
+  try {
+    const r = await app.analyzePalette(${JSON.stringify(input.itemId)}, ${JSON.stringify({ ...(input.maxSwatches !== undefined ? { maxSwatches: input.maxSwatches } : {}) })});
+    // swatches: [{hex, share, …}] largest-first — feed hex values straight into
+    // recolor_palette mapping or the paletteMap filter's swatches[].
+    return { success: true, width: r.width, height: r.height, opaquePixels: r.opaquePixels, swatches: r.swatches };
+  } catch (e) {
+    return { success: false, error: e && e.message ? e.message : String(e) };
+  }
+})();`.trim();
+            case 'recolor_palette':
+                return `
+// Recolor palette: swap colours, keep the shading (GPU path)
+(async function() {
+  if (typeof app.recolorPalette !== 'function') { return { success: false, error: 'app.recolorPalette unavailable — update FxTool to a palette-capable build' }; }
+  try {
+    await app.recolorPalette(${JSON.stringify(input.itemId)}, ${JSON.stringify(input.mapping)}, ${JSON.stringify({ ...(input.amount !== undefined ? { amount: input.amount } : {}), ...(input.preserveShading !== undefined ? { preserveShading: input.preserveShading } : {}) })});
+    return { success: true, action: 'recolor_palette', itemId: ${JSON.stringify(input.itemId)} };
+  } catch (e) {
+    return { success: false, error: e && e.message ? e.message : String(e) };
+  }
+})();`.trim();
         }
     }
     generateLasso(input) {
@@ -5228,6 +5582,338 @@ ${guard}
   if (typeof A.setMediaClip !== 'function') { return { success: false, error: 'setMediaClip unavailable — update FxTool' }; }
   const ok = A.setMediaClip(${JSON.stringify(input.id)}, ${input.inPoint}, ${input.outPoint});
   return { success: ok, action: 'set_clip', id: ${JSON.stringify(input.id)}, inPoint: ${input.inPoint}, outPoint: ${input.outPoint} };
+})();`.trim();
+            // ── Video-editing actions (v1.6.4) — these live on `app` (PinePaper
+            // facades), not the agent media API, so they carry their own guards.
+            // The facades snapshot history themselves; no saveState here.
+            case 'set_time_remap': {
+                const S = (v) => JSON.stringify(v);
+                return `
+// Remap a clip's time — speed ramps, freeze frames, reverse (null clears)
+(function() {
+  if (typeof app.setTimeRemap !== 'function') { return { success: false, error: 'app.setTimeRemap unavailable — update FxTool to a time-remap-capable build' }; }
+  const r = app.setTimeRemap(${S(input.id)}, ${S(input.remapTrack ?? null)});
+  return r && r.ok ? { success: true, action: 'set_time_remap', points: r.points } : { success: false, error: (r && r.error) || 'remap failed' };
+})();`.trim();
+            }
+            case 'speed_ramp': {
+                const S = (v) => JSON.stringify(v);
+                return `
+// Speed ramp: consecutive {duration, speed} segments compiled to a remap curve
+(function() {
+  if (typeof app.speedRamp !== 'function') { return { success: false, error: 'app.speedRamp unavailable — update FxTool to a time-remap-capable build' }; }
+  const r = app.speedRamp(${S(input.id)}, ${S(input.segments)});
+  return r && r.ok ? { success: true, action: 'speed_ramp', points: r.points } : { success: false, error: (r && r.error) || 'speed ramp failed' };
+})();`.trim();
+            }
+            case 'match_cut': {
+                const S = (v) => JSON.stringify(v);
+                const opts = S({
+                    ...(input.subject !== undefined ? { subject: input.subject } : {}),
+                    ...(input.label !== undefined ? { label: input.label } : {}),
+                    ...(input.at !== undefined ? { at: input.at } : {}),
+                    ...(input.settle !== undefined ? { settle: input.settle } : {}),
+                    ...(input.fade !== undefined ? { fade: input.fade } : {}),
+                    ...(input.consent !== undefined ? { consent: input.consent } : {}),
+                });
+                return `
+// Match cut: align the SUBJECT across the cut (on-device detection)
+(async function() {
+  if (typeof app.matchCut !== 'function') { return { success: false, error: 'app.matchCut unavailable — update FxTool to a match-cut-capable build' }; }
+  const r = await app.matchCut(${S(input.fromItemId)}, ${S(input.toItemId)}, ${opts});
+  if (r && r.needsConsent) { return { success: false, needsConsent: true, cost: r.cost, error: 'Detection model download needs consent — re-call with consent: true' }; }
+  if (!r || !r.ok) { return { success: false, error: (r && r.error) || 'match cut failed' }; }
+  return { success: true, action: 'match_cut', aspectMismatch: r.aspectMismatch || false };
+})();`.trim();
+            }
+            case 'apply_track_matte': {
+                const S = (v) => JSON.stringify(v);
+                const opts = S({
+                    ...(input.channel !== undefined ? { channel: input.channel } : {}),
+                    ...(input.invert !== undefined ? { invert: input.invert } : {}),
+                    ...(input.strength !== undefined ? { strength: input.strength } : {}),
+                    ...(input.hideMatte !== undefined ? { hideMatte: input.hideMatte } : {}),
+                    ...(input.live !== undefined ? { live: input.live } : {}),
+                });
+                return `
+// Track matte: the matte item's ${input.channel || 'luma'} drives the target's alpha${input.live ? ' (LIVE — re-cuts as the matte animates)' : ''}
+(async function() {
+  if (typeof app.applyTrackMatte !== 'function') { return { success: false, error: 'app.applyTrackMatte unavailable — update FxTool to a track-matte-capable build' }; }
+  try {
+    await app.applyTrackMatte(${S(input.id)}, ${S(input.matteItemId)}, ${opts});
+    return { success: true, action: 'apply_track_matte', id: ${S(input.id)}, matte: ${S(input.matteItemId)}, live: ${S(!!input.live)} };
+  } catch (e) {
+    // The facade throws on a missing raster/matte rather than returning {ok:false}.
+    return { success: false, error: e && e.message ? e.message : String(e) };
+  }
+})();`.trim();
+            }
+            case 'stop_live_matte': {
+                const S = (v) => JSON.stringify(v);
+                return `
+// Stop a live matte, leaving the last cut in place
+(function() {
+  if (typeof app.stopLiveMatte !== 'function') { return { success: false, error: 'app.stopLiveMatte unavailable — update FxTool' }; }
+  const r = app.stopLiveMatte(${S(input.id)});
+  return r && r.ok ? { success: true, action: 'stop_live_matte' } : { success: false, error: (r && r.error) || 'no live matte on that item' };
+})();`.trim();
+            }
+        }
+    }
+    /**
+     * pinepaper_text_style — display styles + variable-font axes.
+     * All three facades return their own {ok, …} envelopes; forwarded as-is.
+     */
+    generateTextStyle(input) {
+        const S = (v) => JSON.stringify(v);
+        switch (input.action) {
+            case 'apply_style': {
+                const opts = S({
+                    ...(input.palette !== undefined ? { palette: input.palette } : {}),
+                    ...(input.variant !== undefined ? { variant: input.variant } : {}),
+                    ...(input.content !== undefined ? { content: input.content } : {}),
+                    ...(input.fontFamily !== undefined ? { fontFamily: input.fontFamily } : {}),
+                    ...(input.fontSize !== undefined ? { fontSize: input.fontSize } : {}),
+                });
+                return `
+// Display text style: ${input.styleKey} — stacked-layer title, id adopted from the text
+(function() {
+  if (typeof app.applyTextStyle !== 'function') { return { success: false, error: 'app.applyTextStyle unavailable — update FxTool to a text-styles build' }; }
+  const r = app.applyTextStyle(${S(input.itemId)}, ${S(input.styleKey)}, ${opts});
+  if (!r || !r.ok) { return { success: false, error: (r && r.error) || 'style failed' }; }
+  // The styled group ADOPTS the text item's registry id — r.id is the SAME id
+  // the caller passed, so their handle keeps working. Say so in the result.
+  return { success: true, action: 'apply_style', id: r.id, style: r.style, layers: r.layers, palette: r.palette, bounds: r.bounds };
+})();`.trim();
+            }
+            case 'set_font_axes': {
+                return `
+// Variable-font axes (standard trio: weight/width/slant — Canvas 2D has no custom axes)
+(function() {
+  if (typeof app.setFontAxes !== 'function') { return { success: false, error: 'app.setFontAxes unavailable — update FxTool to a variable-font build' }; }
+  const r = app.setFontAxes(${S(input.itemId)}, ${S(input.axes)});
+  if (!r || !r.ok) { return { success: false, error: (r && r.error) || 'axes failed' }; }
+  // rejected is the interesting half: an axis silently ignored is the failure
+  // mode this surface exists to prevent.
+  return { success: true, action: 'set_font_axes', applied: r.applied, rejected: r.rejected || [] };
+})();`.trim();
+            }
+            case 'list_styles': {
+                return `
+// Text styles + palettes + font axes — the picker surface
+(function() {
+  if (typeof app.listTextStyles !== 'function') { return { success: false, error: 'app.listTextStyles unavailable — update FxTool to a text-styles build' }; }
+  return {
+    success: true,
+    styles: app.listTextStyles(),
+    palettes: typeof app.listTextPalettes === 'function' ? app.listTextPalettes() : [],
+    fontAxes: typeof app.listFontAxes === 'function' ? app.listFontAxes() : null,
+  };
+})();`.trim();
+            }
+        }
+    }
+    /**
+     * Shatter a raster into a grid of tiles. The group INHERITS the original's
+     * registry id (relations/handles keep pointing at the thing in its place),
+     * and the result is deliberately inert until something animates the pieces.
+     */
+    generateShatterImage(input) {
+        const S = (v) => JSON.stringify(v);
+        const opts = S({
+            ...(input.pieces !== undefined ? { pieces: input.pieces } : {}),
+            ...(input.rows !== undefined ? { rows: input.rows } : {}),
+            ...(input.cols !== undefined ? { cols: input.cols } : {}),
+            ...(input.keepSource !== undefined ? { keepSource: input.keepSource } : {}),
+        });
+        return `
+// Shatter ${input.itemId} into tiles (inert until animated — that is the point)
+(function() {
+  if (typeof app.shatterImage !== 'function') { return { success: false, error: 'app.shatterImage unavailable — update FxTool to a shatter-capable build' }; }
+  const r = app.shatterImage(${S(input.itemId)}, ${opts});
+  if (!r || !r.ok) { return { success: false, error: (r && r.error) || 'shatter failed' }; }
+  // groupId === the original item's id (adopted). tiles/rows/cols tell the
+  // caller what grid they actually got — 100 pieces of a 3:2 photo is 12x8=96.
+  return { success: true, groupId: r.groupId, tiles: r.tiles, rows: r.rows, cols: r.cols };
+})();`.trim();
+    }
+    /**
+     * Import a decomposed character (layer manifest + per-layer images) as a
+     * role-bound Group. The facade is async and does its own heavy-module
+     * loading (the cold-boot rigging-rules trap is handled inside it).
+     */
+    generateImportLayeredCharacter(input) {
+        const S = (v) => JSON.stringify(v);
+        const opts = S({
+            ...(input.position !== undefined ? { position: input.position } : {}),
+            ...(input.scale !== undefined ? { scale: input.scale } : {}),
+            ...(input.name !== undefined ? { name: input.name } : {}),
+        });
+        return `
+// Import a layered character (decomposer output → role-bound parts; blink works out of the box)
+(async function() {
+  if (typeof app.importLayeredCharacter !== 'function') { return { success: false, error: 'app.importLayeredCharacter unavailable — update FxTool to a layered-character build' }; }
+  // The importer's contract is a Map (it calls images.get) — the wire format is
+  // a plain object, so rebuild the Map here.
+  const bundle = { info: ${S(input.info)}, images: new Map(Object.entries(${S(input.images)})) };
+  const r = await app.importLayeredCharacter(bundle, ${opts});
+  if (!r || !r.groupId) { return { success: false, error: (r && r.error) || 'layered character import failed' }; }
+  // roles maps part roles → item ids; zero roles wired means the character
+  // renders but will NOT animate — surface the count so that cannot hide.
+  return { success: true, groupId: r.groupId, parts: (r.parts || []).length, roles: r.roles || {}, rolesWired: Object.keys(r.roles || {}).length, warnings: r.warnings || [] };
+})();`.trim();
+    }
+    /**
+     * pinepaper_game — pathfinding + tilemaps via the PinePaper facades.
+     * Both are pure data ops; the interesting glue is in the doc: paths feed
+     * moves_along_path, collisionRects feed pinepaper_physics.
+     */
+    generateGame(input) {
+        const S = (v) => JSON.stringify(v);
+        switch (input.action) {
+            case 'pathfind': {
+                const opts = S({ ...(input.diagonal !== undefined ? { diagonal: input.diagonal } : {}) });
+                return `
+// A* pathfind — waypoints for moves_along_path
+(async function() {
+  if (typeof app.findPath !== 'function') { return { success: false, error: 'app.findPath unavailable — update FxTool to a games-capable build' }; }
+  const r = await app.findPath(${S(input.grid)}, ${S(input.start)}, ${S(input.goal)}, ${opts});
+  if (!r || !r.ok) { return { success: false, error: (r && r.error) || 'pathfind failed' }; }
+  // path is world-space [{x,y}] — feed it DIRECTLY to pinepaper_add_relation
+  // moves_along_path params.path, or to a keyframe track.
+  return { success: true, path: r.path, waypoints: r.path.length };
+})();`.trim();
+            }
+            case 'create_tilemap': {
+                const spec = S({
+                    cols: input.cols, rows: input.rows,
+                    ...(input.tileSize !== undefined ? { tileSize: input.tileSize } : {}),
+                    ...(input.origin !== undefined ? { origin: input.origin } : {}),
+                    ...(input.tileset !== undefined ? { tileset: input.tileset } : {}),
+                    ...(input.fills !== undefined ? { fills: input.fills } : {}),
+                });
+                return `
+// Tilemap: board data + pathfinding grid + merged collision rects
+(async function() {
+  if (typeof app.createTilemap !== 'function') { return { success: false, error: 'app.createTilemap unavailable — update FxTool to a games-capable build' }; }
+  const r = await app.createTilemap(${spec});
+  if (!r || !r.ok) { return { success: false, error: (r && r.error) || 'tilemap failed' }; }
+  // map: persist it (item.data / project document) — it is DATA, not items;
+  // grid: pass straight back into pathfind; collisionRects: pinepaper_physics
+  // bodies (greedy-merged, so a 60x1 wall is ONE rect, not 60).
+  return { success: true, map: r.map, grid: r.grid, collisionRects: r.collisionRects, rectCount: r.collisionRects.length };
+})();`.trim();
+            }
+        }
+    }
+    /**
+     * pinepaper_world3d — every action rides the PinePaper world facades. The
+     * world is lazily created by createWorld3D; every other action guards on the
+     * facade AND on a world existing, with the create hint in the error.
+     */
+    generateWorld3D(input) {
+        const S = (v) => JSON.stringify(v);
+        const needWorld = `  if (!app._world3d) { return { success: false, error: "no 3D world — call pinepaper_world3d create first" }; }`;
+        switch (input.action) {
+            case 'create': {
+                const opts = S({ ...(input.character !== undefined ? { character: input.character } : {}) });
+                return `
+// World3D: create — terrain, sky, shadows, walkable character, under the Paper canvas
+(async function() {
+  if (typeof app.createWorld3D !== 'function') { return { success: false, error: 'app.createWorld3D unavailable — update FxTool to a world3d-capable build' }; }
+  await app.createWorld3D(${S(input.spec ?? 'forest')}, ${opts});
+  // describe() is the world's own parameter schema — return the preset list +
+  // top-level keys so the agent knows what configure can touch, without the
+  // full multi-KB schema on every create.
+  const d = typeof app.describeWorld3D === 'function' ? await app.describeWorld3D() : null;
+  return { success: true, action: 'create', spec: ${S(input.spec ?? 'forest')}, configurableKeys: d ? Object.keys(d.params || d) : [] };
+})();`.trim();
+            }
+            case 'describe':
+                return `
+// World3D: the engine's own parameter schema — types, ranges, descriptions
+(async function() {
+  if (typeof app.describeWorld3D !== 'function') { return { success: false, error: 'app.describeWorld3D unavailable — update FxTool' }; }
+  return { success: true, schema: await app.describeWorld3D() };
+})();`.trim();
+            case 'configure':
+                return `
+// World3D: live configure (deep-merged, schema-validated)
+(function() {
+  if (typeof app.configureWorld3D !== 'function') { return { success: false, error: 'app.configureWorld3D unavailable — update FxTool' }; }
+${needWorld}
+  const r = app.configureWorld3D(${S(input.patch)});
+  // The validator names the right key on a wrong one — forward it verbatim.
+  return r && r.ok ? { success: true, action: 'configure' } : { success: false, error: (r && r.error) || 'configure failed' };
+})();`.trim();
+            case 'add_actor': {
+                const actor = S({
+                    ...(input.actorId !== undefined ? { id: input.actorId } : {}),
+                    ...(input.x !== undefined ? { x: input.x } : {}),
+                    ...(input.z !== undefined ? { z: input.z } : {}),
+                    ...(input.height !== undefined ? { height: input.height } : {}),
+                    ...(input.sprite !== undefined ? { sprite: input.sprite } : {}),
+                    ...(input.live !== undefined ? { live: input.live } : {}),
+                });
+                return `
+// World3D: put an actor on the stage${input.live ? ' (live sprite — a rigged character PERFORMS, not a photograph of itself)' : ''}
+(function() {
+  if (typeof app.addWorldActor !== 'function') { return { success: false, error: 'app.addWorldActor unavailable — update FxTool' }; }
+${needWorld}
+  const id = app.addWorldActor(${actor});
+  return id ? { success: true, actorId: id } : { success: false, error: 'actor not added — is the sprite id a canvas item?' };
+})();`.trim();
+            }
+            case 'remove_actor':
+                return `
+// World3D: remove actor
+(function() {
+${needWorld}
+  return { success: !!app.removeWorldActor(${S(input.actorId)}), actorId: ${S(input.actorId)} };
+})();`.trim();
+            case 'list_actors':
+                return `
+// World3D: the addressable stage
+(function() {
+${needWorld}
+  return { success: true, actors: app.listWorldActors() };
+})();`.trim();
+            case 'set_actor_pose':
+                return `
+// World3D: pose an actor — the setter a timeline, sequencer or agent drives
+(function() {
+${needWorld}
+  return { success: !!app.setWorldActorPose(${S(input.actorId)}, ${S(input.pose)}), actorId: ${S(input.actorId)} };
+})();`.trim();
+            case 'set_camera':
+                return `
+// World3D: direct the camera (follow | fixed | orbit)
+(function() {
+${needWorld}
+  const r = app.setWorldCamera(${S(input.camera)});
+  return r === false ? { success: false, error: 'camera config rejected' } : { success: true };
+})();`.trim();
+            case 'add_object':
+                return `
+// World3D: place an object (y defaults to sitting on the terrain)
+(function() {
+${needWorld}
+  const id = app.addWorldObject(${S(input.object)});
+  return id ? { success: true, objectId: id } : { success: false, error: 'object not added' };
+})();`.trim();
+            case 'remove_object':
+                return `
+// World3D: remove object
+(function() {
+${needWorld}
+  return { success: !!app.removeWorldObject(${S(input.objectId)}), objectId: ${S(input.objectId)} };
+})();`.trim();
+            case 'remove_world':
+                return `
+// World3D: tear the world down — Paper's canvas is untouched (it was always its own layer)
+(function() {
+  if (typeof app.removeWorld3D !== 'function') { return { success: false, error: 'app.removeWorld3D unavailable — update FxTool' }; }
+  return { success: !!app.removeWorld3D() };
 })();`.trim();
         }
     }
@@ -5345,6 +6031,61 @@ ${guard}
                 return wrap('Rigging: save shape key', `  const shapeKeyId = R.saveShapeKey(${S(input.skeletonId)}, ${S(input.name ?? null)});
   if (app.historyManager) app.historyManager.saveState();
   return { success: !!shapeKeyId, action: 'save_shape_key', shapeKeyId: shapeKeyId };`);
+            // ── Mocap / rig import — these live on `app` (PinePaper facades), not
+            // riggingSystem, and they are async, so they get their own async IIFE
+            // instead of the sync `wrap` above. Each returns the facade's own result
+            // object: it already carries {ok, error, warnings…} and inventing a
+            // second envelope here would just hide the interesting fields.
+            case 'import_bvh': {
+                const opts = S({
+                    ...(input.view !== undefined ? { view: input.view } : {}),
+                    ...(input.fps !== undefined ? { fps: input.fps } : {}),
+                    ...(input.height !== undefined ? { height: input.height } : {}),
+                    ...(input.rootPosition !== undefined ? { position: input.rootPosition } : {}),
+                    ...(input.name !== undefined ? { name: input.name } : {}),
+                });
+                return `
+// Rigging: import BVH mocap as a new rig (stick figure included)
+(async function() {
+  if (typeof app.importBVH !== 'function') { return { success: false, error: 'app.importBVH unavailable — update FxTool to a BVH-capable build' }; }
+  const r = await app.importBVH(${S(input.bvhText ?? '')}, ${opts});
+  if (!r || !r.ok) { return { success: false, error: (r && r.error) || 'BVH import failed' }; }
+  // (facade snapshots history itself — a second saveState here would cost an extra undo step)
+  return { success: true, action: 'import_bvh', skeletonId: r.skeletonId, poses: r.poses, duration: r.duration, warnings: r.warnings || [] };
+})();`.trim();
+            }
+            case 'retarget_bvh': {
+                const opts = S({
+                    ...(input.fps !== undefined ? { fps: input.fps } : {}),
+                    ...(input.name !== undefined ? { name: input.name } : {}),
+                });
+                return `
+// Rigging: retarget a BVH clip onto an EXISTING rig (matched by bone name)
+(async function() {
+  if (typeof app.retargetBVH !== 'function') { return { success: false, error: 'app.retargetBVH unavailable — update FxTool to a BVH-capable build' }; }
+  const r = await app.retargetBVH(${S(input.bvhText ?? '')}, ${S(input.skeletonId)}, ${opts});
+  if (!r || !r.ok) { return { success: false, error: (r && r.error) || 'BVH retarget failed' }; }
+  // (facade snapshots history itself — a second saveState here would cost an extra undo step)
+  // matched/unmatched matter: a retarget that matched 2 of 15 bones "succeeded"
+  // and looks broken — the caller needs the numbers to know which happened.
+  return { success: true, action: 'retarget_bvh', skeletonId: r.skeletonId, matched: r.matched, unmatchedSource: r.unmatchedSource, unmatchedTarget: r.unmatchedTarget, poses: r.poses, duration: r.duration, warnings: r.warnings || [] };
+})();`.trim();
+            }
+            case 'import_spine': {
+                const opts = S({
+                    ...(input.rootPosition !== undefined ? { position: input.rootPosition } : {}),
+                    ...(input.name !== undefined ? { name: input.name } : {}),
+                });
+                return `
+// Rigging: import a Spine JSON export (bones, poses, attachment placeholders)
+(async function() {
+  if (typeof app.importSpine !== 'function') { return { success: false, error: 'app.importSpine unavailable — update FxTool to a Spine-capable build' }; }
+  const r = await app.importSpine(${S(input.spineJson ?? '')}, ${opts});
+  if (!r || !r.ok) { return { success: false, error: (r && r.error) || 'Spine import failed' }; }
+  // (facade snapshots history itself — a second saveState here would cost an extra undo step)
+  return { success: true, action: 'import_spine', skeletonId: r.skeletonId, bones: r.bones, placeholders: r.placeholders, animations: (r.animations || []).map(function(a) { return a.name; }), warnings: r.warnings || [] };
+})();`.trim();
+            }
         }
     }
     /**