@pinepaper.studio/mcp-server 1.6.6 → 1.6.8

package/dist/types/code-generator.js

@@ -4,8 +4,9 @@
  * Converts MCP tool inputs to executable PinePaper JavaScript code.
  * This code is designed to run in the browser context where window.PinePaper is available.
  */
+import { REQUIRED_ENGINE_METHODS, OPTIONAL_ENGINE_METHODS } from '../tools/engine-methods.js';
 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 +22,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 +98,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 +340,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 +400,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 +504,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 +930,48 @@ 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;
+}
+/**
+ * Largest export the emitted code will hand back as an inline base64 data URL.
+ *
+ * Only reached on a studio with no `app.exportEngine.exportToStore` — with the
+ * store, mp4/webm never base64 in the page at all. Set above what that legacy
+ * path could already deliver (60 s at 8 Mbps is roughly 60 MB, ~80 MB once
+ * base64'd) so raising the duration cap cannot make a previously working
+ * export start refusing; past it the code names the ceiling instead of dying
+ * inside the encode.
+ */
+export const INLINE_MAX_BYTES = 96 * 1024 * 1024;
 export class PinePaperCodeGenerator {
     /**
      * Generate code for creating an item
@@ -781,6 +1009,28 @@ export class PinePaperCodeGenerator {
      */
     generateAddRelation(input) {
         const validated = AddRelationInputSchema.parse(input);
+        // A PRESET decides its own relationType and params, so this is a different
+        // call, not a defaulted one. applyRelationPreset refuses with
+        // `{ok:false, errors:[{field, reason}]}` — a third refusal shape on this
+        // surface, after {ok, reason} and {error} — so the errors are joined rather
+        // than read as a single string, which would render "[object Object]".
+        if (validated.presetId) {
+            return `
+// Adopt relation preset "${validated.presetId}" on ${validated.sourceId}
+(async function() {
+  if (typeof app.applyRelationPreset !== 'function') { return { success: false, error: 'app.applyRelationPreset unavailable — update FxTool' }; }
+  const r = await app.applyRelationPreset(${JSON.stringify(validated.sourceId)}, ${JSON.stringify(validated.presetId)}, ${JSON.stringify(validated.presetValues ?? {})});
+  if (!r || r.ok === false) {
+    const why = (r && Array.isArray(r.errors))
+      ? r.errors.map(function(e) { return e.field + ': ' + e.reason; }).join('; ')
+      : 'the preset did not apply';
+    return { success: false, error: why };
+  }
+  // The preset's own type and resolved values come back, so the caller learns
+  // what it actually adopted rather than only that something worked.
+  return { success: true, presetId: ${JSON.stringify(validated.presetId)}, relationType: r.relationType, params: r.params, values: r.values };
+})();`.trim();
+        }
         return generateAddRelationCode(validated.sourceId, validated.targetId || validated.sourceId, validated.relationType, validated.params);
     }
     /**
@@ -809,6 +1059,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 +1103,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
@@ -997,8 +1268,29 @@ throw new Error('Either svgString or url must be provided');
     };
   }
   const ctx = app.exportCanvasOntology(${optsJson});
+  // SAY WHEN THE ANSWER IS PARTIAL. The engine returns itemCount =
+  // allItems.length (the TRUE total) beside items = allItems.slice(0,
+  // maxItems), and childCount beside a children array capped at maxChildren.
+  // So a caller receives itemCount 800 with 500 items and nothing marking the
+  // gap — an answer indistinguishable from a complete one unless the reader
+  // thinks to compare two fields. That is the silent-refusal shape this repo
+  // has fixed elsewhere; the marker below is the same idiom generateHatching
+  // uses for its 40-path cap.
+  var _shown = Array.isArray(ctx.items) ? ctx.items.length : 0;
+  var _total = typeof ctx.itemCount === 'number' ? ctx.itemCount : _shown;
+  var _clipped = (Array.isArray(ctx.items) ? ctx.items : []).filter(function (i) {
+    return i && typeof i.childCount === 'number' && Array.isArray(i.children)
+      && i.children.length < i.childCount;
+  });
   return {
     success: true,
+    ...(_total > _shown ? { truncated:
+      'showing ' + _shown + ' of ' + _total + ' items. Raise maxItems (up to 500) '
+      + 'to see more; past 500 the scene is truncated rather than paginated, so '
+      + 'narrow with pinepaper_get_items or read a group at a time.' } : {}),
+    ...(_clipped.length ? { childrenTruncated: _clipped.map(function (i) {
+      return i.id + ': ' + i.children.length + ' of ' + i.childCount + ' children';
+    }) } : {}),
     canvasWidth: ctx.canvasWidth,
     canvasHeight: ctx.canvasHeight,
     canvasPreset: ctx.canvasPreset,
@@ -1420,7 +1712,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 +1722,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 +1756,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 +1963,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 +2170,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 +2419,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}' };
 `;
             }
@@ -2161,6 +2469,45 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
     /**
      * Generate code for smart export
      */
+    /**
+     * Read one slice of a held export, base64-encoded.
+     *
+     * The handler calls this in a loop and appends each chunk to the file it was
+     * going to write anyway, so no more than one chunk is ever in memory on
+     * either side of the bridge. Every refusal the engine can give is passed
+     * through untouched — a bad range names the real size, and an id that was
+     * EVICTED to make room says so rather than reporting not-found, because
+     * those are different bugs from the caller's side.
+     */
+    generateReadExportChunk(exportId, offset, length) {
+        const range = { offset };
+        if (typeof length === 'number')
+            range.length = length;
+        return `
+// Read export chunk at ${offset}
+(async function() {
+  if (!app.exportEngine || typeof app.exportEngine.readExport !== 'function') {
+    return { ok: false, reason: 'app.exportEngine.readExport unavailable — update FxTool' };
+  }
+  return await app.exportEngine.readExport(${JSON.stringify(exportId)}, ${JSON.stringify(range)});
+})();`.trim();
+    }
+    /**
+     * Drop a held export once its bytes are safely on disk here.
+     *
+     * Called only after the whole file has been written. A release before that
+     * would be unrecoverable: the store is the only copy.
+     */
+    generateReleaseExport(exportId) {
+        return `
+// Release held export
+(async function() {
+  if (!app.exportEngine || typeof app.exportEngine.releaseExport !== 'function') {
+    return { ok: false, reason: 'app.exportEngine.releaseExport unavailable — update FxTool' };
+  }
+  return await app.exportEngine.releaseExport(${JSON.stringify(exportId)});
+})();`.trim();
+    }
     generateAgentExport(input) {
         const validated = AgentExportInputSchema.parse(input);
         const { platform, format, quality, framing, duration, estimateOnly } = validated;
@@ -2188,6 +2535,76 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
         const preset = platformPresets[platform] || platformPresets['web'];
         // Resolve "auto" format to the platform's recommended format
         const exportFormat = (!format || format === 'auto') ? preset.staticFormat : format;
+        // AUDIO-ONLY EXPORT, off the visual path entirely.
+        //
+        // It takes the OFFLINE renderer, not exportEngine.exportAudio. The latter
+        // is async, needs the videoExporter's Web Audio path, hands back a Blob
+        // that cannot cross page.evaluate, and downloads unless told not to.
+        // renderSoundtrackWav is synchronous, returns bytes, and needs no audio
+        // context — the engine commit that added it is titled "the soundtrack
+        // without Web Audio", and this is the context it was written for.
+        //
+        // No platform preset resolves to wav, so reaching here means it was asked
+        // for by name. Dimensions, framing, fps and bitrate are all absent rather
+        // than passed and ignored.
+        // @engine-methods renderSoundtrackWav exportEngine.sceneHasAudio
+        if (exportFormat === 'wav') {
+            const sr = validated.sampleRate ?? 48000;
+            const bd = validated.bitDepth ?? 16;
+            return `
+// Export: the soundtrack on its own, rendered offline
+(function() {
+  if (typeof app.renderSoundtrackWav !== 'function') {
+    return { success: false, format: 'wav', error: 'app.renderSoundtrackWav unavailable — update FxTool. This build cannot export audio on its own; mp4/webm still mux the soundtrack into the video.' };
+  }
+  // EXACT, not estimated. Uncompressed PCM is header + rate x bytes x channels
+  // x seconds, so a model is not needed and would only be less true. The mix
+  // is mono — the engine encodes a single channel.
+  var exact = 44 + Math.round(${sr} * (${bd} / 8) * 1 * ${videoDuration});
+  if (${estimateOnly ? 'true' : 'false'}) {
+    return { success: true, estimateOnly: true, format: 'wav', bytes: exact,
+      expected: exact, confidence: 'exact',
+      note: 'uncompressed PCM: ' + ${videoDuration} + 's at ' + ${sr} + ' Hz, ' + ${bd} + '-bit mono' };
+  }
+  var r = app.renderSoundtrackWav({ duration: ${videoDuration}, sampleRate: ${sr}, bitDepth: ${bd} });
+  if (!r || !r.wav) {
+    // WHY IT IS EMPTY, NOT JUST THAT IT IS. The offline renderer bakes
+    // SYNTHESIZED sounds only, while the engine's sceneHasAudio() counts
+    // uploaded audio files too. A scene carrying an uploaded track would
+    // otherwise be told it has no audio, which is false and sends the caller
+    // to add a sound they already have.
+    var anyAudio = null;
+    try {
+      if (app.exportEngine && typeof app.exportEngine.sceneHasAudio === 'function') {
+        anyAudio = app.exportEngine.sceneHasAudio();
+      }
+    } catch (_) { /* predicate absent — fall back to the generic answer */ }
+    return {
+      success: false, format: 'wav',
+      error: anyAudio === true
+        ? 'this scene has audio, but it is uploaded file(s) rather than synthesized sounds, and the offline renderer bakes only what it can synthesize. Export mp4 or webm to get that audio muxed with the picture.'
+        : 'no synthesized sounds are placed on this scene, so there is no soundtrack to render. Create one with pinepaper_sound action "create", or place an existing one with "set_placement".',
+      sceneHasAudio: anyAudio,
+    };
+  }
+  var bytes = r.wav;
+  // Chunked: String.fromCharCode.apply over a multi-megabyte array blows the
+  // stack, and a ten-minute soundtrack is tens of megabytes.
+  var bin = '';
+  for (var i = 0; i < bytes.length; i += 8192) {
+    bin += String.fromCharCode.apply(null, bytes.subarray(i, i + 8192));
+  }
+  return {
+    success: true, format: 'wav', platform: '${platform}',
+    data: 'data:audio/wav;base64,' + btoa(bin),
+    size: bytes.length,
+    duration: r.duration, sampleRate: r.sampleRate, sounds: r.sounds, placed: r.placed,
+    // A mix that dropped sounds is a valid file quietly missing tracks.
+    ...(r.dropped > 0 ? { dropped: r.dropped, incomplete:
+      'mixed ' + r.placed + ' sound(s); ' + r.dropped + ' could not be rendered and are absent from this file' } : {}),
+  };
+})();`.trim();
+        }
         return `
 // Smart export for ${platform}
 (async function() {
@@ -2227,7 +2644,12 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
 
   // 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
+  // (mirrors the camera-view framing block in FxTool's
+  // ExportEngine.showVideoExportOptions). Cited by METHOD, not by line: the
+  // previous citation named a line range that had rotted to point at
+  // DPI/canvas-size code in a file nobody here edits. A cross-file line range
+  // cannot be kept accurate — it breaks on any edit above it — so this repo
+  // does not use them. Camera animation still
   // drives motion during export — framing only fixes the output frame.
   let cameraDims = null;
   if (framing === 'camera') {
@@ -2312,32 +2734,110 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
           r.onloadend = () => resolve(r.result);
           r.readAsDataURL(b);
         });
+
+        // THE EXPORT STORE. A long export cannot come back as one base64
+        // string: base64 of a gigabyte is larger than the gigabyte, and it
+        // crosses the browser→server bridge as a single page.evaluate return
+        // value. exportToStore() streams the encode straight to the studio's
+        // origin-private store and hands back an id, so the bytes stay on disk
+        // and the handler pages them into the file it was going to write
+        // anyway. mp4/webm ALWAYS land in a file on the server side, so there
+        // is no size at which building a data URL for them is worth doing —
+        // the id goes back at every size and nothing is base64'd in the page.
+        // gif is refused by name by the store (it has its own encoder and
+        // never streams), so gif keeps the buffered path below.
+        const store = (app.exportEngine
+          && typeof app.exportEngine.exportToStore === 'function'
+          && typeof app.exportEngine.readExport === 'function')
+          ? app.exportEngine : null;
+
+        if (store && format !== 'gif') {
+          const stored = await store.exportToStore({
+            format,
+            duration: baseVideoSettings.duration,
+            fps: settings.fps,
+            // A NUMBER, not the quality tier's name. _calculateBitrate
+            // multiplies by it, and a non-finite value used to survive its
+            // Math.max(100000, NaN) "floor" all the way to
+            // VideoEncoder.configure.
+            quality: settings.compression,
+            width: cameraDims ? cameraDims.width : dimensions.width,
+            height: cameraDims ? cameraDims.height : dimensions.height,
+          });
+          if (!stored || stored.ok === false) {
+            result = { success: false, platform, format, error: (stored && stored.reason) || 'the export store refused the export without saying why' };
+          } else {
+            let chunkBytes = 4 * 1024 * 1024;
+            try {
+              const declared = app.exportEngine.constructor && app.exportEngine.constructor.EXPORT_CHUNK_BYTES;
+              if (typeof declared === 'number' && declared > 0) chunkBytes = declared;
+            } catch (_) { /* keep the default */ }
+            result = {
+              success: true, platform, framing,
+              // Trust the container the store reports over the one asked for:
+              // mp4 falls back to WebM without WebCodecs, and WebM bytes named
+              // .mp4 fail in container-validating players.
+              format: stored.format || format,
+              retained: true,
+              exportId: stored.exportId,
+              mimeType: stored.mimeType || videoMimeType,
+              size: stored.size,
+              chunkBytes: chunkBytes,
+              dimensions: cameraDims || dimensions,
+            };
+          }
+          break;
+        }
+
+        // NO EXPORT STORE ON THIS STUDIO, or gif. Both remaining failures are
+        // named rather than left to blow up: a streamed export hands back a
+        // marker instead of a Blob and FileReader throws on it, and an export
+        // past the inline ceiling used to die somewhere in the base64 rather
+        // than say so. The ceiling sits above what this path could already do
+        // (60 s at 8 Mbps is roughly 60 MB) so nothing that works today starts
+        // refusing.
+        const INLINE_MAX_BYTES = ${INLINE_MAX_BYTES};
+        const mb = (n) => (n / (1024 * 1024)).toFixed(1);
+        const deliver = async (blob) => {
+          if (!blob || typeof blob.size !== 'number' || typeof blob.slice !== 'function') {
+            return {
+              success: false, platform, format,
+              error: 'this export streamed to a file instead of returning bytes, and this studio has no app.exportEngine.exportToStore to page it back from — update FxTool for long-form export',
+            };
+          }
+          if (blob.size > INLINE_MAX_BYTES) {
+            return {
+              success: false, platform, format, size: blob.size,
+              error: 'export is ' + mb(blob.size) + ' MB, over the ' + mb(INLINE_MAX_BYTES)
+                + ' MB inline ceiling, and this studio has no app.exportEngine.exportToStore to page it out of — update FxTool, or lower duration/quality',
+            };
+          }
+          return { success: true, platform, format, framing, data: await blobToDataUrl(blob), mimeType: videoMimeType, size: blob.size };
+        };
+
         // Camera framing requires going direct to videoExporter so width/height
         // pass through — _quickExportVideo strips dim fields.
         if (cameraDims && app.exportEngine && app.exportEngine.videoExporter) {
           const blob = await app.exportEngine.videoExporter.export({ ...baseVideoSettings, width: cameraDims.width, height: cameraDims.height });
-          const dataUrl = await blobToDataUrl(blob);
-          result = { success: true, platform, format, framing, data: dataUrl, mimeType: videoMimeType, size: blob.size, dimensions: cameraDims };
+          result = await deliver(blob);
+          if (result.success) result.dimensions = cameraDims;
         } else if ((format === 'mp4' || format === 'webm') && app.exportEngine && app.exportEngine.videoExporter) {
           // Bypass _quickExportVideo for mp4/webm — it hardcodes
           // quality:undefined for these formats and produces a NaN bitrate.
           const blob = await app.exportEngine.videoExporter.export(baseVideoSettings);
-          const dataUrl = await blobToDataUrl(blob);
-          result = { success: true, platform, format, framing, data: dataUrl, mimeType: videoMimeType, size: blob.size };
+          result = await deliver(blob);
         } else if (app.exportEngine && app.exportEngine._quickExportVideo) {
           // GIF path (working): _quickExportVideo forwards gifQuality to
           // gif.js. Also serves as the fallback if videoExporter is absent.
           const videoResult = await app.exportEngine._quickExportVideo(format, baseVideoSettings, false);
           if (videoResult && videoResult.blob) {
-            const dataUrl = await blobToDataUrl(videoResult.blob);
-            result = { success: true, platform, format, framing, data: dataUrl, mimeType: videoMimeType, size: videoResult.blob.size };
+            result = await deliver(videoResult.blob);
           } else {
             result = { success: false, error: format.toUpperCase() + ' export returned no data' };
           }
         } else if (app.exportEngine && app.exportEngine.videoExporter) {
           const blob = await app.exportEngine.videoExporter.export(baseVideoSettings);
-          const dataUrl = await blobToDataUrl(blob);
-          result = { success: true, platform, format, framing, data: dataUrl, mimeType: videoMimeType, size: blob.size };
+          result = await deliver(blob);
         } else {
           result = { success: false, error: format.toUpperCase() + ' export not available' };
         }
@@ -3618,6 +4118,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 +4564,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 +5005,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 +5272,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,49 +5445,260 @@ ${resolve}
                 return `(function() { return { error: 'Unknown query action: ${input.action}' }; })();`;
         }
     }
-    // ===========================================================================
-    // DEFORMATION
-    // ===========================================================================
-    generateDeform(input) {
-        const guard = `if (!app.deformPresets) return { error: 'DeformPresets not available' };`;
-        switch (input.action) {
-            case 'apply': {
-                if (!input.itemId)
-                    return `(function() { return { error: 'itemId is required for deform apply' }; })();`;
-                if (!input.preset)
-                    return `(function() { return { error: 'preset is required for deform apply' }; })();`;
-                const params = {};
-                if (input.frequency !== undefined)
-                    params.frequency = input.frequency;
-                if (input.amplitude !== undefined)
-                    params.amplitude = input.amplitude;
-                if (input.phase)
-                    params.phase = input.phase;
-                if (input.loop !== undefined)
-                    params.loop = input.loop;
-                if (input.axis)
-                    params.axis = input.axis;
-                if (input.turns !== undefined)
-                    params.turns = input.turns;
-                if (input.waves !== undefined)
-                    params.waves = input.waves;
-                if (input.maxDisplacement !== undefined)
-                    params.maxDisplacement = input.maxDisplacement;
-                if (input.speed !== undefined)
-                    params.speed = input.speed;
-                if (input.steps !== undefined)
-                    params.steps = input.steps;
-                const itemIdStr = JSON.stringify(input.itemId);
-                return `
-// Apply deformation preset
-(function() {
-  ${guard}
-  const entry = app.itemRegistry.get(${itemIdStr});
-  if (!entry || !entry.item) return { error: 'Item not found: ' + ${itemIdStr} };
-  app.deformPresets.apply(entry.item, '${input.preset}', ${JSON.stringify(params)});
-  return { success: true, action: 'apply', itemId: ${itemIdStr}, preset: '${input.preset}' };
-})();`.trim();
-            }
+    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)};
+
+  // WHICH ENGINE METHODS THIS STUDIO HAS.
+  //
+  // Every tool guards the methods it needs and refuses by name without them,
+  // which is right per call and useless in advance: an agent otherwise learns a
+  // studio is too old one tool at a time. getCapabilities cannot answer this —
+  // it reports the engine's VOCABULARY (styles, palettes, relations), not which
+  // of its methods exist.
+  //
+  // The list is DERIVED from the emitters' own guards by
+  // scripts/sync-engine-methods.mjs, so it cannot drift from what the tools
+  // actually check. Required and optional are kept apart because an older
+  // studio that degrades is not an unusable one.
+  if (action === 'studio') {
+    const required = ${S(REQUIRED_ENGINE_METHODS)};
+    const optional = ${S(OPTIONAL_ENGINE_METHODS)};
+    const has = (path) => {
+      // Dotted paths: thirteen methods live behind a sub-facade
+      // (exportEngine.exportToStore, mapSystem.worldTour).
+      let node = app;
+      for (const part of path.split('.')) {
+        if (!node) return false;
+        node = node[part];
+      }
+      return typeof node === 'function';
+    };
+    const missingRequired = required.filter((m) => !has(m));
+    const missingOptional = optional.filter((m) => !has(m));
+    return {
+      success: true,
+      studio: {
+        requiredTotal: required.length,
+        requiredPresent: required.length - missingRequired.length,
+        missingRequired: missingRequired,
+        optionalTotal: optional.length,
+        missingOptional: missingOptional,
+        // A studio missing nothing required can serve every tool this server
+        // publishes. Missing something optional only narrows an answer.
+        complete: missingRequired.length === 0,
+      },
+    };
+  }
+
+  // The registries getCapabilities does NOT aggregate. Each is a capability an
+  // agent otherwise has to guess at, which by this project's rule is the same
+  // as its not existing. Read one at a time and name a missing facade rather
+  // than answering with an empty list, which would read as "none exist".
+  if (action === 'catalogue') {
+    const READERS = {
+      rig_presets: 'listRigPresets', shader_effects: 'listShaderEffects',
+      stroke_decorations: 'listStrokeDecorations', precomps: 'listPrecomps',
+      images: 'listImages', segment_edit_kinds: 'listSegmentEditKinds',
+      shatter_orders: 'listShatterOrders', world_meshes: 'listWorldMeshes',
+      relation_presets: 'loadRelationPresets',
+    };
+    const want = ${S(validated.catalogue)};
+    const fn = READERS[want];
+    if (!fn) { return { success: false, error: 'unknown catalogue ' + JSON.stringify(want) + ' — try ' + Object.keys(READERS).join(', ') }; }
+    if (typeof app[fn] !== 'function') { return { success: false, error: 'app.' + fn + ' unavailable — update FxTool' }; }
+    const entries = await app[fn]();
+    // loadRelationPresets answers {presets, rejected, source} rather than a bare
+    // array, and REJECTED is the half worth surfacing: a preset this build
+    // cannot use is a named absence, where dropping it silently would read as
+    // the catalogue simply being smaller.
+    if (entries && !Array.isArray(entries) && Array.isArray(entries.presets)) {
+      return {
+        success: true, catalogue: want, reader: 'app.' + fn,
+        count: entries.presets.length, entries: entries.presets,
+        rejected: entries.rejected || [], source: entries.source || null,
+      };
+    }
+    return { success: true, catalogue: want, reader: 'app.' + fn, count: Array.isArray(entries) ? entries.length : undefined, entries: entries };
+  }
+
+  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
+    // ===========================================================================
+    generateDeform(input) {
+        const guard = `if (!app.deformPresets) return { error: 'DeformPresets not available' };`;
+        switch (input.action) {
+            case 'apply': {
+                if (!input.itemId)
+                    return `(function() { return { error: 'itemId is required for deform apply' }; })();`;
+                if (!input.preset)
+                    return `(function() { return { error: 'preset is required for deform apply' }; })();`;
+                const params = {};
+                if (input.frequency !== undefined)
+                    params.frequency = input.frequency;
+                if (input.amplitude !== undefined)
+                    params.amplitude = input.amplitude;
+                if (input.phase)
+                    params.phase = input.phase;
+                if (input.loop !== undefined)
+                    params.loop = input.loop;
+                if (input.axis)
+                    params.axis = input.axis;
+                if (input.turns !== undefined)
+                    params.turns = input.turns;
+                if (input.waves !== undefined)
+                    params.waves = input.waves;
+                if (input.maxDisplacement !== undefined)
+                    params.maxDisplacement = input.maxDisplacement;
+                if (input.speed !== undefined)
+                    params.speed = input.speed;
+                if (input.steps !== undefined)
+                    params.steps = input.steps;
+                const itemIdStr = JSON.stringify(input.itemId);
+                return `
+// Apply deformation preset
+(function() {
+  ${guard}
+  const entry = app.itemRegistry.get(${itemIdStr});
+  if (!entry || !entry.item) return { error: 'Item not found: ' + ${itemIdStr} };
+  app.deformPresets.apply(entry.item, '${input.preset}', ${JSON.stringify(params)});
+  return { success: true, action: 'apply', itemId: ${itemIdStr}, preset: '${input.preset}' };
+})();`.trim();
+            }
             case 'trigger': {
                 if (!input.itemId)
                     return `(function() { return { error: 'itemId is required for deform trigger' }; })();`;
@@ -5227,6 +6196,7 @@ ${resolve}
      * (bringToFront / sendToBack / bringForward / sendBackward).
      */
     generateArrange(input) {
+        // @engine-methods bringToFront sendToBack bringForward sendBackward
         const method = {
             front: 'bringToFront',
             back: 'sendToBack',
@@ -5465,9 +6435,41 @@ ${resolve}
         }).compile(input.doc);
         const opsJson = JSON.stringify(ops, null, 2);
         const diagJson = JSON.stringify(diagnostics);
+        const docJson = JSON.stringify(input.doc);
+        // awaitImages: the studio decorates a raster (fit, keyframes, mask) on its
+        // 'load' event and re-runs its finalize steps when the last one lands; a
+        // tool call that screenshots next wants that to have happened.
+        const engineOptsJson = JSON.stringify({ canvas: input.canvas, defaultGeometry: input.defaultGeometry, awaitImages: true });
         return `
 // Instantiate ontology → scene (${ops.filter((o) => o.op === 'create').length} items, ${ops.filter((o) => o.op === 'addRelation').length} relations)
-(function() {
+(async function() {
+  // Engine door first: the studio's own OntologyCompiler reads every node facet
+  // (geometry, paint, text, the keyframe track, masks) and builds through the
+  // template loader's paths — the round trip the studio's pixel tests verify
+  // (e2e/graph-instantiate-parity.spec.js). The server-side compile above is
+  // kept for the diagnostics preview and for studios that predate the facade,
+  // which get the box loop below and a note saying so.
+  const doc = ${docJson};
+  if (typeof app.instantiateOntology === 'function') {
+    const r = await app.instantiateOntology(doc, ${engineOptsJson});
+    const diags = r.diagnostics || [];
+    return {
+      success: !diags.some(function(d) { return d && d.level === 'error'; }) && !r.imagesFailed,
+      engine: 'studio',
+      itemIds: r.itemIds, itemCount: r.itemIds.length,
+      // Every count the engine returns, not a chosen three. imagesFailed is the
+      // one that matters most: a raster that never decoded leaves a scene that
+      // looks built and is not, and dropping the count is how that becomes
+      // invisible. relationsApplied and connectorsApplied are the only way to
+      // tell "the doc declared no edges" from "the edges did not bind".
+      keyframesApplied: r.keyframesApplied, masksApplied: r.masksApplied, deferred: r.deferred,
+      relationsApplied: r.relationsApplied, connectorsApplied: r.connectorsApplied,
+      interactionsApplied: r.interactionsApplied, effectsApplied: r.effectsApplied,
+      groupsCreated: r.groupsCreated, nested: r.nested,
+      imagesFailed: r.imagesFailed, backgroundApplied: r.backgroundApplied, duration: r.duration,
+      diagnostics: diags, errors: [],
+    };
+  }
   if (typeof app.create !== 'function' || typeof app.addRelation !== 'function') {
     return { success: false, error: 'app.create / app.addRelation unavailable' };
   }
@@ -5488,7 +6490,7 @@ ${resolve}
     }
   }
   if (app.historyManager) app.historyManager.saveState();
-  return { success: errors.length === 0, itemIds: itemIds, itemCount: itemIds.length, diagnostics: diagnostics, errors: errors };
+  return { success: errors.length === 0, engine: 'server-box', note: 'this studio predates app.instantiateOntology: items were placed as boxes without paint, text, keyframes or masks', itemIds: itemIds, itemCount: itemIds.length, diagnostics: diagnostics, errors: errors };
 })();`.trim();
     }
     /**
@@ -5709,6 +6711,243 @@ ${guard}
     palettes: typeof app.listTextPalettes === 'function' ? app.listTextPalettes() : [],
     fontAxes: typeof app.listFontAxes === 'function' ? app.listFontAxes() : null,
   };
+})();`.trim();
+            }
+            case 'cursive':
+                return `
+// Text: write it as STROKED handwriting — a path, not a glyph
+(function() {
+  if (typeof app.createCursiveText !== 'function') { return { success: false, error: 'app.createCursiveText unavailable — update FxTool' }; }
+  const item = app.createCursiveText(${S(input.text)}, ${S(input.cursiveOptions ?? {})});
+  if (!item) { return { success: false, error: 'the cursive text produced no path' }; }
+  return { success: true, itemId: item.data && item.data.id };
+})();`.trim();
+            case 'wrap':
+                return `
+// Text: break to a width — reversibly
+(function() {
+  if (typeof app.wrapText !== 'function') { return { success: false, error: 'app.wrapText unavailable — update FxTool' }; }
+  const r = app.wrapText(${S(input.itemId)}, ${S(input.maxWidth)});
+  if (!r || r.ok === false) { return { success: false, error: (r && r.error) || 'that item could not be wrapped' }; }
+  return { success: true, ...r };
+})();`.trim();
+            case 'unwrap':
+                return `
+// Text: restore the single line wrap replaced
+(function() {
+  if (typeof app.unwrapText !== 'function') { return { success: false, error: 'app.unwrapText unavailable — update FxTool' }; }
+  // 'not wrapped' is the engine's own refusal and is more useful than
+  // anything this layer could infer, so it is passed through.
+  const r = app.unwrapText(${S(input.itemId)});
+  if (!r || r.ok === false) { return { success: false, error: (r && r.error) || 'that item is not wrapped' }; }
+  return { success: true, ...r };
+})();`.trim();
+            case 'to_collage':
+                return `
+// Text: turn an EXISTING text item into a letter collage, in place
+(function() {
+  if (typeof app.convertTextToCollage !== 'function') { return { success: false, error: 'app.convertTextToCollage unavailable — update FxTool' }; }
+  const item = app.getItemById ? app.getItemById(${S(input.itemId)}) : null;
+  if (!item) { return { success: false, error: 'no such item: ' + ${S(input.itemId)} }; }
+  // Returns null when there is no letterCollage subsystem — a bare null that
+  // would otherwise read as "the conversion did nothing to your text".
+  const r = app.convertTextToCollage(item, ${S(input.text ?? null)} || item.content, ${S(input.collageOptions ?? {})});
+  if (!r) { return { success: false, error: 'the collage system is unavailable in this build, so the text was left as it was' }; }
+  return { success: true, collage: r };
+})();`.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 } : {}),
+                    ...(input.slant !== undefined ? { slant: input.slant } : {}),
+                    ...(input.overlap !== undefined ? { overlap: input.overlap } : {}),
+                    ...(input.stagger !== undefined ? { stagger: input.stagger } : {}),
+                    ...(input.gapLen !== undefined ? { gapLen: input.gapLen } : {}),
+                    ...(input.gridSize !== undefined ? { gridSize: input.gridSize } : {}),
+                });
+                const roughStr = JSON.stringify(input.roughness ?? 0);
+                const seedStr = JSON.stringify(input.seed ?? 1);
+                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.)' }; }
+  // HAND WOBBLE, applied here rather than in the engine, which has no such
+  // option. Every point of every stitch gets its own phase off the seed, so a
+  // long contour wobbles along its whole length instead of shearing at one end,
+  // and the same seed sews the same irregularities every run.
+  const rough = ${roughStr};
+  if (rough > 0 && g.children) {
+    const rseed = ${seedStr};
+    for (let i = 0; i < g.children.length; i++) {
+      const line = g.children[i];
+      if (!line || !line.segments) continue;
+      for (let j = 0; j < line.segments.length; j++) {
+        line.segments[j].point.x += Math.sin(rseed + i * 2.13 + j * 1.71) * rough * 0.4;
+        line.segments[j].point.y += Math.cos(rseed + i * 3.47 + j * 2.29) * rough * 0.4;
+      }
+    }
+  }
+  return { success: true, action: 'apply_thread', groupId: (g.data && g.data.id) || null, stitches: g.children.length, roughness: rough };`);
+            }
+            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();
             }
         }
@@ -5914,6 +7153,761 @@ ${needWorld}
 (function() {
   if (typeof app.removeWorld3D !== 'function') { return { success: false, error: 'app.removeWorld3D unavailable — update FxTool' }; }
   return { success: !!app.removeWorld3D() };
+})();`.trim();
+            // --- Mesh authoring ---------------------------------------------------
+            // extrudeToMesh / latheToMesh REFUSE by name when there is no world
+            // ({ok:false, reason}), so their reason is passed through rather than
+            // pre-empted with a second wording for the same condition. The facade
+            // check stays, because a studio without the method is a different fault.
+            case 'extrude_path':
+            case 'lathe_path': {
+                const fn = input.action === 'extrude_path' ? 'extrudeToMesh' : 'latheToMesh';
+                const mesh = { ...(input.mesh ?? {}) };
+                // rotY is RADIANS on this path — stored raw and handed to cos()/sin()
+                // in the shader. rotYDegrees is the convenience spelling and is folded
+                // in here so only one of them ever reaches the engine.
+                if (typeof mesh.rotYDegrees === 'number') {
+                    if (mesh.rotY === undefined)
+                        mesh.rotY = mesh.rotYDegrees * Math.PI / 180;
+                    delete mesh.rotYDegrees;
+                }
+                return `
+// World3D: ${input.action} — a canvas path becomes real geometry
+(async function() {
+  // @engine-methods extrudeToMesh latheToMesh importOBJToWorld importGLTFToWorld
+  if (typeof app.${fn} !== 'function') { return { success: false, error: 'app.${fn} unavailable — update FxTool to a world3d-capable build' }; }
+  const r = await app.${fn}(${S(input.pathId)}, ${S(mesh)});
+  if (!r || r.ok === false) { return { success: false, error: (r && r.reason) || 'the world refused the mesh' }; }
+  return { success: true, meshId: r.id, op: ${S(input.action === 'extrude_path' ? 'extrude' : 'lathe')}, sourceId: ${S(input.pathId)} };
+})();`.trim();
+            }
+            case 'list_meshes':
+                return `
+// World3D: every authored mesh on the stage
+(function() {
+  if (typeof app.listWorldMeshes !== 'function') { return { success: false, error: 'app.listWorldMeshes unavailable — update FxTool' }; }
+  return { success: true, meshes: app.listWorldMeshes() };
+})();`.trim();
+            case 'remove_mesh':
+                return `
+// World3D: drop a mesh
+(function() {
+  if (typeof app.removeWorldMesh !== 'function') { return { success: false, error: 'app.removeWorldMesh unavailable — update FxTool' }; }
+  return { success: !!app.removeWorldMesh(${S(input.meshId)}) };
+})();`.trim();
+            // --- Lights -----------------------------------------------------------
+            // addWorldLight THROWS when there is no world, so this one is guarded
+            // ahead of the call rather than reading a refusal back.
+            case 'add_light':
+                return `
+// World3D: add a point light — at most 8, and the ninth is refused by name
+(function() {
+  if (typeof app.addWorldLight !== 'function') { return { success: false, error: 'app.addWorldLight unavailable — update FxTool' }; }
+${needWorld}
+  const r = app.addWorldLight(${S(input.light ?? {})});
+  if (!r || r.ok === false) { return { success: false, error: (r && r.error) || 'the world refused the light' }; }
+  return { success: true, lightId: r.id, light: r.light };
+})();`.trim();
+            case 'set_light':
+                return `
+// World3D: edit a light in place
+(function() {
+  if (typeof app.setWorldLight !== 'function') { return { success: false, error: 'app.setWorldLight unavailable — update FxTool' }; }
+  return { success: !!app.setWorldLight(${S(input.lightId)}, ${S(input.light ?? {})}) };
+})();`.trim();
+            case 'remove_light':
+                return `
+// World3D: drop a light
+(function() {
+  if (typeof app.removeWorldLight !== 'function') { return { success: false, error: 'app.removeWorldLight unavailable — update FxTool' }; }
+  return { success: !!app.removeWorldLight(${S(input.lightId)}) };
+})();`.trim();
+            case 'list_lights':
+                return `
+// World3D: every light, with position, colour, intensity and range
+(function() {
+  if (typeof app.listWorldLights !== 'function') { return { success: false, error: 'app.listWorldLights unavailable — update FxTool' }; }
+  return { success: true, lights: app.listWorldLights() };
+})();`.trim();
+            // --- Materials --------------------------------------------------------
+            case 'add_material':
+                return `
+// World3D: a named, SHARED surface — one edit restyles every object using it
+(function() {
+  if (typeof app.addWorldMaterial !== 'function') { return { success: false, error: 'app.addWorldMaterial unavailable — update FxTool' }; }
+${needWorld}
+  const r = app.addWorldMaterial(${S(input.material ?? {})});
+  if (!r || r.ok === false) { return { success: false, error: (r && r.error) || 'the world refused the material' }; }
+  return { success: true, materialId: r.id, material: r.material };
+})();`.trim();
+            case 'set_material':
+                return `
+// World3D: patch a material — every object referencing it changes next frame
+(function() {
+  if (typeof app.setWorldMaterial !== 'function') { return { success: false, error: 'app.setWorldMaterial unavailable — update FxTool' }; }
+  return { success: !!app.setWorldMaterial(${S(input.materialId)}, ${S(input.material ?? {})}) };
+})();`.trim();
+            case 'remove_material':
+                return `
+// World3D: drop a material
+(function() {
+  if (typeof app.removeWorldMaterial !== 'function') { return { success: false, error: 'app.removeWorldMaterial unavailable — update FxTool' }; }
+  return { success: !!app.removeWorldMaterial(${S(input.materialId)}) };
+})();`.trim();
+            case 'list_materials':
+                return `
+// World3D: every material, with the knobs that actually render
+(function() {
+  if (typeof app.listWorldMaterials !== 'function') { return { success: false, error: 'app.listWorldMaterials unavailable — update FxTool' }; }
+  return { success: true, materials: app.listWorldMaterials() };
+})();`.trim();
+            // --- Import -----------------------------------------------------------
+            // Both importers THROW when there is no world, so both are guarded ahead.
+            case 'import_obj':
+            case 'import_gltf': {
+                const fn = input.action === 'import_obj' ? 'importOBJToWorld' : 'importGLTFToWorld';
+                return `
+// World3D: ${input.action}
+(async function() {
+  // @engine-methods extrudeToMesh latheToMesh importOBJToWorld importGLTFToWorld
+  if (typeof app.${fn} !== 'function') { return { success: false, error: 'app.${fn} unavailable — update FxTool to a world3d-capable build' }; }
+${needWorld}
+  const r = await app.${fn}(${S(input.source)}, ${S(input.importOptions ?? {})});
+  if (!r || r.ok === false) { return { success: false, error: (r && (r.error || r.reason)) || 'the world refused the import' }; }
+  return { success: true, meshIds: r.ids, ...r };
+})();`.trim();
+            }
+            case 'list_mesh_clips':
+                return `
+// World3D: the animation clips an imported skinned mesh carries
+(function() {
+  if (typeof app.listWorldMeshClips !== 'function') { return { success: false, error: 'app.listWorldMeshClips unavailable — update FxTool' }; }
+${needWorld}
+  return { success: true, clips: app.listWorldMeshClips(${S(input.meshId)}) };
+})();`.trim();
+            case 'set_mesh_clip':
+                return `
+// World3D: choose which clip a skinned mesh plays
+(function() {
+  if (typeof app.setWorldMeshClip !== 'function') { return { success: false, error: 'app.setWorldMeshClip unavailable — update FxTool' }; }
+${needWorld}
+  return { success: !!app.setWorldMeshClip(${S(input.meshId)}, ${S(input.clip)}${input.crossfade !== undefined ? `, { crossfade: ${S(input.crossfade)} }` : ''}) };
+})();`.trim();
+            // --- Navigation, picking, camera --------------------------------------
+            // These facades answer `null` — or 0, for groundHeightAt — when there is
+            // NO WORLD, which is indistinguishable from a real answer: ground really
+            // can be at height 0, and a ray really can hit nothing. Guarded ahead so
+            // "there is no world" never arrives disguised as a measurement.
+            case 'set_nav_target':
+                return `
+// World3D: point the pointer at the 2D canvas or the 3D world
+(function() {
+  if (typeof app.setWorldNavTarget !== 'function') { return { success: false, error: 'app.setWorldNavTarget unavailable — update FxTool' }; }
+  const r = app.setWorldNavTarget(${S(input.navTarget)});
+  if (!r || r.ok === false) { return { success: false, error: (r && r.error) || 'the nav target was refused' }; }
+  return { success: true, navTarget: ${S(input.navTarget)} };
+})();`.trim();
+            case 'get_nav_target':
+                return `
+// World3D: which layer the pointer currently drives
+(function() {
+  if (typeof app.getWorldNavTarget !== 'function') { return { success: false, error: 'app.getWorldNavTarget unavailable — update FxTool' }; }
+  return { success: true, navTarget: app.getWorldNavTarget() };
+})();`.trim();
+            case 'ground_height':
+                return `
+// World3D: the terrain height under a world (x, z)
+(function() {
+  if (typeof app.groundHeightAt !== 'function') { return { success: false, error: 'app.groundHeightAt unavailable — update FxTool' }; }
+${needWorld}
+  const p = ${S(input.point)};
+  return { success: true, height: app.groundHeightAt(p.x, p.z !== undefined ? p.z : p.y) };
+})();`.trim();
+            case 'raycast':
+                return `
+// World3D: cast a ray and report what it hits
+(function() {
+  if (typeof app.raycastWorld !== 'function') { return { success: false, error: 'app.raycastWorld unavailable — update FxTool' }; }
+${needWorld}
+  const hit = app.raycastWorld(${S(input.origin)}, ${S(input.direction)}, {});
+  // A null here means MISSED, not "no world" — the guard above already
+  // separated those two, which is the whole reason it is there.
+  return { success: true, hit: hit || null, missed: !hit };
+})();`.trim();
+            case 'dolly_camera':
+                return `
+// World3D: dolly the camera — >1 away, <1 closer
+(function() {
+  if (typeof app.dollyWorldCamera !== 'function') { return { success: false, error: 'app.dollyWorldCamera unavailable — update FxTool' }; }
+${needWorld}
+  return { success: true, camera: app.dollyWorldCamera(${S(input.multiplier)}) };
+})();`.trim();
+            case 'pan_camera':
+                return `
+// World3D: pan the camera across the ground, in SCREEN pixels
+(function() {
+  if (typeof app.panWorldCamera !== 'function') { return { success: false, error: 'app.panWorldCamera unavailable — update FxTool' }; }
+${needWorld}
+  return { success: true, camera: app.panWorldCamera(${S(input.dx)}, ${S(input.dy)}) };
+})();`.trim();
+            case 'world_to_canvas':
+                return `
+// World3D: project a world point onto the Paper canvas
+(function() {
+  if (typeof app.worldToCanvas !== 'function') { return { success: false, error: 'app.worldToCanvas unavailable — update FxTool' }; }
+${needWorld}
+  return { success: true, point: app.worldToCanvas(${S(input.point)}) };
+})();`.trim();
+            case 'canvas_to_ground':
+                return `
+// World3D: where a canvas (x, y) lands on the world's ground
+(function() {
+  if (typeof app.canvasToGround !== 'function') { return { success: false, error: 'app.canvasToGround unavailable — update FxTool' }; }
+${needWorld}
+  const p = ${S(input.point)};
+  return { success: true, ground: app.canvasToGround(p.x, p.y) };
+})();`.trim();
+            // --- Physics in the world ---------------------------------------------
+            // addPhysicsBody3D and fireProjectile3D THROW without a world; the rest
+            // return false, [] or a hollow {contacts:[],removed:[]} — each of which
+            // is a plausible real answer. Both shapes are guarded the same way here.
+            case 'add_body':
+                return `
+// World3D: a body under gravity, colliding with the world
+(function() {
+  if (typeof app.addPhysicsBody3D !== 'function') { return { success: false, error: 'app.addPhysicsBody3D unavailable — update FxTool' }; }
+${needWorld}
+  const r = app.addPhysicsBody3D(${S(input.body)});
+  if (!r || r.ok === false) { return { success: false, error: (r && (r.error || r.reason)) || 'the world refused the body' }; }
+  return { success: true, bodyId: r.id, ...r };
+})();`.trim();
+            case 'fire_projectile':
+                return `
+// World3D: fire a projectile
+(function() {
+  if (typeof app.fireProjectile3D !== 'function') { return { success: false, error: 'app.fireProjectile3D unavailable — update FxTool' }; }
+${needWorld}
+  const r = app.fireProjectile3D(${S(input.body)});
+  if (!r || r.ok === false) { return { success: false, error: (r && (r.error || r.reason)) || 'the projectile was refused' }; }
+  return { success: true, ...r };
+})();`.trim();
+            case 'remove_body':
+                return `
+// World3D: drop a body
+(function() {
+  if (typeof app.removePhysicsBody3D !== 'function') { return { success: false, error: 'app.removePhysicsBody3D unavailable — update FxTool' }; }
+${needWorld}
+  return { success: !!app.removePhysicsBody3D(${S(input.bodyId)}) };
+})();`.trim();
+            case 'list_bodies':
+                return `
+// World3D: every physics body
+(function() {
+  if (typeof app.listPhysicsBodies3D !== 'function') { return { success: false, error: 'app.listPhysicsBodies3D unavailable — update FxTool' }; }
+${needWorld}
+  return { success: true, bodies: app.listPhysicsBodies3D() };
+})();`.trim();
+            case 'step_physics':
+                return `
+// World3D: advance the simulation, and report what touched what
+(function() {
+  if (typeof app.stepPhysics3D !== 'function') { return { success: false, error: 'app.stepPhysics3D unavailable — update FxTool' }; }
+${needWorld}
+  // Without a world this answers {contacts:[],removed:[]} — a perfectly
+  // ordinary quiet step. The guard above is what keeps those apart.
+  const r = app.stepPhysics3D(${S(input.dt)});
+  return { success: true, contacts: r && r.contacts, removed: r && r.removed };
+})();`.trim();
+            case 'impulse':
+                return `
+// World3D: apply an impulse
+(function() {
+  if (typeof app.applyPhysicsImpulse3D !== 'function') { return { success: false, error: 'app.applyPhysicsImpulse3D unavailable — update FxTool' }; }
+${needWorld}
+  return { success: !!app.applyPhysicsImpulse3D(${S(input.bodyId)}, ${S(input.vector)}) };
+})();`.trim();
+            case 'set_velocity':
+                return `
+// World3D: set a body's velocity outright
+(function() {
+  if (typeof app.setPhysicsVelocity3D !== 'function') { return { success: false, error: 'app.setPhysicsVelocity3D unavailable — update FxTool' }; }
+${needWorld}
+  return { success: !!app.setPhysicsVelocity3D(${S(input.bodyId)}, ${S(input.vector)}) };
+})();`.trim();
+            case 'line_of_sight':
+                return `
+// World3D: can one point see another
+(function() {
+  if (typeof app.worldLineOfSight !== 'function') { return { success: false, error: 'app.worldLineOfSight unavailable — update FxTool' }; }
+${needWorld}
+  return { success: true, clear: app.worldLineOfSight(${S(input.from)}, ${S(input.to)}) };
+})();`.trim();
+            case 'set_mesh_instances':
+                return `
+// World3D: replace a mesh's instance data — six floats each
+(function() {
+  if (typeof app.setWorldMeshInstances !== 'function') { return { success: false, error: 'app.setWorldMeshInstances unavailable — update FxTool' }; }
+${needWorld}
+  // x, y, z, scale, rotY (RADIANS, as everywhere on this path), variant.
+  return { success: !!app.setWorldMeshInstances(${S(input.meshId)}, ${S(input.instances)}) };
+})();`.trim();
+        }
+    }
+    /**
+     * pinepaper_design_system — answered in this server, not in the browser.
+     *
+     * Only `compose` with `draw` produces code at all: the tokens, the easings
+     * and the style list are computed here and returned by the handler, because
+     * a design decision does not need the canvas to be open. When a scene IS
+     * drawn, it arrives as a finished list of create calls — the layout was
+     * already decided by a pure function, so nothing is left for the page to
+     * work out.
+     */
+    generateDesignCompose(scene, ops, style) {
+        const S = (v) => JSON.stringify(v);
+        return `
+// Design: compose a ${style} scene — ${ops.length} items, laid out server-side
+(function() {
+  if (typeof app.create !== 'function') { return { success: false, error: 'app.create unavailable — update FxTool' }; }
+  const size = ${S({ width: scene.width, height: scene.height })};
+  if (typeof app.setCanvasSize === 'function') { try { app.setCanvasSize(size.width, size.height); } catch (_) { /* a fixed canvas is not a failure */ } }
+  ${scene.backgroundHex ? `if (typeof app.setBackgroundColor === 'function') { try { app.setBackgroundColor(${S(scene.backgroundHex)}); } catch (_) { /* ditto */ } }` : '// this style paints no background of its own'}
+  const ops = ${S(ops)};
+  const ids = [];
+  const failed = [];
+  for (const op of ops) {
+    const { type, note, name, ...props } = op;
+    try {
+      const item = app.create(type, props);
+      if (item) { ids.push(item.data && item.data.id); } else { failed.push({ name: name, type: type, reason: 'create returned nothing' }); }
+    } catch (e) { failed.push({ name: name, type: type, reason: (e && e.message) || String(e) }); }
+  }
+  if (app.historyManager) app.historyManager.saveState();
+  // A partial composition is reported as one. Half a poster that claims
+  // success is worse than a poster that says which four elements are missing.
+  return { success: failed.length === 0, style: ${S(style)}, itemIds: ids, itemCount: ids.length, failed: failed };
+})();`.trim();
+    }
+    /**
+     * pinepaper_stick — the vendored stick-figure kit.
+     *
+     * Both facades take one options bag, so the schema's named fields are
+     * reassembled into it. Naming them individually is the point: the kit's
+     * options were discoverable only by reading FxTool's source.
+     */
+    generateStick(input) {
+        const S = (v) => JSON.stringify(v);
+        const { action, ...rest } = input;
+        const opts = {};
+        for (const [k, v] of Object.entries(rest))
+            if (v !== undefined)
+                opts[k] = v;
+        const fn = action === 'figure' ? 'stickFigure' : 'stickSet';
+        return `
+// Stick: ${action}
+(async function() {
+  // @engine-methods stickFigure stickSet
+  if (typeof app.${fn} !== 'function') { return { success: false, error: 'app.${fn} unavailable — update FxTool (the stick kit is vendored from mcp-cloud)' }; }
+  const r = await app.${fn}(${S(opts)});
+  if (!r || r.ok === false) { return { success: false, error: (r && (r.reason || r.error)) || 'the stick kit produced nothing' }; }
+  return { success: true, ...r };
+})();`.trim();
+    }
+    /**
+     * pinepaper_story — prose becomes a scene.
+     *
+     * `distill` deliberately draws nothing. A caller should be able to read what
+     * the distiller made of the text and edit it before a scene is assembled
+     * from it, rather than discovering the reading by looking at the result.
+     */
+    generateStory(input) {
+        const S = (v) => JSON.stringify(v);
+        const opts = S(input.options ?? {});
+        switch (input.action) {
+            case 'distill':
+                return `
+// Story: reduce prose to beats, drawing NOTHING
+(async function() {
+  if (typeof app.distillArticle !== 'function') { return { success: false, error: 'app.distillArticle unavailable — update FxTool' }; }
+  const beats = await app.distillArticle(${S(input.text)});
+  if (!beats) { return { success: false, error: 'the distiller made nothing of that text' }; }
+  return { success: true, beats: beats };
+})();`.trim();
+            case 'from_text':
+                return `
+// Story: distill and assemble in one call
+(async function() {
+  if (typeof app.storyFromText !== 'function') { return { success: false, error: 'app.storyFromText unavailable — update FxTool' }; }
+  const r = await app.storyFromText(${S(input.text)}, ${opts});
+  if (!r || r.ok === false) { return { success: false, error: (r && (r.reason || r.error)) || 'the story did not assemble' }; }
+  return { success: true, ...r };
+})();`.trim();
+            case 'apply_spec':
+                return `
+// Story: assemble a spec you already have
+(async function() {
+  if (typeof app.applyStorySpec !== 'function') { return { success: false, error: 'app.applyStorySpec unavailable — update FxTool' }; }
+  const r = await app.applyStorySpec(${S(input.spec)}, ${opts});
+  if (!r || r.ok === false) { return { success: false, error: (r && (r.reason || r.error)) || 'the spec did not assemble' }; }
+  return { success: true, ...r };
+})();`.trim();
+            case 'plan_book':
+                return `
+// Story: lay images out as pages
+(function() {
+  if (typeof app.planBook !== 'function') { return { success: false, error: 'app.planBook unavailable — update FxTool' }; }
+  const plan = app.planBook(${S(input.images)}, ${opts});
+  if (!plan) { return { success: false, error: 'no plan came back for those images' }; }
+  return { success: true, plan: plan };
+})();`.trim();
+        }
+    }
+    /**
+     * pinepaper_interchange — Lottie, dotLottie, GLB, BVH, PNG sequence.
+     *
+     * Three of these refuse through `console.warn` and a falsy return, which the
+     * production build strips — exportGLB with no perspective objects and
+     * exportBVH with no rigging system both do exactly that. Over MCP there is no
+     * console to read, so the PRECONDITION is checked here and named, rather than
+     * letting a caller receive nothing and guess why.
+     */
+    // @engine-methods exportLottie exportDotLottie exportEngine.exportToStore exportEngine.readExport exportEngine.releaseExport
+    generateInterchange(input) {
+        const S = (v) => JSON.stringify(v);
+        const guard = (fn) => `  if (typeof app.${fn} !== 'function') { return { success: false, error: 'app.${fn} unavailable — update FxTool' }; }`;
+        const opts = S(input.options ?? {});
+        switch (input.action) {
+            case 'export_lottie':
+            case 'export_dotlottie': {
+                const fn = input.action === 'export_lottie' ? 'exportLottie' : 'exportDotLottie';
+                return `
+// Interchange: ${fn}
+(async function() {
+${guard(fn)}
+  const out = await app.${fn}(${opts});
+  if (!out) { return { success: false, error: '${fn} produced nothing — the scene may have no animatable content' }; }
+  return { success: true, format: ${S(input.action === 'export_lottie' ? 'lottie' : 'dotlottie')}, data: out };
+})();`.trim();
+            }
+            case 'import_lottie':
+                return `
+// Interchange: a Lottie back onto the canvas
+(async function() {
+${guard('importLottie')}
+  // importLottie logs and returns falsy when the importer is absent — a
+  // stripped console makes that indistinguishable from an empty animation.
+  const r = await app.importLottie(${S(input.data)}, ${opts});
+  if (!r) { return { success: false, error: 'the Lottie did not import — it may be malformed, or this build has no Lottie importer' }; }
+  return { success: true, imported: r };
+})();`.trim();
+            case 'export_glb':
+                return `
+// Interchange: GLB of the perspective 3D objects
+(async function() {
+${guard('exportGLB')}
+  // exportGLB warns and bails when nothing perspective exists. The warning is
+  // stripped in production, so the precondition is checked here instead.
+  const has3d = app._initialized && app._initialized.has && app._initialized.has('threeD');
+  if (!has3d) { return { success: false, error: 'no perspective objects to export — create one with createObject3D first' }; }
+  const out = await app.exportGLB(${opts});
+  if (!out) { return { success: false, error: 'GLB export produced nothing' }; }
+  return { success: true, format: 'glb', data: out };
+})();`.trim();
+            case 'export_bvh':
+                return `
+// Interchange: BVH of one skeleton's motion
+(async function() {
+${guard('exportBVH')}
+  // Same shape as GLB: exportBVH warns and bails without a RiggingSystem.
+  const rigged = app._initialized && app._initialized.has && app._initialized.has('riggingSystem');
+  if (!rigged) { return { success: false, error: 'no rig to export — create a skeleton first (pinepaper_rigging)' }; }
+  const out = await app.exportBVH(${S(input.skeletonId)}, ${opts});
+  if (!out) { return { success: false, error: 'BVH export produced nothing for skeleton ' + ${S(input.skeletonId)} }; }
+  return { success: true, format: 'bvh', skeletonId: ${S(input.skeletonId)}, data: out };
+})();`.trim();
+            case 'export_png_sequence':
+                return `
+// Interchange: one PNG per frame
+(async function() {
+${guard('exportPNGSequence')}
+  const out = await app.exportPNGSequence(${opts});
+  if (!out) { return { success: false, error: 'PNG sequence produced nothing' }; }
+  return { success: true, format: 'png-sequence', result: out };
+})();`.trim();
+        }
+    }
+    /**
+     * pinepaper_sound — synthesis, and the drawing that is the same object.
+     *
+     * Every facade here rides `app.audioGraph`, which is lazily built, so each
+     * action guards the METHOD rather than assuming the graph. The canvas half
+     * (`create`, `timbre_from_path`) goes through PinePaper directly.
+     */
+    generateSound(input) {
+        const S = (v) => JSON.stringify(v);
+        const guard = (fn) => `  if (typeof app.${fn} !== 'function') { return { success: false, error: 'app.${fn} unavailable — update FxTool' }; }`;
+        const simple = (fn, args, key, label) => `
+// Sound: ${label}
+(function() {
+${guard(fn)}
+  return { success: true, ${key}: app.${fn}(${args}) };
+})();`.trim();
+        switch (input.action) {
+            case 'list_instruments': return simple('listInstruments', '', 'instruments', 'the instrument catalogue');
+            case 'list_percussion': return simple('listPercussion', '', 'percussion', 'the percussion catalogue');
+            case 'list_sfx': return simple('listSfx', '', 'sfx', 'the SFX catalogue');
+            case 'play_tone': return simple('playTone', `${S(input.note)}, ${S(input.options ?? {})}`, 'played', `tone ${input.note}`);
+            case 'play_chord': return simple('playChord', `${S(input.root)}, ${S(input.chord)}, ${S(input.options ?? {})}`, 'played', `${input.chord} chord on ${input.root}`);
+            case 'chord_frequencies': return simple('chordFrequencies', `${S(input.root)}, ${S(input.chord)}, ${S(input.options ?? {})}`, 'frequencies', `the Hz of ${input.chord} on ${input.root}`);
+            case 'play_percussion': return simple('playPercussion', `${S(input.name)}, ${S(input.options ?? {})}`, 'played', `percussion ${input.name}`);
+            case 'play_sfx': return simple('playSfx', `${S(input.name)}, ${S(input.options ?? {})}`, 'played', `sfx ${input.name}`);
+            case 'play_spec': return simple('playSound', S(input.spec), 'played', 'a raw spec');
+            case 'play_from_text': return simple('playSoundFromText', S(input.text), 'played', `"${input.text}"`);
+            case 'from_text':
+                return `
+// Sound: resolve "${input.text}" to a spec WITHOUT playing it
+(function() {
+${guard('buildSoundFromText')}
+  const spec = app.buildSoundFromText(${S(input.text)});
+  // A description the resolver cannot read comes back empty rather than
+  // throwing. Saying so beats handing back a spec that plays silence.
+  if (!spec) { return { success: false, error: 'could not resolve ' + ${S(input.text)} + ' into a sound' }; }
+  return { success: true, spec: spec };
+})();`.trim();
+            // DEFINING A SOUND. The engine's three tables are "a curated starting set,
+            // not a claim that music contains six instruments" — its words. Anything
+            // it does not model can be registered at runtime and is then first-class:
+            // listInstruments() reads the LIVE table, so a defined instrument shows
+            // up in list_instruments and plays by name like any built-in.
+            //
+            // The canonical name is RETURNED rather than assumed. Registration
+            // normalises to [a-z][a-z0-9_-]{0,31}, so a model that registers
+            // 'Rhodes' and then plays 'Rhodes' is playing something that does not
+            // exist — the name it actually got is 'rhodes', and it needs to be told.
+            case 'define_instrument':
+            case 'define_percussion':
+            case 'define_sfx': {
+                const fn = input.action === 'define_instrument' ? 'registerInstrument'
+                    : input.action === 'define_percussion' ? 'registerPercussion' : 'registerSfx';
+                const listFn = input.action === 'define_instrument' ? 'listInstruments'
+                    : input.action === 'define_percussion' ? 'listPercussion' : 'listSfx';
+                const spec = {
+                    ...(input.partials ? { partials: input.partials } : {}),
+                    ...(input.envelope ? { envelope: input.envelope } : {}),
+                    ...(input.gain !== undefined ? { gain: input.gain } : {}),
+                    ...(input.aliases ? { aliases: input.aliases } : {}),
+                    ...(input.noise !== undefined ? { noise: input.noise } : {}),
+                    ...(input.noiseFreq !== undefined ? { noiseFreq: input.noiseFreq } : {}),
+                    ...(input.hz !== undefined ? { hz: input.hz } : {}),
+                    ...(input.pitch ? { pitch: input.pitch } : {}),
+                };
+                // @engine-methods registerInstrument registerPercussion registerSfx
+                // The guard below is INTERPOLATED — `guard(fn)` takes a variable, not a
+                // literal — so sync-engine-methods.mjs cannot read the names out of it
+                // and the studio probe would report a studio as complete while never
+                // checking the method a caller needs. It extracted only
+                // renderSoundtrackWav until this line existed.
+                return `
+// Sound: define ${input.name} at runtime
+(function() {
+${guard(fn)}
+  var name;
+  // The engine THROWS on an unusable name or a silent spec, with a message
+  // naming what was wrong. That is the useful answer, so it is caught and
+  // returned rather than allowed to surface as a bridge error with no subject.
+  try { name = app.${fn}(${S(input.name)}, ${S(spec)}); }
+  catch (e) { return { success: false, error: (e && e.message) || String(e) }; }
+  var listed = typeof app.${listFn} === 'function' ? app.${listFn}() : null;
+  var found = Array.isArray(listed)
+    ? listed.some(function (x) { return (x && x.name) === name; })
+    : null;
+  return {
+    success: true,
+    // The name the engine CHOSE, which is what plays. Registering 'Rhodes'
+    // returns 'rhodes'.
+    canonicalName: name,
+    requestedName: ${S(input.name)},
+    normalised: name !== ${S(input.name)},
+    // Defined but unlistable would be a capability nobody can name. Proven per
+    // call rather than assumed, because it is one table lookup.
+    listed: found,
+  };
+})();`.trim();
+            }
+            case 'render_soundtrack': {
+                const opts = {
+                    ...(typeof input.options?.duration === 'number' ? { duration: input.options.duration } : {}),
+                    ...(input.sampleRate !== undefined ? { sampleRate: input.sampleRate } : {}),
+                    ...(input.bitDepth !== undefined ? { bitDepth: input.bitDepth } : {}),
+                };
+                return `
+// Sound: mix every placed sound to a WAV, offline
+(function() {
+${guard('renderSoundtrackWav')}
+  var r = app.renderSoundtrackWav(${S(opts)});
+  // BARE NULL MEANS "NO SOUNDS PLACED". Returned for an empty scene and for a
+  // scene whose sounds all failed to mix — indistinguishable from a malfunction
+  // unless it is named, and "the export produced nothing" is the report that
+  // sends someone debugging the exporter instead of placing a sound.
+  if (!r || !r.wav) {
+    return { success: false, error: 'no sounds are placed on this scene, so there is no soundtrack to render. Create one with action "create", or place an existing sound with "set_placement".' };
+  }
+  var bytes = r.wav;
+  // Uint8Array cannot cross the bridge; base64 in chunks, because
+  // String.fromCharCode.apply over a multi-megabyte array blows the stack.
+  var bin = '';
+  for (var i = 0; i < bytes.length; i += 8192) {
+    bin += String.fromCharCode.apply(null, bytes.subarray(i, i + 8192));
+  }
+  return {
+    success: true,
+    wavBase64: btoa(bin),
+    byteLength: bytes.length,
+    duration: r.duration,
+    sampleRate: r.sampleRate,
+    sounds: r.sounds,
+    placed: r.placed,
+    // DROPPED IS THE SECOND SILENT REFUSAL. A mix with placed > 0 and dropped
+    // > 0 is a valid WAV that is quietly missing sounds — the same shape as an
+    // item list capped below its own itemCount. Reported only when it happened,
+    // so the marker stays meaningful.
+    ...(r.dropped > 0 ? { dropped: r.dropped, incomplete:
+      'mixed ' + r.placed + ' sound(s); ' + r.dropped + ' could not be rendered and are absent from this file' } : {}),
+  };
+})();`.trim();
+            }
+            case 'create':
+                return `
+// Sound: draw it AS a waveform path — the item and the sound are one thing
+(function() {
+${guard('createSound')}
+  const item = app.createSound(${S(input.spec ?? {})}, ${S(input.visual ?? {})});
+  if (!item) { return { success: false, error: 'the sound produced no waveform path' }; }
+  return { success: true, itemId: item.data && item.data.id, itemType: 'sound' };
+})();`.trim();
+            case 'timbre_from_path':
+                return `
+// Sound: read a drawn path's shape as harmonic content
+(function() {
+${guard('timbreFromPath')}
+  const item = app.getItemById ? app.getItemById(${S(input.itemId)}) : null;
+  // timbreFromPath answers a flat {partials:[{h:1,amp:1}]} for anything that is
+  // not a path with length — a real timbre and a refusal look identical, so the
+  // item is checked HERE instead of reading that back as an answer.
+  if (!item) { return { success: false, error: 'no such item: ' + ${S(input.itemId)} }; }
+  if (typeof item.getPointAt !== 'function' || !(item.length > 0)) {
+    return { success: false, error: 'timbre needs a path with length — ' + ${S(input.itemId)} + ' is not one' };
+  }
+  return { success: true, timbre: app.timbreFromPath(item, ${S(input.samples ?? 256)}) };
+})();`.trim();
+            case 'set_placement': return simple('setSoundPlacement', `${S(input.itemId)}, ${S(input.placement ?? {})}`, 'placed', 'placement');
+            case 'remove': return simple('removeSound', S(input.itemId), 'removed', 'remove');
+            case 'stop_all': return simple('stopSounds', '', 'stopped', 'stop everything');
+        }
+    }
+    /**
+     * pinepaper_motion — the generators' Animation knob for any group.
+     *
+     * animateItems returns `{error}` on failure, NOT `{ok:false, reason}` like
+     * the path facades — reading the wrong key here turns "could not attach
+     * \"ripple\" (frame-callback limit reached?)" into undefined.
+     */
+    generateMotion(input) {
+        const S = (v) => JSON.stringify(v);
+        if (input.action === 'list') {
+            return `
+// The engine's own motion catalogue — motions, waveforms, origins, knobs
+(async function() {
+  if (typeof app.listGeneratorMotions !== 'function') { return { success: false, error: 'app.listGeneratorMotions unavailable — update FxTool' }; }
+  const c = await app.listGeneratorMotions();
+  return { success: true, ...c };
+})();`.trim();
+        }
+        const target = input.itemIds && input.itemIds.length ? S(input.itemIds) : S(input.itemId);
+        const opts = { animation: input.motion };
+        for (const k of ['speed', 'intensity', 'waveform', 'origin', 'seed']) {
+            if (input[k] !== undefined)
+                opts[k] = input[k];
+        }
+        return `
+// Motion: ${input.motion} on ${input.itemIds?.length ? `${input.itemIds.length} items` : input.itemId}
+(async function() {
+  if (typeof app.animateItems !== 'function') { return { success: false, error: 'app.animateItems unavailable — update FxTool' }; }
+  const r = await app.animateItems(${target}, ${S(opts)});
+  // An unknown motion comes back with the known list attached, so a caller can
+  // correct itself without a second round trip.
+  if (!r || r.error) { return { success: false, error: (r && r.error) || 'the motion did not attach', motions: r && r.motions }; }
+  return { success: true, motion: ${S(input.motion)} };
+})();`.trim();
+    }
+    /**
+     * pinepaper_path — the destructive path operations.
+     *
+     * Every facade here returns `{ok:false, reason}` and names its own refusal
+     * ("a boolean needs at least two paths", "that path has no stroke to
+     * outline"), so the reason is passed through rather than reworded. A second
+     * wording for one condition is the thing to avoid, not the guard.
+     */
+    generatePathOp(input) {
+        const S = (v) => JSON.stringify(v);
+        const guard = (fn) => `  if (typeof app.${fn} !== 'function') { return { success: false, error: 'app.${fn} unavailable — update FxTool' }; }`;
+        const pass = (expr) => `
+  const r = ${expr};
+  if (!r || r.ok === false) { return { success: false, error: (r && r.reason) || 'the engine refused the operation' }; }
+  return { success: true, ...r };`;
+        switch (input.action) {
+            case 'boolean':
+                return `
+// Path boolean: ${input.op} — CONSUMES its operands and leaves one result
+(function() {
+${guard('booleanOp')}${pass(`app.booleanOp(${S(input.itemIds)}, ${S(input.op)})`)}
+})();`.trim();
+            case 'simplify':
+                return `
+// Simplify: fewer segments, same shape
+(function() {
+${guard('simplifyPath')}${pass(`app.simplifyPath(${S(input.itemId)}${input.tolerance !== undefined ? `, ${S(input.tolerance)}` : ''})`)}
+})();`.trim();
+            case 'outline_stroke':
+                return `
+// Outline stroke: a stroked line becomes a filled shape of the same width
+(function() {
+${guard('outlineStroke')}${pass(`app.outlineStroke(${S(input.itemId)}, ${S(input.tolerance !== undefined ? { tolerance: input.tolerance } : {})})`)}
+})();`.trim();
+            case 'toggle_closed':
+                return `
+// Open or close the path
+(function() {
+${guard('togglePathClosed')}${pass(`app.togglePathClosed(${S(input.itemId)})`)}
+})();`.trim();
+            case 'pattern':
+                return `
+// Pattern: repeat the item — ${input.kind}
+(function() {
+${guard('patternFrom')}${pass(`app.patternFrom(${S(input.itemId)}, ${S(input.kind)}, ${S(input.pattern ?? {})})`)}
+})();`.trim();
+            case 'get_geometry':
+                return `
+// Read the path's segments back
+(function() {
+${guard('getPathGeometry')}
+  const g = app.getPathGeometry(${S(input.itemId)}, {});
+  // null means no such item — the one facade here that does NOT name its
+  // refusal, so this is the one place a wording is supplied rather than passed.
+  if (!g) { return { success: false, error: 'no such item: ' + ${S(input.itemId)} }; }
+  return { success: true, geometry: g };
+})();`.trim();
+            case 'set_locked':
+                return `
+// Lock or unlock — a locked item is also unselectable and undraggable
+(function() {
+${guard('setItemLocked')}${pass(`app.setItemLocked(${S(input.itemId)}, ${S(input.locked)})`)}
+})();`.trim();
+            case 'unlock_all':
+                return `
+// Unlock everything on the canvas
+(function() {
+${guard('unlockAllItems')}${pass('app.unlockAllItems()')}
 })();`.trim();
         }
     }
@@ -5966,7 +7960,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 +7974,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 +7996,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 +8010,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 +8020,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
@@ -6217,6 +8370,21 @@ ${needWorld}
      * object. Guards on the app method so old FxTool builds degrade gracefully.
      */
     generateEquationPath(input) {
+        // An ODE is INTEGRATED, not plotted: the caller gets the trajectory back as
+        // data rather than a drawn path, so it can be inspected, fed to a path, or
+        // used to drive keyframes. Branching here rather than in a separate tool
+        // keeps one place that knows the equation vocabulary.
+        if (input.solveOde) {
+            const ode = input.solveOde;
+            return `
+// Integrate an ODE and return the SOLUTION — nothing is drawn
+(async function() {
+  if (typeof app.solveODE !== 'function') { return { success: false, error: 'app.solveODE unavailable — update FxTool' }; }
+  const sol = await app.solveODE(${JSON.stringify({ equations: ode.equations, initialState: ode.initialState, tEnd: ode.tEnd, dt: ode.dt })}, ${JSON.stringify(ode.method ?? 'rk4')});
+  if (!sol) { return { success: false, error: 'the solver returned nothing — check the equations and the initial state length' }; }
+  return { success: true, method: ${JSON.stringify(ode.method ?? 'rk4')}, solution: sol };
+})();`.trim();
+        }
         const optsJson = JSON.stringify(input);
         const kindJson = JSON.stringify(input.kind);
         return `