@pinepaper.studio/mcp-server 1.6.10 → 1.6.12

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,29 @@ 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)}; }`;
     }
+    // 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
@@ -181,12 +204,27 @@ app.historyManager.saveState();
  */
 function generateModifyItemCode(itemId, properties) {
     const { contentType, contentFormat, countdownTarget, countdownEndText, ...restProperties } = properties;
+    // modifyItem(id, changes), NOT select() + modify().
+    //
+    // modify() operates on the SELECTION, so this selected an id and then edited
+    // whatever was selected — on an id that does not resolve, select changes
+    // nothing and modify edits the PREVIOUS selection instead. modifyItem takes
+    // the reference and returns false when it cannot resolve it, which is the
+    // answer this emitter needs and never asked for.
+    //
+    // The warning the engine logs on that path is console.warn, which production
+    // strips, so the failure was invisible twice over.
     let code = `
 // Modify item ${itemId}
-app.select('${itemId}');`;
-    // Pass non-dynamic-content properties to app.modify
+let _modified = true;`;
     if (Object.keys(restProperties).length > 0) {
-        code += `\napp.modify(${JSON.stringify(restProperties, null, 2)});`;
+        code += `
+_modified = app.modifyItem('${itemId}', ${JSON.stringify(restProperties, null, 2)}) !== false;
+if (!_modified) { return { success: false, error: 'no item ${itemId} — nothing was modified' }; }`;
+    }
+    else {
+        code += `
+if (!app.getItemById('${itemId}')) { return { success: false, error: 'no item ${itemId}' }; }`;
     }
     // Handle dynamic content type changes
     if (contentType !== undefined) {
@@ -212,10 +250,10 @@ if (entry && entry.item && app.setDynamicContent) app.setDynamicContent(entry.it
     }
     code += `
 app.historyManager.saveState();
-
-// Return success
-({ success: true, itemId: '${itemId}' });`;
-    return code.trim();
+return { success: true, itemId: '${itemId}' };`;
+    // Wrapped, because the body now RETURNS early on a miss rather than falling
+    // through to an unconditional success.
+    return `(function() {\n${code.trim()}\n})();`;
 }
 /**
  * Template for deleting items
@@ -460,8 +498,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();
@@ -476,19 +568,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();
@@ -675,9 +754,24 @@ function generateSetCanvasSizeCode(width, height, preset) {
         : `{ width: ${width}, height: ${height} }`;
     return `
 // Set canvas size
-app.setCanvasSize(${sizeArg});
-app.historyManager.saveState();
-({ success: true, width: ${width}, height: ${height} });
+(function() {
+  // READ THE VERDICT. This called setCanvasSize and then declared success with
+  // the dimensions it had ASKED for — so an unknown preset, or a width of -5,
+  // came back as a successful resize while the canvas was left exactly as it
+  // was. The engine now refuses by name; older builds return undefined, which
+  // is not a refusal and must not be read as one.
+  const r = app.setCanvasSize(${sizeArg});
+  if (r && r.ok === false) {
+    return { success: false, error: r.reason || 'the canvas size was refused',
+      ...(r.known ? { knownPresets: r.known } : {}) };
+  }
+  app.historyManager.saveState();
+  // Report what the canvas ACTUALLY took where the engine says so, rather than
+  // echoing the request back.
+  return { success: true, width: (r && r.width) || ${width}, height: (r && r.height) || ${height},
+    ...(r && r.preset ? { preset: r.preset } : {}),
+    ...(r && r.unbounded !== undefined ? { unbounded: r.unbounded } : {}) };
+})();
 `.trim();
 }
 /**
@@ -771,15 +865,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();
 }
 /**
@@ -1011,6 +1141,64 @@ 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 };
+  }
+`;
 export class PinePaperCodeGenerator {
     /**
      * Generate code for creating an item
@@ -1220,19 +1408,37 @@ export class PinePaperCodeGenerator {
         if (url) {
             return `
 // Import SVG from URL${source === 'figma' ? ' (Figma-normalised)' : ''}
-const response = await fetch('${url}');
-const svgText = await response.text();
-const _r = ${importExpr('svgText')};
-const imported = _r.item;
-if (imported) {
+// WRAPPED, because these were bare top-level statements with an await. That
+// parses under the governor, which builds an AsyncFunction, and is a SYNTAX
+// ERROR on the eval fallback — so importing an SVG by URL never ran at all on
+// a studio without runGenerated. A paren-led async IIFE parses on both and
+// still gives the governor a trailing expression to capture.
+(async function() {
+  let response;
+  try {
+    response = await fetch('${url}');
+  } catch (netErr) {
+    return { success: false, error: 'could not reach ${url} — ' + ((netErr && netErr.message) || 'network request failed') };
+  }
+  if (!response.ok) {
+    return { success: false, error: 'the server refused ${url} — HTTP ' + response.status + ' ' + (response.statusText || ''), status: response.status };
+  }
+  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) {
+    return { success: false, error: 'the response from ${url} did not parse as SVG. Check the URL serves the file itself rather than a page around it.' };
+  }
   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 {
-  throw new Error('Failed to import SVG from URL');
-}
+  return { success: true, itemId, changes: _r.changes, position: { x: ${position.x}, y: ${position.y} },
+    ...(_inl.notes.length ? { imageWarnings: _inl.notes } : {}) };
+})();
 `.trim();
         }
         if (svgString) {
@@ -1240,18 +1446,23 @@ if (imported) {
             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 `
@@ -2173,11 +2384,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
@@ -2424,7 +2652,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} });
@@ -2465,8 +2693,12 @@ return { itemId };
                 const modifyProps = JSON.stringify(op.properties || {});
                 return `
 const targetId = ${itemRef};
-app.select(targetId);
-app.modify(${modifyProps});
+// modifyItem(id, changes), not select() + modify(). modify() edits the
+// SELECTION, so an id that does not resolve left the PREVIOUS selection to be
+// edited instead — and this then reported modified:true either way.
+if (app.modifyItem(targetId, ${modifyProps}) === false) {
+  return { success: false, itemId: targetId, error: 'no item ' + targetId + ' — nothing was modified' };
+}
 return { itemId: targetId, modified: true };
 `;
             case 'animate':
@@ -2541,9 +2773,16 @@ return { success: true, generator: '${genName}'${op.generatorRegion ? ', region:
                 const h = op.height || 1080;
                 const sizeArg = op.preset ? `'${op.preset}'` : `{ width: ${w}, height: ${h} }`;
                 return `
-app.setCanvasSize(${sizeArg});
+// Read the verdict, as the standalone tool now does: an unknown preset or an
+// out-of-range dimension is refused by name, and reporting the size we ASKED
+// for left the batch claiming a resize that never happened.
+const _cs = app.setCanvasSize(${sizeArg});
+if (_cs && _cs.ok === false) {
+  return { success: false, error: _cs.reason || 'the canvas size was refused',
+    ...(_cs.known ? { knownPresets: _cs.known } : {}) };
+}
 await new Promise(r => setTimeout(r, 50));
-return { success: true, width: ${w}, height: ${h} };
+return { success: true, width: (_cs && _cs.width) || ${w}, height: (_cs && _cs.height) || ${h} };
 `;
             }
             case 'keyframe_animate': {
@@ -2741,6 +2980,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.
@@ -2825,7 +3077,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
@@ -2851,6 +3131,7 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
       fps: settings.fps,
       dimensions: dimensions.width + 'x' + dimensions.height,
       estimate: est,
+      ...fidelity(format),
     };
   }
 
@@ -3080,6 +3361,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();
@@ -3106,11 +3392,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
@@ -3317,8 +3620,51 @@ 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, ...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;
+        const engineOptions = { ...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() {
@@ -3333,7 +3679,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 };
@@ -4071,7 +4417,7 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
         // records the baked offset at item.data._bakedRotation and sums the two itself
         // (PinePaper.js does exactly this); read the same sum rather than the half of
         // it that happens to be zero.
-        const _rot = (item.data?._bakedRotation || 0) + (item.rotation || 0);
+        const _rot = typeof app.authoredRotation === 'function' ? app.authoredRotation(item) : ((item.data?._bakedRotation || 0) + (item.rotation || 0));
         if (_rot) itemData.properties.rotation = _rot;
         if (item.data?.content) itemData.properties.content = item.data.content;
         if (item.visible === false) itemData.properties.visible = false;
@@ -4433,6 +4779,33 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
   }
 })();
 `.trim();
+    }
+    /**
+     * What THIS item can animate, from the engine's own table.
+     *
+     * The table is derived from the applier rather than written beside it, so it
+     * cannot drift from what actually gets applied — and it is filtered by item
+     * type, because the trim/dash four only exist on a path and a rectangle has
+     * no fontSize.
+     *
+     * `interpolates: false` is passed through VERBATIM and never flattened away.
+     * `content` and `blendMode` are DISCRETE — they hold their value until the
+     * next keyframe rather than blending toward it — and treating content as
+     * tweenable is what made every word in a cycler appear half a beat early.
+     * A list that says only "animatable" rebuilds that bug in the next agent.
+     */
+    generateListItemAnimatableProperties(itemId) {
+        return `
+// Animatable properties of ${JSON.stringify(itemId)}
+(function() {
+  if (typeof app.listAnimatableProperties !== 'function') {
+    return { success: false, error: 'app.listAnimatableProperties unavailable — update the studio. The keyframe tool lists the properties it accepts in its own description meanwhile.' };
+  }
+  const item = app.getItemById(${JSON.stringify(itemId)});
+  if (!item) { return { success: false, error: 'no item ${itemId}' }; }
+  const r = app.listAnimatableProperties(item);
+  return { success: true, ...r };
+})();`.trim();
     }
     generateGetAnimatableProperties() {
         return `
@@ -4559,7 +4932,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 };
   }
@@ -4605,7 +5022,7 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
         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 };
@@ -4829,7 +5246,21 @@ ${mask ? `    app.imageTools.applyMask(raster, '${mask}');\n` : ''}    // The RE
 // Toggle loop mode
 (function() {
   ${guard}
-  app.sceneManager.setLoop(${input.enabled ?? true});
+  // chainLoop is a PROPERTY, set by createChain({loop}) and read by the chain
+  // advance. setLoop has never existed, so this reported a toggle it had not
+  // performed — and a chain built without loop went on not looping.
+  if (typeof app.sceneManager.setLoop === 'function') {
+    app.sceneManager.setLoop(${input.enabled ?? true});
+  } else if ('chainLoop' in app.sceneManager) {
+    app.sceneManager.chainLoop = ${input.enabled ?? true};
+  } else {
+    return { success: false, action: 'toggle_loop',
+      error: 'this build has no chain-loop control to set. Pass loop:true to create_chain instead, which is where the setting is read from.' };
+  }
+  if (!app.sceneManager.sceneChain || !app.sceneManager.sceneChain.length) {
+    return { success: true, action: 'toggle_loop', enabled: ${input.enabled ?? true},
+      note: 'no chain exists yet — this setting applies to the next one created, and create_chain takes loop directly.' };
+  }
   return { success: true, action: 'toggle_loop', enabled: ${input.enabled ?? true} };
 })();
 `.trim();
@@ -5707,7 +6138,7 @@ ${resolve}
     bounds: item.bounds ? { x: item.bounds.x, y: item.bounds.y, width: item.bounds.width, height: item.bounds.height } : null,
     visible: item.visible,
     opacity: item.opacity,
-    rotation: (item.data?._bakedRotation || 0) + (item.rotation || 0),
+    rotation: typeof app.authoredRotation === 'function' ? app.authoredRotation(item) : ((item.data?._bakedRotation || 0) + (item.rotation || 0)),
     selected: item.selected,
   };
 })();`.trim();
@@ -6481,7 +6912,7 @@ if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
   const entry = app.itemRegistry.get(${itemIdStr});
   if (!entry || !entry.item) return { error: 'Item not found: ' + ${itemIdStr} };
   const b = entry.item.bounds;
-  return { success: true, action: 'get_dimensions', itemId: ${itemIdStr}, x: b.x, y: b.y, width: b.width, height: b.height, rotation: (entry.item.data?._bakedRotation || 0) + (entry.item.rotation || 0) };
+  return { success: true, action: 'get_dimensions', itemId: ${itemIdStr}, x: b.x, y: b.y, width: b.width, height: b.height, rotation: typeof app.authoredRotation === 'function' ? app.authoredRotation(entry.item) : ((entry.item.data?._bakedRotation || 0) + (entry.item.rotation || 0)) };
 })();`.trim();
             }
             case 'set_snap': {
@@ -6990,10 +7421,25 @@ ${guard}
                 });
                 return `
 // Display text style: ${input.styleKey} — stacked-layer title, id adopted from the text
-(function() {
+(async function() {
   if (typeof app.applyTextStyle !== 'function') { return { success: false, error: 'app.applyTextStyle unavailable — update FxTool to a text-styles build' }; }
+  // LOAD THE FACES FIRST. The decorative stylesheet is fetched on pointerenter
+  // over the style grid — a gesture no agent ever makes — so every decorative
+  // family was missing in production and a style asking for one silently drew
+  // the fallback and reported success. ensureFontsLoaded is the fix; guarded,
+  // because a studio without it behaves as it always did.
+  if (typeof app.ensureFontsLoaded === 'function') {
+    try { await app.ensureFontsLoaded('decorative'); } catch (_) { /* the pending flag below still reports it */ }
+  }
   const r = app.applyTextStyle(${S(input.itemId)}, ${S(input.styleKey)}, ${opts});
   if (!r || !r.ok) { return { success: false, error: (r && r.error) || 'style failed' }; }
+  // fontPending: the face is not there YET, so this drew in the fallback. Said
+  // out loud rather than left to be discovered in the export.
+  if (r.fontPending) {
+    return { success: true, action: 'apply_style', id: r.id, style: r.style, layers: r.layers,
+      palette: r.palette, bounds: r.bounds, fontPending: true,
+      warning: 'the face for this style had not loaded, so it drew in a FALLBACK font. Re-apply the style, or call pinepaper_font check with the family and your text to see what is really being used.' };
+  }
   // The styled group ADOPTS the text item's registry id — r.id is the SAME id
   // the caller passed, so their handle keeps working. Say so in the result.
   return { success: true, action: 'apply_style', id: r.id, style: r.style, layers: r.layers, palette: r.palette, bounds: r.bounds };
@@ -7824,6 +8270,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}