@pinepaper.studio/mcp-server 1.6.12 → 1.6.13

package/dist/types/code-generator.js

@@ -128,6 +128,27 @@ function generateCreateItemCode(itemType, position, properties) {
 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)}; }`;
     }
+    // RTL IS NOT SUPPORTED, AND SILENCE WAS THE WORST WAY TO SAY SO.
+    //
+    // create('text', {direction:'rtl'}) dropped the property with no error and
+    // left the base direction LTR, so an Arabic sentence's final period landed
+    // at the reader's START — visibly wrong, and attributable to nothing. The
+    // engine has no text-direction support at all: `direction` there is an arc
+    // sweep and an animation direction, and `justification` is the only
+    // text-related alignment it reads.
+    //
+    // Refused by name rather than accepted-and-dropped, and rather than adding a
+    // prop that would be dropped one layer further on. The alignment half is
+    // real and is named, because it is what a caller can actually use today.
+    const rtlAsked = params.direction ?? params.textDirection;
+    if (rtlAsked !== undefined) {
+        return `
+// Create ${itemType} — refused, rather than silently left ltr
+({ success: false, error: ${JSON.stringify(`direction / textDirection is not supported: this studio has no text-direction support, so ${String(rtlAsked)} would have been accepted and the text left LTR. `
+            + 'That is visible as a right-to-left sentence whose final punctuation lands at the start. '
+            + "You can align with justification: 'right', which is read, but the BASE direction needs engine support — "
+            + 'pass pre-shaped text, or split the line, until it lands.')} });`.trim();
+    }
     // AN UNKNOWN ANCHOR IS INVISIBLE OVER MCP.
     //
     // The engine names a bad anchor through console.warn and leaves (x, y) as
@@ -416,6 +437,28 @@ function normalizeKeyframePositions(keyframes) {
 /**
  * Template for keyframe animation
  */
+/**
+ * AN UNKNOWN itemId IS A SILENT SUCCESS, ACROSS A WHOLE FAMILY OF TOOLS.
+ *
+ * `app.addAnimation('c0', …)` on an id that does not exist calls
+ * console.warn and returns undefined — and production strips console.warn, so
+ * over MCP nothing is said at all. The emitter then returned
+ * `{success: true}` because the call did not throw. A pilot animated a
+ * connector id that was never registered and got success for every keyframe.
+ *
+ * Emitted as a shared preamble so the check reads the same everywhere and a
+ * new tool taking an itemId can adopt it in one line. It resolves through the
+ * registry the way the engine does, and names the id it could not find —
+ * "item_7 is not on the canvas" is actionable, silence is not.
+ */
+function requireItem(itemId, what) {
+    return `
+const _target = (app.getItemById && app.getItemById(${JSON.stringify(itemId)}))
+  || (app.itemRegistry && app.itemRegistry.get && app.itemRegistry.get(${JSON.stringify(itemId)}));
+if (!_target) {
+  return { success: false, error: ${JSON.stringify(itemId)} + ' is not on the canvas, so ' + ${JSON.stringify(what)} + ' would have done nothing. Check the id with pinepaper_get_items — create returns the registry id, not the Paper id.' };
+}`.trim();
+}
 function generateKeyframeAnimateCode(itemId, keyframes, duration, loop = false, timeOffset, clipInPoint, clipOutPoint, timeUnits) {
     const keyframesJson = JSON.stringify(normalizeKeyframePositions(keyframes), null, 2);
     const calculatedDuration = duration || Math.max(...keyframes.map(k => k.time));
@@ -430,9 +473,11 @@ function generateKeyframeAnimateCode(itemId, keyframes, duration, loop = false,
         opts.timeUnits = timeUnits;
     return `
 // Apply keyframe animation to ${itemId}
-app.addAnimation('${itemId}', ${keyframesJson}, ${JSON.stringify(opts)});
-
-({ success: true, itemId: '${itemId}', duration: ${calculatedDuration}, loop: ${loop}${timeOffset !== undefined ? `, timeOffset: ${timeOffset}` : ''}${clipInPoint !== undefined ? `, clipInPoint: ${clipInPoint}` : ''}${clipOutPoint !== undefined ? `, clipOutPoint: ${clipOutPoint}` : ''} });
+(function() {
+  ${requireItem(itemId, 'the animation')}
+  app.addAnimation('${itemId}', ${keyframesJson}, ${JSON.stringify(opts)});
+  return { success: true, itemId: '${itemId}', duration: ${calculatedDuration}, loop: ${loop}${timeOffset !== undefined ? `, timeOffset: ${timeOffset}` : ''}${clipInPoint !== undefined ? `, clipInPoint: ${clipInPoint}` : ''}${clipOutPoint !== undefined ? `, clipOutPoint: ${clipOutPoint}` : ''} };
+})();
 `.trim();
 }
 /**
@@ -1199,6 +1244,49 @@ const INLINE_REMOTE_IMAGES = `
     return { svg: svgText, notes: notes };
   }
 `;
+/**
+ * A HEX COLOUR IN THE 3D WORLD POISONS EVERY LATER EXPORT.
+ *
+ * addWorldObject hands `color` to a WebGL uniform — its own example is
+ * `color: [0.9, 0.3, 0.2]`, three floats in 0..1. Give it '#ef4444' and
+ * uniform3fv throws "cannot be converted to a sequence"; the object is
+ * reported as added, and then EVERY subsequent MP4 export fails, because the
+ * broken uniform is in the scene from then on. Same shape as the tainted
+ * canvas: one bad value, success reported, and the damage surfaces somewhere
+ * else entirely.
+ *
+ * Converted here. A caller writing '#ef4444' is not wrong — it is the colour
+ * spelling every other tool in this package takes — so the emitter absorbs the
+ * difference rather than the caller learning a second convention.
+ */
+function world3dColor(value) {
+    if (Array.isArray(value)) {
+        // Already a triple. Accept 0-255 too, since that is the other common form.
+        const nums = value.filter((v) => typeof v === 'number');
+        if (nums.length < 3)
+            return value;
+        return nums.slice(0, 3).map((n) => (n > 1 ? n / 255 : n));
+    }
+    if (typeof value !== 'string')
+        return value;
+    const hex = value.trim().replace(/^#/, '');
+    const full = hex.length === 3 ? hex.split('').map((c) => c + c).join('') : hex;
+    if (!/^[0-9a-f]{6}$/i.test(full))
+        return value;
+    return [0, 2, 4].map((i) => parseInt(full.slice(i, i + 2), 16) / 255);
+}
+/** Recursively convert every `color` field in a world3d payload. */
+function world3dColors(value) {
+    if (Array.isArray(value))
+        return value.map((v) => world3dColors(v));
+    if (!value || typeof value !== 'object')
+        return value;
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        out[k] = k === 'color' ? world3dColor(v) : world3dColors(v);
+    }
+    return out;
+}
 export class PinePaperCodeGenerator {
     /**
      * Generate code for creating an item
@@ -2032,7 +2120,25 @@ const connector = app.diagramSystem.connect(sourceItem, targetItem, config);
 const connectorId = connector.data?.registryId || connector.id;
 app.historyManager.saveState();
 
-({ connectorId, sourceItemId: '${sourceItemId}', targetItemId: '${targetItemId}' });
+// A REQUESTED id IS NOT NECESSARILY THE id YOU GOT.
+//
+// Connector itself honours 'config.id || <generated>', but DiagramSystem.connect
+// rebuilds the config from an allowlist — routing, lineColor, lineWidth,
+// headStyle, headSize, boltEnabled — and 'id' is not on it. So a caller's id is
+// dropped before the Connector sees it and a timestamp id is minted instead,
+// which then makes update_connector / remove_connector say "not found" for the
+// id the caller chose. Engine-side, raised with fxtool; until it lands, the
+// mismatch is REPORTED rather than left for a later call to trip over.
+({
+  connectorId,
+  sourceItemId: '${sourceItemId}',
+  targetItemId: '${targetItemId}',
+  ...(${JSON.stringify(id ?? null)} && connectorId !== ${JSON.stringify(id ?? null)}
+    ? { requestedId: ${JSON.stringify(id ?? null)},
+        idHonoured: false,
+        note: 'this studio dropped the id you asked for and minted its own — use connectorId above for update_connector and remove_connector, not the one you passed.' }
+    : {}),
+});
 `.trim();
     }
     /**
@@ -2445,12 +2551,16 @@ throw new Error('Unknown diagram mode action: ${action}');
 
   // Check relations
   if (app.relationRegistry) {
-    const relations = app.relationRegistry.getAll ? app.relationRegistry.getAll() : [];
-    analysis.hasRelations = relations.length > 0;
-    relations.forEach(rel => {
-      if (rel.relationType) relationSet.add(rel.relationType);
-    });
+    // getAll() has never existed on the registry, so this branch always took
+    // the empty fallback and every analysis reported NO relations. getStats()
+    // is the real accessor and answers both questions directly:
+    // associationsByType is keyed by relation type.
+    const relStats = typeof app.relationRegistry.getStats === 'function'
+      ? app.relationRegistry.getStats()
+      : null;
+    (Object.keys((relStats && relStats.associationsByType) || {})).forEach(t => relationSet.add(t));
     analysis.relationTypes = Array.from(relationSet);
+    analysis.hasRelations = !!relStats && (relStats.activeItems > 0 || analysis.relationTypes.length > 0);
     if (analysis.hasRelations) analysis.hasAnimations = true;
   }
 
@@ -3158,13 +3268,38 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
     if (!params || (params.mode || 'keyframes') !== 'keyframes' || !params.keyframes || !params.keyframes.length) {
       return { success: false, platform, format, framing, error: 'framing: "camera" requires a keyframe-mode camera walkthrough with at least one keyframe.' };
     }
-    const firstKf = params.keyframes[0];
-    const firstZoom = firstKf && firstKf.zoom > 0 ? firstKf.zoom : 1;
-    const canvasEl = document.querySelector('canvas');
-    cameraDims = {
-      width: Math.round((canvasEl ? canvasEl.width : dimensions.width) / firstZoom),
-      height: Math.round((canvasEl ? canvasEl.height : dimensions.height) / firstZoom),
-    };
+    // MATCH THE ENGINE'S FRAME EXACTLY, AND DO NOT SECOND-GUESS THE ZOOM.
+    //
+    // This divided canvasEl.width — device pixels — so a camera export came
+    // out 2234x1472 whatever the board was. That is fixed by reading the
+    // artboard, and the chain below is deliberately the same one the engine's
+    // own _exportFrameSize() uses: getCanvasSize(), then app.canvasSize, then
+    // a known frame. Two places computing one number is how they drift.
+    //
+    // The zoom divide is gone too, and that is the part worth explaining.
+    // VideoExporter._frameCropRect returns the WHOLE canvas element whenever a
+    // camera animation exists — the camera owns the view, so it captures
+    // everything the camera frames. Dividing by the first keyframe's zoom
+    // therefore never reframed anything; it only shrank the output, so a
+    // zoom-2 export produced a half-size video of the same content. Asking for
+    // the artboard's own size is both simpler and right.
+    //
+    // NOTE: the engine currently scales that whole-canvas crop into the output
+    // frame without preserving aspect, so the picture is squashed by the ratio
+    // between the workspace canvas and the board (measured: 1.17 landscape,
+    // 0.37 portrait). That is VideoExporter._frameCropRect, not this — raised
+    // with fxtool-f2. Matching frames here means that when it is fixed, these
+    // two cannot disagree about the aspect on top of it.
+    let camBase = null;
+    if (typeof app.getCanvasSize === 'function') {
+      const cs = app.getCanvasSize();
+      if (cs && cs.width > 0) camBase = { width: cs.width, height: cs.height };
+    }
+    if (!camBase && app.canvasSize && app.canvasSize.width > 0) {
+      camBase = { width: app.canvasSize.width, height: app.canvasSize.height };
+    }
+    if (!camBase) camBase = { width: dimensions.width, height: dimensions.height };
+    cameraDims = { width: camBase.width, height: camBase.height };
   }
 
   let result = { success: false, platform, format, quality, framing };
@@ -3186,14 +3321,35 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
 
       case 'png':
         if (app.exportEngine && app.exportEngine.exportPNG) {
-          const dataUrl = await app.exportEngine.exportPNG({ dpi: settings.dpi });
+          // PNG IGNORED THE PLATFORM ENTIRELY.
+          //
+          // exportPNG takes dpi or scale and no dimensions, so passing only
+          // dpi scaled the CANVAS by dpi/96 and the preset was never applied:
+          // platform 'youtube-thumbnail' (1280x720) and platform 'auto' on a
+          // 1920x1080 board both returned 3000x1688, which is 1920 x 150/96.
+          // Third member of the same family as the camera dims and analyze —
+          // a pixel count that came from the rendering scale rather than from
+          // what the caller asked for.
+          //
+          // dimensions is already resolved: the preset for a named platform,
+          // the board itself for auto. Turning it into a scale is the only
+          // lever exportPNG offers, so that is what it gets.
+          const pngBoard = (typeof app.getCanvasSize === 'function' && app.getCanvasSize())
+            || app.canvasSize
+            || { width: dimensions.width, height: dimensions.height };
+          const pngScale = pngBoard.width > 0 ? dimensions.width / pngBoard.width : 1;
+          const png = await app.exportEngine.exportPNG({ scale: pngScale });
+          const dataUrl = (png && png.dataUrl) ? png.dataUrl : png;
           result = {
             success: true,
             platform,
             format: 'png',
             data: dataUrl,
             mimeType: 'image/png',
-            size: Math.round(dataUrl.length * 0.75)
+            size: Math.round(String(dataUrl).length * 0.75),
+            dimensions: (png && png.width)
+              ? { width: png.width, height: png.height }
+              : { width: dimensions.width, height: dimensions.height },
           };
         } else {
           const canvas = document.querySelector('canvas');
@@ -3460,12 +3616,16 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
 
   // Check relations
   if (app.relationRegistry) {
-    const relations = app.relationRegistry.getAll ? app.relationRegistry.getAll() : [];
-    analysis.hasRelations = relations.length > 0;
-    relations.forEach(rel => {
-      if (rel.relationType) relationSet.add(rel.relationType);
-    });
+    // getAll() has never existed on the registry, so this branch always took
+    // the empty fallback and every analysis reported NO relations. getStats()
+    // is the real accessor and answers both questions directly:
+    // associationsByType is keyed by relation type.
+    const relStats = typeof app.relationRegistry.getStats === 'function'
+      ? app.relationRegistry.getStats()
+      : null;
+    (Object.keys((relStats && relStats.associationsByType) || {})).forEach(t => relationSet.add(t));
     analysis.relationTypes = Array.from(relationSet);
+    analysis.hasRelations = !!relStats && (relStats.activeItems > 0 || analysis.relationTypes.length > 0);
     if (analysis.hasRelations) analysis.hasAnimations = true;
   }
 
@@ -3631,7 +3791,7 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
         // interactivity flags have other names entirely. Every one was accepted,
         // JSON-stringified into the call and dropped — a caller who set fillColor
         // got the default grey with no indication why.
-        const { fillColor, strokeColor, strokeWidth, hoverFill, hoverStroke, enableHover, enableClick, ...passthrough } = raw;
+        const { fillColor, strokeColor, strokeWidth, hoverFill, hoverStroke, enableHover, enableClick, options: extraOptions, ...passthrough } = raw;
         // The engine's own style vocabulary — see stylePresets in MapSystem.js.
         const styles = {};
         if (fillColor !== undefined)
@@ -3653,7 +3813,15 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
         // learns why their outline did not move.
         if (hoverStroke !== undefined)
             styles.hoverStroke = hoverStroke;
-        const engineOptions = { ...passthrough };
+        // `options` was declared by the tool's description and stripped by the
+        // schema, so `{style: 'dark'}` never reached loadMap. It carries the
+        // options not named individually above — style presets, showOcean,
+        // fitBounds, preserve — and is spread FIRST so an explicitly named field
+        // still wins over the same key inside it.
+        const engineOptions = {
+            ...(extraOptions && typeof extraOptions === 'object' ? extraOptions : {}),
+            ...passthrough,
+        };
         if (Object.keys(styles).length > 0)
             engineOptions.styles = styles;
         if (enableHover !== undefined)
@@ -3693,7 +3861,28 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
     generateHighlightRegions(input) {
         const validated = HighlightRegionsInputSchema.parse(input);
         const regionIds = JSON.stringify(validated.regionIds);
-        const optionsStr = validated.options ? JSON.stringify(validated.options) : '{}';
+        // highlightRegions(ids, style) reads style.fill / .stroke / .strokeWidth.
+        // This passed fillColor / strokeColor / strokeWidth, so the first two were
+        // dropped and every highlight came out the default blue. A caller reaching
+        // for `color` — the obvious name, and the one a pilot actually used — was
+        // rejected by the schema before it got this far; it is accepted now and
+        // means the fill.
+        const ho = (validated.options ?? {});
+        const style = {};
+        const fill = ho.color ?? ho.fillColor ?? ho.fill;
+        if (fill !== undefined)
+            style.fill = fill;
+        const stroke = ho.strokeColor ?? ho.stroke;
+        if (stroke !== undefined)
+            style.stroke = stroke;
+        if (ho.strokeWidth !== undefined)
+            style.strokeWidth = ho.strokeWidth;
+        for (const [k, v] of Object.entries(ho)) {
+            if (!['color', 'fillColor', 'fill', 'strokeColor', 'stroke', 'strokeWidth'].includes(k) && v !== undefined) {
+                style[k] = v;
+            }
+        }
+        const optionsStr = JSON.stringify(style);
         return `
 // Highlight map regions
 (function() {
@@ -3738,7 +3927,45 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
     generateApplyDataColors(input) {
         const validated = ApplyDataColorsInputSchema.parse(input);
         const dataStr = JSON.stringify(validated.data);
-        const optionsStr = validated.options ? JSON.stringify(validated.options) : '{}';
+        // THE ENGINE TAKES A COLOUR RAMP, NOT THE NAME OF ONE.
+        //
+        // applyDataColors destructures `colorScale = ['#f7fbff', '#08519c']` — two
+        // endpoints it interpolates between — plus `domain` and `legend`. This tool
+        // published a preset NAME ('greens'), which the engine then indexed as an
+        // array: colorScale[0] of a string is 'g', and every region came out
+        // near-black. It also published minValue/maxValue/showLegend, none of which
+        // the engine reads.
+        //
+        // Translated here rather than in the schema: the names are the friendlier
+        // surface and this is ordinary cross-repo vocabulary drift, which is what
+        // the emitter exists to absorb.
+        const RAMPS = {
+            blues: ['#f7fbff', '#08519c'],
+            greens: ['#f7fcf5', '#006d2c'],
+            reds: ['#fff5f0', '#a50f15'],
+            oranges: ['#fff5eb', '#a63603'],
+            purples: ['#fcfbfd', '#54278f'],
+            heat: ['#ffffb2', '#bd0026'],
+        };
+        const o = validated.options ?? {};
+        const engineOptions = {};
+        if (o.colorScale)
+            engineOptions.colorScale = RAMPS[o.colorScale] ?? RAMPS.blues;
+        if (o.minValue !== undefined || o.maxValue !== undefined) {
+            const values = Object.values(validated.data);
+            engineOptions.domain = [
+                o.minValue ?? Math.min(...values),
+                o.maxValue ?? Math.max(...values),
+            ];
+        }
+        if (o.showLegend !== undefined)
+            engineOptions.legend = o.showLegend;
+        for (const [k, v] of Object.entries(o)) {
+            if (!['colorScale', 'minValue', 'maxValue', 'showLegend'].includes(k) && v !== undefined) {
+                engineOptions[k] = v;
+            }
+        }
+        const optionsStr = JSON.stringify(engineOptions);
         return `
 // Apply choropleth data colors
 (function() {
@@ -3805,8 +4032,18 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
   }
 
   try {
-    app.mapSystem.addLabels({ regions: ${regionsStr}, ...${optionsStr} });
-    return { success: true };
+    // addLabels() has never existed. addRegionLabel(regionId, options) is the
+    // engine's own per-region call, and this tool's input is a list of regions,
+    // so the loop IS the mapping — applyCustomLabels takes a
+    // {regionId: text} map instead, which is a different question.
+    const _labelled = [];
+    const _missed = [];
+    for (const _r of ${regionsStr}) {
+      const _item = app.mapSystem.addRegionLabel(_r, ${optionsStr});
+      (_item ? _labelled : _missed).push(_r);
+    }
+    return { success: _labelled.length > 0, labelled: _labelled, count: _labelled.length,
+      ...(_missed.length ? { notLabelled: _missed, note: 'no region on this map matched these ids — check get_highlighted_map_regions or the map you loaded.' } : {}) };
   } catch (error) {
     return { success: false, error: error.message };
   }
@@ -3831,8 +4068,13 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
   }
 
   try {
-    app.mapSystem.panTo(${validated.lat}, ${validated.lon}${Object.keys(options).length > 0 ? ', ' + JSON.stringify(options) : ''});
-    return { success: true, panTo: [${validated.lat}, ${validated.lon}] };
+    // panTo() has never existed on any studio, and there is no lat/lon pan for
+    // a flat map to route this to. Refused by NAME with the calls that do work,
+    // rather than letting the caller take an undefined-is-not-a-function.
+    return { success: false, error: 'pan_map is not supported: the engine has no lat/lon pan. '
+      + 'On a globe, rotateGlobeTo brings a coordinate to the front; on a flat map, zoom to a REGION '
+      + '(zoomToRegion) or call resetView for the whole view. This tool accepted coordinates and did '
+      + 'nothing for as long as it existed.' };
   } catch (error) {
     return { success: false, error: error.message };
   }
@@ -3857,8 +4099,11 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
   }
 
   try {
-    app.mapSystem.zoomTo(${validated.level}${Object.keys(options).length > 0 ? ', ' + JSON.stringify(options) : ''});
-    return { success: true, zoomLevel: ${validated.level} };
+    // zoomTo(level) has never existed. The engine zooms to a REGION, not to a
+    // numeric level, so there is nothing to convert a level into.
+    return { success: false, error: 'zoom_map takes a numeric level and the engine has no such call: it zooms to a REGION. '
+      + 'Use zoomToRegion with a region id, or resetView for the full view. A level was accepted here and did '
+      + 'nothing for as long as this tool existed.' };
   } catch (error) {
     return { success: false, error: error.message };
   }
@@ -3877,8 +4122,15 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
   }
 
   try {
-    const mapData = app.mapSystem.exportMap();
-    return { success: true, ...mapData };
+    // exportMap() has never existed. exportGeoJSON() is the real one, and it
+    // returns the geometry rather than a "configuration" — named accordingly
+    // instead of being spread into a shape the caller cannot rely on.
+    if (typeof app.mapSystem.exportGeoJSON !== 'function') {
+      return { success: false, error: 'this studio cannot export map data — app.mapSystem.exportGeoJSON is unavailable.' };
+    }
+    const geojson = app.mapSystem.exportGeoJSON();
+    const info = typeof app.mapSystem.getMapSourceInfo === 'function' ? app.mapSystem.getMapSourceInfo() : null;
+    return { success: true, geojson, ...(info ? { source: info } : {}) };
   } catch (error) {
     return { success: false, error: error.message };
   }
@@ -3945,7 +4197,16 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
   }
 
   try {
-    const region = app.mapSystem.getRegionAtPoint({ x: ${validated.x}, y: ${validated.y} });
+    // getRegionAtPoint() has never existed; the engine exposes no hit test.
+    // canvasToGeo turns a point into COORDINATES, which is a different answer,
+    // so it is offered rather than quietly substituted.
+    if (typeof app.mapSystem.canvasToGeo === 'function') {
+      const coord = app.mapSystem.canvasToGeo(${validated.x}, ${validated.y});
+      return { success: false, coordinate: coord,
+        error: 'the engine has no region hit test. That point is at ' + JSON.stringify(coord)
+          + ' — find regions by id with get_highlighted_map_regions or getSelectedRegions.' };
+    }
+    const region = null;
     if (region) {
       return { success: true, regionId: region.id, regionName: region.name, properties: region.properties };
     }
@@ -3999,7 +4260,7 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
   }
 
   try {
-    const result = app.mapSystem.animateWave({
+    const result = app.mapSystem.animateRegionsWave({
       duration: ${validated.duration || 10},
       loop: ${validated.loop !== false},
       colors: ${colorsStr},
@@ -4697,6 +4958,17 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
         const keyframesStr = validated.keyframes ? JSON.stringify(validated.keyframes) : 'null';
         const maskOptionsStr = validated.maskOptions ? JSON.stringify(validated.maskOptions) : '{}';
         const preset = validated.preset || validated.maskType || 'wipeLeft';
+        // MODE 3 PASSED AN ANIMATION PRESET WHERE A MASK SHAPE GOES.
+        //
+        // applyCustomMask(item, maskType, keyframes, options) wants a SHAPE —
+        // 'rectangle', 'circle', 'star'. With preset + keyframes this handed it
+        // 'iris' or 'wipeLeft', which is an animation name, so the shape was
+        // whatever the engine falls back to and the keyframes drove the wrong
+        // geometry. maskType is the field that carries the shape, and it is only
+        // used as the preset above when no preset was given at all.
+        const customShape = validated.maskType && validated.maskType !== preset
+            ? validated.maskType
+            : 'rectangle';
         // Per-preset options. Custom keyframes are an animated-mask extension —
         // when supplied, fall through to maskingSystem.applyCustomMask instead.
         return `
@@ -4712,7 +4984,7 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
     const mergedOpts = Object.assign({}, ${optionsStr}, ${maskOptionsStr});
     let maskedGroup;
     if (${keyframesStr} && app.maskingSystem && app.maskingSystem.applyCustomMask) {
-      maskedGroup = app.maskingSystem.applyCustomMask(item, '${preset}', ${keyframesStr}, mergedOpts);
+      maskedGroup = app.maskingSystem.applyCustomMask(item, '${customShape}', ${keyframesStr}, mergedOpts);
     } else {
       maskedGroup = app.applyAnimatedMask(item, '${preset}', mergedOpts);
     }
@@ -5016,6 +5288,18 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
     // the network again — so a host that allows fetch but blocks the image
     // load (CORS on <img>, a tainted-canvas refusal) now works too.
     let src = '${url}';
+    // A STAGED KEY, not the bytes. The handler writes anything over ~64KB to
+    // window.__ppStage and passes the key instead, because the governor's
+    // loop-guard transform bails on a code string that large and takes the
+    // run's return value with it. See ExecuteCodeOptions.stage.
+    if (src.indexOf('__ppStage:') === 0) {
+      const _key = src.slice('__ppStage:'.length);
+      const _staged = window.__ppStage && window.__ppStage[_key];
+      if (!_staged) {
+        return { success: false, error: 'the image bytes were staged as ' + _key + ' and are not on the page — this is a bug in the MCP server, not your call.' };
+      }
+      src = _staged;
+    }
     if (!src.startsWith('data:')) {
       let res;
       try {
@@ -5872,7 +6156,7 @@ ${mask ? `    app.imageTools.applyMask(raster, '${mask}');\n` : ''}    // The RE
 // Get history state
 (function() {
   ${guard}
-  const state = app.historyManager.getState();
+  const state = app.historyManager.getInfo();
   return { success: true, action: 'get_state', ...state };
 })();`.trim();
             default:
@@ -5949,38 +6233,45 @@ ${resolve}
         }
     }
     generateLasso(input) {
-        const guard = `if (!app.imageTools) return { error: 'ImageTools not available' };`;
+        // LASSO IS A MOUSE TOOL. IT HAS NO HEADLESS FORM.
+        //
+        // These called app.imageTools.activateLasso and .applyLasso, neither of
+        // which exists — imageTools is an ImageToolsManager and the lasso lives on
+        // app.lassoTool. `activate` is real there, but the extraction is driven by
+        // startStroke / continueStroke / endStroke: a freehand path the USER draws.
+        // There is no applyLasso to finish it, so wiring activate alone would leave
+        // a caller in a mode it cannot get out of or complete.
+        //
+        // Refused by name, with the tools that do the same job without a pointer.
+        const why = 'the lasso is an interactive mouse tool (app.lassoTool: activate, then startStroke/continueStroke/endStroke as the user draws). '
+            + 'There is no headless call that completes an extraction, so this tool could never work over MCP. '
+            + 'To cut a region without a pointer, use pinepaper_extract_object (detects and extracts by description), '
+            + 'or pinepaper_cutout_style / the mask actions on pinepaper_image_tools to shape an existing raster.';
         switch (input.action) {
             case 'activate':
-                return `
-// Activate lasso selection
-(async function() {
-  ${guard}
-  try {
-    await app.imageTools.activateLasso(${JSON.stringify(input.itemId || '')});
-    return { success: true, action: 'activate', itemId: ${JSON.stringify(input.itemId || '')} };
-  } catch (e) {
-    return { error: 'Failed to activate lasso: ' + e.message };
-  }
-})();`.trim();
             case 'apply':
                 return `
-// Apply lasso selection
-(async function() {
-  ${guard}
-  try {
-    const result = await app.imageTools.applyLasso();
-    return { success: true, action: 'apply' };
-  } catch (e) {
-    return { error: 'Failed to apply lasso: ' + e.message };
-  }
-})();`.trim();
+// Lasso — refused, rather than calling into a method that does not exist
+({ success: false, action: ${JSON.stringify(input.action)}, error: ${JSON.stringify(why)} });`.trim();
             default:
                 return `(function() { return { error: 'Unknown lasso action: ${input.action}' }; })();`;
         }
     }
     generateCutoutStyle(input) {
-        const guard = `if (!app.imageTools) return { error: 'ImageTools not available' };`;
+        // THE FACADE WAS THE WRONG ONE ENTIRELY.
+        //
+        // These called app.imageTools.applyCutoutStyle / .getCutoutStyles, and
+        // neither exists anywhere in the engine — imageTools is an
+        // ImageToolsManager and knows nothing about cutout presets. Reported from
+        // production as "apply returns success:true with the error nested inside",
+        // which is what awaiting a call on undefined inside a try looks like.
+        //
+        // The real surface is app.cutoutStyles (a CutoutStylePresets), with
+        // applyPreset(item, name, options) and getPresets(). The parity guard
+        // could not see this: readFacades resolved a class by CONVENTION —
+        // imageTools -> ImageTools, which is not the class's name — so the facade
+        // was never mapped, and an unmapped facade is not checked.
+        const guard = `if (!app.cutoutStyles) return { success: false, error: 'cutout styles are unavailable on this studio (app.cutoutStyles is absent) — update PinePaper Studio.' };`;
         switch (input.action) {
             case 'apply':
                 return `
@@ -5988,7 +6279,11 @@ ${resolve}
 (async function() {
   ${guard}
   try {
-    const result = await app.imageTools.applyCutoutStyle(${JSON.stringify(input.itemId || '')}, ${JSON.stringify(input.preset || '')}, ${JSON.stringify(input.options || {})});
+    const target = app.getItemById && app.getItemById(${JSON.stringify(input.itemId || '')});
+    if (!target) {
+      return { success: false, action: 'apply', error: 'no item ' + ${JSON.stringify(input.itemId || '')} + ' — applyPreset takes a live item, so the id has to resolve first.' };
+    }
+    const result = await app.cutoutStyles.applyPreset(target, ${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;
@@ -6005,7 +6300,9 @@ ${resolve}
 // List available cutout styles
 (function() {
   ${guard}
-  const styles = app.imageTools.getCutoutStyles();
+  const styles = typeof app.getCutoutStylePresets === 'function'
+    ? app.getCutoutStylePresets()
+    : app.cutoutStyles.getPresets();
   return { success: true, action: 'list', styles };
 })();`.trim();
             default:
@@ -6046,14 +6343,25 @@ ${resolve}
 
   const precomp = app.createPrecomp(items, opts);
   if (!precomp) return { success: false, error: 'createPrecomp returned nothing' };
-  return { success: true, action: 'create', precompId: precomp?.id || precomp, itemCount: items.length, name: ${JSON.stringify(input.name || '')} };
+  // STRINGIFIED, because the schema declares precompId as a string and the
+  // engine mints a NUMBER. Returning the number meant the id could not be
+  // round-tripped: pass it back to add/remove and zod rejects it before the
+  // call is made.
+  const _pid = precomp && precomp.id !== undefined ? precomp.id : precomp;
+  return { success: true, action: 'create', precompId: String(_pid), itemCount: items.length, name: ${JSON.stringify(input.name || '')} };
 })();`.trim();
             }
             case 'add':
                 return `
 // Add item to precomp
 (function() {
-  app.addToPrecomp(${JSON.stringify(input.precompId || '')}, ${JSON.stringify(input.itemId || '')});
+  // addToPrecomp answers falsy when the precomp or the item is not found, and
+  // this reported success regardless — the same silent-success shape as an
+  // unknown itemId elsewhere.
+  const _ok = app.addToPrecomp(${JSON.stringify(input.precompId || '')}, ${JSON.stringify(input.itemId || '')});
+  if (_ok === false || _ok === null || _ok === undefined) {
+    return { success: false, action: 'add', error: 'nothing was added — check the precompId (create returns it as a string) and the itemId with pinepaper_get_items.' };
+  }
   return { success: true, action: 'add', precompId: ${JSON.stringify(input.precompId || '')}, itemId: ${JSON.stringify(input.itemId || '')} };
 })();`.trim();
             case 'remove':
@@ -6572,7 +6880,7 @@ if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
 // Trigger interaction action
 (function() {
   ${guard}
-  app.interactionSystem.triggerAction('${input.actionType}', ${params});
+  app.interactionSystem.executeAction('${input.actionType}', ${params});
   return { success: true, action: 'trigger_action', actionType: '${input.actionType}' };
 })();`.trim();
             }
@@ -7468,6 +7776,9 @@ ${guard}
     ...(r.note ? { note: r.note } : {}) };
 })();`.trim();
             }
+            // 'list' is the spelling pinepaper_text_effect uses for the same action,
+            // accepted here so moving between the two tools does not dead-end.
+            case 'list':
             case 'list_styles': {
                 return `
 // Text styles + palettes + font axes — the picker surface
@@ -7703,9 +8014,42 @@ ${guard}
   // 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.
+  // EVERY EFFECT PLAYS FROM t=0, so in a multi-shot video they all fire on the
+  // opening frame and only the first title reads. The engine has no start
+  // delay, so the keyframes it just wrote are shifted here — the same thing a
+  // caller was doing by hand through execute_custom_code.
+  //
+  // Shifted, then held: without an explicit invisible keyframe at 0 the
+  // characters sit in their FIRST pose until the effect starts, which for most
+  // of the 37 is a scatter that looks like a bug. hideAfter closes the other
+  // end, because they otherwise survive to the end of the clip.
+  const _startAt = ${S(input.startAt ?? 0)};
+  const _hideAfter = ${S(input.hideAfter ?? null)};
+  let _shifted = 0;
+  if ((_startAt > 0 || _hideAfter) && Array.isArray(r.ids)) {
+    for (const _id of r.ids) {
+      const _it = app.getItemById && app.getItemById(_id);
+      const _kfs = _it && _it.data && _it.data.keyframes;
+      if (!Array.isArray(_kfs) || _kfs.length === 0) continue;
+      if (_startAt > 0) {
+        for (const _k of _kfs) _k.time += _startAt;
+        _kfs.unshift({ time: 0, properties: { opacity: 0 }, easing: 'linear' });
+        _kfs.splice(1, 0, { time: Math.max(0, _startAt - 0.001), properties: { opacity: 0 }, easing: 'linear' });
+      }
+      if (_hideAfter) {
+        _kfs.push({ time: Math.max(0, _hideAfter - 0.001), properties: { opacity: 1 }, easing: 'linear' });
+        _kfs.push({ time: _hideAfter, properties: { opacity: 0 }, easing: 'linear' });
+      }
+      _kfs.sort((a, b) => a.time - b.time);
+      _shifted++;
+    }
+  }
   return {
     success: true, action: 'apply', effect: r.effect, ids: r.ids, count: r.count,
-    duration: r.duration, sourceRemoved: ${S(input.keepSource !== true)},
+    duration: (r.duration || 0) + _startAt, sourceRemoved: ${S(input.keepSource !== true)},
+    ...(_startAt > 0 ? { startAt: _startAt } : {}),
+    ...(_hideAfter ? { hideAfter: _hideAfter } : {}),
+    ...((_startAt > 0 || _hideAfter) ? { retimed: _shifted } : {}),
   };
 })();`.trim();
             }
@@ -7828,7 +8172,7 @@ ${guard}
 // World3D: create — terrain, sky, shadows, walkable character, under the Paper canvas
 (async function() {
   if (typeof app.createWorld3D !== 'function') { return { success: false, error: 'app.createWorld3D unavailable — update FxTool to a world3d-capable build' }; }
-  await app.createWorld3D(${S(input.spec ?? 'forest')}, ${opts});
+  await app.createWorld3D(${S(world3dColors(input.spec ?? 'forest'))}, ${opts});
   // describe() is the world's own parameter schema — return the preset list +
   // top-level keys so the agent knows what configure can touch, without the
   // full multi-KB schema on every create.
@@ -7849,7 +8193,7 @@ ${guard}
 (function() {
   if (typeof app.configureWorld3D !== 'function') { return { success: false, error: 'app.configureWorld3D unavailable — update FxTool' }; }
 ${needWorld}
-  const r = app.configureWorld3D(${S(input.patch)});
+  const r = app.configureWorld3D(${S(world3dColors(input.patch))});
   // The validator names the right key on a wrong one — forward it verbatim.
   return r && r.ok ? { success: true, action: 'configure' } : { success: false, error: (r && r.error) || 'configure failed' };
 })();`.trim();
@@ -7905,7 +8249,7 @@ ${needWorld}
 // World3D: place an object (y defaults to sitting on the terrain)
 (function() {
 ${needWorld}
-  const id = app.addWorldObject(${S(input.object)});
+  const id = app.addWorldObject(${S(world3dColors(input.object))});
   return id ? { success: true, objectId: id } : { success: false, error: 'object not added' };
 })();`.trim();
             case 'remove_object':
@@ -8442,6 +8786,24 @@ ${guard('exportBVH')}
 ${guard('exportPNGSequence')}
   const out = await app.exportPNGSequence(${opts});
   if (!out) { return { success: false, error: 'PNG sequence produced nothing' }; }
+  // A BLOB SERIALISES TO {}. exporter.export() answers a Blob, and returning it
+  // raw produced a success whose result was an empty object — which reads as
+  // "it worked and gave me nothing" rather than "the bytes could not cross
+  // the bridge". Structured clone drops a Blob's
+  // contents; only a string survives.
+  if (typeof Blob !== 'undefined' && out instanceof Blob) {
+    const dataUrl = await new Promise(function(res, rej) {
+      const fr = new FileReader();
+      fr.onload = function() { res(fr.result); };
+      fr.onerror = function() { rej(new Error('could not read the PNG sequence')); };
+      fr.readAsDataURL(out);
+    });
+    return { success: true, format: 'png-sequence', data: dataUrl, mimeType: out.type || 'application/zip', size: out.size };
+  }
+  if (Array.isArray(out)) {
+    return { success: true, format: 'png-sequence', frames: out.length,
+      note: 'the frames stayed in the page — pass download: true to write them out.' };
+  }
   return { success: true, format: 'png-sequence', result: out };
 })();`.trim();
         }
@@ -8586,15 +8948,27 @@ ${guard('renderSoundtrackWav')}
   };
 })();`.trim();
             }
-            case 'create':
+            case 'create': {
+                const v = (input.visual ?? {});
+                const { startTime, duration, ...visualOnly } = v;
+                const placement = (startTime !== undefined || duration !== undefined)
+                    ? { ...(startTime !== undefined ? { startTime } : {}), ...(duration !== undefined ? { duration } : {}) }
+                    : null;
                 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 ?? {})});
+  const item = app.createSound(${S(input.spec ?? {})}, ${S(visualOnly)});
   if (!item) { return { success: false, error: 'the sound produced no waveform path' }; }
-  return { success: true, itemId: item.data && item.data.id, itemType: 'sound' };
+  const _sid = item.data && item.data.id;
+  // ONE CALL PER CUE, NOT TWO. startTime/duration were stripped from visual,
+  // so placing a cue meant create + set_placement every time — a pilot made
+  // 160 calls where 80 would do. Applied here when given, using the same
+  // setSoundPlacement the separate action calls.
+  ${placement ? `if (_sid && app.setSoundPlacement) { app.setSoundPlacement(_sid, ${S(placement)}); }` : ''}
+  return { success: true, itemId: _sid, itemType: 'sound'${placement ? `, placement: ${S(placement)}` : ''} };
 })();`.trim();
+            }
             case 'timbre_from_path':
                 return `
 // Sound: read a drawn path's shape as harmonic content