@pinepaper.studio/mcp-server 1.6.11 → 1.6.13

package/dist/types/code-generator.js

@@ -86,7 +86,7 @@ function generateCreateItemCode(itemType, position, properties) {
     const params = {
         x: position.x,
         y: position.y,
-        ...baseProperties,
+        ...withRadiusAxes(baseProperties),
     };
     // Handle simple solid colors in params
     if (color && !isGradient(color)) {
@@ -128,6 +128,50 @@ 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
+    // the centre — good behaviour in the editor, and nothing at all here, since
+    // the production build strips console.warn. A typo would therefore displace
+    // the item by half its own size, which is the exact bug `anchor` exists to
+    // remove, arriving silently. Checked before it is sent instead.
+    const ANCHORS = ['top-left', 'top-right', 'bottom-left', 'bottom-right', 'center', 'centre'];
+    const anchorGiven = params.anchor ?? params.origin;
+    if (anchorGiven !== undefined) {
+        const normalized = String(anchorGiven).toLowerCase().replace(/[\s_]+/g, '-');
+        if (!ANCHORS.includes(normalized)) {
+            return `
+// Create ${itemType} — refused, rather than silently centred
+({ success: false, error: ${JSON.stringify(`anchor ${JSON.stringify(String(anchorGiven))} is not one of ${ANCHORS.slice(0, 5).join(', ')}. `
+                + 'The engine would leave x/y as the CENTRE and say so only in a console this tool cannot read, '
+                + 'so the item would land half its own size away with nothing to explain it.')} });`.trim();
+        }
+        if (params.anchor !== undefined)
+            params.anchor = normalized;
+        if (params.origin !== undefined)
+            params.origin = normalized;
+    }
     // Build the code
     let code = `
 // Create ${itemType} item
@@ -393,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));
@@ -407,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();
 }
 /**
@@ -475,8 +543,62 @@ app.applyEffect(item, '${effectType}', ${JSON.stringify(params, null, 2)});
 /**
  * Template for getting items
  */
+/**
+ * radiusX / radiusY REACH NOTHING.
+ *
+ * The engine's create() feeds a shape's config from width, height and radius.
+ * radiusX and radiusY are not among them, so an ellipse asked for
+ * `{radiusX: 250, radiusY: 72}` was built at the DEFAULT 100x60 and reported
+ * success — measured from production as "about 90x50". This package documented
+ * that exact pair as the ellipse's properties and used it in two worked
+ * examples, so a model following the guide got the wrong size every time and
+ * nothing anywhere said why.
+ *
+ * Mapped rather than merely re-documented: the radii are the natural way to
+ * describe an ellipse, the conversion is unambiguous (a radius is half its
+ * axis), and a caller who already wrote radiusX should not have to rewrite it.
+ * An explicit width/height wins, so nothing that works today changes.
+ *
+ * A COMPATIBILITY SHIM WITH A REMOVAL CONDITION. FxTool aaaf98ae aliases the
+ * same pair in the engine's shared param normaliser, which is the better place
+ * — it fixes every door at once, not just this one. This stays until that
+ * reaches the studios this package is pointed at, which is not the same moment
+ * it reaches origin/main: mcp-server ships independently and drives whatever
+ * studio it is given. The two cannot fight, because this deletes radiusX
+ * before the call, so the engine's alias never sees it.
+ *
+ * Delete this when a studio without aaaf98ae is no longer worth supporting.
+ */
+function withRadiusAxes(props) {
+    const { radiusX, radiusY, ...rest } = props;
+    if (radiusX === undefined && radiusY === undefined)
+        return props;
+    const out = { ...rest };
+    if (typeof radiusX === 'number' && out.width === undefined)
+        out.width = radiusX * 2;
+    if (typeof radiusY === 'number' && out.height === undefined)
+        out.height = radiusY * 2;
+    return out;
+}
 function generateGetItemsCode(filter) {
-    if (!filter || Object.keys(filter).length === 0) {
+    // A filter OBJECT is not the same as a filter. `{}` is already handled, but
+    // so is `{ type: undefined }` and anything whose keys this function does not
+    // recognise: those have a non-zero key count and contribute no conditions,
+    // and the emitted `entries.filter(entry => )` is a SYNTAX ERROR rather than
+    // a wrong answer — the whole call dies before it runs. Decide on the
+    // conditions, not on the keys.
+    const conditions = [];
+    if (filter?.type)
+        conditions.push(`entry.type === '${filter.type}'`);
+    if (filter?.source)
+        conditions.push(`entry.source === '${filter.source}'`);
+    if (filter?.hasAnimation !== undefined) {
+        conditions.push(`!!entry.item.data?.animationType === ${filter.hasAnimation}`);
+    }
+    if (filter?.hasRelation !== undefined) {
+        conditions.push(`(app.getRelations(entry.id || entry.itemId).length > 0) === ${filter.hasRelation}`);
+    }
+    if (conditions.length === 0) {
         return `
 // Get all items
 const entries = app.itemRegistry.getAll();
@@ -491,19 +613,6 @@ const items = entries.map(entry => ({
 ({ items, count: items.length });
 `.trim();
     }
-    const conditions = [];
-    if (filter.type) {
-        conditions.push(`entry.type === '${filter.type}'`);
-    }
-    if (filter.source) {
-        conditions.push(`entry.source === '${filter.source}'`);
-    }
-    if (filter.hasAnimation !== undefined) {
-        conditions.push(`!!entry.item.data?.animationType === ${filter.hasAnimation}`);
-    }
-    if (filter.hasRelation !== undefined) {
-        conditions.push(`(app.getRelations(entry.id || entry.itemId).length > 0) === ${filter.hasRelation}`);
-    }
     return `
 // Get items with filter
 const entries = app.itemRegistry.getAll();
@@ -801,15 +910,51 @@ const stats = app.getRelationStats();
 function generateListGeneratorsCode() {
     return `
 // List available generators
-const generators = app.getAvailableBackgroundGenerators();
-const formatted = generators.map(g => ({
-  name: g.name,
-  displayName: g.displayName || g.name,
-  category: g.category || 'background',
-  description: g.description || ''
-}));
+//
+// THREE OF SEVENTY-FOUR. getAvailableBackgroundGenerators() returned a
+// hand-written literal of three names while the registry held 74 — nothing was
+// broken, the other seventy-one executed fine BY NAME, they were simply
+// invisible to anyone asking what exists. listGenerators() merges the registry
+// and awaits it; it is newer than some studios, so the old call stays as the
+// fallback and the result says which answer you got.
+//
+// Wrapped in an async IIFE deliberately: a bare top-level await parses under
+// the governor and is a syntax error on the eval path.
+(async function() {
+  let generators;
+  let complete = true;
+  if (typeof app.listGenerators === 'function') {
+    generators = await app.listGenerators();
+  } else {
+    generators = app.getAvailableBackgroundGenerators();
+    // The merged array carries a non-enumerable pending flag when the registry
+    // chunk has not landed, so a cold page honestly answers three.
+    complete = !generators || generators.pending !== true;
+  }
+  // PARAMS ARE THE WHOLE POINT OF ASKING.
+  //
+  // The tool says it lists generators "with their parameters" and this mapper
+  // dropped the params key, so every answer was a name and a sentence. A
+  // caller who wanted to know what drawGradientMesh accepts had to guess, and
+  // an unknown generatorParams key is accepted in silence — so a guess that
+  // was wrong looked exactly like one that was right.
+  const formatted = (generators || []).map(g => ({
+    name: g.name,
+    displayName: g.displayName || g.name,
+    category: g.category || 'background',
+    description: g.description || '',
+    ...(g.params ? { params: g.params } : {})
+  }));
 
-({ generators: formatted });
+  return {
+    generators: formatted,
+    count: formatted.length,
+    ...(complete ? {} : {
+      partial: true,
+      note: 'the generator registry had not finished loading, so this is a partial list — the built-ins only. Retry for the full set.',
+    }),
+  };
+})();
 `.trim();
 }
 /**
@@ -1041,6 +1186,107 @@ const ENSURE_EXPORT_ENGINE = `
   if (!app.exportEngine && typeof app.ensureHeavyModules === 'function') {
     try { await app.ensureHeavyModules(); } catch (_) { /* the guards below still speak */ }
   }`;
+/**
+ * A REMOTE <image> INSIDE AN SVG TAINTS THE CANVAS, PERMANENTLY.
+ *
+ * paper.importSVG draws a cross-origin raster straight onto the canvas. The
+ * canvas then has an origin-dirty flag, and every export afterwards throws
+ * "Tainted canvases may not be exported" — not just the one containing the
+ * image. Nothing recovers it but a page reload, so ONE import poisons the
+ * whole session, long after the call that did it returned success.
+ *
+ * Reported from production: import_svg with a picsum href answered
+ * success/itemsCreated:0 and then broke every later export.
+ *
+ * So each remote href is fetched and inlined as a data: URL before the SVG
+ * goes anywhere near the importer — the same thing import_image does, for the
+ * same reason. An href that CANNOT be inlined has its element removed: a
+ * missing picture is a visible, local, recoverable problem, and leaving it in
+ * is an unrecoverable one that surfaces somewhere else entirely.
+ */
+const INLINE_REMOTE_IMAGES = `
+  async function inlineRemoteImages(svgText) {
+    const notes = [];
+    const hrefs = [];
+    const re = /(?:xlink:)?href\\s*=\\s*("|')(https?:\\/\\/[^"']+)\\1/gi;
+    let m;
+    while ((m = re.exec(svgText)) !== null) if (hrefs.indexOf(m[2]) === -1) hrefs.push(m[2]);
+    if (hrefs.length === 0) return { svg: svgText, notes: notes };
+    for (const href of hrefs) {
+      let dataUrl = null;
+      try {
+        const r = await fetch(href, { mode: 'cors' });
+        if (r.ok) {
+          const blob = await r.blob();
+          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 ' + href)); };
+            fr.readAsDataURL(blob);
+          });
+        }
+      } catch (e) { /* fall through to removal */ }
+      if (dataUrl) {
+        svgText = svgText.split(href).join(dataUrl);
+      } else {
+        // Drop the element rather than let it taint the canvas.
+        const esc = href.replace(/[.*+?^\\\${}()|[\\]\\\\]/g, '\\\\$&');
+        svgText = svgText.replace(new RegExp('<image\\\\b[^>]*' + esc + '[^>]*\\\\/?>', 'gi'), '');
+        svgText = svgText.replace(new RegExp('<image\\\\b[^>]*' + esc + '[\\\\s\\\\S]*?<\\\\/image>', 'gi'), '');
+        notes.push({
+          url: href,
+          action: 'removed',
+          reason: 'unfetchable',
+          message: 'removed an embedded image this page could not fetch (' + href + '). It was dropped rather than imported, because a cross-origin raster taints the canvas and every later export would have failed with "Tainted canvases may not be exported" until a reload.',
+        });
+      }
+    }
+    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
@@ -1265,7 +1511,10 @@ export class PinePaperCodeGenerator {
   if (!response.ok) {
     return { success: false, error: 'the server refused ${url} — HTTP ' + response.status + ' ' + (response.statusText || ''), status: response.status };
   }
-  const svgText = await response.text();
+  let svgText = await response.text();
+${INLINE_REMOTE_IMAGES}
+  const _inl = await inlineRemoteImages(svgText);
+  svgText = _inl.svg;
   const _r = ${importExpr('svgText')};
   const imported = _r.item;
   if (!imported) {
@@ -1275,7 +1524,8 @@ export class PinePaperCodeGenerator {
   imported.scale(${scale});
   const itemId = app.registerItem(imported, 'svg-import', { source: 'mcp' });
   app.historyManager.saveState();
-  return { success: true, itemId, changes: _r.changes, position: { x: ${position.x}, y: ${position.y} } };
+  return { success: true, itemId, changes: _r.changes, position: { x: ${position.x}, y: ${position.y} },
+    ...(_inl.notes.length ? { imageWarnings: _inl.notes } : {}) };
 })();
 `.trim();
         }
@@ -1284,18 +1534,23 @@ export class PinePaperCodeGenerator {
             const escapedSvg = svgString.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$/g, '\\$');
             return `
 // Import SVG string${source === 'figma' ? ' (Figma-normalised)' : ''}
-const svgString = \`${escapedSvg}\`;
+(async function() {
+let svgString = \`${escapedSvg}\`;
+${INLINE_REMOTE_IMAGES}
+const _inl = await inlineRemoteImages(svgString);
+svgString = _inl.svg;
 const _r = ${importExpr('svgString')};
 const imported = _r.item;
-if (imported) {
-  imported.position = new paper.Point(${position.x}, ${position.y});
-  imported.scale(${scale});
-  const itemId = app.registerItem(imported, 'svg-import', { source: 'mcp' });
-  app.historyManager.saveState();
-  ({ success: true, itemId, changes: _r.changes, position: { x: ${position.x}, y: ${position.y} } });
-} else {
+if (!imported) {
   throw new Error('Failed to import SVG');
 }
+imported.position = new paper.Point(${position.x}, ${position.y});
+imported.scale(${scale});
+const itemId = app.registerItem(imported, 'svg-import', { source: 'mcp' });
+app.historyManager.saveState();
+return { success: true, itemId, changes: _r.changes, position: { x: ${position.x}, y: ${position.y} },
+  ...(_inl.notes.length ? { imageWarnings: _inl.notes } : {}) };
+})();
 `.trim();
         }
         return `
@@ -1865,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();
     }
     /**
@@ -2217,11 +2490,28 @@ throw new Error('Unknown diagram mode action: ${action}');
     hasImages: false,
   };
 
-  // Get canvas size
-  if (app.canvasEl) {
-    analysis.canvasSize = { width: app.canvasEl.width, height: app.canvasEl.height };
-  } else if (paper.view) {
-    analysis.canvasSize = { width: paper.view.size.width, height: paper.view.size.height };
+  // THE ARTBOARD, NOT THE BACKING STORE.
+  //
+  // canvasEl.width and paper.view.size are both in device pixels, so a
+  // 1920x1080 artboard was reported as 2233x1472 — measured from production.
+  // That is not even the device pixel ratio (a 2233px store in a 924px box is
+  // 2.4166), so a caller cannot divide it back out. Anything derived from it
+  // is wrong by an unknown factor, and synthetic clicks computed from it miss
+  // in silence. getCanvasSize() is the artboard the caller set.
+  if (typeof app.getCanvasSize === 'function') {
+    const cs = app.getCanvasSize();
+    if (cs && cs.width) analysis.canvasSize = { width: cs.width, height: cs.height };
+  }
+  if (!analysis.canvasSize.width) {
+    if (app.canvasSize && app.canvasSize.width) {
+      analysis.canvasSize = { width: app.canvasSize.width, height: app.canvasSize.height };
+    } else if (app.canvasEl) {
+      // Last resort on a studio with neither: a backing-store size is better
+      // than zero, and it is flagged so nobody treats it as the artboard.
+      analysis.canvasSize = { width: app.canvasEl.width, height: app.canvasEl.height, backingStore: true };
+    } else if (paper.view) {
+      analysis.canvasSize = { width: paper.view.size.width, height: paper.view.size.height, backingStore: true };
+    }
   }
 
   // Count items and analyze
@@ -2261,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;
   }
 
@@ -2468,7 +2762,7 @@ throw new Error('Unknown diagram mode action: ${action}');
         switch (op.type) {
             case 'create': {
                 const pos = op.position || { x: 400, y: 300 };
-                const createProps = (op.properties || {});
+                const createProps = withRadiusAxes((op.properties || {}));
                 const props = JSON.stringify(createProps);
                 let createCode = `
 const item = app.create('${op.itemType}', { position: { x: ${pos.x}, y: ${pos.y} }, ...${props} });
@@ -2796,6 +3090,19 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
         const scaled = scale !== undefined && scale !== 1
             ? { width: even(preset.width * scale), height: even(preset.height * scale) }
             : { width: preset.width, height: preset.height };
+        // 'auto' MEANS THE CANVAS, NOT A PRESET THAT HAPPENS TO BE FIRST.
+        //
+        // `platform` defaults to 'auto', 'auto' is not a key in platformPresets,
+        // and the lookup falls through to `web` — so an export that named no
+        // platform silently rendered 800x600. A beta probe measured exactly that:
+        // three exports of a 960x540 canvas all came back 800x600, reported as a
+        // dimension mismatch because from outside it is one. Nothing said the
+        // canvas had been replaced by a preset.
+        //
+        // Resolved in the generated code rather than here, because the canvas size
+        // is only known in the page. The preset stays the fallback for a studio
+        // too old to report one, and `scale` still applies either way.
+        const usesCanvasSize = !platformPresets[platform];
         // 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.
@@ -2880,7 +3187,35 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
   // doubled the frame count and the render time — a surprise the schema used
   // to hide because there was no way to ask for one without the other.
   const settings = ${JSON.stringify(fps !== undefined ? { ...qualitySettings, fps } : qualitySettings)};
-  const dimensions = ${JSON.stringify(scaled)};
+${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as a fallback for a
+  // studio too old to report one. Named platforms emit a plain object literal
+  // just below, so what they render stays readable in the code itself.
+  const __presetDims = ${JSON.stringify(scaled)};
+  const __canvasDims = app.canvasSize || (app.view && app.view.viewSize) || null;
+  const __even = (n) => Math.max(2, Math.round((n * ${scale !== undefined ? scale : 1}) / 2) * 2);
+  const dimensions = (__canvasDims && __canvasDims.width && __canvasDims.height)
+    ? { width: __even(__canvasDims.width), height: __even(__canvasDims.height) }
+    : __presetDims;` : `  const dimensions = ${JSON.stringify(scaled)};`}
+
+  // WHAT THIS SCENE LOSES TO THIS FORMAT, asked at the moment you would care.
+  //
+  // exportFidelity walks the actual scene: a PNG of an animated scene is one
+  // frame, a GIF with a soundtrack drops it, a wav of a silent scene is
+  // silence. The engine derived it so that 117 tool descriptions would not
+  // have to answer "does this survive export?" by hand and drift.
+  //
+  // Reported ONLY when there is something to report. An empty list would read
+  // as "this format is lossless", and it does not mean that — it means this
+  // scene has nothing THIS format will lose. Omitting it entirely is the one
+  // shape that cannot be misread, and it keeps a clean export quiet.
+  function fidelity(fmt) {
+    try {
+      if (!app.exportEngine || typeof app.exportEngine.exportFidelity !== 'function') return {};
+      const r = app.exportEngine.exportFidelity(fmt);
+      if (!r || !r.warnings || r.warnings.length === 0) return {};
+      return { fidelity: { warnings: r.warnings, checked: r.checked } };
+    } catch (e) { return {}; }
+  }
 
   // Preflight: same resolved settings as the real export, but render nothing.
   // Branching HERE rather than in a separate tool is deliberate — the estimate
@@ -2906,6 +3241,7 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
       fps: settings.fps,
       dimensions: dimensions.width + 'x' + dimensions.height,
       estimate: est,
+      ...fidelity(format),
     };
   }
 
@@ -2932,13 +3268,38 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
     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 };
@@ -2960,14 +3321,35 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
 
       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');
@@ -3135,6 +3517,11 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
     result = { success: false, error: e.message, platform, format };
   }
 
+  // One site, after every branch has set its result: a successful export says
+  // what this scene lost to this format, rather than the caller finding out by
+  // opening the file. Only when there is something to say — see fidelity().
+  if (result && result.success) Object.assign(result, fidelity(format));
+
   return result;
 })();
 `.trim();
@@ -3161,11 +3548,28 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
     hasImages: false,
   };
 
-  // Get canvas size
-  if (app.canvasEl) {
-    analysis.canvasSize = { width: app.canvasEl.width, height: app.canvasEl.height };
-  } else if (paper.view) {
-    analysis.canvasSize = { width: paper.view.size.width, height: paper.view.size.height };
+  // THE ARTBOARD, NOT THE BACKING STORE.
+  //
+  // canvasEl.width and paper.view.size are both in device pixels, so a
+  // 1920x1080 artboard was reported as 2233x1472 — measured from production.
+  // That is not even the device pixel ratio (a 2233px store in a 924px box is
+  // 2.4166), so a caller cannot divide it back out. Anything derived from it
+  // is wrong by an unknown factor, and synthetic clicks computed from it miss
+  // in silence. getCanvasSize() is the artboard the caller set.
+  if (typeof app.getCanvasSize === 'function') {
+    const cs = app.getCanvasSize();
+    if (cs && cs.width) analysis.canvasSize = { width: cs.width, height: cs.height };
+  }
+  if (!analysis.canvasSize.width) {
+    if (app.canvasSize && app.canvasSize.width) {
+      analysis.canvasSize = { width: app.canvasSize.width, height: app.canvasSize.height };
+    } else if (app.canvasEl) {
+      // Last resort on a studio with neither: a backing-store size is better
+      // than zero, and it is flagged so nobody treats it as the artboard.
+      analysis.canvasSize = { width: app.canvasEl.width, height: app.canvasEl.height, backingStore: true };
+    } else if (paper.view) {
+      analysis.canvasSize = { width: paper.view.size.width, height: paper.view.size.height, backingStore: true };
+    }
   }
 
   // Count items and analyze types
@@ -3212,12 +3616,16 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
 
   // 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;
   }
 
@@ -3372,8 +3780,59 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
      */
     generateLoadMap(input) {
         const validated = LoadMapInputSchema.parse(input);
-        const { mapId, ...mapOptions } = validated;
-        const optionsStr = Object.keys(mapOptions).length > 0 ? JSON.stringify(mapOptions) : '{}';
+        const { mapId, ...raw } = validated;
+        // THIS SCHEMA AND loadMap() SHARED ALMOST NO VOCABULARY.
+        //
+        // loadMap(source, options) destructures projection, center, scale, rotate,
+        // fitBounds, parent, styles, style, interactive, selectable, showOcean,
+        // oceanColor, quality, smoothPaths and simplifyTolerance. Of the twelve
+        // options this tool offered, SEVEN were none of those: the styling keys
+        // live nested under `styles` and are spelled differently there, and the two
+        // 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, options: extraOptions, ...passthrough } = raw;
+        // The engine's own style vocabulary — see stylePresets in MapSystem.js.
+        const styles = {};
+        if (fillColor !== undefined)
+            styles.fill = fillColor;
+        if (strokeColor !== undefined)
+            styles.stroke = strokeColor;
+        // strokeWidth only survives inside `styles`; the merge overwrites a
+        // top-level one with the quality preset's value.
+        if (strokeWidth !== undefined)
+            styles.strokeWidth = strokeWidth;
+        if (hoverFill !== undefined)
+            styles.hoverFill = hoverFill;
+        // hoverStroke reads from mergedStyles beside hoverFill, so it belongs in
+        // the same place. It landed late — the two MCP specs documented it for a
+        // long time before any source file did — and an older studio merges it,
+        // finds nothing that reads it, and leaves the outline at the base stroke.
+        // Mapped rather than stripped so it simply starts working on such a studio
+        // without a change here, and reported below so a caller on an older one
+        // learns why their outline did not move.
+        if (hoverStroke !== undefined)
+            styles.hoverStroke = hoverStroke;
+        // `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)
+            engineOptions.interactive = enableHover;
+        if (enableClick !== undefined)
+            engineOptions.selectable = enableClick;
+        const ignored = hoverStroke !== undefined ? ['hoverStroke'] : [];
+        const optionsStr = Object.keys(engineOptions).length > 0 ? JSON.stringify(engineOptions) : '{}';
+        const warn = ignored.length
+            ? `\n      conditional: ${JSON.stringify(ignored)},\n      note: 'hoverStroke needs a studio recent enough to read it; an older one ignores it and the hover outline stays the base stroke.',`
+            : '';
         return `
 // Load geographic map
 (async function() {
@@ -3388,7 +3847,7 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
       mapId: result.mapId || '${mapId}',
       regions: result.regions?.length || 0,
       bounds: result.bounds,
-      center: result.center
+      center: result.center,${warn}
     };
   } catch (error) {
     return { success: false, error: error.message };
@@ -3402,7 +3861,28 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
     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() {
@@ -3447,7 +3927,45 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
     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() {
@@ -3514,8 +4032,18 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
   }
 
   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 };
   }
@@ -3540,8 +4068,13 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
   }
 
   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 };
   }
@@ -3566,8 +4099,11 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
   }
 
   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 };
   }
@@ -3586,8 +4122,15 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
   }
 
   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 };
   }
@@ -3654,7 +4197,16 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
   }
 
   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 };
     }
@@ -3708,7 +4260,7 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
   }
 
   try {
-    const result = app.mapSystem.animateWave({
+    const result = app.mapSystem.animateRegionsWave({
       duration: ${validated.duration || 10},
       loop: ${validated.loop !== false},
       colors: ${colorsStr},
@@ -4406,6 +4958,17 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
         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 `
@@ -4421,7 +4984,7 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
     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);
     }
@@ -4641,7 +5204,51 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
   }
   try {
     await app.templateManager.loadTemplate('${templateId}', true);
-    return { success: true, templateId: '${templateId}', message: 'Template applied successfully. Canvas has been replaced with template content.' };
+
+    // DID THE CLIPPED CHARACTER PARTS SURVIVE?
+    //
+    // A clipped character group is saved with its nested texture and mask in
+    // paperJSON. A studio whose restore predates the reader for that key
+    // rebuilds it through the generic group branch instead — an empty,
+    // unclipped group — so the part is written to the template correctly and
+    // dropped on the way back in, with nothing raised.
+    //
+    // Checked by BEHAVIOUR, not by version: the template says how many clipped
+    // groups it carries, the canvas says how many came back. An engine that
+    // restores them makes this condition unreachable, so it needs no removing
+    // later; an older studio is exactly where it still matters, and this
+    // package ships independently of the studio it drives.
+    //
+    // THE WARNING MATTERS MORE THAN THE LOAD. Loading is harmless and
+    // reversible — the file on disk still holds the paperJSON, so the same
+    // template reloads intact on a studio that can read it. Re-SAVING from
+    // this canvas is not: the exporter would serialise the empty group it can
+    // see, and the texture and mask would leave the file for good.
+    let fidelity = {};
+    try {
+      const tpl = (app.templateManager.getAllTemplates() || [])
+        .find(function(t) { return t && (t.id === '${templateId}' || t.templateId === '${templateId}'); });
+      const items = tpl && tpl.data && Array.isArray(tpl.data.items) ? tpl.data.items : null;
+      const declared = items ? items.filter(function(i) { return i && i.type === 'group' && i.paperJSON; }).length : 0;
+      if (declared > 0 && app.itemRegistry && typeof app.itemRegistry.getAll === 'function') {
+        const clipped = (app.itemRegistry.getAll() || []).filter(function(e) {
+          const it = e && (e.item || e);
+          return it && it.className === 'Group' && it.clipped === true;
+        }).length;
+        if (clipped === 0) {
+          fidelity = {
+            clippedPartsLost: declared,
+            warning: 'This template carries ' + declared + ' clipped character part(s) with a nested texture and mask, '
+              + 'and this studio restored none of them — they are on the canvas as empty groups. '
+              + 'DO NOT SAVE THIS CANVAS BACK OVER THE TEMPLATE: the export would write the empty groups and the '
+              + 'texture would be lost from the file permanently. The template itself is still intact; update the '
+              + 'studio and load it again.',
+          };
+        }
+      }
+    } catch (e) { /* a check that cannot run must not fail the load */ }
+
+    return { success: true, templateId: '${templateId}', message: 'Template applied successfully. Canvas has been replaced with template content.', ...fidelity };
   } catch (e) {
     return { error: 'Failed to apply template: ' + e.message };
   }
@@ -4681,13 +5288,25 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
     // 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 {
         res = await fetch(src);
       } catch (netErr) {
         return { success: false, error: 'could not reach ' + src + ' — ' + (netErr && netErr.message ? netErr.message : 'network request failed')
-          + '. This is the browser\'s network stack: check the host resolves, the port is open, and that any proxy passes plain HTTP as well as HTTPS CONNECT.' };
+          + '. The failure is in the browser network stack: check the host resolves, the port is open, and that any proxy passes plain HTTP as well as HTTPS CONNECT.' };
       }
       if (!res.ok) {
         return { success: false, error: 'the server refused ' + src + ' — HTTP ' + res.status + ' ' + (res.statusText || ''), status: res.status };
@@ -5537,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:
@@ -5614,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 `
@@ -5653,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;
@@ -5670,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:
@@ -5711,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':
@@ -6237,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();
             }
@@ -7133,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
@@ -7368,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();
             }
@@ -7493,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.
@@ -7514,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();
@@ -7570,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':
@@ -7935,6 +8614,40 @@ ${needWorld}
         for (const [k, v] of Object.entries(rest))
             if (v !== undefined)
                 opts[k] = v;
+        // SPREAD-THROUGH IS NOT THE SAME AS AGREEING.
+        //
+        // Everything above this line reaches app.stickFigure verbatim, which made
+        // the schema look consumed to every guard we have while four fields meant
+        // something the engine does not. The engine compares propSide against
+        // 'L' | 'R', so 'right' — which the schema declared and advertised —
+        // matched neither arm of that test and every prop went to the LEFT hand.
+        // Nothing failed; the figure just held it in the wrong hand, forever.
+        if (action === 'figure') {
+            const side = typeof opts.propSide === 'string' ? opts.propSide : undefined;
+            if (side)
+                opts.propSide = side.toUpperCase().startsWith('R') ? 'R' : 'L';
+            // The engine iterates opts.walk, so `true` — the form the schema itself
+            // advertised as "the default" — walked exactly nowhere.
+            if (opts.walk === true)
+                opts.walk = [{ seconds: 1.2, from: 0 }];
+            else if (opts.walk === false)
+                delete opts.walk;
+            // `facing` is read for chairs and for nothing else. Passing it here
+            // would be accepted and ignored, which is the thing being fixed, so it
+            // is refused by name instead — the add_ports precedent.
+            if (opts.facing !== undefined) {
+                // Built through S() rather than interpolated: the message names two
+                // quoted values, and hand-escaping them into a single-quoted emitted
+                // string produced a syntax error the first time.
+                const msg = `facing is a property of a chair, not of a figure — app.stickFigure `
+                    + `never reads it, so ${String(opts.facing)} would have been accepted and ignored. `
+                    + `A figure faces the way it travels, so give it travel, or a pose that turns it. `
+                    + `facing belongs on action "set" with kind "chair".`;
+                return `
+// Stick: figure — refused, rather than accepted and ignored
+({ success: false, error: ${S(msg)} });`.trim();
+            }
+        }
         const fn = action === 'figure' ? 'stickFigure' : 'stickSet';
         return `
 // Stick: ${action}
@@ -8073,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();
         }
@@ -8217,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