@pinepaper.studio/mcp-server 1.6.6 → 1.6.7

package/dist/types/code-generator.js

@@ -5,7 +5,7 @@
  * This code is designed to run in the browser context where window.PinePaper is available.
  */
 import { generateP5DrawCode } from '../tools/p5-compat/p5-helpers.js';
-import { CreateItemInputSchema, ModifyItemInputSchema, AddRelationInputSchema, AnimateItemInputSchema, KeyframeAnimateInputSchema, ExecuteGeneratorInputSchema, ApplyEffectInputSchema, SetBackgroundColorInputSchema, SetCanvasSizeInputSchema, CreateGlossySphereInputSchema, CreateDiagonalStripesInputSchema, BatchCreateInputSchema, BatchModifyInputSchema, CreateGridInputSchema, CreateSceneInputSchema, 
+import { CreateItemInputSchema, ImportMotionCaptureInputSchema, ModifyItemInputSchema, AddRelationInputSchema, AnimateItemInputSchema, KeyframeAnimateInputSchema, ExecuteGeneratorInputSchema, ApplyEffectInputSchema, SetBackgroundColorInputSchema, SetCanvasSizeInputSchema, CreateGlossySphereInputSchema, CreateDiagonalStripesInputSchema, BatchCreateInputSchema, BatchModifyInputSchema, CreateGridInputSchema, CreateSceneInputSchema, 
 // Diagram types
 CreateDiagramShapeInputSchema, ConnectInputSchema, ConnectPortsInputSchema, AddPortsInputSchema, AutoLayoutInputSchema, GetDiagramShapesInputSchema, UpdateConnectorInputSchema, RemoveConnectorInputSchema, DiagramModeInputSchema, 
 // Agent flow mode types
@@ -21,7 +21,7 @@ GlobeEnableInputSchema, GlobeRotateToInputSchema, GlobeSpinInputSchema, WorldTou
 // Custom relation/code types
 RegisterCustomRelationInputSchema, ExecuteCustomCodeInputSchema, 
 // Mask types
-ApplyAnimatedMaskInputSchema, ApplyCustomMaskInputSchema, RemoveMaskInputSchema, } from './schemas.js';
+ApplyAnimatedMaskInputSchema, ApplyCustomMaskInputSchema, RemoveMaskInputSchema, SceneGraphInputSchema, SequenceInputSchema, StaggerInputSchema, FlipInputSchema, QueryCapabilitiesInputSchema, } from './schemas.js';
 import { OntologyCompiler } from '../ontology/ontology-compiler.js';
 // =============================================================================
 // HELPER FUNCTIONS
@@ -97,6 +97,36 @@ function generateCreateItemCode(itemType, position, properties) {
     if (strokeColor && !isGradient(strokeColor)) {
         params.strokeColor = strokeColor;
     }
+    // RENDER-TIME SURFACES DEGRADE, THEY DO NOT FAIL.
+    //
+    // `shader` and `field` are drawn per pixel by the cloud rasterizer from the
+    // scene document; the browser engine has no such item type and answers
+    // `create('shader')` with "unknown type — nothing was created". Emitting that
+    // call would hand every local user a silent hole where their backdrop was.
+    //
+    // So locally they become a plate: a rectangle carrying the same id, position,
+    // size and colour, which keeps the composition readable and the item
+    // addressable by every later call. The scene document still says `shader`, so
+    // a cloud render draws the real surface. The divergence is declared here
+    // rather than discovered in a frame.
+    if (itemType === 'shader' || itemType === 'field') {
+        const plate = {
+            x: position.x,
+            y: position.y,
+            width: params.width ?? 200,
+            height: params.height ?? 200,
+            fillColor: params.fillColor ?? params.fill ?? '#334155',
+        };
+        if (params.id)
+            plate.id = params.id;
+        if (params.opacity != null)
+            plate.opacity = params.opacity;
+        return `
+// ${itemType} — a render-time surface. Drawn per pixel by the cloud renderer;
+// stood in for locally by a flat plate so the layout still reads.
+const item = app.create('rectangle', ${JSON.stringify(plate, null, 2)});
+if (item && item.data) { item.data.renderAs = ${JSON.stringify(itemType)}; item.data.renderParams = ${JSON.stringify(params)}; }`;
+    }
     // Build the code
     let code = `
 // Create ${itemType} item
@@ -309,7 +339,23 @@ app.animate(item, {
   animationSpeed: ${speed}${extra}
 });
 
-({ success: true, itemId: '${itemId}', animationType: '${animationType}' });
+// The engine records a refused type on the item rather than throwing, because
+// animate() is on too many paths for a throw to be safe. It used to warn only
+// to a console the production build strips, so an unknown type left the item
+// still and every caller told it had worked. Read the record back.
+(() => {
+  const r = item.data && item.data.animationRejected;
+  if (r) {
+    return {
+      success: false,
+      itemId: '${itemId}',
+      error: 'Unknown animationType "' + r.requested + '" — nothing will move.',
+      requested: r.requested,
+      known: r.known,
+    };
+  }
+  return { success: true, itemId: '${itemId}', animationType: '${animationType}' };
+})();
 `.trim();
 }
 /**
@@ -353,6 +399,36 @@ app.addAnimation('${itemId}', ${keyframesJson}, ${JSON.stringify(opts)});
 /**
  * Template for executing generators
  */
+function generateImportMotionCaptureCode(bvh, mode, skeletonId, opts = {}) {
+    // Both FxTool entry points are async and return {ok, ...} rather than throwing, so the failure
+    // path is a value the model can read (unmatchedSource/unmatchedTarget tell it exactly which bone
+    // names to put in boneMap) instead of an opaque exception.
+    const bvhLiteral = JSON.stringify(bvh);
+    const optsLiteral = JSON.stringify(opts);
+    if (mode === 'retarget') {
+        return `
+// Retarget a BVH clip onto an existing rig — proportions from the rig, motion from the capture
+(async function() {
+  const res = await app.retargetBVH(${bvhLiteral}, ${JSON.stringify(skeletonId ?? '')}, ${optsLiteral});
+  if (!res || res.ok === false) {
+    return { success: false, error: (res && res.error) || 'retarget failed',
+             unmatchedSource: res && res.unmatchedSource, unmatchedTarget: res && res.unmatchedTarget };
+  }
+  return { success: true, skeletonId: res.skeletonId, matched: res.matched,
+           unmatchedSource: res.unmatchedSource, unmatchedTarget: res.unmatchedTarget };
+})()`;
+    }
+    return `
+// Import a BVH clip as a NEW skeleton
+(async function() {
+  const res = await app.importBVH(${bvhLiteral}, ${optsLiteral});
+  if (!res || res.ok === false) {
+    return { success: false, error: (res && res.error) || 'import failed' };
+  }
+  return { success: true, skeletonId: res.skeletonId, bones: res.bones, poses: res.poses,
+           duration: res.duration };
+})()`;
+}
 function generateExecuteGeneratorCode(generatorName, params, region) {
     // FxTool signature: app.executeGenerator(name, params, options).
     // region lives in options (added in FxTool c81781c).
@@ -427,11 +503,120 @@ const items = filtered.map(entry => ({
 ({ items, count: items.length });
 `.trim();
 }
-/**
- * Template for timeline control
- */
-function generatePlayTimelineCode(action, duration, loop, time, deterministic) {
+// Where a scroll binding parks its unbind function. `bindTimelineToScroll`
+// returns a FUNCTION, which cannot cross the tool boundary — so it lives on the
+// page, where a later unbind_scroll call can still reach it.
+const SCRUB_UNBIND_KEY = '__ppScrubUnbind';
+function generatePlayTimelineCode(action, duration, loop, time, deterministic, extra) {
+    const S = (v) => JSON.stringify(v);
     switch (action) {
+        case 'set_time_scale': {
+            // Deliberately not clamped: 0 freezes the clock without stopping, and a
+            // negative rate runs the scene backwards.
+            const rate = extra?.rate ?? 1;
+            return `
+// pp:TimeScale — the rate the scene clock runs at.
+(function() {
+  if (typeof app.setTimeScale !== 'function') {
+    return { success: false, error: 'app.setTimeScale unavailable — update FxTool' };
+  }
+  // Changing the rate rebases the clock so the CURRENT position is preserved;
+  // without that, doubling the rate mid-play jumps the playhead to twice its
+  // elapsed time, which reads as a glitch rather than a speed change.
+  const rate = app.setTimeScale(${S(rate)});
+  // Export drives time itself, so a scene watched at 0.5x still exports its
+  // real duration rather than a file twice as long.
+  return { success: true, action: 'set_time_scale', rate, affectsExport: false };
+})();
+`.trim();
+        }
+        case 'get_time_scale':
+            return `
+(function() {
+  if (typeof app.getTimeScale !== 'function') {
+    return { success: false, error: 'app.getTimeScale unavailable — update FxTool' };
+  }
+  return { success: true, action: 'get_time_scale', rate: app.getTimeScale() };
+})();
+`.trim();
+        case 'get_progress':
+            return `
+(function() {
+  if (typeof app.getProgress !== 'function') {
+    return { success: false, error: 'app.getProgress unavailable — update FxTool' };
+  }
+  return { success: true, action: 'get_progress', progress: app.getProgress() };
+})();
+`.trim();
+        case 'set_progress':
+            return `
+// Seek by proportion rather than by seconds — the unit a scrubber has.
+(function() {
+  if (typeof app.setProgress !== 'function') {
+    return { success: false, error: 'app.setProgress unavailable — update FxTool' };
+  }
+  const time = app.setProgress(${S(extra?.progress ?? 0)});
+  return { success: true, action: 'set_progress', progress: ${S(extra?.progress ?? 0)}, time };
+})();
+`.trim();
+        case 'list_scrub_anchors':
+            return `
+(function() {
+  if (typeof app.listScrubAnchors !== 'function') {
+    return { success: false, error: 'app.listScrubAnchors unavailable — update FxTool' };
+  }
+  const anchors = app.listScrubAnchors();
+  return { success: true, action: 'list_scrub_anchors', count: anchors.length, anchors };
+})();
+`.trim();
+        case 'bind_scroll': {
+            const scroll = extra?.scroll || {};
+            return `
+// pp:InputDrivenPlayback — drive the timeline from scroll instead of a clock.
+(function() {
+  if (typeof app.bindTimelineToScroll !== 'function') {
+    return { success: false, error: 'app.bindTimelineToScroll unavailable — update FxTool' };
+  }
+  const cfg = ${S(scroll)};
+  // The listener holds the app instance, so rebinding without unbinding leaks
+  // the old binding AND leaves two of them scrubbing the same timeline. Always
+  // release the previous one first.
+  let replaced = false;
+  if (typeof window !== 'undefined' && typeof window.${SCRUB_UNBIND_KEY} === 'function') {
+    try { window.${SCRUB_UNBIND_KEY}(); replaced = true; } catch (e) { /* already gone */ }
+    window.${SCRUB_UNBIND_KEY} = null;
+  }
+  const el = cfg.elementId && typeof document !== 'undefined'
+    ? document.getElementById(cfg.elementId)
+    : undefined;
+  if (cfg.elementId && !el) {
+    return { success: false, error: 'No element with id "' + cfg.elementId + '" — bind_scroll tracks a real DOM element' };
+  }
+  const unbind = app.bindTimelineToScroll({
+    ...(el ? { element: el } : {}),
+    ...(cfg.start !== undefined ? { start: cfg.start } : {}),
+    ...(cfg.end !== undefined ? { end: cfg.end } : {}),
+    ...(cfg.scrub !== undefined ? { scrub: cfg.scrub } : {}),
+    ...(cfg.range !== undefined ? { range: cfg.range } : {}),
+  });
+  if (typeof window !== 'undefined') window.${SCRUB_UNBIND_KEY} = unbind;
+  return { success: true, action: 'bind_scroll', bound: true, replaced, config: cfg };
+})();
+`.trim();
+        }
+        case 'unbind_scroll':
+            return `
+(function() {
+  // Nothing bound is an answer, not an error — an agent tidying up should not
+  // have to know whether it bound anything.
+  if (typeof window === 'undefined' || typeof window.${SCRUB_UNBIND_KEY} !== 'function') {
+    return { success: true, action: 'unbind_scroll', bound: false };
+  }
+  window.${SCRUB_UNBIND_KEY}();
+  window.${SCRUB_UNBIND_KEY} = null;
+  return { success: true, action: 'unbind_scroll', bound: true };
+})();
+`.trim();
         case 'play':
             return `
 // Play keyframe timeline
@@ -744,6 +929,37 @@ const grid = app.createGrid({
 // =============================================================================
 // CODE GENERATOR CLASS
 // =============================================================================
+/**
+ * Agent PLATFORM name → the engine's canvas-preset key.
+ *
+ * AgentPlatformSchema is an export-target vocabulary ('instagram', 'youtube')
+ * that was also being handed straight to app.setCanvasSize(), which keys on
+ * 'instagram-post' and 'full-hd-1080p'. Seven of the ten names matched nothing:
+ * the engine fell through to its default and resized the artboard to 800x600
+ * while recording the preset as applied, so an agent asking for an Instagram
+ * canvas silently got neither the size nor an error. (FxTool 496d3910 now
+ * refuses an unknown key instead — better, but it warns to a console the
+ * production build strips, so the agent still learns nothing.)
+ *
+ * Mapping rather than renaming: 'instagram' is the right word for an export
+ * TARGET and a poor one for a canvas SIZE, and only the second use was wrong.
+ */
+const PLATFORM_TO_CANVAS_PRESET = {
+    instagram: 'instagram-post', // 1080x1080
+    'instagram-story': 'instagram-story',
+    tiktok: 'tiktok',
+    youtube: 'full-hd-1080p', // the video frame, 1920x1080
+    'youtube-thumbnail': 'youtube-thumbnail',
+    twitter: 'twitter-post',
+    linkedin: 'linkedin-post',
+    web: 'hd-720p', // 1280x720
+    'print-a4': 'a4-portrait',
+    'print-letter': 'letter-portrait',
+};
+/** The engine key for a platform, falling back to the value itself. */
+export function canvasPresetFor(platform) {
+    return PLATFORM_TO_CANVAS_PRESET[platform] || platform;
+}
 export class PinePaperCodeGenerator {
     /**
      * Generate code for creating an item
@@ -809,6 +1025,27 @@ export class PinePaperCodeGenerator {
         const validated = KeyframeAnimateInputSchema.parse(input);
         return generateKeyframeAnimateCode(validated.itemId, validated.keyframes, validated.duration, validated.loop, validated.timeOffset, validated.clipInPoint, validated.clipOutPoint, validated.timeUnits);
     }
+    /**
+     * Generate code for importing / retargeting a motion-capture clip
+     */
+    generateImportMotionCapture(input) {
+        const v = ImportMotionCaptureInputSchema.parse(input);
+        if (v.mode === 'retarget' && !v.skeletonId) {
+            throw new Error("pinepaper_import_motion_capture: mode='retarget' requires skeletonId (the rig to drive)");
+        }
+        const opts = {};
+        if (v.fps !== undefined)
+            opts.fps = v.fps;
+        if (v.height !== undefined)
+            opts.height = v.height;
+        if (v.position !== undefined)
+            opts.position = v.position;
+        if (v.name !== undefined)
+            opts.name = v.name;
+        if (v.boneMap !== undefined)
+            opts.boneMap = v.boneMap;
+        return generateImportMotionCaptureCode(v.bvh, v.mode, v.skeletonId, opts);
+    }
     /**
      * Generate code for executing a generator
      */
@@ -832,8 +1069,8 @@ export class PinePaperCodeGenerator {
     /**
      * Generate code for timeline control
      */
-    generatePlayTimeline(action, duration, loop, time, deterministic) {
-        return generatePlayTimelineCode(action, duration, loop, time, deterministic);
+    generatePlayTimeline(action, duration, loop, time, deterministic, extra) {
+        return generatePlayTimelineCode(action, duration, loop, time, deterministic, extra);
     }
     /**
      * Generate code for setting background color
@@ -1420,7 +1657,7 @@ app.historyManager.saveState();
      */
     generateConnect(input) {
         const validated = ConnectInputSchema.parse(input);
-        const { sourceItemId, targetItemId, routing, lineColor, lineWidth, lineStyle, headStyle, tailStyle, label, curvature, boltEnabled, boltColor, } = validated;
+        const { id, sourceItemId, targetItemId, routing, lineColor, lineWidth, lineStyle, headStyle, tailStyle, label, curvature, boltEnabled, boltColor, } = validated;
         const config = {
             routing,
             lineStyle,
@@ -1430,6 +1667,13 @@ app.historyManager.saveState();
             boltEnabled,
             boltColor,
         };
+        // A caller-supplied id is honoured by Connector (`config.id || <generated>`),
+        // and it is the ONLY way a caller can address this connector afterwards:
+        // update/remove take a connectorId, and the fallback the engine mints is
+        // `connector_${Date.now()}_${random}` — unpredictable, and different on
+        // every run of the same scene.
+        if (id)
+            config.id = id;
         if (lineColor)
             config.lineColor = lineColor;
         if (lineWidth)
@@ -1457,8 +1701,13 @@ app.historyManager.saveState();
      */
     generateConnectPorts(input) {
         const validated = ConnectPortsInputSchema.parse(input);
-        const { sourceItemId, sourcePort, targetItemId, targetPort, config } = validated;
-        const configStr = config ? JSON.stringify(config, null, 2) : '{}';
+        const { id, sourceItemId, sourcePort, targetItemId, targetPort, config } = validated;
+        // `id` sits at the TOP level of the tool's input but belongs inside the
+        // engine's config object, which is where Connector reads it from. Merged
+        // here rather than asking callers to nest it, since every other style
+        // option they pass is nested and the id is not a style.
+        const merged = id ? { ...(config ?? {}), id } : config;
+        const configStr = merged ? JSON.stringify(merged, null, 2) : '{}';
         return `
 // Connect ports: ${sourceItemId}:${sourcePort} -> ${targetItemId}:${targetPort}
 const sourceItem = app.getItemById('${sourceItemId}');
@@ -1659,8 +1908,8 @@ throw new Error('Unknown diagram mode action: ${action}');
         }
         if (canvasPreset) {
             code += `
-  // Set canvas size to preset
-  app.setCanvasSize('${canvasPreset}');
+  // Set canvas size to preset (platform name → engine preset key)
+  app.setCanvasSize('${canvasPresetFor(canvasPreset)}');
   // Allow canvas resize to take effect
   await new Promise(r => setTimeout(r, 50));
 `;
@@ -1866,8 +2115,8 @@ throw new Error('Unknown diagram mode action: ${action}');
         }
         if (canvasPreset) {
             code += `
-  // Set canvas to preset
-  app.setCanvasSize('${canvasPreset}');
+  // Set canvas to preset (platform name → engine preset key)
+  app.setCanvasSize('${canvasPresetFor(canvasPreset)}');
   // Allow canvas resize to take effect
   await new Promise(r => setTimeout(r, 50));
 `;
@@ -2115,6 +2364,10 @@ const item = app.getItemById(targetId);
 if (!item) throw new Error('Item not found: ' + targetId);
 if (!app.applyAnimatedMask) throw new Error('Mask system not available');
 const maskedGroup = app.applyAnimatedMask(item, '${preset}', ${maskOpts});
+const maskRej = maskedGroup && maskedGroup.data && maskedGroup.data.maskAnimationRejected;
+if (maskRej) {
+  return { success: false, itemId: targetId, error: 'Masked, but animation preset "' + maskRej.requested + '" is unknown — it will NOT animate.', requested: maskRej.requested, known: maskRej.known };
+}
 return { success: !!maskedGroup, itemId: targetId, preset: '${preset}' };
 `;
             }
@@ -3618,6 +3871,18 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
     } else {
       maskedGroup = app.applyAnimatedMask(item, '${preset}', mergedOpts);
     }
+    // A mask with an unknown ANIMATION preset still masks — the item just never
+    // animates — so !!maskedGroup is true either way. The engine records which.
+    const rej = maskedGroup && maskedGroup.data && maskedGroup.data.maskAnimationRejected;
+    if (rej) {
+      return {
+        success: false,
+        itemId: '${validated.itemId}',
+        error: 'Masked, but the animation preset "' + rej.requested + '" is unknown — it will NOT animate.',
+        requested: rej.requested,
+        known: rej.known,
+      };
+    }
     return { success: !!maskedGroup, itemId: '${validated.itemId}', preset: '${preset}' };
   } catch (error) {
     return { success: false, error: error.message };
@@ -4052,6 +4317,238 @@ ${mask ? `    app.imageTools.applyMask(raster, '${mask}');\n` : ''}    // The RE
                 return `(function() { return { error: 'Unknown scene_playback action: ${input.action}' }; })();`;
         }
     }
+    generateSceneGraph(input) {
+        const validated = SceneGraphInputSchema.parse(input);
+        const S = (v) => JSON.stringify(v);
+        if (validated.action === 'validate') {
+            return `
+// Check a scene graph WITHOUT drawing it — the same check createSceneGraph runs,
+// so an author can fix the graph before committing to a canvas full of cards.
+(function() {
+  if (typeof app.validateSceneGraph !== 'function') {
+    return { success: false, error: 'app.validateSceneGraph unavailable — update FxTool' };
+  }
+  const r = app.validateSceneGraph(${S(validated.graph)});
+  return {
+    success: true,
+    action: 'validate',
+    ok: r ? r.ok : false,
+    errors: (r && r.errors) || [],
+    // Cycles are legitimate (a retry loop) but reported: an accidental one
+    // looks exactly like a game that never ends.
+    warnings: (r && r.warnings) || [],
+    reachable: (r && r.reachable) || [],
+    cycles: (r && r.cycles) || [],
+  };
+})();
+`.trim();
+        }
+        return `
+// Create interactive scene graph (story / quiz cards)
+(async function() {
+  if (typeof app.createSceneGraph !== 'function') {
+    return { success: false, error: 'app.createSceneGraph unavailable — update FxTool' };
+  }
+  const result = await app.createSceneGraph(${S(validated.graph)}, ${S(validated.opts || {})});
+  if (!result) return { success: false, error: 'No result returned' };
+  return {
+    success: result.ok !== false,
+    ok: result.ok,
+    errors: result.errors || [],
+    warnings: result.warnings || [],
+    // The engine reports these and this tool used to drop them. \`failed\` is the
+    // one that matters: a graph can compile, render, and still leave N click
+    // relations unwired — it looks built and is inert, and nothing else in the
+    // result says so. A refused plan returns early without them, hence the
+    // defaults.
+    wired: result.wired,
+    failed: result.failed,
+    cycles: result.cycles || [],
+    entranced: result.entranced,
+    start: result.start,
+    ids: result.ids || {},
+  };
+})();
+`.trim();
+    }
+    // ===========================================================================
+    // RELATIVE TIMING, STAGGERS, FLIP
+    // ===========================================================================
+    generateSequence(input) {
+        const validated = SequenceInputSchema.parse(input);
+        const S = (v) => JSON.stringify(v);
+        if (validated.action === 'list_forms') {
+            return `
+(function() {
+  if (typeof app.listPositionForms !== 'function') {
+    return { success: false, error: 'app.listPositionForms unavailable — update FxTool' };
+  }
+  const forms = app.listPositionForms();
+  return { success: true, action: 'list_forms', count: forms.length, forms };
+})();
+`.trim();
+        }
+        if (validated.action === 'resolve') {
+            return `
+// Resolve ONE relative position to absolute seconds.
+(function() {
+  if (typeof app.resolveTimelinePosition !== 'function') {
+    return { success: false, error: 'app.resolveTimelinePosition unavailable — update FxTool' };
+  }
+  const ctx = { ...${S(validated.context || {})}, labels: ${S(validated.labels || {})} };
+  const seconds = app.resolveTimelinePosition(${S(validated.position ?? null)}, ctx);
+  return { success: true, action: 'resolve', position: ${S(validated.position ?? null)}, seconds, context: ctx };
+})();
+`.trim();
+        }
+        return `
+// Place a run of clips in order, each resolved against the ones before it.
+(function() {
+  if (typeof app.placeSequence !== 'function') {
+    return { success: false, error: 'app.placeSequence unavailable — update FxTool' };
+  }
+  const clips = ${S(validated.clips || [])};
+  const result = app.placeSequence(clips, {
+    startAt: ${S(validated.startAt ?? 0)},
+    labels: ${S(validated.labels || {})},
+  });
+  // Echo the caller's own clip ids back onto the placements — placeSequence
+  // answers positionally, and an agent that named its clips should get the
+  // names back rather than having to re-zip two arrays by index.
+  const placed = (result.placed || []).map((p, i) => (
+    clips[i] && clips[i].id ? { id: clips[i].id, ...p } : p
+  ));
+  return {
+    success: true,
+    action: 'place',
+    placed,
+    labels: result.labels,
+    // The timeline only ever grows: a clip placed early with "-=" must not pull
+    // the end back and silently truncate everything after it.
+    duration: result.duration,
+  };
+})();
+`.trim();
+    }
+    generateStagger(input) {
+        const validated = StaggerInputSchema.parse(input);
+        const S = (v) => JSON.stringify(v);
+        if (validated.action === 'list_origins') {
+            return `
+(function() {
+  if (typeof app.listStaggerOrigins !== 'function') {
+    return { success: false, error: 'app.listStaggerOrigins unavailable — update FxTool' };
+  }
+  const origins = app.listStaggerOrigins();
+  return { success: true, action: 'list_origins', count: origins.length, origins };
+})();
+`.trim();
+        }
+        if (validated.action === 'preview') {
+            return `
+// Delays for a count, without touching the canvas — plan before committing.
+(function() {
+  if (typeof app.staggerDelays !== 'function') {
+    return { success: false, error: 'app.staggerDelays unavailable — update FxTool' };
+  }
+  const delays = app.staggerDelays(${S(validated.count ?? 0)}, ${S(validated.opts || {})});
+  return {
+    success: true,
+    action: 'preview',
+    count: ${S(validated.count ?? 0)},
+    delays,
+    span: delays.length ? Math.max(...delays) : 0,
+  };
+})();
+`.trim();
+        }
+        return `
+// Apply a stagger to real items, in the order given.
+(function() {
+  if (typeof app.staggerItems !== 'function') {
+    return { success: false, error: 'app.staggerItems unavailable — update FxTool' };
+  }
+  const ids = ${S(validated.itemIds || [])};
+  if (!ids.length) {
+    return { success: false, error: 'apply needs itemIds, in the order the stagger should follow (row-major for a grid)' };
+  }
+  const r = app.staggerItems(ids, ${S(validated.opts || {})});
+  return {
+    success: r && r.ok === true,
+    action: 'apply',
+    // 'applied' can be lower than the ids given — an id that resolves to
+    // nothing is skipped, and a stagger that silently covered fewer items than
+    // asked for is the failure worth seeing.
+    requested: ids.length,
+    applied: r ? r.applied : 0,
+    delays: r ? r.delays : [],
+    span: r ? r.span : 0,
+  };
+})();
+`.trim();
+    }
+    generateFlip(input) {
+        const validated = FlipInputSchema.parse(input);
+        const S = (v) => JSON.stringify(v);
+        if (validated.action === 'record') {
+            return `
+// pp:Flip step one — record where things are NOW, before the change.
+//
+// The record stays ON THE PAGE rather than travelling back through the tool
+// result: it is one snapshot per item of raw geometry, useless to read and
+// expensive to carry, and \`apply\` is the only thing that ever wants it.
+(function() {
+  if (typeof app.recordFlipState !== 'function') {
+    return { success: false, error: 'app.recordFlipState unavailable — update FxTool' };
+  }
+  const ids = ${S(validated.itemIds || null)};
+  const record = ids && ids.length ? app.recordFlipState(ids) : app.recordFlipState();
+  if (typeof window !== 'undefined') window.__ppFlipRecord = record;
+  return {
+    success: true,
+    action: 'record',
+    recorded: (record.snapshots || []).length,
+    takenAt: record.takenAt,
+    ids: (record.snapshots || []).map(s => s.id),
+  };
+})();
+`.trim();
+        }
+        const opts = {};
+        if (validated.duration !== undefined)
+            opts.duration = validated.duration;
+        if (validated.easing !== undefined)
+            opts.easing = validated.easing;
+        if (validated.enter !== undefined)
+            opts.enter = validated.enter;
+        if (validated.stagger !== undefined)
+            opts.stagger = validated.stagger;
+        return `
+// pp:Flip step two — animate from the recorded state to wherever things are now.
+// Writes ordinary keyframes, so the transition scrubs, exports to SMIL and
+// Lottie, and survives a reload.
+(function() {
+  if (typeof app.flipItems !== 'function') {
+    return { success: false, error: 'app.flipItems unavailable — update FxTool' };
+  }
+  const record = typeof window !== 'undefined' ? window.__ppFlipRecord : null;
+  if (!record || !(record.snapshots || []).length) {
+    return { success: false, error: 'Nothing was recorded — run pinepaper_flip { action: "record" } BEFORE the change, then rearrange, then apply' };
+  }
+  const r = app.flipItems(record, ${S(opts)});
+  return {
+    success: r && r.ok === true,
+    action: 'apply',
+    moved: r ? r.moved : 0,
+    entered: r ? r.entered : [],
+    // Items that LEFT during the change cannot be animated out — they are gone
+    // already. Remove them after the flip, not before.
+    left: r ? r.left : [],
+    duration: r ? r.duration : 0,
+  };
+})();
+`.trim();
+    }
     // ===========================================================================
     // SELECTION, TRANSFORM & HISTORY
     // ===========================================================================
@@ -4261,6 +4758,14 @@ ${mask ? `    app.imageTools.applyMask(raster, '${mask}');\n` : ''}    // The RE
                     ...(input.assets ? { assets: input.assets } : {}),
                     ...(input.audio ? { audio: input.audio } : {}),
                     ...(input.grid ? { grid: true } : {}),
+                    // The design axes. A register resolves the craft (gutter, margin,
+                    // hue budget, type scale); a medium says what makes the marks and
+                    // is REFUSED when a composition cannot be rendered in it.
+                    ...(input.register ? { register: input.register } : {}),
+                    ...(input.level !== undefined ? { level: input.level } : {}),
+                    ...(input.medium ? { medium: input.medium } : {}),
+                    ...(input.stitch ? { stitch: input.stitch } : {}),
+                    ...(input.stitchBudget !== undefined ? { stitchBudget: input.stitchBudget } : {}),
                 })}`, 'Compose: apply pattern');
         }
     }
@@ -4520,6 +5025,12 @@ ${resolve}
   ${guard}
   try {
     const result = await app.imageTools.applyCutoutStyle(${JSON.stringify(input.itemId || '')}, ${JSON.stringify(input.preset || '')}, ${JSON.stringify(input.options || {})});
+    // An unknown preset returns the very item it was given, unchanged — so a
+    // truthy result proves nothing. The engine records the refusal on it.
+    const cutRej = result && result.data && result.data.cutoutStyleRejected;
+    if (cutRej) {
+      return { success: false, action: 'apply', itemId: ${JSON.stringify(input.itemId || '')}, error: 'Unknown cutout preset "' + cutRej.requested + '" — the item is UNCHANGED.', requested: cutRej.requested, known: cutRej.known };
+    }
     return { success: true, action: 'apply', itemId: ${JSON.stringify(input.itemId || '')}, preset: ${JSON.stringify(input.preset || '')} };
   } catch (e) {
     return { error: 'Failed to apply cutout style: ' + e.message };
@@ -4687,6 +5198,144 @@ ${resolve}
                 return `(function() { return { error: 'Unknown query action: ${input.action}' }; })();`;
         }
     }
+    generateQueryCapabilities(input) {
+        const validated = QueryCapabilitiesInputSchema.parse(input);
+        const S = (v) => JSON.stringify(v);
+        // Warming is the engine's default and the honest answer, so the argument is
+        // omitted unless the caller explicitly opted out — no reason to spend bytes
+        // restating a default.
+        const warmArg = validated.warm === undefined ? '' : S({ warm: validated.warm });
+        return `
+// Query capabilities / recommend treatments from the engine's LIVE registries.
+//
+// Reads app.getCapabilities(), which warms the lazily-constructed registries
+// before answering and returns a coverage report saying what it read from.
+// \`warm: false\` skips that and answers from whatever is already resident —
+// cheaper, and the coverage report labels itself \`warmed: false\` when it does.
+// This tool previously rebuilt that index itself, and because generatorRegistry
+// is null until ensureHeavyModules() lands (~1.2s after boot) and the rigging /
+// blending / deform relation rules only register when their subsystem is first
+// touched, an early call reported ZERO generators and ~77 of ~100 relations as
+// if that were the whole engine.
+(async function() {
+  const action = ${S(validated.action || 'list')};
+  const kind = ${S(validated.kind)};
+  const mood = ${S(validated.mood)};
+  const subject = ${S(validated.subject)};
+  const avoid = ${S(validated.avoid)};
+  const seed = ${S(validated.seed)};
+  const key = ${S(validated.key)};
+  const exclude = ${S(validated.exclude)};
+
+  if (typeof app.getCapabilities !== 'function') {
+    return { success: false, error: 'app.getCapabilities unavailable — update FxTool' };
+  }
+
+  let caps = [], report = null;
+  try {
+    const res = await app.getCapabilities(${warmArg});
+    caps = (res && res.capabilities) || [];
+    report = (res && res.coverage) || null;
+  } catch (e) {
+    return { success: false, error: 'Failed to inspect capabilities: ' + e.message };
+  }
+
+  if (action === 'coverage') {
+    // The engine's own report: totals per kind, the entries that can be applied
+    // but not RANKED (no label, no definition), the kinds with no source wired,
+    // and which lazy registries were live when it answered.
+    return { success: true, action: 'coverage', ...(report || {}), total: caps.length };
+  }
+
+  if (action === 'find') {
+    if (!key) return { success: false, error: 'find action requires key' };
+    const found = caps.find(c => c.key === String(key));
+    return found ? { success: true, action: 'find', capability: found } : { success: false, error: 'Capability not found: ' + key };
+  }
+
+  let filtered = caps;
+  if (kind) {
+    const kinds = new Set(Array.isArray(kind) ? kind : [kind]);
+    filtered = caps.filter(c => kinds.has(c.kind));
+  }
+
+  if (action === 'list') {
+    return {
+      success: true,
+      action: 'list',
+      count: filtered.length,
+      total: caps.length,
+      unwiredKinds: report ? report.unwiredKinds : undefined,
+      capabilities: filtered.map(c => ({
+        key: c.key, kind: c.kind, label: c.label,
+        definition: c.definition, applyWith: c.applyWith, describable: c.describable
+      }))
+    };
+  }
+
+  if (action === 'choose') {
+    const STOP = new Set(['the', 'a', 'an', 'and', 'or', 'of', 'to', 'in', 'into', 'at', 'on', 'as', 'is', 'are', 'then', 'their', 'they', 'it', 'its', 'each', 'from', 'with', 'that', 'characters', 'character', 'letters', 'letter', 'text', 'frame', 'real']);
+    const tokenize = (t) => String(t || '').toLowerCase().split(/[^a-z0-9]+/).filter(w => w.length > 2 && !STOP.has(w));
+    const MOOD_TERMS = {
+      reveal: ['resolve', 'resolves', 'reveal', 'appear', 'emerge', 'decode', 'decrypt', 'unscramble', 'form', 'assemble', 'converge'],
+      triumphant: ['burst', 'launch', 'firework', 'bloom', 'spark', 'explode', 'shine', 'glow', 'celebrate', 'rise'],
+      failure: ['crumble', 'fall', 'collapse', 'burn', 'decay', 'dissolve', 'break', 'shatter', 'sink', 'error', 'corrupt'],
+      calm: ['drift', 'float', 'gentle', 'slow', 'settle', 'fade', 'wave', 'ripple', 'pour'],
+      technical: ['binary', 'matrix', 'grid', 'scan', 'code', 'digital', 'circuit', 'data', 'print', 'terminal'],
+      energetic: ['bounce', 'swarm', 'spray', 'shoot', 'fast', 'rapid', 'scatter', 'slam', 'volley']
+    };
+
+    // Deterministic tiebreak. Equal-scoring candidates used to fall out in
+    // array order, which made \`seed\` — documented as giving reproducible
+    // selection — do nothing at all. FNV-1a over seed+key gives a stable
+    // shuffle per seed; with no seed the order is stable by key, so a repeated
+    // call still answers the same way.
+    const tiebreak = (k) => {
+      if (!seed) return null;
+      let h = 2166136261;
+      const s = String(seed) + '|' + k;
+      for (let i = 0; i < s.length; i++) { h ^= s.charCodeAt(i); h = Math.imul(h, 16777619); }
+      return h >>> 0;
+    };
+
+    const exSet = new Set(Array.isArray(exclude) ? exclude : []);
+    const scored = filtered.filter(c => !exSet.has(c.key)).map(c => {
+      const words = new Set(tokenize(c.text || (c.label + ' ' + c.definition)));
+      if (!words.size) return { item: c, score: 0 };
+      let score = 0;
+      const moods = Array.isArray(mood) ? mood : (mood ? [mood] : []);
+      for (const m of moods) {
+        for (const term of (MOOD_TERMS[m] || [])) { if (words.has(term)) score += 12; }
+      }
+      for (const w of tokenize(subject)) { if (words.has(w)) score += 7; }
+      for (const av of (Array.isArray(avoid) ? avoid : (avoid ? [avoid] : []))) {
+        for (const term of (MOOD_TERMS[av] || [])) { if (words.has(term)) score -= 10; }
+      }
+      return { item: c, score };
+    });
+
+    scored.sort((a, b) => {
+      if (b.score !== a.score) return b.score - a.score;
+      const ha = tiebreak(a.item.key), hb = tiebreak(b.item.key);
+      if (ha !== null && ha !== hb) return ha - hb;
+      return a.item.key.localeCompare(b.item.key);
+    });
+    const top = scored.slice(0, 5).map(s => ({ ...s.item, score: s.score }));
+    return {
+      success: true,
+      action: 'choose',
+      recommendation: top[0] || null,
+      topCandidates: top,
+      // A chooser scores on description, so entries without one can never be
+      // recommended. Saying so beats silently never offering them.
+      unrankable: report ? report.unrankable : undefined
+    };
+  }
+
+  return { success: false, error: 'Unknown capabilities action: ' + action };
+})();
+`.trim();
+    }
     // ===========================================================================
     // DEFORMATION
     // ===========================================================================
@@ -5709,6 +6358,178 @@ ${guard}
     palettes: typeof app.listTextPalettes === 'function' ? app.listTextPalettes() : [],
     fontAxes: typeof app.listFontAxes === 'function' ? app.listFontAxes() : null,
   };
+})();`.trim();
+            }
+        }
+    }
+    /**
+     * pinepaper_text_effect — the 37 character-level text effects.
+     *
+     * `applyTextEffect` is ASYNC (it lazy-`import()`s the effects chunk), so this
+     * emits an async IIFE — a sync wrapper would hand the bridge a pending
+     * Promise instead of the result.
+     *
+     * The returned `items` are live Paper objects and cannot cross the bridge;
+     * only ids/count/duration are forwarded. `ids` is the whole handle set the
+     * caller now has, since the source item is gone.
+     */
+    /**
+     * The medium axis. `list_media` and `resolve` are READS — they exist so an
+     * agent can find out what this build can honestly make before it promises a
+     * medium in prose, which is the failure the axis was built to prevent.
+     */
+    generateDesignMedium(input) {
+        const S = (v) => JSON.stringify(v);
+        const wrap = (comment, body) => `\n// ${comment}\n(function() {\n${body}\n})();`.trim();
+        switch (input.action) {
+            case 'list_media':
+                return wrap('Medium: list', `  if (typeof app.listDesignMedia !== 'function') { return { success: false, error: 'medium axis unavailable — update FxTool' }; }
+  const media = app.listDesignMedia();
+  return { success: true, action: 'list_media', media: media, native: media.filter(function(m) { return m.fidelity === 'native'; }).map(function(m) { return m.key; }) };`);
+            case 'resolve':
+                return wrap('Medium: resolve', `  if (typeof app.resolveDesignMedium !== 'function') { return { success: false, error: 'medium axis unavailable — update FxTool' }; }
+  const v = app.resolveDesignMedium(${S(input.medium)});
+  return Object.assign({ success: true, action: 'resolve' }, v);`);
+            case 'list_stitches':
+                return wrap('Medium: list stitches', `  if (typeof app.listStitches !== 'function') { return { success: false, error: 'thread medium unavailable — update FxTool' }; }
+  const stitches = app.listStitches();
+  return { success: true, action: 'list_stitches', stitches: stitches, count: stitches.length };`);
+            case 'apply_thread': {
+                const opts = S({
+                    ...(input.stitch !== undefined ? { stitch: input.stitch } : {}),
+                    ...(input.field !== undefined ? { field: input.field } : {}),
+                    ...(input.stitchLen !== undefined ? { stitchLen: input.stitchLen } : {}),
+                    ...(input.rowGap !== undefined ? { rowGap: input.rowGap } : {}),
+                    ...(input.variance !== undefined ? { variance: input.variance } : {}),
+                    ...(input.width !== undefined ? { width: input.width } : {}),
+                    ...(input.sheen !== undefined ? { sheen: input.sheen } : {}),
+                    ...(input.color !== undefined ? { color: input.color } : {}),
+                    ...(input.seed !== undefined ? { seed: input.seed } : {}),
+                    ...(input.count !== undefined ? { count: input.count } : {}),
+                });
+                return wrap('Medium: render in thread', `  if (typeof app.applyThreadPainting !== 'function') { return { success: false, error: 'thread medium unavailable — update FxTool' }; }
+  const entry = app.itemRegistry && app.itemRegistry.get(${S(input.itemId)});
+  const src = entry && entry.item;
+  if (!src) { return { success: false, action: 'apply_thread', error: 'no item ' + ${S(input.itemId)} }; }
+  // Check the shape BEFORE calling, so the refusal can name the fix. The
+  // engine warns to a console production strips, which an agent never sees.
+  if (src.content !== undefined && typeof src.getPointAt !== 'function') {
+    return { success: false, action: 'apply_thread', error: 'a text item has no outline to stitch. Convert it to glyph paths first (pinepaper_text_style), then stitch the result — the collage it produces is a group of closed paths, which this accepts.' };
+  }
+  const g = app.applyThreadPainting(${S(input.itemId)}, ${opts});
+  if (!g) { return { success: false, action: 'apply_thread', error: 'nothing stitchable here — thread needs a CLOSED path, a compound path, or a group containing them. An open stroke, a raster and an empty group all land here. (If you passed a stitch name, check it against list_stitches.)' }; }
+  return { success: true, action: 'apply_thread', groupId: (g.data && g.data.id) || null, stitches: g.children.length };`);
+            }
+            case 'list_flow_fields':
+                return wrap('Medium: list flow fields', `  if (typeof app.listFlowFields !== 'function') { return { success: false, error: 'hatch medium unavailable — update FxTool' }; }
+  const fields = app.listFlowFields();
+  return { success: true, action: 'list_flow_fields', fields: fields, count: fields.length };`);
+            case 'list_hatch_options':
+                return wrap('Medium: hatch defaults', `  if (typeof app.listHatchOptions !== 'function') { return { success: false, error: 'hatch medium unavailable — update FxTool' }; }
+  return { success: true, action: 'list_hatch_options', defaults: app.listHatchOptions() };`);
+            case 'apply_hatch': {
+                const opts = S({
+                    ...(input.distance !== undefined ? { distance: input.distance } : {}),
+                    ...(input.angle !== undefined ? { angle: input.angle } : {}),
+                    ...(input.gradient !== undefined ? { gradient: input.gradient } : {}),
+                    ...(input.rand !== undefined ? { rand: input.rand } : {}),
+                    ...(input.continuous !== undefined ? { continuous: input.continuous } : {}),
+                    ...(input.flowField !== undefined ? { field: input.flowField } : {}),
+                    ...(input.t !== undefined ? { t: input.t } : {}),
+                    ...(input.width !== undefined ? { width: input.width } : {}),
+                    ...(input.color !== undefined ? { color: input.color } : {}),
+                    ...(input.seed !== undefined ? { seed: input.seed } : {}),
+                });
+                return wrap('Medium: rule an item with hatching', `  if (typeof app.applyHatching !== 'function') { return { success: false, error: 'hatch medium unavailable — update FxTool' }; }
+  const entry = app.itemRegistry && app.itemRegistry.get(${S(input.itemId)});
+  const src = entry && entry.item;
+  if (!src) { return { success: false, action: 'apply_hatch', error: 'no item ' + ${S(input.itemId)} }; }
+  // Every refusal below is one the engine only console.warns, and production
+  // strips the console — so an agent would otherwise get a bare null and no
+  // idea which of five different things went wrong.
+  if (src.content !== undefined && typeof src.getPointAt !== 'function') {
+    return { success: false, action: 'apply_hatch', error: 'a text item has no outline to hatch. Convert it to glyph paths first (pinepaper_text_style), then hatch the result — the collage it produces is a group of closed paths, which this accepts.' };
+  }
+  // Count the closed paths BEFORE the call, so a truncated group can be
+  // reported as truncated rather than looking complete.
+  let closed = 0;
+  const isGroup = src.children && !(typeof src.getPointAt === 'function' && src.closed);
+  if (isGroup) {
+    const walk = function(n) {
+      for (const c of (n.children || [])) {
+        if (c.children && typeof c.getPointAt !== 'function') walk(c);
+        else if (typeof c.getPointAt === 'function' && c.closed && c.length > 0) closed++;
+      }
+    };
+    walk(src);
+    if (!closed) { return { success: false, action: 'apply_hatch', error: 'that group contains no closed paths to hatch — hatching needs a closed outline, and open strokes, rasters and empty groups all land here.' }; }
+  }
+  const b = src.bounds;
+  const g = app.applyHatching(${S(input.itemId)}, ${opts});
+  if (!g) {
+    // Spacing wider than the shape is the usual cause and is otherwise a
+    // silent no-op: the item just vanishes behind an empty group.
+    return { success: false, action: 'apply_hatch', error: 'nothing was ruled. Most often the spacing exceeds the shape — distance is ' + ${S(input.distance ?? 6)} + 'px against bounds ' + Math.round(b.width) + 'x' + Math.round(b.height) + '. Otherwise the item has no closed outline: hatching needs a closed path, a compound path, or a group of them.' };
+  }
+  const parts = (g.data && g.data.parts) || null;
+  return {
+    success: true,
+    action: 'apply_hatch',
+    groupId: (g.data && g.data.id) || null,
+    lines: g.children ? g.children.length : 0,
+    angle: (g.data && g.data.angle) !== undefined ? g.data.angle : null,
+    spacing: (g.data && g.data.spacing) !== undefined ? g.data.spacing : null,
+    // The engine hatches at most 40 paths from a group and warns about the rest.
+    ...(parts !== null ? { parts: parts } : {}),
+    ...(closed > 40 ? { truncated: 'hatched the first 40 of ' + closed + ' closed paths' } : {}),
+    // Re-hatching REPLACES: a second set of lines over the first is
+    // indistinguishable from nothing having happened, so trying spacings in
+    // turn is safe and is the flow this exists for.
+    note: 'the source item is now hidden behind the hatching; re-hatching replaces rather than stacks',
+  };`);
+            }
+            default:
+                return wrap('Medium: unknown action', `  return { success: false, error: 'unknown action' };`);
+        }
+    }
+    generateTextEffect(input) {
+        const S = (v) => JSON.stringify(v);
+        switch (input.action) {
+            case 'apply': {
+                // options spreads FIRST so the named fields win on collision — the
+                // schema advertises that precedence, so it has to be real here.
+                const opts = S({
+                    ...(input.options ?? {}),
+                    ...(input.duration !== undefined ? { duration: input.duration } : {}),
+                    ...(input.seed !== undefined ? { seed: input.seed } : {}),
+                    ...(input.gradient !== undefined ? { gradient: input.gradient } : {}),
+                    ...(input.gradientStops !== undefined ? { gradientStops: input.gradientStops } : {}),
+                    ...(input.gradientDirection !== undefined ? { gradientDirection: input.gradientDirection } : {}),
+                    ...(input.gradientSteps !== undefined ? { gradientSteps: input.gradientSteps } : {}),
+                    ...(input.keepSource !== undefined ? { keepSource: input.keepSource } : {}),
+                });
+                return `
+// Text effect: ${input.effect} — the text becomes one animated item PER CHARACTER
+(async function() {
+  if (typeof app.applyTextEffect !== 'function') { return { success: false, error: 'app.applyTextEffect unavailable — update FxTool to a text-effects build' }; }
+  const r = await app.applyTextEffect(${S(input.itemId)}, ${S(input.effect)}, ${opts});
+  if (!r || !r.ok) { return { success: false, error: (r && r.error) || 'text effect failed' }; }
+  // r.items are live Paper objects — NOT serializable, deliberately dropped.
+  // The source item id is GONE unless keepSource was set, so r.ids is now the
+  // caller's entire handle set; returning it is what makes the tool usable.
+  return {
+    success: true, action: 'apply', effect: r.effect, ids: r.ids, count: r.count,
+    duration: r.duration, sourceRemoved: ${S(input.keepSource !== true)},
+  };
+})();`.trim();
+            }
+            case 'list': {
+                return `
+// The 37 character-level text effects — the picker surface
+(async function() {
+  if (typeof app.listTextEffects !== 'function') { return { success: false, error: 'app.listTextEffects unavailable — update FxTool to a text-effects build' }; }
+  const effects = await app.listTextEffects();
+  return { success: true, effects, count: effects.length };
 })();`.trim();
             }
         }
@@ -5966,7 +6787,8 @@ ${needWorld}
                 const root = input.rootPosition ? S(input.rootPosition) : S({ x: 400, y: 300 });
                 return wrap('Rigging: create skeleton', `  const skeletonId = R.createSkeleton(${S(input.name ?? null)}, ${root});
   if (app.historyManager) app.historyManager.saveState();
-  return { success: !!skeletonId, action: 'create_skeleton', skeletonId: skeletonId };`);
+  if (!skeletonId) { return { success: false, action: 'create_skeleton', error: "the engine returned no skeleton id — createSkeleton does not normally fail, so treat this as a broken rigging subsystem rather than bad input" }; }
+  return { success: true, action: 'create_skeleton', skeletonId: skeletonId };`);
             }
             case 'add_bone': {
                 const config = S({
@@ -5979,13 +6801,15 @@ ${needWorld}
                 });
                 return wrap('Rigging: add bone', `  const boneId = R.addBone(${S(input.skeletonId)}, ${config});
   if (app.historyManager) app.historyManager.saveState();
-  return { success: !!boneId, action: 'add_bone', boneId: boneId };`);
+  if (!boneId) { return { success: false, action: 'add_bone', error: "no such skeleton. Call list_skeletons for the ids that exist" }; }
+  return { success: true, action: 'add_bone', boneId: boneId };`);
             }
             case 'attach_item': {
                 const opts = S(input.attachPoint !== undefined ? { attachPoint: input.attachPoint } : {});
                 return wrap('Rigging: attach item to bone', `  const ok = R.attachItem(${S(input.skeletonId)}, ${S(input.boneId)}, ${S(input.itemId)}, ${opts});
   if (app.historyManager) app.historyManager.saveState();
-  return { success: !!ok, action: 'attach_item', itemId: ${S(input.itemId)}, boneId: ${S(input.boneId)} };`);
+  if (!ok) { return { success: false, action: 'attach_item', error: "no such skeleton, or no such bone on it. list_bones gives the bone ids for a skeleton" }; }
+  return { success: true, action: 'attach_item', itemId: ${S(input.itemId)}, boneId: ${S(input.boneId)} };`);
             }
             case 'create_ik_chain': {
                 const config = S({
@@ -5999,7 +6823,8 @@ ${needWorld}
                 });
                 return wrap('Rigging: create IK chain', `  const chainId = R.createIKChain(${S(input.skeletonId)}, ${config});
   if (app.historyManager) app.historyManager.saveState();
-  return { success: !!chainId, action: 'create_ik_chain', chainId: chainId };`);
+  if (!chainId) { return { success: false, action: 'create_ik_chain', error: "no such skeleton, or fewer than 2 boneIds — a chain needs at least two bones to solve. Call list_bones for the ids on this rig" }; }
+  return { success: true, action: 'create_ik_chain', chainId: chainId };`);
             }
             case 'add_pose_keyframe': {
                 const opts = S({
@@ -6012,7 +6837,8 @@ ${needWorld}
                 });
                 return wrap('Rigging: add pose keyframe', `  const ok = R.addPoseKeyframe(${S(input.skeletonId)}, ${input.time}, ${S(input.pose)}, ${S(input.easing ?? 'linear')}, ${opts});
   if (app.historyManager) app.historyManager.saveState();
-  return { success: !!ok, action: 'add_pose_keyframe', time: ${input.time} };`);
+  if (!ok) { return { success: false, action: 'add_pose_keyframe', error: "no such skeleton, or 'pose' named a saved pose that does not exist. Pass an inline { boneId: angleDeg } map instead, or list_poses for the saved ones" }; }
+  return { success: true, action: 'add_pose_keyframe', time: ${input.time} };`);
             }
             case 'set_target_path': {
                 const opts = S({
@@ -6021,16 +6847,170 @@ ${needWorld}
                 });
                 return wrap('Rigging: set IK target path', `  const ok = R.setTargetPath(${S(input.skeletonId)}, ${S(input.chainId)}, ${S(input.waypoints)}, ${opts});
   if (app.historyManager) app.historyManager.saveState();
-  return { success: !!ok, action: 'set_target_path', chainId: ${S(input.chainId)} };`);
+  if (!ok) { return { success: false, action: 'set_target_path', error: "no such skeleton, no such IK chain on it, or waypoints was not an array. create_ik_chain returns the chainId to use here" }; }
+  return { success: true, action: 'set_target_path', chainId: ${S(input.chainId)} };`);
             }
             case 'save_pose':
                 return wrap('Rigging: save pose', `  const poseId = R.savePose(${S(input.skeletonId)}, ${S(input.name ?? null)});
   if (app.historyManager) app.historyManager.saveState();
-  return { success: !!poseId, action: 'save_pose', poseId: poseId };`);
+  if (!poseId) { return { success: false, action: 'save_pose', error: "no such skeleton. A pose is a snapshot of ITS bone angles, so the skeleton has to exist first — call list_skeletons" }; }
+  return { success: true, action: 'save_pose', poseId: poseId };`);
             case 'save_shape_key':
                 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 };`);
+  if (!shapeKeyId) { return { success: false, action: 'save_shape_key', error: "no such skeleton, or nothing is attached to its bones — a shape key snapshots the attached items, so a bare skeleton has nothing to capture" }; }
+  return { success: true, action: 'save_shape_key', shapeKeyId: shapeKeyId };`);
+            // ── Pose motion. Every case below maps 1:1 to a method that exists on
+            // riggingSystem (or, for stitch_poses, a PinePaper facade) — checked
+            // against the engine source, not against the docs, because the docs have
+            // named tools that were never registered before now.
+            case 'list_skeletons':
+                return wrap('Rigging: list skeletons', `  const skeletons = R.listSkeletons();
+  return { success: true, action: 'list_skeletons', skeletons: skeletons, count: skeletons.length };`);
+            case 'list_bones':
+                // Without this an inline pose is unwritable: a pose is
+                // { boneId: angleDeg } and nothing else returns a bone id.
+                return wrap('Rigging: list bones', `  if (typeof R.listBones !== 'function') { return { success: false, error: 'listBones unavailable — update FxTool' }; }
+  const bones = R.listBones(${S(input.skeletonId)});
+  return { success: true, action: 'list_bones', bones: bones, count: bones.length };`);
+            case 'list_pose_libraries':
+                return wrap('Rigging: list pose libraries', `  return (async function() {
+    if (typeof R.ensurePoseLibraries !== 'function') { return { success: false, error: 'pose libraries unavailable — update FxTool' }; }
+    const names = await R.ensurePoseLibraries();
+    return { success: true, action: 'list_pose_libraries', libraries: names.libraries, transitions: names.transitions };
+  })();`);
+            case 'load_pose_library': {
+                // The libraries used to load only from an editor button, so every
+                // agent ran with none and got null from every preset name. Awaited
+                // here so the guarantee is real rather than dependent on whether a
+                // human happened to click something earlier in the session.
+                const map = input.boneMap ? S(input.boneMap) : 'null';
+                return wrap('Rigging: load a stock pose library', `  return (async function() {
+    if (typeof R.ensurePoseLibraries !== 'function') { return { success: false, error: 'pose libraries unavailable — update FxTool' }; }
+    const avail = await R.ensurePoseLibraries();
+    let boneMap = ${map};
+    if (!boneMap) {
+      boneMap = {};
+      for (const b of (R.listBones ? R.listBones(${S(input.skeletonId)}) : [])) { if (b.name) boneMap[b.name] = b.id; }
+    }
+    const res = R.loadPoseLibrary(${S(input.skeletonId)}, ${S(input.libraryName)}, boneMap);
+    if (!res) { return { success: false, action: 'load_pose_library', error: 'no such library, or none of its bone names matched this rig. Available: ' + avail.libraries.join(', '), available: avail.libraries }; }
+    if (app.historyManager) app.historyManager.saveState();
+    return { success: true, action: 'load_pose_library', library: ${S(input.libraryName)}, poses: res };
+  })();`);
+            }
+            case 'list_poses':
+                return wrap('Rigging: list poses', `  const poses = R.listPoses(${S(input.skeletonId ?? null)});
+  return { success: true, action: 'list_poses', poses: poses, count: poses.length };`);
+            case 'load_pose':
+                return wrap('Rigging: load pose', `  const ok = R.loadPose(${S(input.poseId)});
+  if (app.historyManager) app.historyManager.saveState();
+  if (!ok) { return { success: false, action: 'load_pose', error: "no such pose, or the skeleton it was saved against is gone. list_poses for what is still loadable" }; }
+  return { success: true, action: 'load_pose', poseId: ${S(input.poseId)} };`);
+            case 'interpolate_poses':
+                return wrap('Rigging: interpolate poses', `  const ok = R.interpolatePoses(${S(input.poseIdA)}, ${S(input.poseIdB)}, ${input.t ?? 0.5});
+  if (!ok) { return { success: false, action: 'interpolate_poses', error: "one of the two poses does not exist, or they belong to DIFFERENT skeletons — blending across rigs is not defined. Call list_poses to see which skeleton each belongs to" }; }
+  return { success: true, action: 'interpolate_poses', t: ${input.t ?? 0.5} };`);
+            case 'play_pose_sequence': {
+                const opts = S({
+                    ...(input.loop !== undefined ? { loop: input.loop } : {}),
+                    ...(input.options ?? {}),
+                });
+                return wrap('Rigging: play pose sequence', `  const ok = R.playPoseSequence(${S(input.skeletonId)}, ${S(input.sequence ?? [])}, ${opts});
+  if (!ok) { return { success: false, action: 'play_pose_sequence', error: "no such skeleton, or the sequence was empty. Each key needs a 'pose' id or an inline 'angles' map — call list_poses for the saved ids" }; }
+  return { success: true, action: 'play_pose_sequence', keys: ${(input.sequence ?? []).length} };`);
+            }
+            case 'stop_pose_sequence':
+                return wrap('Rigging: stop pose sequence', `  const ok = R.stopPoseSequence(${S(input.skeletonId)});
+  if (!ok) { return { success: false, action: 'stop_pose_sequence', error: "nothing was playing on that skeleton — this is a no-op rather than a failure" }; }
+  return { success: true, action: 'stop_pose_sequence' };`);
+            case 'stitch_poses': {
+                // The one action on `app` rather than riggingSystem: stitching resolves
+                // saved pose ids and then installs the merged sequence through the
+                // ordinary player, so there is one code path and one thing to scrub.
+                const opts = S({
+                    ...(input.blend !== undefined ? { blend: input.blend } : {}),
+                    ...(input.blendSteps !== undefined ? { blendSteps: input.blendSteps } : {}),
+                    ...(input.matchPhase !== undefined ? { matchPhase: input.matchPhase } : {}),
+                    ...(input.loop !== undefined ? { loop: input.loop } : {}),
+                    ...(input.plan !== undefined ? { plan: input.plan } : {}),
+                    ...(input.options ?? {}),
+                });
+                return wrap('Rigging: stitch pose clips', `  if (typeof app.stitchPoses !== 'function') { return { success: false, error: 'app.stitchPoses unavailable — update FxTool' }; }
+  const res = app.stitchPoses(${S(input.skeletonId)}, ${S(input.clips ?? [])}, ${opts});
+  return Object.assign({ success: !!res.ok, action: 'stitch_poses' }, res);`);
+            }
+            case 'apply_pose_transition':
+                return wrap('Rigging: apply pose transition', `  return (async function() {
+    if (typeof R.ensurePoseLibraries === 'function') { await R.ensurePoseLibraries(); }
+    // A transition names POSES BY NAME, so it needs name → id. Requiring the
+    // caller to build that by hand from list_poses is busywork with one
+    // correct answer, and getting it wrong returns a bare null. Build it here
+    // when it is omitted, exactly as load_pose_library builds its bone map.
+    let poseIdMap = ${input.poseIdMap ? S(input.poseIdMap) : 'null'};
+    if (!poseIdMap || !Object.keys(poseIdMap).length) {
+      poseIdMap = {};
+      for (const pose of (R.listPoses ? R.listPoses(${S(input.skeletonId)}) : [])) { if (pose.name) poseIdMap[pose.name] = pose.id; }
+    }
+    const res = R.applyPoseTransition(${S(input.skeletonId)}, ${S(input.transitionName)}, poseIdMap);
+    if (!res) { return { success: false, action: 'apply_pose_transition', error: "no such transition, or none of its pose names are saved on this skeleton. Load the matching library first (load_pose_library), then retry — the transition plays poses BY NAME." }; }
+    if (app.historyManager) app.historyManager.saveState();
+    return { success: true, action: 'apply_pose_transition', transition: ${S(input.transitionName)} };
+  })();`);
+            case 'auto_walk':
+            case 'auto_breath':
+            case 'auto_idle':
+            case 'auto_jump': {
+                const method = { auto_walk: 'autoWalk', auto_breath: 'autoBreath', auto_idle: 'autoIdle', auto_jump: 'autoJump' }[input.action];
+                // These return null when the rig has no bone the preset recognises BY
+                // NAME, which is a real refusal and not an error — but `result: null`
+                // tells an agent nothing, and a silent nothing is what sends it into a
+                // retry loop. Say which names each one looks for.
+                const needs = {
+                    // autoWalk cycles through SAVED poses named walk_00…walk_07 or
+                    // walk_contact_L/walk_passing_L/… — the ones the `humanoid` library
+                    // saves. It is not a procedural generator, it is a pose player, and
+                    // saying "needs a skeleton" when the skeleton is right there sends an
+                    // agent looking in the wrong place.
+                    auto_walk: "at least 2 saved walk poses (walk_00…, or walk_contact_L / walk_passing_L / walk_contact_R / walk_passing_R). Run load_pose_library with libraryName 'humanoid' (or 'quadruped') first — it saves exactly those",
+                    auto_breath: 'a bone named spine, chest, upper_spine or body',
+                    auto_idle: 'a bone named head, hip, upper_hub or spine',
+                    auto_jump: 'a skeleton, and saved jump poses if you want a posed jump rather than a root arc',
+                };
+                return wrap(`Rigging: ${input.action}`, `  const res = R.${method}(${S(input.skeletonId)}, ${S(input.options ?? {})});
+  if (res && app.historyManager) app.historyManager.saveState();
+  if (!res) { return { success: false, action: ${S(input.action)}, error: ${S(`refused — needs ${needs[input.action]}.`)} }; }
+  return { success: true, action: ${S(input.action)}, result: res };`);
+            }
+            case 'move_root':
+                return wrap('Rigging: root locomotion track', `  const ok = R.moveRoot(${S(input.skeletonId)}, ${S(input.keyframes ?? [])}, ${S(input.options ?? {})});
+  if (!ok) { return { success: false, action: 'move_root', error: "no such skeleton, or keyframes was empty. Each key is { t, x, y } with t in SCENE SECONDS" }; }
+  return { success: true, action: 'move_root', keys: ${(input.keyframes ?? []).length} };`);
+            case 'stop_root_track':
+                return wrap('Rigging: stop root track', `  const ok = R.stopRootTrack(${S(input.skeletonId)});
+  if (!ok) { return { success: false, action: 'stop_root_track', error: "no root track was running on that skeleton — this is a no-op rather than a failure" }; }
+  return { success: true, action: 'stop_root_track' };`);
+            case 'add_secondary_motion':
+                return wrap('Rigging: secondary motion', `  const res = R.addSecondaryMotion(${S(input.skeletonId)}, ${S(input.boneNames ?? [])}, ${S(input.options ?? {})});
+  if (!res) { return { success: false, action: 'add_secondary_motion', error: "no such skeleton, or fewer than 2 of the given bone NAMES resolve on it. A spring chain needs at least two; list_bones for the names this rig uses" }; }
+  return { success: true, action: 'add_secondary_motion', bones: ${(input.boneNames ?? []).length} };`);
+            case 'skin_path':
+                return wrap('Rigging: skin path to bones', `  const res = R.skinPath(${S(input.skeletonId)}, ${S(input.itemId)}, ${S(input.options ?? {})});
+  if (app.historyManager) app.historyManager.saveState();
+  if (!res) { return { success: false, action: 'skin_path', error: "no such skeleton or item, the item is not a path, or no bone is close enough to influence it. Skinning binds vertices to nearby bones, so the path has to overlap the rig — call list_bones to see where they are" }; }
+  return { success: true, action: 'skin_path', itemId: ${S(input.itemId)} };`);
+            case 'bake_animation':
+                return wrap('Rigging: bake animation to keyframes', `  const res = R.bakeAnimation(${S(input.skeletonId)}, ${S(input.options ?? {})});
+  if (res && app.historyManager) app.historyManager.saveState();
+  if (!res) { return { success: false, action: 'bake_animation', error: "nothing to bake — no such skeleton, or no items are ATTACHED to its bones. Baking writes keyframes onto the attached items, so a bare skeleton has no output." }; }
+  return { success: true, action: 'bake_animation', result: res };`);
+            case 'list_shape_keys':
+                return wrap('Rigging: list shape keys', `  const keys = R.listShapeKeys(${S(input.skeletonId)});
+  return { success: true, action: 'list_shape_keys', shapeKeys: keys, count: keys.length };`);
+            case 'load_shape_key':
+                return wrap('Rigging: load shape key', `  const ok = R.loadShapeKey(${S(input.skeletonId)}, ${S(input.shapeKeyId)}, ${input.weight ?? 1});
+  if (!ok) { return { success: false, action: 'load_shape_key', error: "no such skeleton, or no such shape key on it. list_shape_keys for what is saved" }; }
+  return { success: true, action: 'load_shape_key', weight: ${input.weight ?? 1} };`);
             // ── 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