@pinepaper.studio/mcp-server 1.6.11 → 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
@@ -475,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();
@@ -491,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();
@@ -801,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();
 }
 /**
@@ -1041,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
@@ -1265,7 +1423,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 +1436,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 +1446,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 `
@@ -2217,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
@@ -2468,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} });
@@ -2796,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.
@@ -2880,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
@@ -2906,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),
     };
   }
 
@@ -3135,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();
@@ -3161,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
@@ -3372,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() {
@@ -3388,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 };
@@ -4641,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 };
   }
@@ -4687,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 };
@@ -7935,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}