@pinepaper.studio/mcp-server 1.6.18 → 1.6.19

package/dist/types/code-generator.js

@@ -25,7 +25,7 @@ GlobeEnableInputSchema, GlobeRotateToInputSchema, GlobeSpinInputSchema, WorldTou
 // Custom relation/code types
 RegisterCustomRelationInputSchema, ExecuteCustomCodeInputSchema, 
 // Mask types
-ApplyAnimatedMaskInputSchema, ApplyCustomMaskInputSchema, RemoveMaskInputSchema, SceneGraphInputSchema, SequenceInputSchema, StaggerInputSchema, FlipInputSchema, QueryCapabilitiesInputSchema, KEYFRAME_EASINGS, EASING_DESCRIPTIONS, } from './schemas.js';
+ApplyAnimatedMaskInputSchema, ApplyCustomMaskInputSchema, RemoveMaskInputSchema, SceneGraphInputSchema, SequenceInputSchema, StaggerInputSchema, FlipInputSchema, QueryCapabilitiesInputSchema, KEYFRAME_EASINGS, EASING_DESCRIPTIONS, MaskTypeSchema, MaskPresetSchema, } from './schemas.js';
 import { OntologyCompiler } from '../ontology/ontology-compiler.js';
 // =============================================================================
 // HELPER FUNCTIONS
@@ -480,6 +480,19 @@ const DIRECTION_KEYS = ['direction', 'textDirection', 'dir'];
 // first STRONG character decides. Mirrored so a result can say which way
 // 'auto' went.
 const RTL_SCRIPT = /[\p{Script=Hebrew}\p{Script=Arabic}\p{Script=Syriac}\p{Script=Thaana}\p{Script=Nko}\p{Script=Samaritan}\p{Script=Mandaic}\p{Script=Adlam}\p{Script=Hanifi_Rohingya}]/u;
+/**
+ * cursiveOptions as createCursiveText reads them. The engine takes `nib` as a
+ * boolean or a tuning object; the tool also takes the words 'monoline' and
+ * 'broad', which the engine would read as truthy (= broad) both times.
+ */
+export function cursiveEngineOptions(o) {
+    if (!o)
+        return {};
+    const { nib, ...rest } = o;
+    if (nib === undefined)
+        return rest;
+    return { ...rest, nib: nib === 'monoline' ? false : nib === 'broad' ? true : nib };
+}
 function baseDirection(text) {
     for (const ch of text) {
         if (RTL_SCRIPT.test(ch))
@@ -1477,7 +1490,9 @@ function generateGetItemsCode(filter) {
     if (filter?.source)
         conditions.push(`entry.source === '${filter.source}'`);
     if (filter?.hasAnimation !== undefined) {
-        conditions.push(`!!entry.item.data?.animationType === ${filter.hasAnimation}`);
+        // 'none' is what the engine stores on a still item, and !!'none' is true
+        // (gate H5): animated means a real loop animation OR keyframes.
+        conditions.push(`!!((entry.item.data?.animationType && entry.item.data.animationType !== 'none') || (Array.isArray(entry.item.data?.keyframes) && entry.item.data.keyframes.length > 0)) === ${filter.hasAnimation}`);
     }
     if (filter?.hasRelation !== undefined) {
         conditions.push(`(app.getRelations(entry.id || entry.itemId).length > 0) === ${filter.hasRelation}`);
@@ -1490,7 +1505,7 @@ const items = entries.map(entry => ({
   id: entry.id || entry.itemId,
   type: entry.type,
   position: entry.item.position ? { x: entry.item.position.x, y: entry.item.position.y } : null,
-  hasAnimation: !!entry.item.data?.animationType,
+  hasAnimation: !!((entry.item.data?.animationType && entry.item.data.animationType !== 'none') || (Array.isArray(entry.item.data?.keyframes) && entry.item.data.keyframes.length > 0)),
   relations: app.getRelations(entry.id || entry.itemId).map(r => r.relation || r.type)
 }));
 
@@ -1505,7 +1520,7 @@ const items = filtered.map(entry => ({
   id: entry.id || entry.itemId,
   type: entry.type,
   position: entry.item.position ? { x: entry.item.position.x, y: entry.item.position.y } : null,
-  hasAnimation: !!entry.item.data?.animationType,
+  hasAnimation: !!((entry.item.data?.animationType && entry.item.data.animationType !== 'none') || (Array.isArray(entry.item.data?.keyframes) && entry.item.data.keyframes.length > 0)),
   relations: app.getRelations(entry.id || entry.itemId).map(r => r.relation || r.type)
 }));
 
@@ -1679,7 +1694,7 @@ app.setBackgroundColor('${color}');
  */
 function generateSetCanvasSizeCode(width, height, preset) {
     const sizeArg = preset
-        ? `'${preset}'`
+        ? JSON.stringify(preset)
         : `{ width: ${width}, height: ${height} }`;
     return `
 // Set canvas size
@@ -1697,9 +1712,10 @@ function generateSetCanvasSizeCode(width, height, preset) {
   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},
+  const __sz = app.getCanvasSize ? app.getCanvasSize() : null;
+  return { success: true, width: (r && r.width) || (__sz && __sz.width) || ${width ?? null}, height: (r && r.height) || (__sz && __sz.height) || ${height ?? null},
     ...(r && r.preset ? { preset: r.preset } : {}),
-    ...(r && r.unbounded !== undefined ? { unbounded: r.unbounded } : {})${!preset && (width > 8192 || height > 8192) ? `,
+    ...(r && r.unbounded !== undefined ? { unbounded: r.unbounded } : {})${!preset && ((width ?? 0) > 8192 || (height ?? 0) > 8192) ? `,
     note: 'above 8192 px per side: Chrome and Firefox render it (the studio allows up to 16384 safely), but Safari and iOS may produce a blank or corrupt canvas — export from Chrome.'` : ''} };
 })();
 `.trim();
@@ -2210,8 +2226,11 @@ function world3dColor(value) {
         return value;
     const hex = value.trim().replace(/^#/, '');
     const full = hex.length === 3 ? hex.split('').map((c) => c + c).join('') : hex;
+    // A string that is not hex is refused HERE, naming both forms: passed on,
+    // the engine answered "must be [r,g,b]", which contradicted the docs
+    // saying hex works (gate A, 1.6.19).
     if (!/^[0-9a-f]{6}$/i.test(full))
-        return value;
+        throw new Error(`"${value}" is not a colour: use hex ("#03050c" or "#abc") or [r, g, b]`);
     return [0, 2, 4].map((i) => parseInt(full.slice(i, i + 2), 16) / 255);
 }
 /**
@@ -2313,6 +2332,52 @@ export const SHEET_RUBRIC = {
         'a jump between the last and first frame of a loop (loopSeam)',
     ],
 };
+/**
+ * Page code: what a project holds, counted the same way before a save and
+ * after a load, so a round trip can be checked (keyframes in = keyframes out).
+ */
+const SCENE_COUNTS_JS = `function __ppSceneCounts() {
+  const all = (app.itemRegistry && typeof app.itemRegistry.getAll === 'function') ? app.itemRegistry.getAll() : [];
+  let animated = 0, keyframes = 0;
+  all.forEach(function (e) {
+    const k = e && e.item && e.item.data && e.item.data.keyframes;
+    if (Array.isArray(k) && k.length) { animated++; keyframes += k.length; }
+  });
+  const rel = (app.relationRegistry && typeof app.relationRegistry.exportForSave === 'function') ? app.relationRegistry.exportForSave().length : null;
+  return { items: all.length, animatedItems: animated, keyframes: keyframes, relations: rel };
+}`;
+/**
+ * Page code: the REGISTRY id for a Paper item, walking up from a child (a hit
+ * test lands on a group's inner path). Results used to fall back to Paper's
+ * internal numeric id (gate D9/D10, 1.6.19), which no other tool can address.
+ */
+const REG_ID_JS = `function __ppRegId(it) {
+  for (let n = it; n; n = n.parent) {
+    const id = n.data && (n.data.id || n.data.registryId);
+    if (id && app.itemRegistry && app.itemRegistry.get(id)) return id;
+  }
+  const all = (app.itemRegistry && typeof app.itemRegistry.getAll === 'function') ? app.itemRegistry.getAll() : [];
+  for (let n = it; n; n = n.parent) { const e = all.find(function (x) { return x && x.item === n; }); if (e) return e.itemId; }
+  return null;
+}`;
+/**
+ * Page code: any binary an engine export returns (Blob, ArrayBuffer, typed
+ * array) as a data URL, so it crosses the bridge as bytes and the handler can
+ * write a file. A Uint8Array crossed as a JSON object of byte indices
+ * ({"0": 80, "1": 75, ...}): export_dotlottie was unusable (gate D7, 1.6.19).
+ */
+const TO_DATA_URL_JS = `async function __ppToDataUrl(out, mime) {
+  if (typeof out === 'string') return out.indexOf('data:') === 0 ? out : null;
+  let blob = null;
+  if (out instanceof Blob) blob = out;
+  else if (out instanceof ArrayBuffer || ArrayBuffer.isView(out)) blob = new Blob([out], { type: mime });
+  if (!blob) return null;
+  return await new Promise(function (res, rej) { const r = new FileReader(); r.onload = function () { res(r.result); }; r.onerror = rej; r.readAsDataURL(blob); });
+}`;
+/** Why map pan / zoom refuse, and what to do instead. */
+const MAP_VIEW_REFUSAL = (action) => `map ${action} is not supported: the map has no view transform, and moving the camera changes only the studio view, `
+    + 'which a canvas export ignores. To frame part of a map in an export: keyframe the camera with pinepaper_camera_animate '
+    + 'and export with framing:"camera".';
 export class PinePaperCodeGenerator {
     /**
      * Generate code for creating an item
@@ -2354,8 +2419,14 @@ export class PinePaperCodeGenerator {
     /**
      * Generate code for adding a relation
      */
-    generateAddRelation(input) {
-        const validated = AddRelationInputSchema.parse(input);
+    generateAddRelation(input, customName = false) {
+        // The handler has already parsed, and a session-registered custom
+        // relation name is not in the enum (gate D2); the handler says so, and the
+        // name is re-parsed with a built-in stand-in and put back.
+        const rt = input.relationType;
+        const validated = AddRelationInputSchema.parse(customName ? { ...input, relationType: 'orbits' } : input);
+        if (customName)
+            validated.relationType = rt;
         // A PRESET decides its own relationType and params, so this is a different
         // call, not a defaulted one. applyRelationPreset refuses with
         // `{ok:false, errors:[{field, reason}]}` — a third refusal shape on this
@@ -3068,9 +3139,12 @@ if (typeof _gen === 'function') {
         codeParts.push(`
 // Save history and return results
 app.historyManager.saveState();
-results;
+return results;
 `);
-        return codeParts.join('\n');
+        // ONE (-led FUNCTION (gate C4, 1.6.19). This was a statement list ending
+        // in a bare \`results;\`, and the governor keeps only a (-led snippet's
+        // value, so every created id was collected and then dropped.
+        return `(async function() {\n${codeParts.join('\n')}\n})();`;
     }
     // =============================================================================
     // DIAGRAM TOOLS
@@ -3191,12 +3265,26 @@ if (!sourceItem) throw new Error('Source item not found: ${sourceItemId}');
 if (!targetItem) throw new Error('Target item not found: ${targetItemId}');
 
 const config = ${configStr};
-const connector = app.diagramSystem.connectPorts(
-  sourceItem, '${sourcePort}',
-  targetItem, '${targetPort}',
-  config
-);
-const connectorId = connector.data?.registryId || connector.id;
+// connectPorts(sourcePort, targetPort, config) takes PORT OBJECTS (gate C8,
+// 1.6.19). This passed (item, name, item, name, config): five arguments to a
+// three-argument method, so the engine got an item where a port belongs,
+// returned null, and connector.data threw. Ports are resolved by name or
+// position first; an item with none gets the standard diagram ports.
+const __pm = app.diagramSystem.portManager;
+const __port = function (item, name) {
+  let p = __pm.getPort(item, name);
+  if (!p && !(__pm.getPorts(item) || []).length) { app.diagramSystem.addPorts(item); p = __pm.getPort(item, name); }
+  return p;
+};
+const __sp = __port(sourceItem, ${JSON.stringify(sourcePort)});
+const __tp = __port(targetItem, ${JSON.stringify(targetPort)});
+if (!__sp || !__tp) {
+  const __names = function (item) { return (__pm.getPorts(item) || []).map(function (p) { return p.position || p.id; }).join(', '); };
+  return { success: false, error: 'no such port: ' + (!__sp ? ${JSON.stringify(sourcePort)} + ' on ' + ${JSON.stringify(sourceItemId)} + ' (has: ' + __names(sourceItem) + ')' : ${JSON.stringify(targetPort)} + ' on ' + ${JSON.stringify(targetItemId)} + ' (has: ' + __names(targetItem) + ')') };
+}
+const connector = app.diagramSystem.connectPorts(__sp, __tp, config);
+if (!connector) { return { success: false, error: 'the diagram system did not create the connector' }; }
+const connectorId = connector.id || connector.data?.registryId;
 app.historyManager.saveState();
 
 ({ connectorId, sourceItemId: '${sourceItemId}', sourcePort: '${sourcePort}', targetItemId: '${targetItemId}', targetPort: '${targetPort}' });
@@ -3291,61 +3379,50 @@ const shapes = category ? _lib.getByCategory(category) : _lib.getAll();
     generateUpdateConnector(input) {
         const validated = UpdateConnectorInputSchema.parse(input);
         const { connectorId, style, label, labelPosition } = validated;
-        const updates = [];
-        if (style) {
-            updates.push(`style: ${JSON.stringify(style)}`);
-        }
-        if (label !== undefined) {
-            updates.push(`label: ${JSON.stringify(label)}`);
-        }
-        if (labelPosition !== undefined) {
-            updates.push(`labelPosition: ${labelPosition}`);
-        }
-        const updatesStr = updates.length > 0 ? `{ ${updates.join(', ')} }` : '{}';
         return `
 // Update connector: ${connectorId}
-const connector = app.getItemById('${connectorId}');
-if (!connector) throw new Error('Connector not found: ${connectorId}');
-
-const updates = ${updatesStr};
-
-// THERE IS NO updateConnector. ConnectorManager publishes removeConnector,
-// findConnector and updateSelectedStyle — nothing that edits one connector's
-// properties in place. The old emitter called app.diagramSystem.updateConnector
-// and reported updated:true, so a caller changing a connector's colour got a
-// success and an unchanged connector.
-//
-// Applied directly where the property is a plain Paper.js one, and refused by
-// name where it is not, rather than claiming a change that did not happen.
-// The engine gained getConnector(id) / updateConnector(id, style), which is
-// the call this tool always wanted: addressable by the id a connector is
-// created and serialised with. Guarded, because a studio predating that still
-// has to do something sensible rather than throw.
-if (typeof app.diagramSystem?.updateConnector === 'function') {
-  const res = app.diagramSystem.updateConnector('${connectorId}', updates);
-  if (res && res.ok === false) { return { success: false, error: res.reason || 'the connector could not be updated' }; }
+(function() {
+  // CONNECTORS LIVE IN THE DIAGRAM SYSTEM, NOT THE ITEM REGISTRY (gate D1,
+  // 1.6.19): getItemById never resolves the id connect returned.
+  const __cid = ${JSON.stringify(connectorId)};
+  const ds = app.diagramSystem;
+  const connector = ds && typeof ds.getConnector === 'function' ? ds.getConnector(__cid) : null;
+  if (!connector) return { success: false, error: 'Connector not found: ' + __cid + '. Use the connectorId pinepaper_connect returned.' };
+  // updateConnector(id, style) takes the STYLE BAG ITSELF. This passed
+  // { style: {...}, label } (gate run 2, 1.6.19), so the engine merged a key
+  // named "style" into the connector's style, changed nothing it draws, and
+  // the tool reported updated:true over an unchanged connector.
+  const style = ${JSON.stringify(style ?? {})};
+  const label = ${label === undefined ? 'undefined' : JSON.stringify(label)};
+  const labelPosition = ${labelPosition === undefined ? 'undefined' : labelPosition};
+  const keys = Object.keys(style);
+  if (!keys.length && label === undefined && labelPosition === undefined) {
+    return { success: false, error: 'nothing to update: pass style, label or labelPosition' };
+  }
+  const applied = [];
+  if (keys.length) {
+    if (typeof ds.updateConnector !== 'function') {
+      return { success: false, error: 'this studio has no per-connector update (app.diagramSystem.updateConnector); update the studio' };
+    }
+    const res = ds.updateConnector(__cid, style);
+    if (!res || res.ok === false) return { success: false, error: (res && res.reason) || 'the connector could not be updated' };
+    const unchanged = keys.filter(function (k) { return connector.style[k] !== style[k]; });
+    if (unchanged.length) return { success: false, error: 'the studio did not take ' + unchanged.join(', ') };
+    keys.forEach(function (k) { applied.push('style.' + k); });
+  }
+  if (label !== undefined || labelPosition !== undefined) {
+    connector.setLabel(label !== undefined ? label : connector.label, labelPosition !== undefined ? labelPosition : connector.labelPosition);
+    applied.push(label !== undefined ? 'label' : 'labelPosition');
+  }
   app.historyManager.saveState();
-  return { connectorId: '${connectorId}', updated: true, applied: Object.keys(updates) };
-}
-
-const _applied = [];
-const _unsupported = [];
-for (const [k, v] of Object.entries(updates)) {
-  if (k === 'lineColor' && connector.strokeColor !== undefined) { connector.strokeColor = v; _applied.push(k); }
-  else if (k === 'lineWidth' && connector.strokeWidth !== undefined) { connector.strokeWidth = v; _applied.push(k); }
-  else _unsupported.push(k);
-}
-if (_applied.length) { app.historyManager.saveState(); app._scheduleRepaint?.(); }
-if (_unsupported.length && !_applied.length) {
-  throw new Error(
-    'this build cannot update ' + _unsupported.join(', ') + ' on an existing connector — '
-    + 'this build has no per-connector update — app.diagramSystem.updateConnector arrived later. '
-    + 'Update the studio for it. Removing and recreating the connector works, but mints a NEW id '
-    + 'and orphans anything holding the old one, so it is a last resort rather than the fix.'
-  );
-}
-
-({ connectorId: '${connectorId}', updated: _applied.length > 0, applied: _applied, unsupported: _unsupported });
+  // What it now DRAWS, read off the path, so a caller can check rather than trust.
+  const p = connector.path;
+  return {
+    success: true, connectorId: __cid, updated: true, applied: applied,
+    drawn: p ? { stroke: p.strokeColor ? p.strokeColor.toCSS(true) : null, width: p.strokeWidth, dash: p.dashArray || [] } : null,
+    label: connector.label || null,
+  };
+})();
 `.trim();
     }
     /**
@@ -3356,8 +3433,10 @@ if (_unsupported.length && !_applied.length) {
         const { connectorId } = validated;
         return `
 // Remove connector: ${connectorId}
-const connector = app.getItemById('${connectorId}');
-if (!connector) throw new Error('Connector not found: ${connectorId}');
+// Resolved through the diagram system (gate D1, 1.6.19), as update_connector is.
+const __cid = ${JSON.stringify(connectorId)};
+const connector = (app.diagramSystem && app.diagramSystem.getConnector(__cid)) || app.getItemById(__cid);
+if (!connector) throw new Error('Connector not found: ' + __cid);
 
 app.diagramSystem.connectorManager.removeConnector(connector);
 app.historyManager.saveState();
@@ -3446,6 +3525,23 @@ throw new Error('Unknown diagram mode action: ${action}');
   app.setCanvasSize('${canvasPresetFor(canvasPreset)}');
   // Allow canvas resize to take effect
   await new Promise(r => setTimeout(r, 50));
+`;
+        }
+        else {
+            code += `
+  // BOUND THE BOARD IT REPORTS (gate D57). An UNBOUNDED canvas still answers
+  // getCanvasSize with its 1920x1080 fallback, which is what this job reports
+  // and what every sizing rule here is relative to; but its stills export the
+  // artwork's bounds plus a margin (432x232 for one rectangle), while video
+  // exports the board. Fixing it at the size reported makes the two agree.
+  let _boundedFrom = null;
+  if (app.canvasSize && app.canvasSize.unbounded && typeof app.setCanvasSize === 'function') {
+    const _u = app.getCanvasSize ? app.getCanvasSize() : app.canvasSize;
+    if (_u && _u.width > 0 && _u.height > 0) {
+      const _r = app.setCanvasSize({ width: _u.width, height: _u.height });
+      if (!(_r && _r.ok === false)) _boundedFrom = 'unbounded';
+    }
+  }
 `;
         }
         if (wantOntology) {
@@ -3479,7 +3575,8 @@ throw new Error('Unknown diagram mode action: ${action}');
     screenshotPolicy: '${policyStr}',
     canvasPreset: ${canvasPreset ? `'${canvasPreset}'` : 'null'},
     canvasCleared: ${shouldClear},
-    canvasSize: { width: _cs.width || 800, height: _cs.height || 600 }${wantOntology ? `,
+    canvasSize: { width: _cs.width || 800, height: _cs.height || 600 }${canvasPreset ? '' : `,
+    ...(_boundedFrom ? { note: 'the canvas was unbounded (it exported the artwork, not the board); it is now fixed at ' + (_cs.width || 800) + 'x' + (_cs.height || 600) + ', so stills and video both export that size.' } : {})`}${wantOntology ? `,
     ontology: _ontology,
     ontologyUnavailable: _ontologyUnavailable || undefined` : ''}
   };
@@ -3558,12 +3655,13 @@ throw new Error('Unknown diagram mode action: ${action}');
 
     if (entry.type === 'text' || item.className === 'PointText') analysis.hasText = true;
     if (item.className === 'Raster') analysis.hasImages = true;
-    if (data.animationType) {
+    // 'none' is what a still item stores (gate C5, 1.6.19): it is not an animation.
+    if (data.animationType && data.animationType !== 'none') {
       analysis.hasAnimations = true;
       animationSet.add(data.animationType);
     }
     // Detect keyframe animations (added via app.addAnimation with keyframes array)
-    if (data.keyframes || data.animation || data.keyframeAnimation) {
+    if ((Array.isArray(data.keyframes) && data.keyframes.length > 0) || data.animation || data.keyframeAnimation) {
       analysis.hasAnimations = true;
       animationSet.add('keyframe');
     }
@@ -3915,7 +4013,7 @@ return { success: true, backgroundColor: '${bgColor}' };
             case 'set_canvas_size': {
                 const w = op.width || 1080;
                 const h = op.height || 1080;
-                const sizeArg = op.preset ? `'${op.preset}'` : `{ width: ${w}, height: ${h} }`;
+                const sizeArg = op.preset ? JSON.stringify(op.preset) : `{ width: ${w}, height: ${h} }`;
                 return `
 // 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
@@ -4403,7 +4501,11 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
       // A 3D world under the canvas IS the background: since FxTool #50
       // (747315e3) jpg/webp stills composite it, so nothing turns white/black.
       const hasWorld = !!app._world3d;
-      if (hasColor || hasBgItems || hasWorld) return [];
+      // So does a styled scene: one raster sized to COVER the frame (gate run 3:
+      // every export after styled_scene warned of black areas it does not have).
+      const hasStyledScene = !!(app.textItemGroup && app.textItemGroup.children
+        && app.textItemGroup.children.some(function (it) { return it && it.data && it.data.styledScene && it.visible !== false; }));
+      if (hasColor || hasBgItems || hasWorld || hasStyledScene) return [];
       return [{ code: 'alpha_dropped', message: fmt === 'apng'
         ? 'apng with transparent: false and no background colour: the frames are filled BLACK. Set a background colour, or drop transparent: false to keep the alpha.'
         : fmt === 'jpg'
@@ -4530,7 +4632,11 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
       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 };
+    // scale applies here too: it was dropped, so scale 0.5 rendered full
+    // size and nothing said so (gate C7).
+    const __cs = ${scale !== undefined ? scale : 1};
+    const __ev = (n) => Math.max(2, Math.round((n * __cs) / 2) * 2);
+    cameraDims = { width: __ev(camBase.width), height: __ev(camBase.height) };
   }
 
   // AN EXPORTER ANSWERS A BLOB OR A RECORD AROUND ONE.
@@ -4693,6 +4799,12 @@ ${stillTime !== undefined ? `
               ? { width: png.width, height: png.height }
               : { width: dimensions.width, height: dimensions.height },
           };
+          // An unbounded canvas exports its ARTWORK (bounds plus a margin), not
+          // the board getCanvasSize reports (gate D57). Say so rather than
+          // hand back a size nobody asked for unexplained.
+          if (app.canvasSize && app.canvasSize.unbounded) {
+            result.warning = (result.warning ? result.warning + ' ' : '') + 'this canvas is unbounded, so the still is cropped to the artwork, not the ' + pngBoard.width + 'x' + pngBoard.height + ' board. pinepaper_set_canvas_size {width, height} fixes the board; video exports the board either way.';
+          }
         } else {
           const canvas = document.querySelector('canvas');
           if (canvas) {
@@ -5369,6 +5481,21 @@ ${(() => {
         })()}
 ${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) { /* the still is already rendered */ }
   if (result && result.success) result.time = ${stillTime};` : ''}
+  // RELIGHT (FxTool D5): applied to png / pdf / mp4 / webm, not gif / apng
+  // or the vector formats; and it is what makes a video export slow.
+  if (result && result.success && typeof app.getRelight === 'function') {
+    try {
+      const __rl = app.getRelight();
+      if (__rl && __rl.enabled) {
+        result.fidelity = result.fidelity || { warnings: [] };
+        if (['png', 'jpg', 'webp', 'pdf', 'mp4', 'webm'].indexOf(${JSON.stringify(format)}) === -1) {
+          result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'relight_not_applied', message: 'a relight rig is set, but ${format} is not relit. Export png, pdf, mp4 or webm to keep the lighting.' }]);
+        } else {
+          result.relight = { applied: true, lights: (__rl.lights || []).length };
+        }
+      }
+    } catch (_) { /* the export stands */ }
+  }
 
   return result;
 })();
@@ -5436,12 +5563,13 @@ ${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) {
     if (entry.type === 'text' || item.className === 'PointText') analysis.hasText = true;
     if (item.className === 'Raster') analysis.hasImages = true;
 
-    if (data.animationType) {
+    // 'none' is what a still item stores (gate C5, 1.6.19): it is not an animation.
+    if (data.animationType && data.animationType !== 'none') {
       analysis.hasAnimations = true;
       animationSet.add(data.animationType);
     }
     // Detect keyframe animations (added via app.addAnimation with keyframes array)
-    if (data.keyframes || data.animation || data.keyframeAnimation) {
+    if ((Array.isArray(data.keyframes) && data.keyframes.length > 0) || data.animation || data.keyframeAnimation) {
       analysis.hasAnimations = true;
       animationSet.add('keyframe');
     }
@@ -5693,7 +5821,9 @@ ${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) {
     return {
       success: true,
       mapId: result.mapId || '${mapId}',
-      regions: result.regions?.length || 0,
+      // regionPaths is a Map: .length was undefined, so every load reported
+      // regions: 0 (gate D3). size, with the feature count as a fallback.
+      regions: (result.regions && (result.regions.size ?? result.regions.length)) || (result.geoData && result.geoData.features ? result.geoData.features.length : 0),
       bounds: result.bounds,
       center: result.center,${warn}
     };
@@ -5702,6 +5832,55 @@ ${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) {
   }
 })();
 `.trim();
+    }
+    /**
+     * Emitted helpers for reading a map's region colours back.
+     *
+     * highlightRegions and applyDataColors both write ONE channel — a colour
+     * override keyed on the feature's _mapId — and log a console.warn for an id
+     * they cannot resolve, which production strips. getHighlightedRegions reads
+     * path.data.highlighted over regionPaths, which a rasterised map leaves
+     * empty, so it saw nothing either tool did (gate D51). The override, read
+     * through the public getRegionOverride, is the record the engine leaves.
+     * Ids resolve the way the engine resolves them: exact, then lower-case.
+     */
+    mapRegionReadbackJs() {
+        return `
+  function __resolve(id) {
+    const m = app.mapSystem.regionNameMappings;
+    if (!m || typeof m.get !== 'function') return null;
+    return m.get(id) || m.get(String(id).toLowerCase()) || null;
+  }
+  function __features() {
+    const seen = new Map();
+    app.mapSystem.regionNameMappings.forEach(function (f) { if (f && !seen.has(f._mapId)) seen.set(f._mapId, f); });
+    return Array.from(seen.values());
+  }
+  function __row(f, asked) {
+    const o = app.mapSystem.getRegionOverride(f._mapId);
+    const r = { regionId: f._mapId, name: f._mapName, fill: o ? o.fill : null };
+    if (asked !== undefined) r.asked = asked;
+    return r;
+  }
+  function __overridden() {
+    return __features().filter(function (f) { return !!app.mapSystem.getRegionOverride(f._mapId); })
+      .map(function (f) { return __row(f); });
+  }
+  // No map loaded: every id is "not on this map", which blames the ids.
+  const __noMap = { success: false, error: 'no map is loaded. Load one with pinepaper_map {action: "load"} first.' };
+  function __sampleIds() {
+    return __features().slice(0, 8).map(function (f) { return f._mapId + ' (' + f._mapName + ')'; }).join(', ');
+  }
+  function __check(asked) {
+    const done = [], notFound = [], notApplied = [];
+    asked.forEach(function (id) {
+      const f = __resolve(id);
+      if (!f) { notFound.push(id); return; }
+      const r = __row(f, id);
+      (r.fill ? done : notApplied).push(r);
+    });
+    return { done: done, notFound: notFound, notApplied: notApplied };
+  }`;
     }
     /**
      * Generate code to highlight map regions
@@ -5720,13 +5899,19 @@ ${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) {
         const fill = ho.color ?? ho.fillColor ?? ho.fill;
         if (fill !== undefined)
             style.fill = fill;
+        // OPACITY IS A TINT OVER THE LAND (gate D59). The override REPLACES a
+        // region's land fill rather than drawing over it, and an rgba fill lost
+        // its alpha on the way to the exported pixels, so the readback reported a
+        // blend the PNG did not draw. The colour is blended over each region's own
+        // land fill in the browser and sent opaque: export and readback agree.
+        const opacity = typeof ho.opacity === 'number' ? ho.opacity : null;
         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) {
+            if (!['color', 'fillColor', 'fill', 'strokeColor', 'stroke', 'strokeWidth', 'opacity'].includes(k) && v !== undefined) {
                 style[k] = v;
             }
         }
@@ -5738,9 +5923,68 @@ ${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) {
     return { success: false, error: 'Map system not available' };
   }
 
-  try {
-    app.mapSystem.highlightRegions(${regionIds}, ${optionsStr});
-    return { success: true, highlighted: ${regionIds} };
+  try {${this.mapRegionReadbackJs()}
+    if (!__features().length) return __noMap;
+    const __style = ${optionsStr};
+    const __op = ${JSON.stringify(opacity)};
+    const __expected = {};
+    const __unblended = [];
+    if (__op !== null && typeof __style.fill === 'string') {
+      const __rgb = function (c) {
+        const m = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(String(c || ''));
+        if (!m) return null;
+        const x = m[1].length === 3 ? m[1].replace(/./g, function (ch) { return ch + ch; }) : m[1];
+        return [0, 2, 4].map(function (i) { return parseInt(x.slice(i, i + 2), 16); });
+      };
+      const __src = __rgb(__style.fill);
+      const __p = app.mapSystem._mapRenderParams;
+      const __ms = (__p && __p.mergedStyles) || {};
+      const __user = (app.mapSystem.currentMap && app.mapSystem.currentMap.geoData && app.mapSystem.currentMap.geoData.features) || [];
+      ${regionIds}.forEach(function (id) {
+        const f = __resolve(id);
+        if (!f) return;
+        // The land the engine paints under this region: a user feature takes
+        // the map's fill, a basemap country its basemapFill.
+        const __land = __rgb(__user.indexOf(f) !== -1 ? __ms.fill
+          : (__ms.basemapFill || (app.mapSystem.defaultStyles || {}).basemapFill));
+        let __fill = __style.fill;
+        if (__src && __land) {
+          __fill = '#' + [0, 1, 2].map(function (i) {
+            return ('0' + Math.round(__src[i] * __op + __land[i] * (1 - __op)).toString(16)).slice(-2);
+          }).join('');
+        } else {
+          __unblended.push(id);
+        }
+        __expected[id] = __fill;
+        app.mapSystem.highlightRegions([id], Object.assign({}, __style, { fill: __fill }));
+      });
+    } else {
+      app.mapSystem.highlightRegions(${regionIds}, __style);
+    }
+    // READ BACK (gate D16, D51): every id is resolved and its colour read.
+    const __r = __check(${regionIds});
+    if (!__r.done.length) {
+      return { success: false, notFound: __r.notFound, notApplied: __r.notApplied,
+        error: 'no region was highlighted.'
+          + (__r.notFound.length ? ' Not on this map: ' + __r.notFound.join(', ') + '. Ids on this map include ' + __sampleIds() + '; names work too.' : '') };
+    }
+    // The colour asked for must be the colour drawn (gate D59: the readback
+    // reported #3b82f6 for a #e11d48 request and still said success).
+    const __want = ${JSON.stringify(style.fill ?? null)};
+    if (__want) {
+      const __exp = function (d) { return __expected[d.asked] || __want; };
+      const __off = __r.done.filter(function (d) { return String(d.fill).toLowerCase() !== String(__exp(d)).toLowerCase(); });
+      if (__off.length === __r.done.length) {
+        return { success: false, highlighted: __r.done, error: 'the regions were highlighted in ' + __off[0].fill + ', not the ' + __exp(__off[0]) + ' asked for.' };
+      }
+      if (__off.length) __r.wrongFill = __off;
+    }
+    const __res = { success: true, highlighted: __r.done };
+    if (__unblended.length) { __res.unblended = __unblended; __res.warning = 'opacity needs a hex colour and a hex land fill; drawn at full strength: ' + __unblended.join(', ') + '.'; }
+    if (__r.wrongFill) { __res.wrongFill = __r.wrongFill; __res.warning = 'some regions were not drawn in ' + __want + ': ' + __r.wrongFill.map(function (d) { return d.regionId; }).join(', ') + '.'; }
+    if (__r.notFound.length) { __res.notFound = __r.notFound; __res.warning = 'not on this map, so not highlighted: ' + __r.notFound.join(', ') + '. Ids on this map include ' + __sampleIds() + '.'; }
+    if (__r.notApplied.length) __res.notApplied = __r.notApplied;
+    return __res;
   } catch (error) {
     return { success: false, error: error.message };
   }
@@ -5821,9 +6065,20 @@ ${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) {
     return { success: false, error: 'Map system not available' };
   }
 
-  try {
-    app.mapSystem.applyDataColors(${dataStr}, ${optionsStr});
-    return { success: true, regionsColored: ${Object.keys(validated.data).length} };
+  try {${this.mapRegionReadbackJs()}
+    if (!__features().length) return __noMap;
+    const __legend = app.mapSystem.applyDataColors(${dataStr}, ${optionsStr});
+    // READ BACK (gate D51): the engine skips a key it cannot resolve with a
+    // console warning, which production strips, so a misspelt key looked coloured.
+    const __r = __check(${JSON.stringify(Object.keys(validated.data))});
+    if (!__r.done.length) {
+      return { success: false, unmatched: __r.notFound,
+        error: 'no region was coloured: none of the keys is on this map. Ids on this map include ' + __sampleIds() + '; names work too.' };
+    }
+    const __res = { success: true, regionsColored: __r.done.length, colored: __r.done };
+    if (__legend && __legend.id !== undefined) __res.legendId = __legend.id;
+    if (__r.notFound.length) { __res.unmatched = __r.notFound; __res.warning = 'not on this map, so not coloured: ' + __r.notFound.join(', ') + '.'; }
+    return __res;
   } catch (error) {
     return { success: false, error: error.message };
   }
@@ -5857,8 +6112,19 @@ ${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) {
   }
 
   try {
-    const marker = app.mapSystem.addMarker(${JSON.stringify(options)});
-    return { success: true, markerId: marker?.id || 'marker_added' };
+    // addMarker(longitude, latitude, options). One object went in as the
+    // longitude, projected to NaN, and the engine returned null while this
+    // reported success with the made-up id 'marker_added' (gate D51).
+    const __o = ${JSON.stringify(options)};
+    const marker = app.mapSystem.addMarker(__o.lon, __o.lat, __o);
+    if (!marker) {
+      return { success: false, error: 'no marker was added: [' + __o.lat + ', ' + __o.lon + '] (lat, lon) is outside the visible map, or no map is loaded.' };
+    }
+    // A REGISTRY id, so modify / animate / delete can take it. register()
+    // leaves the marker inside the map group; registerItem would move it out,
+    // and it would stop panning and clearing with the map.
+    const markerId = app.itemRegistry.register(marker, 'mapMarker', { lat: __o.lat, lon: __o.lon, label: __o.label || null }, 'user');
+    return { success: true, markerId: markerId, position: [marker.position.x, marker.position.y] };
   } catch (error) {
     return { success: false, error: error.message };
   }
@@ -5908,26 +6174,13 @@ ${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) {
             options.animate = validated.animate;
         if (validated.duration !== undefined)
             options.duration = validated.duration;
-        return `
-// Pan map to coordinates
-(function() {
-  if (!app.mapSystem) {
-    return { success: false, error: 'Map system not available' };
-  }
-
-  try {
-    // 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 };
-  }
-})();
-`.trim();
+        // REFUSED, HONESTLY (gate run 2, 1.6.19). Run 1 turned pan into a camera
+        // pan, which moves the studio VIEW but not the map: a canvas-framed export
+        // ignores the camera, so the call reported success and the export was
+        // unchanged. The map itself cannot be moved without breaking geoToCanvas
+        // (it projects against the untransformed map, so markers would land in the
+        // wrong place). Until the engine has a map view transform, say so.
+        return `(function() { return { success: false, error: ${JSON.stringify(MAP_VIEW_REFUSAL('pan'))} }; })();`;
     }
     /**
      * Generate code to zoom the map
@@ -5939,24 +6192,8 @@ ${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) {
             options.animate = validated.animate;
         if (validated.duration !== undefined)
             options.duration = validated.duration;
-        return `
-// Set map zoom level
-(function() {
-  if (!app.mapSystem) {
-    return { success: false, error: 'Map system not available' };
-  }
-
-  try {
-    // 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 };
-  }
-})();
-`.trim();
+        // Refused for the same reason as pan (see generatePanMap).
+        return `(function() { return { success: false, error: ${JSON.stringify(MAP_VIEW_REFUSAL('zoom'))} }; })();`;
     }
     /**
      * Generate code to export map configuration
@@ -6001,7 +6238,11 @@ ${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) {
 
   try {
     const result = await app.mapSystem.importCustomMap('${validated.url}', ${optionsStr});
-    return { success: true, ...result };
+    // A summary, not the engine's return: that carries the Paper group and
+    // the region Map, which serialised into a raw Paper.js dump (gate N1).
+    const __r = result && result.regions;
+    const __n = (__r && (__r.size ?? __r.length)) || (result && result.geoData && result.geoData.features ? result.geoData.features.length : 0);
+    return { success: !!result, mapId: (result && result.mapId) || null, regions: __n, regionIds: (__r && __r.size ? Array.from(__r.keys()) : ((result && result.geoData && result.geoData.features) || []).map(function (f) { return (f.properties && f.properties.name) || f.id; })).slice(0, 50) };
   } catch (error) {
     return { success: false, error: error.message };
   }
@@ -6018,7 +6259,11 @@ ${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) {
 
   try {
     const result = await app.mapSystem.importCustomMap(${JSON.stringify(validated.geoJson)}, ${optionsStr});
-    return { success: true, ...result };
+    // A summary, not the engine's return: that carries the Paper group and
+    // the region Map, which serialised into a raw Paper.js dump (gate N1).
+    const __r = result && result.regions;
+    const __n = (__r && (__r.size ?? __r.length)) || (result && result.geoData && result.geoData.features ? result.geoData.features.length : 0);
+    return { success: !!result, mapId: (result && result.mapId) || null, regions: __n, regionIds: (__r && __r.size ? Array.from(__r.keys()) : ((result && result.geoData && result.geoData.features) || []).map(function (f) { return (f.properties && f.properties.name) || f.id; })).slice(0, 50) };
   } catch (error) {
     return { success: false, error: error.message };
   }
@@ -6045,20 +6290,17 @@ ${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) {
   }
 
   try {
-    // 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 };
-    }
-    return { success: true, regionId: null, message: 'No region at this point' };
+    if (!app.mapSystem.currentMap) {
+      return { success: false, error: 'no map is loaded. Load one with pinepaper_map {action: "load"} first.' };
+    }
+    // canvasToGeo takes ONE [x, y] argument; (x, y) handed it a bare number.
+    const coord = typeof app.mapSystem.canvasToGeo === 'function' ? app.mapSystem.canvasToGeo([${validated.x}, ${validated.y}]) : null;
+    // The hit test the studio's own hover uses (getRegionAtPoint never existed).
+    const f = app.mapSystem._findFeatureAtCanvasPoint(${validated.x}, ${validated.y});
+    if (!f) return { success: true, regionId: null, coordinate: coord, message: 'no region at this point (off the map, or ocean)' };
+    const p = f.properties || {};
+    return { success: true, regionId: f._mapId !== undefined ? f._mapId : (p.id || p.ISO_A3 || p.name || null),
+      regionName: f._mapName || p.name || p.NAME || null, coordinate: coord, properties: p };
   } catch (error) {
     return { success: false, error: error.message };
   }
@@ -6111,7 +6353,8 @@ ${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) {
     const result = app.mapSystem.animateRegionsWave({
       duration: ${validated.duration || 10},
       loop: ${validated.loop !== false},
-      colors: ${colorsStr},
+      colors: ${colorsStr},${validated.waveSpeed !== undefined ? `
+      waveSpeed: ${validated.waveSpeed},` : ''}
       waveDirection: '${validated.waveDirection || 'horizontal'}'
     });
     return { success: true, animatedRegions: result?.animatedRegions || [], totalRegions: result?.totalRegions || 0 };
@@ -6277,9 +6520,17 @@ ${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) {
     return { success: false, error: 'Map system not available' };
   }
 
-  try {
-    const result = app.mapSystem.getHighlightedRegions();
-    return { highlighted: result?.highlighted || [], count: result?.count || 0 };
+  try {${this.mapRegionReadbackJs()}
+    // getHighlightedRegions returns an ARRAY of {regionId, name, path}; this
+    // read result.highlighted off it and always answered [] (gate D51). It also
+    // walks regionPaths, empty on a rasterised map, so the override channel is
+    // read as well.
+    const __byId = new Map();
+    (app.mapSystem.getHighlightedRegions() || []).forEach(function (r) { __byId.set(r.regionId, { regionId: r.regionId, name: r.name }); });
+    __overridden().forEach(function (r) { __byId.set(r.regionId, r); });
+    const __list = Array.from(__byId.values());
+    return { success: true, highlighted: __list, count: __list.length,
+      note: 'highlight and apply_colors share one colour channel, so this lists every region either has coloured.' };
   } catch (error) {
     return { success: false, error: error.message };
   }
@@ -6481,6 +6732,87 @@ ${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) {
     /**
      * Generate code to export the complete scene state
      */
+    /**
+     * pinepaper_place_on_surface (FxTool #56): app.placeOnSurface corner-pins
+     * the UI into the photo's screen, mattes it so a hand stays in front, and
+     * BAKES it into the photo's pixels. Async. Only plain fields come back.
+     */
+    generatePlaceOnSurface(input) {
+        // Named, not spread: a spread makes every field look consumed, which is
+        // how an accepted-and-ignored option hides (the guard test reads these).
+        const opts = {};
+        if (input.quad !== undefined)
+            opts.quad = input.quad;
+        if (input.quadSpace !== undefined)
+            opts.quadSpace = input.quadSpace;
+        if (input.occlusion !== undefined)
+            opts.occlusion = input.occlusion;
+        if (input.key !== undefined)
+            opts.key = input.key;
+        if (input.erode !== undefined)
+            opts.erode = input.erode;
+        if (input.matteBlur !== undefined)
+            opts.matteBlur = input.matteBlur;
+        if (input.soften !== undefined)
+            opts.soften = input.soften;
+        if (input.glare !== undefined)
+            opts.glare = input.glare;
+        if (input.spill !== undefined)
+            opts.spill = input.spill;
+        if (input.spillRadius !== undefined)
+            opts.spillRadius = input.spillRadius;
+        if (input.tint !== undefined)
+            opts.tint = input.tint;
+        if (input.slot !== undefined)
+            opts.slot = input.slot;
+        if (input.hideSource !== undefined)
+            opts.hideSource = input.hideSource;
+        const { photoId, sourceId } = input;
+        return `
+// Place a UI onto a screen in a photo
+(async function() {
+  if (typeof app.placeOnSurface !== 'function') { return { success: false, error: 'app.placeOnSurface unavailable — update FxTool' }; }
+  const r = await app.placeOnSurface(${JSON.stringify(photoId)}, ${JSON.stringify(sourceId)}, ${JSON.stringify(opts)});
+  if (!r || r.ok === false) { return { success: false, error: (r && r.error) || 'the UI could not be placed' }; }
+  return { success: true, photoId: r.id, slot: r.slot, quad: r.quad, detected: r.detected || null,
+    key: r.key, matteCoverage: r.matteCoverage, ...(r.lostSlots && r.lostSlots.length ? { lostSlots: r.lostSlots } : {}) };
+})();`.trim();
+    }
+    /**
+     * A RESTORABLE project document (D28): app.captureProjectDocument, the
+     * engine's own durable format (core/ProjectDocument.js), which carries
+     * relations, rigging, connectors, scene chains and animation config.
+     * NOT exportProjectJSON: the engine documents that one as a bare Paper tree
+     * that drops roughly half of a non-trivial scene.
+     */
+    generateCaptureProject(name) {
+        return `
+// Capture a restorable project document
+(function() {
+  if (typeof app.captureProjectDocument !== 'function') { return { success: false, error: 'app.captureProjectDocument unavailable — update FxTool' }; }
+  ${SCENE_COUNTS_JS}
+  const doc = app.captureProjectDocument(${JSON.stringify(name ? { name } : {})});
+  return { success: true, json: JSON.stringify(doc), counts: __ppSceneCounts() };
+})();`.trim();
+    }
+    /** Load a staged project document (window.__ppStage.projectDoc), replacing the scene. */
+    generateLoadProject(strict) {
+        return `
+// Load a project document, replacing the current scene
+(function() {
+  if (typeof app.loadProjectDocument !== 'function') { return { success: false, error: 'app.loadProjectDocument unavailable — update FxTool' }; }
+  ${SCENE_COUNTS_JS}
+  const text = window.__ppStage && window.__ppStage.projectDoc;
+  if (typeof text !== 'string' || !text) { return { success: false, error: 'no project document was staged' }; }
+  // Second guard, in the page: nothing but a project document reaches the loader.
+  let __doc = null;
+  try { __doc = JSON.parse(text); } catch (e) { return { success: false, error: 'not a PinePaper scene file (not JSON); nothing was changed' }; }
+  if (!__doc || __doc.kind !== 'pinepaper.project') { return { success: false, error: 'not a PinePaper scene file (no kind "pinepaper.project"); nothing was changed' }; }
+  const r = app.loadProjectDocument(__doc, { strict: ${strict ? 'true' : 'false'} });
+  if (!r || r.ok === false) { return { success: false, error: 'the document was refused: ' + ((r && r.errors && r.errors.join('; ')) || 'invalid project document'), warnings: (r && r.warnings) || [] }; }
+  return { success: true, counts: __ppSceneCounts(), warnings: r.warnings || [], meta: r.meta || null };
+})();`.trim();
+    }
     generateExportScene() {
         return `
 // Export complete scene state
@@ -6592,7 +6924,11 @@ ${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) {
       backgroundColor: backgroundColor,
       canvasSize: canvasSize,
       itemCount: items.length,
-      relationCount: relations.length
+      relationCount: relations.length,
+      // NOT A BACKUP (D28). This summary carries positions and bounds, not
+      // keyframe tracks, rigging or scene chains: a scene saved this way and
+      // rebuilt from it has no motion. Said in the result, not only in docs.
+      note: 'summary for inspection: animation tracks, rigging and scene chains are not included and this cannot be restored. To save a restorable scene: pinepaper_export_scene with full: true, then pinepaper_import_scene.'
     };
   } catch (error) {
     return { success: false, error: error.message };
@@ -6693,29 +7029,32 @@ ${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) {
   try {
     // Import the Paper.js item from JSON
     const item = paper.project.importJSON(${itemJsonStr});
-    if (!item) {
-      return { success: false, error: 'Failed to import item from JSON' };
+    // importJSON accepts anything: { bogus: true } came back as an object with
+    // no bounds and was registered as an item (found by the 1.6.19 gate). Only
+    // a real Paper item with geometry may be registered.
+    if (!item || !(item instanceof paper.Item) || !item.bounds) {
+      try { if (item && typeof item.remove === 'function') item.remove(); } catch (e) {}
+      return { success: false, error: 'itemJson is not a Paper.js item (pass the output of item.exportJSON())' };
+    }
+
+    // REGISTER THROUGH THE ENGINE (gate H1, 1.6.19). This used to call
+    // app.itemRegistry.set(), which does not exist ("not a function", nothing
+    // registered), with an id invented from .size (undefined, so 'item_NaN',
+    // or a collision), and it moved every item into the TEXT group. The
+    // registry's own register() mints the id, never steals a live one, treats
+    // re-registration as an update, and returns the id it assigned.
+    // importJSON already put the item in the active layer.
+    if (!app.itemRegistry || typeof app.itemRegistry.register !== 'function') {
+      try { item.remove(); } catch (e) {}
+      return { success: false, error: 'app.itemRegistry.register unavailable — update FxTool' };
     }
-
-    // Register in item registry
-    const itemId = app.itemRegistry ? 'item_' + (app.itemRegistry.size + 1) : 'item_1';
-    item.data = item.data || {};
-    item.data.registryId = itemId;
-    item.data.type = ${JSON.stringify(input.itemType)};
-
-    // Merge custom properties
     const customProps = ${propertiesStr};
-    Object.assign(item.data, customProps);
-
-    // Add to registry
-    if (app.itemRegistry) {
-      app.itemRegistry.set(itemId, item);
-    }
-
-    // Add to appropriate group
-    if (app.textItemGroup) {
-      app.textItemGroup.addChild(item);
+    const itemId = app.itemRegistry.register(item, ${JSON.stringify(input.itemType)}, customProps, 'import');
+    if (!itemId) {
+      try { item.remove(); } catch (e) {}
+      return { success: false, error: 'the registry refused the item' };
     }
+    try { if (paper.view) paper.view.update(); } catch (e) {}
 
     return {
       success: true,
@@ -6997,7 +7336,9 @@ ${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) {
 // Get available mask types
 (function() {
   return {
-    maskTypes: ['rectangle', 'circle', 'ellipse', 'star', 'triangle', 'hexagon', 'heart', 'rounded', 'custom']
+    // From the enum the mask tools validate against: this listed 'custom',
+    // which both refuse (1.6.19 gate).
+    maskTypes: ${JSON.stringify(MaskTypeSchema.options)}
   };
 })();
 `.trim();
@@ -7007,14 +7348,7 @@ ${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) {
 // Get available mask animation presets
 (function() {
   return {
-    animations: [
-      'wipeLeft', 'wipeRight', 'wipeUp', 'wipeDown',
-      'iris', 'irisOut',
-      'star', 'heart',
-      'curtainHorizontal', 'curtainVertical', 'cinematic',
-      'diagonalWipe',
-      'revealUp', 'revealDown'
-    ]
+    animations: ${JSON.stringify(MaskPresetSchema.options)}
   };
 })();
 `.trim();
@@ -7028,10 +7362,12 @@ ${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) {
             const categoryFilter = category ? `'${category}'` : 'null';
             return `
 // List available templates
-(function() {
+(async function() {
   if (!app.templateManager) {
     return { error: 'Template manager not available. Make sure PinePaper Studio is loaded.' };
   }
+  // The built-in catalogue loads lazily; a fresh page listed none (1.6.19 gate).
+  try { if (app.templateManager._ensureTemplateData) await app.templateManager._ensureTemplateData(); } catch (e) {}
   const allTemplates = app.templateManager.getAllTemplates();
   const category = ${categoryFilter};
   const filtered = category
@@ -7056,8 +7392,25 @@ ${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) {
   if (!app.templateManager) {
     return { error: 'Template manager not available. Make sure PinePaper Studio is loaded.' };
   }
+  // AN UNKNOWN ID IS AN ERROR, NOT A SUCCESS (gate C1, 1.6.19). loadTemplate
+  // on an id that does not exist changed nothing and this still reported
+  // "Template applied successfully"; the description's own example id
+  // ('solar-system') was one of them. The nearest real ids are offered.
+  const __tid = ${JSON.stringify(templateId)};
+  // The built-in catalogue loads LAZILY: on a fresh page getAllTemplates() is
+  // [] until it does, which made every id look unknown. Load it first, as
+  // loadTemplate itself does, and count the cloud templates it falls back to.
+  try { if (app.templateManager._ensureTemplateData) await app.templateManager._ensureTemplateData(); } catch (e) {}
+  const __cloud = (app.templateManager.cloudSync && app.templateManager.cloudSync.cloudTemplates) || [];
+  const __all = app.templateManager.getAllTemplates().concat(__cloud.filter(Boolean));
+  if (__all.length && !__all.some(function(t) { return t && t.id === __tid; })) {
+    const __lev = function(a, b) { const m = a.length, n = b.length; const d = Array.from({ length: m + 1 }, function(_, i) { return [i]; }); for (let j = 1; j <= n; j++) d[0][j] = j; for (let i = 1; i <= m; i++) for (let j = 1; j <= n; j++) d[i][j] = Math.min(d[i-1][j] + 1, d[i][j-1] + 1, d[i-1][j-1] + (a[i-1] === b[j-1] ? 0 : 1)); return d[m][n]; };
+    const __near = __all.map(function(t) { const id = String(t.id); return { id: id, d: id.indexOf(__tid) >= 0 || __tid.indexOf(id) >= 0 ? 0 : __lev(__tid, id) }; })
+      .sort(function(a, b) { return a.d - b.d; }).slice(0, 5).map(function(x) { return x.id; });
+    return { success: false, error: 'no template "' + __tid + '". Nearest: ' + __near.join(', ') + '. List them with listOnly: true.' };
+  }
   try {
-    await app.templateManager.loadTemplate('${templateId}', true);
+    await app.templateManager.loadTemplate(__tid, true);
 
     // DID THE CLIPPED CHARACTER PARTS SURVIVE?
     //
@@ -7714,7 +8067,7 @@ ${mask ? `    // A MASK REPLACES THE RASTER (round 8 DD, 4.10). applyMask builds
   for (const id of ids) {
     const entry = app.itemRegistry.get(id);
     if (entry && entry.item) {
-      ${mode === 'remove' ? 'entry.item.selected = false;' : 'app.select(entry.item);'}
+      ${mode === 'remove' ? 'entry.item.selected = false;' : 'app.select(entry.item, false);'}
       selected.push(id);
     }
   }
@@ -7725,8 +8078,9 @@ ${mask ? `    // A MASK REPLACES THE RASTER (round 8 DD, 4.10). applyMask builds
                 return `
 // Select all items
 (function() {
+  ${REG_ID_JS}
   app.selectAll();
-  const items = app.getSelectedItems().map(i => i.data?.itemId || i.name || i.id);
+  const items = app.getSelectedItems().map(i => __ppRegId(i)).filter(Boolean);
   return { success: true, action: 'select_all', count: items.length, items };
 })();`.trim();
             case 'deselect_all':
@@ -7740,8 +8094,9 @@ ${mask ? `    // A MASK REPLACES THE RASTER (round 8 DD, 4.10). applyMask builds
                 return `
 // Get current selection
 (function() {
+  ${REG_ID_JS}
   const items = app.getSelectedItems().map(i => ({
-    itemId: i.data?.itemId || i.name || i.id,
+    itemId: __ppRegId(i),
     type: i.data?.itemType || i.className,
     bounds: i.bounds ? { x: i.bounds.x, y: i.bounds.y, width: i.bounds.width, height: i.bounds.height } : null
   }));
@@ -7751,8 +8106,9 @@ ${mask ? `    // A MASK REPLACES THE RASTER (round 8 DD, 4.10). applyMask builds
                 return `
 // Delete selected items
 (function() {
+  ${REG_ID_JS}
   const selection = app.getSelectedItems();
-  const deleted = selection.map(i => i.data?.itemId || i.name || i.id);
+  const deleted = selection.map(i => __ppRegId(i)).filter(Boolean);
   app.deleteSelected();
   return { success: true, action: 'delete_selected', deleted, count: deleted.length };
 })();`.trim();
@@ -7931,7 +8287,7 @@ ${loads}
             case 'lineage': return this._facadeCall('getLineage', id, 'Provenance: lineage');
             case 'dependents': return this._facadeCall('getDependents', id, 'Provenance: dependents');
             case 'record':
-                return this._facadeCall('recordLineage', `${id}, ${JSON.stringify(input.kind || 'derived')}, ${JSON.stringify(input.sourceRef || '')}, ${JSON.stringify(input.meta || {})}`, 'Provenance: record lineage');
+                return this._facadeCall('recordLineage', `${id}, ${JSON.stringify(input.kind || 'derivedFrom')}, ${JSON.stringify(input.sourceRef || '')}, ${JSON.stringify(input.meta || {})}`, 'Provenance: record lineage');
         }
     }
     generateCompose(input) {
@@ -7953,27 +8309,46 @@ ${loads}
                 // vector and audio halves of composeCollage were unreachable through
                 // MCP, so agents converged on the four static patterns the description
                 // happened to name. A capability gap reads as model bias from outside.
-                return this._facadeCall('composeCollage', `${JSON.stringify(input.pattern || '')}, ${JSON.stringify(input.itemIds || [])}, ${JSON.stringify({
-                    ...(input.treatment ? { treatment: input.treatment } : {}),
-                    ...(input.applyCamera === false ? { applyCamera: false } : {}),
-                    ...(input.loop ? { loop: true } : {}),
-                    ...(input.craft ? { craft: input.craft } : {}),
-                    ...(input.reveal !== undefined ? { reveal: input.reveal } : {}),
-                    ...(input.revealOptions ? { revealOptions: input.revealOptions } : {}),
-                    ...(input.style ? { style: input.style } : {}),
-                    ...(input.text ? { text: input.text } : {}),
-                    ...(input.assets ? { assets: input.assets } : {}),
-                    ...(input.audio ? { audio: input.audio } : {}),
-                    ...(input.grid ? { grid: true } : {}),
-                    // The design axes. A register resolves the craft (gutter, margin,
-                    // hue budget, type scale); a medium says what makes the marks and
-                    // is REFUSED when a composition cannot be rendered in it.
-                    ...(input.register ? { register: input.register } : {}),
-                    ...(input.level !== undefined ? { level: input.level } : {}),
-                    ...(input.medium ? { medium: input.medium } : {}),
-                    ...(input.stitch ? { stitch: input.stitch } : {}),
-                    ...(input.stitchBudget !== undefined ? { stitchBudget: input.stitchBudget } : {}),
-                })}`, 'Compose: apply pattern');
+                {
+                    const apply = this._facadeCall('composeCollage', `${JSON.stringify(input.pattern || '')}, ${JSON.stringify(input.itemIds || [])}, ${JSON.stringify({
+                        ...(input.treatment ? { treatment: input.treatment } : {}),
+                        ...(input.applyCamera === false ? { applyCamera: false } : {}),
+                        ...(input.loop ? { loop: true } : {}),
+                        ...(input.craft ? { craft: input.craft } : {}),
+                        ...(input.reveal !== undefined ? { reveal: input.reveal } : {}),
+                        ...(input.revealOptions ? { revealOptions: input.revealOptions } : {}),
+                        ...(input.style ? { style: input.style } : {}),
+                        ...(input.text ? { text: input.text } : {}),
+                        ...(input.assets ? { assets: input.assets } : {}),
+                        ...(input.audio ? { audio: input.audio } : {}),
+                        ...(input.grid ? { grid: true } : {}),
+                        // The design axes. A register resolves the craft (gutter, margin,
+                        // hue budget, type scale); a medium says what makes the marks and
+                        // is REFUSED when a composition cannot be rendered in it.
+                        ...(input.register ? { register: input.register } : {}),
+                        ...(input.level !== undefined ? { level: input.level } : {}),
+                        ...(input.medium ? { medium: input.medium } : {}),
+                        ...(input.stitch ? { stitch: input.stitch } : {}),
+                        ...(input.stitchBudget !== undefined ? { stitchBudget: input.stitchBudget } : {}),
+                    })}`, 'Compose: apply pattern');
+                    ;
+                    if (typeof input.reveal !== 'string' || !input.reveal)
+                        return apply;
+                    // CHECK THE REVEAL FIRST (gate C3). composeCollage lays the items out
+                    // and wires their relations BEFORE it reaches an unknown reveal, so a
+                    // typo errored with the grid already applied and nothing reverted.
+                    return `
+// Compose: check the reveal, then apply
+(async function() {
+  if (typeof app.listReveals === 'function') {
+    const __keys = (app.listReveals() || []).map(function (r) { return r && r.key; });
+    if (__keys.length && __keys.indexOf(${JSON.stringify(input.reveal)}) === -1) {
+      return { success: false, error: 'unknown reveal ' + ${JSON.stringify(JSON.stringify(input.reveal))} + ' — known: ' + __keys.join(', ') + '. Nothing was changed.' };
+    }
+  }
+  return await ${apply.replace(/^\/\/[^\n]*\n/, '').replace(/;\s*$/, '')};
+})();`.trim();
+                }
         }
     }
     generateAudioBeats(input) {
@@ -8624,16 +8999,28 @@ ${resolve}
                 return `
 // Clear background
 (function() {
+  // clearBackground() removes generated patterns, drawings and the image, but
+  // not the colour; the tool promises "remove entirely" and left #1e293b
+  // behind (gate C6, 1.6.19). The colour goes too, to transparent.
   app.clearBackground();
-  return { success: true, action: 'clear' };
+  if (typeof app.setBackgroundColor === 'function') app.setBackgroundColor('transparent');
+  return { success: true, action: 'clear', removed: ['pattern', 'drawing', 'image', 'color'] };
 })();`.trim();
             case 'get':
                 return `
 // Get background info
 (function() {
-  // FxTool exposes getBackgroundMode() returning the mode string only.
+  // getBackgroundMode() returns only the mode, so 'color' came back with no
+  // colour (gate C6, 1.6.19). The colour is read from the canvas, as hex.
   const mode = app.getBackgroundMode ? app.getBackgroundMode() : null;
-  return { success: true, action: 'get', mode };
+  const css = (app.canvasEl && app.canvasEl.style && app.canvasEl.style.backgroundColor) || '';
+  // No regex: this is a template literal, and \\( or \\s here reach the page
+  // without their backslash (that was the #NaN293b).
+  const open = css.indexOf('('), close = css.indexOf(')');
+  let color = css || null;
+  if (css.indexOf('rgb') === 0 && open > 0 && close > open) { const p = css.slice(open + 1, close).split(',').join(' ').split('/').join(' ').split(' ').filter(Boolean).map(function (x) { return parseFloat(x); }); color = (p.length > 3 && p[3] === 0) ? 'transparent' : '#' + p.slice(0, 3).map(function (v) { return Math.round(v).toString(16).padStart(2, '0'); }).join(''); }
+  const patterns = app.patternGroup && app.patternGroup.children ? app.patternGroup.children.length : 0;
+  return { success: true, action: 'get', mode, color, hasPattern: patterns > 0, hasImage: !!(app.config && app.config.backgroundImage) };
 })();`.trim();
             default:
                 return `(function() { return { error: 'Unknown background action: ${input.action}' }; })();`;
@@ -8669,13 +9056,14 @@ ${resolve}
                 return `
 // Hit test at point
 (function() {
+  ${REG_ID_JS}
   const point = new paper.Point(${input.x ?? 0}, ${input.y ?? 0});
   ${all
                     ? `const results = app.hitTestAll(point, { tolerance: ${tolerance} });
   const hits = results.map(r => ({
-    itemId: r.item?.data?.itemId || r.item?.name || r.item?.id,
-    type: r.item?.data?.itemType || r.item?.className,
-    point: { x: r.point?.x, y: r.point?.y }
+    itemId: __ppRegId(r.item),
+    type: r.item?.data?.type || r.item?.className,
+    point: r.point ? { x: r.point.x, y: r.point.y } : null
   }));
   return { success: true, action: 'hit_test', x: ${input.x ?? 0}, y: ${input.y ?? 0}, hits, count: hits.length };`
                     : `const result = app.hitTest(point, { tolerance: ${tolerance} });
@@ -8683,7 +9071,7 @@ ${resolve}
   return {
     success: true, action: 'hit_test',
     x: ${input.x ?? 0}, y: ${input.y ?? 0},
-    hit: { itemId: result.item?.data?.itemId || result.item?.name || result.item?.id, type: result.item?.data?.itemType || result.item?.className }
+    hit: { itemId: __ppRegId(result.item), type: result.item?.data?.type || result.item?.className, point: result.point ? { x: result.point.x, y: result.point.y } : null }
   };`}
 })();`.trim();
             }
@@ -9083,12 +9471,47 @@ if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
   ${guard}
   const entry = app.itemRegistry.get(${itemIdStr});
   if (!entry || !entry.item) return { error: 'Item not found: ' + ${itemIdStr} };
-  app.interactionSystem.removeContinuousBehavior(entry.item, ${behaviorIdStr});
-  return { success: true, action: 'remove_behavior', itemId: ${itemIdStr}, behaviorId: ${behaviorIdStr} };
+  // The engine's remove returns nothing, and this used to echo its inputs, so
+  // a wrong behaviorId still "succeeded" (gate run 2). Count what went.
+  const __list = function () { const m = app.interactionSystem.continuousBehaviors; const l = m && m.get ? m.get(${itemIdStr}) : null; return (l || []).map(function (b) { return b.id; }); };
+  const __before = __list();
+  const __bid = ${behaviorIdStr};
+  if (__bid && __before.indexOf(__bid) === -1) {
+    return { success: false, error: 'no behavior ' + JSON.stringify(__bid) + ' on ' + ${itemIdStr} + (__before.length ? '; it has: ' + __before.join(', ') : '; it has none') + '. Use the behaviorId add_behavior returned, or omit it to remove all.' };
+  }
+  if (__bid) app.interactionSystem.removeContinuousBehavior(entry.item, __bid);
+  else {
+    // "Remove all" means the behaviors a caller ADDED. The engine's own
+    // selectable / draggable go too with a bare remove, which left the item
+    // impossible to select or drag (gate run 3, N4).
+    const __sys = ['selectable', 'draggable'];
+    const __m = app.interactionSystem.continuousBehaviors;
+    ((__m && __m.get ? __m.get(${itemIdStr}) : null) || []).slice()
+      .filter(function (b) { return __sys.indexOf(b.type) === -1; })
+      .forEach(function (b) { app.interactionSystem.removeContinuousBehavior(entry.item, b.id); });
+  }
+  const __after = __list();
+  const removed = __before.filter(function (id) { return __after.indexOf(id) === -1; });
+  return { success: removed.length > 0, action: 'remove_behavior', itemId: ${itemIdStr}, removed: removed, remaining: __after, ...(removed.length ? {} : { error: 'nothing was removed: the item has no behaviors added to it (the built-in selectable / draggable are kept)' }) };
 })();`.trim();
             }
             case 'trigger_action': {
-                const params = JSON.stringify(input.params || {});
+                // The engine's handlers read params.items (ids) for show / hide /
+                // animate / stopAnimation, and params.points for incrementScore. The
+                // tool documented neither, so { itemId } hid nothing and { amount: 5 }
+                // scored 1 (gate D13, 1.6.19). The natural names are accepted too.
+                const raw = { ...(input.params || {}) };
+                if (raw.items === undefined) {
+                    const one = raw.itemId ?? raw.targetItemId;
+                    const many = raw.itemIds;
+                    if (Array.isArray(many))
+                        raw.items = many;
+                    else if (typeof one === 'string')
+                        raw.items = [one];
+                }
+                if (input.actionType === 'incrementScore' && raw.points === undefined && typeof raw.amount === 'number')
+                    raw.points = raw.amount;
+                const params = JSON.stringify(raw);
                 return `
 // Trigger interaction action
 (function() {
@@ -9460,8 +9883,10 @@ if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
 // Toggle grid
 (function() {
   ${guard}
-  // showGrid()/hideGrid(), not a boolean setter — setGridVisible never existed.
-  app.measurementSystem[${enabled} ? 'showGrid' : 'hideGrid']();
+  // setUnitGridEnabled shows/hides the grid AND records the setting that
+  // set_snap depends on; showGrid() alone left snapping inert (1.6.19 gate).
+  if (typeof app.setUnitGridEnabled === 'function') app.setUnitGridEnabled(${enabled});
+  else app.measurementSystem[${enabled} ? 'showGrid' : 'hideGrid']();
   return { success: true, action: 'set_grid', enabled: ${enabled} };
 })();`.trim();
             }
@@ -9480,17 +9905,18 @@ if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
 })();`.trim();
             }
             case 'set_snap': {
-                // `enabled` is deliberately unread: there is no mode to set either way.
+                // The engine has setSnapToUnitEnabled now; this refused, saying it had
+                // never existed (1.6.19 gate). It is an EDITOR setting: it snaps a
+                // drag or resize to the unit grid's ticks, and does nothing while that
+                // grid is off. Tool-placed items are not snapped, and the result says so.
                 return `
-// Snap to grid — refused, see below
+// Snap to unit grid (drag / resize in the studio)
 (function() {
-  ${guard}
-  // NO EQUIVALENT. MeasurementSystem publishes snapCoordinate(), which snaps a
-  // coordinate you hand it, and nothing that turns snapping on as a mode —
-  // setSnapToUnitEnabled has never existed, so this reported success over a
-  // setting that was never changed. Refused by name, with the thing that works.
-  return { success: false, action: 'set_snap',
-    error: 'this build has no snap-to-unit MODE to switch: the measurement system snaps a coordinate on request rather than holding a setting. Snap positions yourself before creating or moving items, or set a grid with the grid action and place on its multiples.' };
+  if (typeof app.setSnapToUnitEnabled !== 'function') { return { success: false, action: 'set_snap', error: 'this studio has no snap-to-unit setting; update FxTool' }; }
+  const enabled = app.setSnapToUnitEnabled(${input.enabled !== false});
+  const gridOn = typeof app.getUnitGridEnabled === 'function' ? app.getUnitGridEnabled() : null;
+  return { success: true, action: 'set_snap', enabled: enabled, unitGrid: gridOn,
+    note: 'snaps dragging and resizing in the studio to the unit grid' + (gridOn === false ? ', which is OFF, so nothing snaps until it is on (set_grid)' : '') + '. Items placed by tools are not snapped: give them grid multiples.' };
 })();`.trim();
             }
             default:
@@ -9568,6 +9994,30 @@ if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
      * Extract the best-matching detected region from an image as a NEW item (FxTool
      * ImageWorkflow.extractObject). Async (runs detection first).
      */
+    /**
+     * pinepaper_styled_scene (FxTool K2). app.styledScene answers {ok:false,
+     * error} rather than rejecting, so the verdict is read, not assumed. The
+     * result carries the duration to export for: the scene item lives that long,
+     * and an export left at its own default would cut it short or pad it.
+     */
+    generateStyledScene(input) {
+        const opts = {
+            ...(input.style !== undefined ? { style: input.style } : {}),
+            ...(input.duration !== undefined ? { duration: input.duration } : {}),
+            ...(input.id !== undefined ? { id: input.id } : {}),
+        };
+        return `
+// Styled scene${input.style ? ` (${input.style.replace(/[\r\n]/g, ' ')})` : ''}
+(async function() {
+  if (typeof app.styledScene !== 'function') { return { success: false, error: 'app.styledScene unavailable — update FxTool' }; }
+  const r = await app.styledScene(${JSON.stringify(input.spec ?? {})}, ${JSON.stringify(opts)});
+  if (!r || r.ok === false) { return { success: false, error: (r && r.error) || 'the styled scene was refused' }; }
+  const notes = ['export for ' + r.duration + ' s (agent_export duration: ' + r.duration + '): the scene runs that long'];
+  if (r.style === 'dither' || r.style === 'ascii') notes.push(r.style + ' needs a Chrome renderer (WebKit ignores the canvas filter it uses)');
+  notes.push('the scene redraws every exported frame; after a page reload it is a still until styled_scene is called again');
+  return { success: true, itemId: r.id, style: r.style, width: r.width, height: r.height, duration: r.duration, firstFrameMs: r.firstFrameMs, notes: notes };
+})();`.trim();
+    }
     generateExtractObject(input) {
         const args = JSON.stringify({
             ...(input.label !== undefined ? { label: input.label } : {}),
@@ -9584,6 +10034,16 @@ if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
   }
   try {
     const res = await app.extractObject(${args});
+    // A numeric itemId is Paper's own id: the engine's register fallback did
+    // not take, so the new item was unaddressable and uncounted (gate run 2:
+    // itemId 226, itemsCreated 0). Register it here and hand back that id.
+    if (res && res.ok && typeof res.itemId === 'number' && typeof paper !== 'undefined' && paper.project) {
+      const __n = res.itemId;
+      const __it = paper.project.getItem({ match: function (i) { return i.id === __n; } });
+      const __rid = __it && app.itemRegistry && app.itemRegistry.register ? app.itemRegistry.register(__it, 'image', { source: 'extract' }, 'import') : null;
+      if (typeof __rid === 'string') res.itemId = __rid;
+      else return { success: false, error: 'the object was extracted but could not be registered, so it has no usable id (Paper id ' + __n + ')' };
+    }
     const out = Object.assign({ success: !!(res && res.ok) }, res || {});
     if (!out.success && typeof out.error === 'string') out.error = (${PinePaperCodeGenerator.MODEL_FETCH_HINT})(out.error);
     return out;
@@ -9971,12 +10431,26 @@ ${checks.includes('contrast') ? `  // SAMPLED OVER TIME (round 12, 12.9): text i
   // which get the box loop below and a note saying so.
   const doc = ${docJson};
   if (typeof app.instantiateOntology === 'function') {
-    const r = await app.instantiateOntology(doc, ${engineOptsJson});
+    // THE LIVE CANVAS, unless one was given: the engine lays out for 1080x1080
+    // otherwise, which put items at (540,540) on a 640x360 canvas (gate run 3).
+    const __opts = ${engineOptsJson};
+    if (!__opts.canvas && app.getCanvasSize) { const __c = app.getCanvasSize(); if (__c && __c.width > 0) __opts.canvas = { width: __c.width, height: __c.height }; }
+    // REGISTRY IDS. The engine returns the DOCUMENT's ids ("bar"), which no
+    // other tool resolves; the new registry entries are found by diffing.
+    const __all = function () { return (app.itemRegistry && app.itemRegistry.getAll) ? app.itemRegistry.getAll() : []; };
+    const __before = new Set(__all().map(function (e) { return e.itemId; }));
+    const r = await app.instantiateOntology(doc, __opts);
     const diags = r.diagnostics || [];
+    const __new = __all().filter(function (e) { return !__before.has(e.itemId) && e.item && e.item.data && e.item.data._origin === 'ontology'; }).map(function (e) { return e.itemId; });
+    const docIds = r.itemIds || [];
+    const idMap = {};
+    if (__new.length === docIds.length) docIds.forEach(function (d, i) { idMap[d] = __new[i]; });
     return {
       success: !diags.some(function(d) { return d && d.level === 'error'; }) && !r.imagesFailed,
       engine: 'studio',
-      itemIds: r.itemIds, itemCount: r.itemIds.length,
+      itemIds: __new, itemCount: __new.length, docIds: docIds,
+      ...(Object.keys(idMap).length ? { idMap: idMap } : { note: 'document ids could not be paired with registry ids one to one; use itemIds' }),
+      canvas: __opts.canvas || null,
       // Every count the engine returns, not a chosen three. imagesFailed is the
       // one that matters most: a raster that never decoded leaves a scene that
       // looks built and is not, and dropping the count is how that becomes
@@ -10464,7 +10938,9 @@ ${guard}
   // item — so reading .data.id off the answer returned no id, every time. The
   // group is registered only on one of its two branches; the other is
   // registered here so the caller always gets an addressable id.
-  const r = app.createCursiveText(${S(input.text)}, ${S(input.cursiveOptions ?? {})});
+  // nib goes to the engine as a boolean or a tuning object. A STRING is
+  // truthy there, so 'monoline' would have selected the broad nib (D31).
+  const r = app.createCursiveText(${S(input.text)}, ${S(cursiveEngineOptions(input.cursiveOptions))});
   const g = r && (r.group || (r.data ? r : null));
   if (!g) { return { success: false, error: 'the cursive text produced no path' }; }
   let itemId = g.data && (g.data.id || g.data.registryId);
@@ -10505,7 +10981,11 @@ ${guard}
   // would otherwise read as "the conversion did nothing to your text".
   const r = app.convertTextToCollage(item, ${S(input.text ?? null)} || item.content, ${S(input.collageOptions ?? {})});
   if (!r) { return { success: false, error: 'the collage system is unavailable in this build, so the text was left as it was' }; }
-  return { success: true, collage: r };
+  // A summary, not the collage's Paper group (that was a raw dump, gate run 3).
+  ${REG_ID_JS}
+  const __g = (r && (r.group || r.item)) || (r && typeof r.className === 'string' ? r : null);
+  return { success: true, itemId: __g ? __ppRegId(__g) : null, letters: __g && __g.children ? __g.children.length : undefined,
+    bounds: __g && __g.bounds ? { x: __g.bounds.x, y: __g.bounds.y, width: __g.bounds.width, height: __g.bounds.height } : undefined };
 })();`.trim();
         }
     }
@@ -10520,6 +11000,117 @@ ${guard}
      * only ids/count/duration are forwarded. `ids` is the whole handle set the
      * caller now has, since the source item is gone.
      */
+    /**
+     * pinepaper_relight — FxTool D5's relight post pass over the 3D world layer.
+     * The rig is not saved with the project, GIF / APNG are not relit, and it
+     * costs ~0.42 s per 1080p frame on the CPU, so a set says what an export
+     * will pay.
+     */
+    generateRelight(input) {
+        const S = (v) => JSON.stringify(v);
+        const missing = (fn) => `if (typeof app.${fn} !== 'function') { return { success: false, action: ${S(input.action)}, error: 'this studio has no relight pass (app.${fn}) — it predates FxTool D5.' }; }`;
+        switch (input.action) {
+            case 'set': {
+                const spec = S({
+                    ...(input.lights !== undefined ? { lights: input.lights } : {}),
+                    ...(input.ambient !== undefined ? { ambient: input.ambient } : {}),
+                    ...(input.strength !== undefined ? { strength: input.strength } : {}),
+                    ...(input.enabled !== undefined ? { enabled: input.enabled } : {}),
+                    ...(input.preview !== undefined ? { preview: input.preview } : {}),
+                });
+                return `
+// Relight: set the rig
+(function() {
+  ${missing('setRelight')}
+  const r = app.setRelight(${spec});
+  if (!r || r.ok === false) { return { success: false, action: 'set', error: (r && ((r.errors && r.errors.join('; ')) || r.reason)) || 'the relight rig was refused' }; }
+  // What an export will pay: ~418 ms per 1920x1080 frame, scaled by pixels.
+  const __f = (typeof app.exportFrameRect === 'function' && app.exportFrameRect()) || (app.getCanvasSize && app.getCanvasSize()) || { width: 1920, height: 1080 };
+  const __ms = Math.round(418 * (__f.width * __f.height) / (1920 * 1080));
+  const res = { success: true, action: 'set', active: r.active, relight: r.relight,
+    cost: { msPerFrame: __ms, frame: { width: __f.width, height: __f.height },
+      tenSecondsAt30fps: Math.round(__ms * 300 / 1000) + ' s extra' },
+    note: 'applied in the preview and in PNG, PDF, MP4 and WebM exports; GIF and APNG are not relit. The rig is NOT saved with the project — set it again after a reload.' };
+  if (r.reason) res.reason = r.reason;
+  if (r.active === false) res.warning = 'the rig is set but not active' + (r.reason ? ': ' + r.reason : '') + ' — relight needs a 3D world (pinepaper_world3d create).';
+  return res;
+})();`.trim();
+            }
+            case 'get':
+                return `
+// Relight: the current rig
+(function() {
+  ${missing('getRelight')}
+  return Object.assign({ success: true, action: 'get' }, app.getRelight());
+})();`.trim();
+            case 'clear':
+                return `
+// Relight: remove the rig
+(function() {
+  ${missing('clearRelight')}
+  const r = app.clearRelight();
+  return { success: true, action: 'clear', cleared: !!(r && r.cleared) };
+})();`.trim();
+            case 'list_lights':
+                return `
+// Relight: light types
+(function() {
+  ${missing('listRelightLights')}
+  return { success: true, action: 'list_lights', lights: app.listRelightLights() };
+})();`.trim();
+        }
+    }
+    /**
+     * pinepaper_shader_graph — FxTool D5's JSON pixel graphs. Applying to an
+     * item makes a NEW image item and hides the source (one undo step);
+     * applying to 'scene' returns the processed frame and changes nothing.
+     */
+    generateShaderGraph(input) {
+        const S = (v) => JSON.stringify(v);
+        const ref = input.graph ?? input.graphId;
+        const head = `  if (!app.shaderGraph || typeof app.shaderGraph.create !== 'function') { return { success: false, action: ${S(input.action)}, error: 'this studio has no shader graph (app.shaderGraph) — it predates FxTool D5.' }; }`;
+        const fail = `(r && ((r.errors && r.errors.join('; ')) || r.reason)) || 'the shader graph call failed'`;
+        const body = (() => {
+            switch (input.action) {
+                case 'node_types': return `  return { success: true, action: 'node_types', nodeTypes: app.shaderGraph.nodeTypes() };`;
+                case 'list': return `  const r = app.shaderGraph.list();\n  return { success: true, action: 'list', graphs: (r && r.graphs) || [] };`;
+                case 'validate': return `  const r = app.shaderGraph.validate(${S(input.graph)});\n  if (!r || !r.ok) return { success: false, action: 'validate', errors: (r && r.errors) || [], error: ${fail} };\n  return { success: true, action: 'validate', order: r.order };`;
+                case 'create': return `  const r = app.shaderGraph.create(${S(input.graph)});\n  if (!r || !r.ok) return { success: false, action: 'create', errors: (r && r.errors) || [], error: ${fail} };\n  return { success: true, action: 'create', graphId: r.id, order: r.order, nodes: r.nodes, replaced: r.replaced };`;
+                case 'get': return `  const r = app.shaderGraph.get(${S(input.graphId)});\n  if (!r || !r.ok) return { success: false, action: 'get', error: ${fail} };\n  return { success: true, action: 'get', graph: r.graph };`;
+                case 'remove': return `  const r = app.shaderGraph.remove(${S(input.graphId)});\n  if (!r || !r.ok) return { success: false, action: 'remove', error: ${fail} };\n  return { success: true, action: 'remove', removed: r.removed };`;
+                case 'apply': {
+                    const opts = S({ ...(input.keepSource !== undefined ? { keepSource: input.keepSource } : {}), ...(input.asItem !== undefined ? { asItem: input.asItem } : {}) });
+                    return `  if (typeof app.applyShaderGraph !== 'function') { return { success: false, action: 'apply', error: 'this studio has no app.applyShaderGraph — it predates FxTool D5.' }; }
+  const r = await app.applyShaderGraph(${S(input.target)}, ${S(ref)}, ${opts});
+  if (!r || !r.ok) return { success: false, action: 'apply', errors: (r && r.errors) || undefined, error: ${fail} };
+  if (r.target === 'item') {
+    if (!r.id) return { success: false, action: 'apply', error: 'the graph ran but made no item' };
+    // The new item's OWN bounds: a bloom with reach (FxTool D60) is larger
+    // than its source, centred on it, so the source's bounds are not these.
+    const __ne = app.itemRegistry && typeof app.itemRegistry.get === 'function' ? app.itemRegistry.get(r.id) : null;
+    const __ni = __ne && __ne.item;
+    // An image item made from a data URL decodes ASYNCHRONOUSLY and has 0x0
+    // bounds until it does (prod read {width:0, height:0}); wait for it.
+    if (__ni && __ni.className === 'Raster' && !__ni.loaded && typeof __ni.once === 'function') {
+      await new Promise(function (resolve) { const t = setTimeout(resolve, 5000); __ni.once('load', function () { clearTimeout(t); resolve(); }); });
+    }
+    const __nb = __ni && __ni.bounds && __ni.bounds.width > 0 ? __ni.bounds : null;
+    return { success: true, action: 'apply', target: 'item', itemId: r.id, sourceId: r.sourceId, sourceHidden: r.sourceHidden, graphId: r.graphId, width: r.width, height: r.height,
+      ...(__nb ? { bounds: { x: __nb.x, y: __nb.y, width: __nb.width, height: __nb.height } } : {}) };
+  }
+  const res = { success: true, action: 'apply', target: 'scene', graphId: r.graphId, width: r.width, height: r.height };
+  if (r.id) { res.itemId = r.id; } else { res.data = r.dataURL; res.mimeType = 'image/png'; res.note = 'the processed frame; the scene is unchanged. asItem: true adds it as an image item instead.'; }
+  return res;`;
+                }
+            }
+        })();
+        return `
+// Shader graph: ${input.action}
+(async function() {
+${head}
+${body}
+})();`.trim();
+    }
     /**
      * The medium axis. `list_media` and `resolve` are READS — they exist so an
      * agent can find out what this build can honestly make before it promises a
@@ -10542,8 +11133,43 @@ ${guard}
   if (!r || r.ok === false) {
     return { success: false, error: (r && (r.error || r.reason)) || 'the medium could not be applied', medium: ${S(input.medium)}, ...(r && r.fidelity ? { fidelity: r.fidelity } : {}) };
   }
+  // ink / charcoal restyle IN PLACE (FxTool D32): the same item, marked with
+  // data.brushStyle on its paths and texts. Read the mark back, so an item
+  // the engine passed over is a failure rather than a success (gate D32).
+  if (${S(input.medium)} === 'ink' || ${S(input.medium)} === 'charcoal') {
+    const __e = app.itemRegistry && app.itemRegistry.get(r.id || ${S(input.itemId)});
+    const __it = (__e && __e.item) || r.item;
+    let __styled = 0;
+    const __walk = function (n) {
+      if (!n) return;
+      if (n.data && n.data.brushStyle) __styled++;
+      (n.children || []).forEach(__walk);
+    };
+    __walk(__it);
+    if (!__styled) {
+      return { success: false, action: 'apply', medium: ${S(input.medium)}, error: 'the studio reported ' + ${S(input.medium)} + ' applied, but no path or text in ' + ${S(input.itemId)} + ' carries it. Ink and charcoal restyle paths and text; a primitive shape is skipped.' };
+    }
+    return { success: true, action: 'apply', medium: ${S(input.medium)}, fidelity: r.fidelity, itemId: r.id || ${S(input.itemId)}, inPlace: true, styled: __styled, ...(r.note ? { note: r.note } : {}) };
+  }
   return { success: true, action: 'apply', medium: r.medium || ${S(input.medium)}, fidelity: r.fidelity, itemId: r.id, ...(r.note ? { note: r.note } : {}) };
 })();`.trim();
+            case 'sdf_stroke': {
+                // FxTool D5: an SDF capsule stroke rendered to a bitmap and created as a
+                // registered, undoable image item. CPU-backed.
+                const opts = S({
+                    ...(input.width !== undefined ? { width: input.width } : {}),
+                    ...(input.softness !== undefined ? { softness: input.softness } : {}),
+                    ...(input.color !== undefined ? { color: input.color } : {}),
+                    ...(input.opacity !== undefined ? { opacity: input.opacity } : {}),
+                    ...(input.resolution !== undefined ? { resolution: input.resolution } : {}),
+                    ...(input.name !== undefined ? { name: input.name } : {}),
+                });
+                return wrap('Medium: SDF brush stroke', `  if (typeof app.sdfBrushStroke !== 'function') { return { success: false, action: 'sdf_stroke', error: 'this studio has no SDF brush (app.sdfBrushStroke) — it predates FxTool D5.' }; }
+  const r = app.sdfBrushStroke(${S(input.points)}, ${opts});
+  if (!r || r.ok === false) { return { success: false, action: 'sdf_stroke', error: (r && ((r.errors && r.errors.join('; ')) || r.reason)) || 'the stroke was not drawn' }; }
+  if (!r.id) { return { success: false, action: 'sdf_stroke', error: 'the stroke was drawn but returned no item id' }; }
+  return { success: true, action: 'sdf_stroke', itemId: r.id, bounds: r.bounds, pixelSize: r.pixelSize, backend: r.backend };`);
+            }
             case 'list_media':
                 return wrap('Medium: list', `  if (typeof app.listDesignMedia !== 'function') { return { success: false, error: 'medium axis unavailable — update FxTool' }; }
   const media = app.listDesignMedia();
@@ -10792,14 +11418,60 @@ ${guard}
 // Import a layered character (decomposer output → role-bound parts; blink works out of the box)
 (async function() {
   if (typeof app.importLayeredCharacter !== 'function') { return { success: false, error: 'app.importLayeredCharacter unavailable — update FxTool to a layered-character build' }; }
-  // The importer's contract is a Map (it calls images.get) — the wire format is
-  // a plain object, so rebuild the Map here.
-  const bundle = { info: ${S(input.info)}, images: new Map(Object.entries(${S(input.images)})) };
+  // The engine looks layers up by NORMALISED tag (lowercase, no dir/extension,
+  // '_'/'-' collapsed to a space): parseSeeThroughManifest asks
+  // images.has(normalizePartTag(tag)), then images.get(layer.tag). Its own
+  // folder reader keys the Map that way; a wire object keyed 'eye_left' is never
+  // found and every multi-word layer is skipped as "no image found".
+  // Mirrors FxTool js/ontology/CharacterPartTaxonomy.js normalizePartTag.
+  const norm = (t) => String(t).trim().toLowerCase().replace(/^.*[\\\\/]/, '').replace(/\\.(png|webp|tga|psd)$/i, '').replace(/[_\\-\\s]+/g, ' ').trim();
+  // The taxonomy resolves DECOMPOSER tags (eyel, iridesr, eyebrowl, hairf) — not
+  // the role tokens it emits. A layer tagged with a role token (eye_left,
+  // pupil_right, hair_front) resolves to no role, so alias role tokens to the
+  // decomposer tag that produces them.
+  const SIDED = { eye: 'eye', pupil: 'irides', brow: 'eyebrow', eyelash: 'eyelash', ear: 'ears', hand: 'handwear' };
+  const FLAT = { 'hair front': 'hairf', 'hair back': 'hairb', torso: 'topwear', hips: 'bottomwear', legs: 'legwear', feet: 'footwear', prop: 'objects' };
+  const canon = (t) => {
+    const k = norm(t);
+    let m = /^(.+) (left|right|l|r)$/.exec(k);
+    if (m && SIDED[m[1]] !== undefined) return SIDED[m[1]] + m[2][0];
+    m = /^(left|right) (.+)$/.exec(k);
+    if (m && SIDED[m[2]] !== undefined) return SIDED[m[2]] + m[1][0];
+    return FLAT[k] || k;
+  };
+  const rawInfo = ${S(input.info)};
+  const rawImages = ${S(input.images)};
+  const partsKey = rawInfo.parts ? 'parts' : (rawInfo.tag2pinfo ? 'tag2pinfo' : null);
+  const info = { ...rawInfo };
+  const notes = [];
+  if (partsKey && rawInfo[partsKey] && typeof rawInfo[partsKey] === 'object' && !Array.isArray(rawInfo[partsKey])) {
+    info[partsKey] = {};
+    for (const [t, v] of Object.entries(rawInfo[partsKey])) {
+      const c = canon(t);
+      if (info[partsKey][c]) { notes.push('layer "' + t + '" collides with another layer as "' + c + '" — kept the first'); continue; }
+      info[partsKey][c] = v;
+    }
+  }
+  const images = new Map();
+  const suppliedBy = {}; // canonical tag → the caller's own key, for naming
+  for (const [t, v] of Object.entries(rawImages)) {
+    const c = canon(t);
+    if (images.has(c)) { notes.push('image "' + t + '" collides with "' + suppliedBy[c] + '" — kept the first'); continue; }
+    images.set(c, v); suppliedBy[c] = t;
+  }
+  const bundle = { info, images };
   const r = await app.importLayeredCharacter(bundle, ${opts});
   if (!r || !r.groupId) { return { success: false, error: (r && r.error) || 'layered character import failed' }; }
   // roles maps part roles → item ids; zero roles wired means the character
   // renders but will NOT animate — surface the count so that cannot hide.
-  return { success: true, groupId: r.groupId, parts: (r.parts || []).length, roles: r.roles || {}, rolesWired: Object.keys(r.roles || {}).length, warnings: r.warnings || [] };
+  const imported = new Set((r.parts || []).map((p) => p.tag));
+  const skipped = Object.keys(suppliedBy).filter((c) => !imported.has(c)).map((c) => suppliedBy[c]);
+  const unroled = (r.parts || []).filter((p) => !p.role).map((p) => suppliedBy[p.tag] || p.tag);
+  const result = { groupId: r.groupId, parts: (r.parts || []).length, roles: r.roles || {}, rolesWired: Object.keys(r.roles || {}).length, skipped, unroled, warnings: [...notes, ...(r.warnings || [])] };
+  // A supplied image that did not land is the caller's input dropped — not a
+  // success. The group IS on the canvas, so hand back its id to fix or delete.
+  if (skipped.length) { return { success: false, ...result, error: 'supplied layer(s) not imported: ' + skipped.join(', ') + ' — each needs a matching key under info.parts with a usable xyxy (see warnings)' }; }
+  return { success: true, ...result };
 })();`.trim();
     }
     /**
@@ -10902,7 +11574,9 @@ ${needWorld}
 (function() {
   if (typeof app.addWorldActor !== 'function') { return { success: false, error: 'app.addWorldActor unavailable — update FxTool' }; }
 ${needWorld}
-  const id = app.addWorldActor(${actor});
+  const __r = app.addWorldActor(${actor});
+  // The engine may return the actor itself; the id is what later calls take (gate D5).
+  const id = (__r && typeof __r === 'object') ? (__r.id || null) : __r;
   return id ? { success: true, actorId: id } : { success: false, error: 'actor not added — is the sprite id a canvas item?' };
 })();`.trim();
             }
@@ -10940,7 +11614,9 @@ ${needWorld}
 // World3D: place an object (y defaults to sitting on the terrain)
 (function() {
 ${needWorld}
-  const id = app.addWorldObject(${S(world3dColors(input.object))});
+  const __o = app.addWorldObject(${S(world3dColors(input.object))});
+  // addWorldObject returns the OBJECT; its id is what set/remove calls take (gate D5).
+  const id = (__o && typeof __o === 'object') ? (__o.id || null) : __o;
   return id ? { success: true, objectId: id } : { success: false, error: 'object not added' };
 })();`.trim();
             case 'remove_object':
@@ -10955,7 +11631,10 @@ ${needWorld}
 // World3D: tear the world down — Paper's canvas is untouched (it was always its own layer)
 (function() {
   if (typeof app.removeWorld3D !== 'function') { return { success: false, error: 'app.removeWorld3D unavailable — update FxTool' }; }
-  return { success: !!app.removeWorld3D() };
+  // removeWorld3D's return value is not a success flag; whether the world is
+  // gone is (gate D5: it worked and reported failure).
+  app.removeWorld3D();
+  return { success: !app._world3d };
 })();`.trim();
             // --- Mesh authoring ---------------------------------------------------
             // extrudeToMesh / latheToMesh REFUSE by name when there is no world
@@ -11008,7 +11687,19 @@ ${needWorld}
 // World3D: every authored mesh on the stage
 (function() {
   if (typeof app.listWorldMeshes !== 'function') { return { success: false, error: 'app.listWorldMeshes unavailable — update FxTool' }; }
-  return { success: true, meshes: app.listWorldMeshes() };
+  // Summarised (gate A, 1.6.19): one star returned over 10 KB, nearly all of it
+  // collision and vertex arrays nobody asked for. Arrays longer than 16 numbers
+  // become their length; everything else passes as is.
+  const __slim = function (v, depth) {
+    // Typed arrays too: collision positions are a Float32Array, which
+    // Array.isArray misses, so a star still came back as 12 KB (gate run 2).
+    if (ArrayBuffer.isView(v)) return v.length > 16 ? { length: v.length } : Array.prototype.slice.call(v);
+    if (Array.isArray(v)) return v.length > 16 ? { length: v.length } : v.map(function (x) { return __slim(x, depth + 1); });
+    if (v && typeof v === 'object' && depth < 4) { const o = {}; for (const k in v) { if (typeof v[k] !== 'function') o[k] = __slim(v[k], depth + 1); } return o; }
+    return v;
+  };
+  const __m = app.listWorldMeshes() || [];
+  return { success: true, count: __m.length, meshes: __m.map(function (m) { return __slim(m, 0); }) };
 })();`.trim();
             case 'remove_mesh':
                 return `
@@ -11178,7 +11869,10 @@ ${needWorld}
 (function() {
   if (typeof app.worldToCanvas !== 'function') { return { success: false, error: 'app.worldToCanvas unavailable — update FxTool' }; }
 ${needWorld}
-  return { success: true, point: app.worldToCanvas(${S(input.point)}) };
+  // projectToCanvas destructures [x, y, z]; an {x, y, z} object threw "is not iterable" (gate D5).
+  const __p = ${S(input.point)};
+  const __pt = app.worldToCanvas(Array.isArray(__p) ? __p : [__p.x, __p.y, __p.z ?? 0]);
+  return __pt ? { success: true, point: Array.isArray(__pt) ? { x: __pt[0], y: __pt[1] } : __pt } : { success: false, error: 'the point is not in front of the camera, or there is no world' };
 })();`.trim();
             case 'canvas_to_ground':
                 return `
@@ -11285,14 +11979,20 @@ ${needWorld}
      * already decided by a pure function, so nothing is left for the page to
      * work out.
      */
-    generateDesignCompose(scene, ops, style) {
+    generateDesignCompose(scene, ops, style, sizeWarning) {
         const S = (v) => JSON.stringify(v);
         return `
 // Design: compose a ${style} scene — ${ops.length} items, laid out server-side
 (function() {
   if (typeof app.create !== 'function') { return { success: false, error: 'app.create unavailable — update FxTool' }; }
   const size = ${S({ width: scene.width, height: scene.height })};
-  if (typeof app.setCanvasSize === 'function') { try { app.setCanvasSize(size.width, size.height); } catch (_) { /* a fixed canvas is not a failure */ } }
+  // The layout was computed for this size, so the canvas is set to it — and
+  // the result SAYS so: a 1080x1080 canvas became 1280x720 silently (gate C).
+  const __before = app.getCanvasSize ? app.getCanvasSize() : null;
+  if (typeof app.setCanvasSize === 'function') { try { app.setCanvasSize({ width: size.width, height: size.height }); } catch (_) { /* a fixed canvas is not a failure */ } }
+  const __after = app.getCanvasSize ? app.getCanvasSize() : null;
+  const canvasResized = __before && __after && (__before.width !== __after.width || __before.height !== __after.height)
+    ? { from: { width: __before.width, height: __before.height }, to: { width: __after.width, height: __after.height } } : null;
   ${scene.backgroundHex ? `if (typeof app.setBackgroundColor === 'function') { try { app.setBackgroundColor(${S(scene.backgroundHex)}); } catch (_) { /* ditto */ } }` : '// this style paints no background of its own'}
   const ops = ${S(ops)};
   const ids = [];
@@ -11307,7 +12007,9 @@ ${needWorld}
   if (app.historyManager) app.historyManager.saveState();
   // A partial composition is reported as one. Half a poster that claims
   // success is worse than a poster that says which four elements are missing.
-  return { success: failed.length === 0, style: ${S(style)}, itemIds: ids, itemCount: ids.length, failed: failed };
+  return { success: failed.length === 0, style: ${S(style)}, itemIds: ids, itemCount: ids.length, failed: failed,
+    ...(canvasResized ? { canvasResized: canvasResized, note: 'the canvas was resized to the composition' + (${S(sizeWarning ?? '')} ? '' : '; pass width and height to compose at your canvas size') } : {}),
+    ...(${S(sizeWarning ?? '')} ? { warning: ${S(sizeWarning ?? '')} } : {}) };
 })();`.trim();
     }
     /**
@@ -11448,9 +12150,13 @@ ${needWorld}
 // Interchange: ${fn}
 (async function() {
 ${guard(fn)}
+  ${TO_DATA_URL_JS}
   const out = await app.${fn}(${opts});
   if (!out) { return { success: false, error: '${fn} produced nothing — the scene may have no animatable content' }; }
-  return { success: true, format: ${S(input.action === 'export_lottie' ? 'lottie' : 'dotlottie')}, data: out };
+  ${input.action === 'export_lottie'
+                    ? `return { success: true, format: 'lottie', data: out };`
+                    : `const __url = await __ppToDataUrl(out, 'application/zip');
+  return __url ? { success: true, format: 'dotlottie', data: __url } : { success: false, error: 'exportDotLottie returned something that is not binary' };`}
 })();`.trim();
             }
             case 'import_lottie':
@@ -11460,9 +12166,23 @@ ${guard(fn)}
 ${guard('importLottie')}
   // importLottie logs and returns falsy when the importer is absent — a
   // stripped console makes that indistinguishable from an empty animation.
+  ${REG_ID_JS}
   const r = await app.importLottie(${S(input.data)}, ${opts});
-  if (!r) { return { success: false, error: 'the Lottie did not import — it may be malformed, or this build has no Lottie importer' }; }
-  return { success: true, imported: r };
+  // importLottie ALWAYS answers { success, items, duration, warnings, errors };
+  // only !r was checked, so a failed import read as a success, and the ids
+  // were looked for on fields it does not have (gate N2: itemId null).
+  if (!r || r.success === false) {
+    const why = r && Array.isArray(r.errors) && r.errors.length ? r.errors.join('; ') : 'the Lottie did not import — it may be malformed';
+    return { success: false, error: why, ...(r && r.warnings && r.warnings.length ? { warnings: r.warnings } : {}) };
+  }
+  const __items = Array.isArray(r.items) ? r.items : [];
+  const itemIds = __items.map(function (it) { return __ppRegId(it); }).filter(Boolean);
+  if (!__items.length) return { success: false, error: 'the Lottie imported no items' };
+  let __b = null;
+  __items.forEach(function (it) { if (it && it.bounds) __b = __b ? __b.unite(it.bounds) : it.bounds; });
+  return { success: true, itemId: itemIds[0] || null, itemIds: itemIds, items: __items.length, duration: r.duration,
+    bounds: __b ? { x: __b.x, y: __b.y, width: __b.width, height: __b.height } : undefined,
+    ...(r.warnings && r.warnings.length ? { warnings: r.warnings } : {}) };
 })();`.trim();
             case 'export_glb':
                 return `
@@ -11473,9 +12193,11 @@ ${guard('exportGLB')}
   // stripped in production, so the precondition is checked here instead.
   const has3d = app._initialized && app._initialized.has && app._initialized.has('threeD');
   if (!has3d) { return { success: false, error: 'no perspective objects to export — create one with createObject3D first' }; }
+  ${TO_DATA_URL_JS}
   const out = await app.exportGLB(${opts});
   if (!out) { return { success: false, error: 'GLB export produced nothing' }; }
-  return { success: true, format: 'glb', data: out };
+  const __url = await __ppToDataUrl(out, 'model/gltf-binary');
+  return __url ? { success: true, format: 'glb', data: __url } : { success: true, format: 'glb', data: out };
 })();`.trim();
             case 'export_bvh':
                 return `
@@ -11536,7 +12258,16 @@ ${guard('exportPNGSequence')}
     generateSound(input) {
         const S = (v) => JSON.stringify(v);
         const guard = (fn) => `  if (typeof app.${fn} !== 'function') { return { success: false, error: 'app.${fn} unavailable — update FxTool' }; }`;
-        const simple = (fn, args, key, label) => `
+        const simple = (fn, args, key, label) => key === 'played' ? `
+// Sound: ${label}
+(function() {
+${guard(fn)}
+  // A play that returns no voice played nothing, and reported success (gate
+  // sweep D, 1.6.19). A headless studio may have no audio output at all.
+  const __v = app.${fn}(${args});
+  if (__v == null) { return { success: false, error: 'nothing played: the studio returned no voice (it may have no audio output). Placed sounds (create, sequence) and render_soundtrack work without one.' }; }
+  return { success: true, played: __v };
+})();`.trim() : `
 // Sound: ${label}
 (function() {
 ${guard(fn)}
@@ -11551,8 +12282,12 @@ ${guard(fn)}
             case 'chord_frequencies': return simple('chordFrequencies', `${S(input.root)}, ${S(input.chord)}, ${S(input.options ?? {})}`, 'frequencies', `the Hz of ${input.chord} on ${input.root}`);
             case 'play_percussion': return simple('playPercussion', `${S(input.name)}, ${S(input.options ?? {})}`, 'played', `percussion ${input.name}`);
             case 'play_sfx': return simple('playSfx', `${S(input.name)}, ${S(input.options ?? {})}`, 'played', `sfx ${input.name}`);
-            case 'play_spec': return simple('playSound', S(input.spec), 'played', 'a raw spec');
-            case 'play_from_text': return simple('playSoundFromText', S(input.text), 'played', `"${input.text}"`);
+            // options are merged into the spec, as play_tone's are; play_spec and
+            // play_from_text dropped them (gate sweep D).
+            case 'play_spec': return simple('playSound', `Object.assign({}, ${S(input.spec)}, ${S(input.options ?? {})})`, 'played', 'a raw spec');
+            case 'play_from_text': return input.options
+                ? simple('playSound', `Object.assign({}, app.buildSoundFromText(${S(input.text)}) || {}, ${S(input.options)})`, 'played', 'a described sound')
+                : simple('playSoundFromText', S(input.text), 'played', 'a described sound');
             case 'from_text':
                 return `
 // Sound: resolve "${input.text}" to a spec WITHOUT playing it
@@ -11712,7 +12447,9 @@ ${guard('createSound')}
   for (let i = 0; i < cues.length; i++) {
     const c = cues[i];
     try {
-      const spec = c.spec || (c.preset ? { preset: c.preset, note: c.note } : null);
+      // The engine reads spec.instrument and never preset, so a preset cue
+      // played a plain sine (gate sweep D).
+      const spec = c.spec || (c.preset ? { instrument: c.preset, note: c.note } : null);
       if (!spec) { failed.push({ index: i, t: c.t, error: 'neither spec nor preset' }); continue; }
       const item = app.createSound(spec, c.visual || {});
       if (!item) { failed.push({ index: i, t: c.t, error: 'the cue produced no waveform path' }); continue; }
@@ -11801,10 +12538,20 @@ ${guard('timbreFromPath')}
     generatePathOp(input) {
         const S = (v) => JSON.stringify(v);
         const guard = (fn) => `  if (typeof app.${fn} !== 'function') { return { success: false, error: 'app.${fn} unavailable — update FxTool' }; }`;
+        // Paper items in the engine's answer become their registry ids: spread
+        // as-is they serialised to raw Paper dumps (1.6.19 gate: boolean,
+        // outline_stroke and pattern).
         const pass = (expr) => `
+  ${REG_ID_JS}
+  const __isItem = function (v) { return v && typeof v === 'object' && typeof v.className === 'string' && 'bounds' in v; };
+  const __clean = function (v) { return __isItem(v) ? (__ppRegId(v) || ('paper:' + v.id)) : (Array.isArray(v) && v.some(__isItem) ? v.map(__clean) : v); };
   const r = ${expr};
   if (!r || r.ok === false) { return { success: false, error: (r && r.reason) || 'the engine refused the operation' }; }
-  return { success: true, ...r };`;
+  const out = { success: true };
+  Object.keys(r).forEach(function (k) { out[k] = __clean(r[k]); });
+  // itemId, as every other tool names it; the engine says id (gate run 3).
+  if (out.itemId === undefined && typeof out.id === 'string') out.itemId = out.id;
+  return out;`;
         switch (input.action) {
             case 'boolean':
                 return `
@@ -12146,7 +12893,14 @@ ${guard('unlockAllItems')}${pass('app.unlockAllItems()')}
                 return wrap('Rigging: bake animation to keyframes', `  const res = R.bakeAnimation(${S(input.skeletonId)}, ${S(input.options ?? {})});
   if (res && app.historyManager) app.historyManager.saveState();
   if (!res) { return { success: false, action: 'bake_animation', error: "nothing to bake — no such skeleton, or no items are ATTACHED to its bones. Baking writes keyframes onto the attached items, so a bare skeleton has no output." }; }
-  return { success: true, action: 'bake_animation', result: res };`);
+  // bakeAnimation returns a MAP (itemId -> keyframes), which serialised to {},
+  // and its report is a non-enumerable bakeReport (gate run 3). Read both.
+  const rep = res.bakeReport || {};
+  const detached = rep.detached || 0;
+  return { success: (rep.written || 0) > 0 || ${input.options && input.options.write === false ? 'true' : 'false'}, action: 'bake_animation',
+    items: res.size, written: rep.written || 0, keyframes: rep.keyframes || 0, cleared: rep.cleared || 0, detached: detached,
+    wrote: rep.wrote || [], ...(rep.skipped && rep.skipped.length ? { skipped: rep.skipped } : {}),
+    ...(detached ? { note: detached + ' item(s) were DETACHED from the rig: their motion is now keyframes, and the bones no longer drive them. Pass options.detach:false to keep the rig driving.' } : {}) };`);
             case 'list_shape_keys':
                 return wrap('Rigging: list shape keys', `  const keys = R.listShapeKeys(${S(input.skeletonId)});
   return { success: true, action: 'list_shape_keys', shapeKeys: keys, count: keys.length };`);