@pinepaper.studio/mcp-server 1.6.7 → 1.6.8

package/dist/types/code-generator.js

@@ -4,6 +4,7 @@
  * 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, ImportMotionCaptureInputSchema, ModifyItemInputSchema, AddRelationInputSchema, AnimateItemInputSchema, KeyframeAnimateInputSchema, ExecuteGeneratorInputSchema, ApplyEffectInputSchema, SetBackgroundColorInputSchema, SetCanvasSizeInputSchema, CreateGlossySphereInputSchema, CreateDiagonalStripesInputSchema, BatchCreateInputSchema, BatchModifyInputSchema, CreateGridInputSchema, CreateSceneInputSchema, 
 // Diagram types
@@ -960,6 +961,17 @@ const PLATFORM_TO_CANVAS_PRESET = {
 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
@@ -997,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);
     }
     /**
@@ -1234,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,
@@ -2414,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;
@@ -2441,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() {
@@ -2480,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') {
@@ -2565,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' };
         }
@@ -5227,6 +5474,79 @@ ${resolve}
   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' };
   }
@@ -5876,6 +6196,7 @@ ${resolve}
      * (bringToFront / sendToBack / bringForward / sendBackward).
      */
     generateArrange(input) {
+        // @engine-methods bringToFront sendToBack bringForward sendBackward
         const method = {
             front: 'bringToFront',
             back: 'sendToBack',
@@ -6114,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' };
   }
@@ -6137,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();
     }
     /**
@@ -6360,6 +6713,48 @@ ${guard}
   };
 })();`.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();
         }
     }
     /**
@@ -6406,7 +6801,14 @@ ${guard}
                     ...(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;
@@ -6418,7 +6820,23 @@ ${guard}
   }
   const g = app.applyThreadPainting(${S(input.itemId)}, ${opts});
   if (!g) { return { success: false, action: 'apply_thread', error: 'nothing stitchable here — thread needs a CLOSED path, a compound path, or a group containing them. An open stroke, a raster and an empty group all land here. (If you passed a stitch name, check it against list_stitches.)' }; }
-  return { success: true, action: 'apply_thread', groupId: (g.data && g.data.id) || null, stitches: g.children.length };`);
+  // 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' }; }
@@ -6735,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();
         }
     }
@@ -7197,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 `