@pinepaper.studio/mcp-server 1.6.18 → 1.6.20

package/dist/types/code-generator.js

@@ -4,12 +4,13 @@
  * Converts MCP tool inputs to executable PinePaper JavaScript code.
  * This code is designed to run in the browser context where window.PinePaper is available.
  */
+import { compileChoreography } from '../tools/choreograph.js';
 import { normalizeSvgSize } from '../utils/svg-size.js';
 import { WORLD3D_COLOR_PATHS } from '../tools/engine-lists.js';
 import { REQUIRED_ENGINE_METHODS, OPTIONAL_ENGINE_METHODS } from '../tools/engine-methods.js';
 import { ACCEPTED_CREATE_PARAMS, NORMALIZE_PARAM_READS, MODIFY_CHANGE_READS } from '../tools/shape-params.js';
 import { generateP5DrawCode } from '../tools/p5-compat/p5-helpers.js';
-import { CreateItemInputSchema, ImportMotionCaptureInputSchema, ModifyItemInputSchema, AddRelationInputSchema, AnimateItemInputSchema, KeyframeAnimateInputSchema, ExecuteGeneratorInputSchema, ApplyEffectInputSchema, SetBackgroundColorInputSchema, SetCanvasSizeInputSchema, CreateGlossySphereInputSchema, CreateDiagonalStripesInputSchema, BatchCreateInputSchema, BatchModifyInputSchema, CreateGridInputSchema, CreateSceneInputSchema, 
+import { CreateItemInputSchema, ScreenSpaceSchema, StepTimingSchema, CounterSchema, ImportMotionCaptureInputSchema, ModifyItemInputSchema, AddRelationInputSchema, AnimateItemInputSchema, KeyframeAnimateInputSchema, ExecuteGeneratorInputSchema, ApplyEffectInputSchema, SetBackgroundColorInputSchema, SetCanvasSizeInputSchema, CreateGlossySphereInputSchema, CreateDiagonalStripesInputSchema, BatchCreateInputSchema, BatchModifyInputSchema, CreateGridInputSchema, CreateSceneInputSchema, 
 // Diagram types
 CreateDiagramShapeInputSchema, ConnectInputSchema, ConnectPortsInputSchema, AddPortsInputSchema, AutoLayoutInputSchema, GetDiagramShapesInputSchema, UpdateConnectorInputSchema, RemoveConnectorInputSchema, DiagramModeInputSchema, 
 // Agent flow mode types
@@ -25,7 +26,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 +481,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 +1491,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 +1506,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 +1521,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 +1695,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 +1713,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();
@@ -1939,6 +1956,108 @@ export function planKeyframeMerges(operations) {
  * Such a snippet's value is its last top-level (-led statement; the
  * font-loading form is an async IIFE, which is awaited instead.
  */
+/**
+ * The active brand's defaults for a new item (D69): only what the caller did
+ * not name. Closed shapes take colors.primary; text takes colors.text (or
+ * primary) and the heading font from 32 px up, else the body font. Applied
+ * through modifyItem after create, so the engine's own bookkeeping runs.
+ */
+const BRAND_FILL_TYPES = new Set(['circle', 'star', 'rectangle', 'triangle', 'polygon', 'ellipse', 'pentagon', 'hexagon', 'diamond', 'arrow', 'heart']);
+function withBrandDefaults(code, itemType, props) {
+    if (props.noBrand === true)
+        return code;
+    const isText = itemType === 'text';
+    if (!isText && !BRAND_FILL_TYPES.has(itemType))
+        return code;
+    const hasColor = ['color', 'fillColor', 'fill'].some((k) => props[k] !== undefined);
+    const hasFont = props.fontFamily !== undefined;
+    if (hasColor && (!isText || hasFont))
+        return code;
+    const size = typeof props.fontSize === 'number' ? props.fontSize : 36;
+    const anchor = 'const itemId = item.data.registryId;';
+    if (!code.includes(anchor))
+        return code;
+    const patch = `
+// Active brand (D69): fill in what this call did not name.
+const __bk = (typeof window !== 'undefined' && window.__ppActiveBrand) || null;
+let __brand = null;
+if (__bk && __bk.colors && app.modifyItem) {
+  const __bm = {};
+  ${hasColor ? '' : `__bm.color = ${isText ? '__bk.colors.text || __bk.colors.primary' : '__bk.colors.primary'};`}
+  ${isText && !hasFont ? `const __f = __bk.fonts && (${size >= 32 ? '__bk.fonts.heading || __bk.fonts.body' : '__bk.fonts.body || __bk.fonts.heading'}); if (__f) __bm.fontFamily = __f;` : ''}
+  if (Object.keys(__bm).length) { app.modifyItem(itemId, __bm); __brand = __bm; }
+}`;
+    return code.replace(anchor, anchor + patch).replace(/\(\{ itemId, type:/, '({ itemId, ...(__brand ? { brand: __brand } : {}), type:');
+}
+const ITEM_SETTERS = [
+    { key: 'screenSpace', fn: 'setScreenSpace', what: 'screen-space (HUD) items', since: 'D20' },
+    { key: 'stepTiming', fn: 'setStepTiming', what: 'step timing', since: 'D11' },
+    { key: 'counter', fn: 'setCounter', what: 'counters', since: 'D70' },
+];
+/** Lift screenSpace / hud / stepTiming out of a properties bag (mutated), explicit fields winning. */
+function takeItemSetters(props, explicit = {}) {
+    const out = {};
+    // From properties a caller may write hud: 1; it means on. The top-level
+    // field is still a strict boolean.
+    const ss = explicit.screenSpace ?? (props.screenSpace ?? props.hud);
+    if (ss !== undefined)
+        out.screenSpace = explicit.screenSpace !== undefined ? ScreenSpaceSchema.parse(ss) : !!ss;
+    const st = explicit.stepTiming !== undefined ? explicit.stepTiming : props.stepTiming;
+    if (st !== undefined)
+        out.stepTiming = StepTimingSchema.parse(st);
+    // A counter from properties is lifted only when it is a valid spec; anything
+    // else stays where it was, for the engine to read and refuse by name.
+    let liftCounter = explicit.counter !== undefined;
+    if (liftCounter)
+        out.counter = CounterSchema.parse(explicit.counter);
+    else if (props.counter !== undefined && CounterSchema.safeParse(props.counter).success) {
+        out.counter = props.counter;
+        liftCounter = true;
+    }
+    delete props.screenSpace;
+    delete props.hud;
+    delete props.stepTiming;
+    if (liftCounter)
+        delete props.counter;
+    return out;
+}
+function hasItemSetters(s) {
+    return s.screenSpace !== undefined || s.stepTiming !== undefined || s.counter !== undefined;
+}
+/** Statements: refuse, before anything changes, when a requested setter is missing. */
+function itemSettersPreflightJs(s) {
+    return ITEM_SETTERS.filter((d) => s[d.key] !== undefined).map((d) => `  if (typeof app.${d.fn} !== 'function') { return { success: false, error: 'this studio has no ${d.what} (app.${d.fn}) — it predates FxTool ${d.since}; nothing was changed.' }; }`).join('\n');
+}
+/** Statements: apply each setter to idExpr, folding the verdict into resVar. */
+function itemSettersApplyJs(s, idExpr, resVar) {
+    return ITEM_SETTERS.filter((d) => s[d.key] !== undefined).map((d) => {
+        const arg = JSON.stringify(s[d.key]);
+        return `  {
+    const __sr = app.${d.fn}(${idExpr}, ${arg});
+    if (!__sr || __sr.ok === false) {
+      return Object.assign({}, ${resVar}, { success: false, error: '${d.key} was not applied to ' + ${idExpr} + ': ' + ((__sr && (__sr.reason || __sr.error)) || 'refused by the studio') });
+    }
+    ${resVar}.${d.key} = ${d.key === 'screenSpace' ? arg : `(__sr.${d.key} !== undefined ? __sr.${d.key} : ${arg})`};${d.key === 'counter' ? `\n    if (__sr.text !== undefined) ${resVar}.counterText = __sr.text;` : ''}
+  }`;
+    }).join('\n');
+}
+/** Wrap a create / modify snippet so the setters run after it, on its item. */
+function withItemSetters(code, s, idExpr) {
+    if (!hasItemSetters(s))
+        return code;
+    return `(async function() {
+${itemSettersPreflightJs(s)}
+  const __res = await (async function() {
+${asReturningBody(code)}
+  })();
+  if (!__res || __res.success === false) return __res;
+  const __sid = ${idExpr};
+  if (!__sid) return __res;
+${itemSettersApplyJs(s, '__sid', '__res')}
+  if (__res.success === undefined) __res.success = true;
+  return __res;
+})();`;
+}
 function asReturningBody(snippet) {
     const single = snippet.trim();
     if (single.startsWith('(async function()'))
@@ -2210,8 +2329,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 +2435,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
@@ -2333,17 +2501,27 @@ export class PinePaperCodeGenerator {
             properties.keyframes = validated.keyframes;
         if (validated.anchor !== undefined && properties.anchor === undefined && properties.origin === undefined)
             properties.anchor = validated.anchor;
-        return generateCreateItemCode(validated.itemType, validated.position, properties, validated.data, positionGiven);
+        const setters = takeItemSetters(properties, { screenSpace: validated.screenSpace, stepTiming: validated.stepTiming, counter: validated.counter });
+        const brandProps = { ...properties };
+        delete properties.noBrand;
+        return withItemSetters(withBrandDefaults(generateCreateItemCode(validated.itemType, validated.position, properties, validated.data, positionGiven), validated.itemType, brandProps), setters, '__res.itemId');
     }
     /**
      * Generate code for modifying an item
      */
     generateModifyItem(input) {
         const validated = ModifyItemInputSchema.parse(input);
+        const props = { ...validated.properties };
+        const setters = takeItemSetters(props, { screenSpace: validated.screenSpace, stepTiming: validated.stepTiming, counter: validated.counter });
+        const idExpr = JSON.stringify(validated.itemId);
         if (validated.atTime !== undefined) {
-            return generateAutoKeyCode(validated.itemId, validated.properties, validated.atTime, validated.easing);
+            return withItemSetters(generateAutoKeyCode(validated.itemId, props, validated.atTime, validated.easing), setters, idExpr);
         }
-        return generateModifyItemCode(validated.itemId, validated.properties, validated.data);
+        // Only a setter asked for: no property edit to run.
+        if (hasItemSetters(setters) && Object.keys(props).length === 0 && !validated.data) {
+            return withItemSetters(`({ success: true, itemId: ${idExpr} });`, setters, idExpr);
+        }
+        return withItemSetters(generateModifyItemCode(validated.itemId, props, validated.data), setters, idExpr);
     }
     /**
      * Generate code for deleting an item
@@ -2354,8 +2532,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
@@ -2381,7 +2565,15 @@ export class PinePaperCodeGenerator {
         if (validated.relationType === 'moves_along_path') {
             return generateMovesAlongPathCode(validated.sourceId, validated.targetId ?? undefined, (validated.params ?? {}));
         }
-        return generateAddRelationCode(validated.sourceId, validated.targetId || validated.sourceId, validated.relationType, validated.params);
+        const code = generateAddRelationCode(validated.sourceId, validated.targetId || validated.sourceId, validated.relationType, validated.params);
+        // NO TARGET (event reactions like on_event_play_sound, self-relations): the
+        // engine is handed the source as the target, but the reply must not say
+        // "item_2 → item_2" — a model reads that as the event wired to itself.
+        if (validated.targetId)
+            return code;
+        return code
+            .replace(`return { success: true, sourceId: '${validated.sourceId}', targetId: '${validated.sourceId}',`, `return { success: true, sourceId: '${validated.sourceId}', targetId: null,`)
+            .replace(`relation between ${validated.sourceId} and ${validated.sourceId}.`, `relation on ${validated.sourceId} (no target).`);
     }
     /**
      * Generate code for removing a relation
@@ -2407,7 +2599,19 @@ export class PinePaperCodeGenerator {
      */
     generateKeyframeAnimate(input) {
         const validated = KeyframeAnimateInputSchema.parse(input);
-        return generateKeyframeAnimateCode(validated.itemId, validated.keyframes, validated.duration, validated.loop, validated.timeOffset, validated.clipInPoint, validated.clipOutPoint, validated.timeUnits, validated.append);
+        // Hold keys (FxTool D11) on an engine without them would interpolate in
+        // silence; refuse before anything is written. setStepTiming ships in the
+        // same change, so it is the probe.
+        const holds = validated.keyframes.some((k) => k.interpolation === 'hold' || k.hold === true);
+        const code = generateKeyframeAnimateCode(validated.itemId, validated.keyframes, validated.duration, validated.loop, validated.timeOffset, validated.clipInPoint, validated.clipOutPoint, validated.timeUnits, validated.append);
+        if (!holds)
+            return code;
+        return `(async function() {
+  if (!(typeof app.setStepTiming === 'function')) { return { success: false, error: 'this studio has no hold keys (interpolation: \\'hold\\') — it predates FxTool D11; nothing was written. Use two keys a frame apart for a cut.' }; }
+  return await (async function() {
+${asReturningBody(code)}
+  })();
+})();`;
     }
     /**
      * Generate code for importing / retargeting a motion-capture clip
@@ -2655,6 +2859,15 @@ throw new Error('Either svgString or url must be provided');
     success: !!result.success,
     nodeCount: nodes.length,
     edgeCount: edges.length,
+    // CANVAS ids, the ones auto_layout / animate / add_relation take. The
+    // engine's own nodeIds are the MERMAID ids (A, B…), which resolve to
+    // nothing on the canvas (gate D45). Newer engines return nodeItemIds;
+    // otherwise they are read off the registered nodes.
+    nodeItemIds: Array.isArray(result.nodeItemIds) && result.nodeItemIds.length
+      ? result.nodeItemIds
+      : nodes.map((n) => n.id).filter((id) => typeof id === 'string' && /^item_/.test(id)),
+    ...(result.nodeIdMap && typeof result.nodeIdMap === 'object' ? { nodeIdMap: result.nodeIdMap } : {}),
+    ...(Array.isArray(result.edgeIds) && result.edgeIds.length ? { edgeIds: result.edgeIds } : {}),
     nodes,
     edges,
     errors: result.errors || [],
@@ -3068,9 +3281,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 +3407,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 +3521,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 +3575,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 +3667,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 +3717,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` : ''}
   };
@@ -3499,6 +3738,8 @@ throw new Error('Unknown diagram mode action: ${action}');
         let code = `
 // End agent job
 (async function() {
+  // Close the studio's job (D92). It never reloads.
+  try { if (typeof window !== 'undefined' && window.PinePaperAgent && window.PinePaperAgent.endJob) window.PinePaperAgent.endJob(); } catch (_) { /* older studio */ }
   const result = {
     success: true,
     jobEnded: true
@@ -3558,12 +3799,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');
     }
@@ -3802,12 +4044,19 @@ throw new Error('Unknown diagram mode action: ${action}');
                 // the exact emitter create_item uses, adapted to return its result
                 // inside this op's function.
                 const pos = op.position || { x: 400, y: 300 };
-                const createProps = withRadiusAxes((op.properties || {}));
-                const returning = asReturningBody(generateCreateItemCode(op.itemType, pos, { ...(op.properties || {}) }, undefined, op.position !== undefined));
-                let createCode = `
+                const opProps = { ...(op.properties || {}) };
+                const opSetters = takeItemSetters(opProps, { screenSpace: op.screenSpace, stepTiming: op.stepTiming, counter: op.counter });
+                const createProps = withRadiusAxes(opProps);
+                const opBrand = { ...opProps };
+                delete opProps.noBrand;
+                const returning = asReturningBody(withBrandDefaults(generateCreateItemCode(op.itemType, pos, { ...opProps }, undefined, op.position !== undefined), op.itemType, opBrand));
+                let createCode = `${hasItemSetters(opSetters) ? `\n${itemSettersPreflightJs(opSetters)}` : ''}
 const __created = await (async function() {
 ${returning}
-})();`;
+})();${hasItemSetters(opSetters) ? `
+if (__created && __created.success !== false && __created.itemId) {
+${itemSettersApplyJs(opSetters, '__created.itemId', '__created')}
+}` : ''}`;
                 // Coordinate-built items (path from segments/pathData, line/arc from
                 // from/through/to) derive their geometry from those coordinates and
                 // IGNORE params.position — so `create` at a point silently produced an
@@ -3915,7 +4164,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 +4652,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 +4783,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 +4950,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 +5632,49 @@ ${(() => {
         })()}
 ${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) { /* the still is already rendered */ }
   if (result && result.success) result.time = ${stillTime};` : ''}
+  // SCREEN-SPACE ITEMS (FxTool D20): SVG and Lottie write geometry, not the
+  // camera's frame map, so a HUD item is placed as if the camera had not moved.
+  if (result && result.success && typeof app.screenSpaceItems === 'function' && ['svg', 'lottie', 'dotlottie'].indexOf(${JSON.stringify(format)}) !== -1) {
+    try {
+      const __hud = app.screenSpaceItems() || [];
+      if (__hud.length) {
+        result.fidelity = result.fidelity || { warnings: [] };
+        result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'screen_space_ignored', message: __hud.length + ' screen-space (HUD) item(s) are written at their frame coordinates in world space: ${format} has no camera frame, so they do not stay fixed under the camera move. Export mp4, webm, gif or png to keep them fixed.' }]);
+      }
+    } catch (_) { /* the export stands */ }
+  }
+  // WHICH STUDIO MADE THIS FILE (D92): a service worker can serve a stale
+  // build right after a deploy, and a retest then judges old code. The
+  // engine's own identity, version + build sha, rides on every export reply.
+  try { if (result && typeof result === 'object' && app.buildId) result.studioBuild = app.buildId; } catch (_) { /* older studio */ }
+  // A STALE STUDIO (D92): the file was made by an old build. Said in the
+  // fidelity warnings the reply shows, not only as a field.
+  try {
+    const __bs = app.buildStatus ? app.buildStatus() : null;
+    if (result && typeof result === 'object' && __bs) {
+      result.liveBuild = __bs.liveBuildId;
+      if (__bs.stale) {
+        result.stale = true;
+        result.fidelity = result.fidelity || { warnings: [] };
+        result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'stale_build', message: 'this studio is running an old build (' + __bs.buildId + '; the live build is ' + __bs.liveBuildId + '): this file was made by the old code. Start a new job (pinepaper_agent_start_job, which reloads it) and export again.' }]);
+      }
+    }
+  } catch (_) { /* older studio */ }
+  // 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 +5742,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 +6000,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 +6011,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 +6078,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 +6102,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 +6244,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 +6291,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 +6353,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 +6371,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 +6417,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 +6438,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 +6469,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 +6532,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 +6699,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 +6911,91 @@ ${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 } : {})});
+  // What the document CANNOT carry (D29): render hooks added as raw functions
+  // and frame callbacks from generated code. Named, never dropped in silence.
+  const __un = (doc && Array.isArray(doc.unserialized)) ? doc.unserialized
+    : (app.listUnserializedCallbacks ? app.listUnserializedCallbacks() : []);
+  return { success: true, json: JSON.stringify(doc), counts: __ppSceneCounts(), unserialized: __un };
+})();`.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 +7107,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 +7212,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 +7519,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 +7531,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 +7545,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 +7575,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?
     //
@@ -7356,13 +7892,22 @@ ${mask ? `    // A MASK REPLACES THE RASTER (round 8 DD, 4.10). applyMask builds
                     opts.push(`defaultTransition: ${JSON.stringify(input.defaultTransition)}`);
                 if (input.transitionDuration !== undefined)
                     opts.push(`transitionDuration: ${input.transitionDuration * 1000}`);
+                if (input.cutSound !== undefined)
+                    opts.push(`cutSound: ${JSON.stringify(input.cutSound)}`);
                 const optsStr = opts.length > 0 ? `, { ${opts.join(', ')} }` : '';
                 return `
 // Create scene chain for sequential playback
 (function() {
   ${guard}
-  app.sceneManager.createChain(${JSON.stringify(input.sceneIds)}${optsStr});
-  return { success: true, action: 'create_chain', sceneIds: ${JSON.stringify(input.sceneIds)}${input.loop !== undefined ? `, loop: ${input.loop}` : ''}${input.defaultDuration !== undefined ? `, defaultDuration: ${input.defaultDuration}` : ''} };
+  const __cr = app.sceneManager.createChain(${JSON.stringify(input.sceneIds)}${optsStr});
+  // An unknown cut sound comes back {ok:false, reason} (FxTool D85); a
+  // studio without cut sounds ignores the option, which the cuts readback shows.
+  if (__cr && __cr.ok === false) { return { success: false, action: 'create_chain', error: __cr.reason || 'the chain was refused' }; }
+  const __res = { success: true, action: 'create_chain', sceneIds: ${JSON.stringify(input.sceneIds)}${input.loop !== undefined ? `, loop: ${input.loop}` : ''}${input.defaultDuration !== undefined ? `, defaultDuration: ${input.defaultDuration}` : ''} };
+${input.cutSound !== undefined ? `  const __cuts = (__cr && __cr.cuts) || (app.sceneManager.getChainCuts ? app.sceneManager.getChainCuts() : null);
+  if (__cuts) __res.cuts = __cuts;
+  else __res.warning = 'this studio placed no cut sounds: it predates them (FxTool D85). The chain plays without them.';
+` : ''}  return __res;
 })();
 `.trim();
             }
@@ -7714,7 +8259,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 +8270,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 +8286,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 +8298,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();
@@ -7787,6 +8335,32 @@ ${mask ? `    // A MASK REPLACES THE RASTER (round 8 DD, 4.10). applyMask builds
 })();`.trim();
     }
     generateBrandKit(input) {
+        // THE ACTIVE BRAND (D69). apply recolours what is on the canvas once; a
+        // later beat's new items knew nothing of it. 'set' applies AND makes the
+        // kit the studio's active brand, which every create reads (withBrandDefaults).
+        // It lives in the PAGE, not this process: one cloud server serves many
+        // studios, and a brand must not cross between them.
+        if (input.action === 'get' || input.action === 'clear') {
+            return `
+// Brand kit: ${input.action} the active brand
+(function() {
+  const b = (typeof window !== 'undefined' && window.__ppActiveBrand) || null;
+  ${input.action === 'clear' ? 'if (typeof window !== "undefined") window.__ppActiveBrand = null;' : ''}
+  return { success: true, action: ${JSON.stringify(input.action)}, ${input.action === 'clear' ? 'cleared: !!b' : 'brand: b'} };
+})();`.trim();
+        }
+        if (input.action === 'set') {
+            const applied = this.generateBrandKit({ ...input, action: 'apply' });
+            return `
+// Brand kit: apply, then make it the active brand every new item inherits
+(async function() {
+  const out = await ${applied.replace(/^\/\/[^\n]*\n/, '').replace(/;\s*$/, '')};
+  if (out && (out.success === false || out.ok === false)) return out;
+  if (typeof window !== 'undefined') window.__ppActiveBrand = ${JSON.stringify(input.kit)};
+  return Object.assign({}, out, { success: true, action: 'set', active: true,
+    note: 'new shapes take colors.primary and new text colors.text with the heading (32 px and up) or body font, wherever the call names none; noBrand: true opts an item out. The active brand lives with this studio session: set it again after a reload.' });
+})();`.trim();
+        }
         const opts = JSON.stringify({ ...(input.selectionOnly ? { selectionOnly: true } : {}) });
         const method = input.action === 'plan' ? 'planBrandKit' : 'applyBrandKit';
         const facade = this._facadeCall(method, `${JSON.stringify(input.kit)}, ${opts}`, `Brand kit: ${input.action}`);
@@ -7931,7 +8505,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 +8527,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) {
@@ -8292,8 +8885,8 @@ ${resolveSource}
         const resolve = `  const item = (typeof app._resolveRaster === 'function')
     ? app._resolveRaster(${JSON.stringify(input.itemId)})
     : (app.itemRegistry ? app.itemRegistry.getItem(${JSON.stringify(input.itemId)}) : null);
-  if (!item) return { error: 'Item not found or not a raster: ' + ${JSON.stringify(input.itemId)} };
-  if (typeof app.applyImageFilter !== 'function') return { error: 'GPU image filters unavailable — update FxTool' };`;
+  if (!item) return { success: false, error: 'Item not found or not a raster: ' + ${JSON.stringify(input.itemId)} };
+  if (typeof app.applyImageFilter !== 'function') return { success: false, error: 'GPU image filters unavailable — update FxTool' };`;
         switch (input.action) {
             case 'apply':
                 return `
@@ -8310,7 +8903,7 @@ ${resolve}
     }
     return { success: true, action: 'apply', itemId: ${JSON.stringify(input.itemId)}, filter: ${JSON.stringify(input.filterName || '')} };
   } catch (e) {
-    return { error: 'Failed to apply filter: ' + e.message };
+    return { success: false, action: 'apply', error: 'Failed to apply filter: ' + e.message };
   }
 })();`.trim();
             case 'chain':
@@ -8323,7 +8916,7 @@ ${resolve}
     await app.applyImageFilterChain(item, filters);
     return { success: true, action: 'chain', itemId: ${JSON.stringify(input.itemId)}, filterCount: filters.length };
   } catch (e) {
-    return { error: 'Failed to apply filter chain: ' + e.message };
+    return { success: false, action: 'chain', error: 'Failed to apply filter chain: ' + e.message };
   }
 })();`.trim();
             default:
@@ -8624,16 +9217,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 +9274,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 +9289,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 +9689,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 +10101,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 +10123,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 +10212,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 +10252,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 +10649,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 +11156,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 +11199,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 +11218,404 @@ ${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.
+     */
+    /**
+     * pinepaper_choreograph (D67). The compiler runs IN THE STUDIO, serialised
+     * by toString, because the track depends on the actor's live size, scale,
+     * rotation and the export frame. Merged into the actor's track, read back
+     * the way keyframe_animate reads its own.
+     */
+    generateChoreograph(input) {
+        const S = (v) => JSON.stringify(v);
+        const id = S(input.itemId);
+        return `
+// Choreograph ${input.beats.length} beat(s) for ${input.itemId}
+(function() {
+  const __it = (app.getItemById && app.getItemById(${id}))
+    || (app.itemRegistry && app.itemRegistry.get && (app.itemRegistry.get(${id}) || {}).item);
+  if (!__it || !__it.bounds) { return { success: false, error: ${id} + ' is not on the canvas — check the id with pinepaper_get_items.' }; }
+  const __sc = __it.scaling || { x: 1, y: 1 };
+  const __b = __it.bounds;
+  const __baked = (__it.data && typeof __it.data._bakedRotation === 'number') ? __it.data._bakedRotation : 0;
+  const __fr = (typeof app.exportFrameRect === 'function' && app.exportFrameRect()) || (app.getCanvasSize && app.getCanvasSize()) || { width: 1920, height: 1080 };
+  const __frame = { x: __fr.x || 0, y: __fr.y || 0, width: __fr.width, height: __fr.height };
+  const __actor = { x: __it.position.x, y: __it.position.y,
+    w: __b.width / (Math.abs(__sc.x) || 1), h: __b.height / (Math.abs(__sc.y) || 1),
+    sx: __sc.x || 1, sy: __sc.y || 1, rot: (__it.rotation || 0) + __baked };
+  const __r = (${compileChoreography.toString()})(__actor, __frame, ${S(input.beats)});
+  if (__r.error) { return { success: false, itemId: ${id}, error: __r.error }; }
+  const __prev = (__it.data && Array.isArray(__it.data.keyframes)) ? __it.data.keyframes : [];
+  const __prevTimes = __prev.map(function (k) { return k && k.time; });
+  const __ours = ['x', 'y', 'scaleX', 'scaleY', 'rotation', 'opacity'];
+  const __other = __prev.reduce(function (acc, k) { Object.keys((k && k.properties) || {}).forEach(function (p) { if (__ours.indexOf(p) < 0 && acc.indexOf(p) < 0) acc.push(p); }); return acc; }, []);
+  app.addAnimation(${id}, __r.keyframes, { duration: Math.max(__r.end, __prev.reduce(function (m, k) { return Math.max(m, (k && k.time) || 0); }, 0)), loop: false, mode: 'merge' });
+  const __now = (__it.data && Array.isArray(__it.data.keyframes)) ? __it.data.keyframes.map(function (k) { return k && k.time; }) : [];
+  const __warnings = (__r.warnings || []).slice();
+  if (__prevTimes.length && !__prevTimes.every(function (t) { return __now.indexOf(t) >= 0; })) {
+    __warnings.push('this studio replaced the existing track of the actor (' + __prevTimes.length + ' key(s)) instead of merging: put the other keys in after choreographing.');
+  }
+  if (__other.length) {
+    __warnings.push('the actor already animates ' + __other.join(', ') + '; the beat keys leave those out, which the engine can break at the beat keys. Re-key ' + __other.join(', ') + ' with every key carrying them, after choreographing.');
+  }
+  if (__r.final && !__r.final.onScreen) __warnings.push('after the last beat the actor is off screen at [' + __r.final.x + ', ' + __r.final.y + '].');
+  const __res = { success: true, itemId: ${id}, beats: ${input.beats.length}, keyframes: __r.keyframes.length, duration: __r.end, final: __r.final };
+${input.sound ? `  // SOUND ON THE ACTION (D68): one placed sound per moment the motion makes —
+  // pop, launch, contact, shake — loud as the moment is strong. A sound that
+  // does not place is reported; it never undoes the motion.
+  const __map = Object.assign({ pop: 'pop', whoosh: 'whoosh', contact: 'tom', shake: 'hat' }, ${S(typeof input.sound === 'object' ? Object.fromEntries(Object.entries(input.sound).filter(([k]) => k !== 'gain')) : {})});
+  const __gain = ${S(typeof input.sound === 'object' && input.sound.gain !== undefined ? input.sound.gain : 0.8)};
+  const __sounds = [];
+  const __silent = [];
+  if (typeof app.createSound !== 'function' || (typeof app.sfxSpec !== 'function' && typeof app.percussionSpec !== 'function')) {
+    __warnings.push('no sound was placed: this studio cannot place synthesized sounds (app.createSound / sfxSpec). The motion is written.');
+  } else {
+    (__r.events || []).forEach(function (e) {
+      const name = __map[e.kind];
+      if (name === false || name === undefined) return;
+      const base = (typeof app.sfxSpec === 'function' && app.sfxSpec(name)) || (typeof app.percussionSpec === 'function' && app.percussionSpec(name));
+      if (!base) { if (__silent.indexOf(name) < 0) __silent.push(name); return; }
+      const spec = Object.assign({}, base, { gain: Math.round(((base.gain || 0.8) * __gain * (0.35 + 0.65 * e.strength)) * 1000) / 1000 });
+      // MP4 (AAC) encoder priming swallows the first ~50 ms of audio, and this
+      // muxer writes no edit list (the engine reports audio_lead_trimmed): a pop
+      // at 0 s exported as silence (prod retest of D68). 60 ms later is in sync
+      // to the eye and audible in every format.
+      const at = e.time < 0.06 ? 0.06 : e.time;
+      const it = app.createSound(spec, { startTime: at, duration: spec.duration || 0.5 });
+      if (it && it.data) __sounds.push(Object.assign({ t: at, kind: e.kind, sound: name, itemId: it.data.id }, at !== e.time ? { movedFrom: e.time } : {}));
+    });
+    if (__silent.length) __warnings.push('not in the sound catalogue, so silent: ' + __silent.join(', ') + ' (pinepaper_sound list_sfx / list_percussion for the names).');
+  }
+  __res.sounds = __sounds;
+` : ''}
+  if (__warnings.length) __res.warnings = __warnings;
+  return __res;
+})();`.trim();
+    }
+    /**
+     * pinepaper_morph_sequence (D73): ONE element through N states — R8's pill →
+     * input → dot → grid → composer → orb. The engine already chains morphs_to
+     * on one shape (per-relation state since gap 2.27); what a model could not
+     * do was time the chain, make the reference shapes, and ride the camera on
+     * the same curve. Compiled here to that chain, a camera track and sounds.
+     */
+    generateMorphSequence(input) {
+        const S = (v) => JSON.stringify(v);
+        const states = [...input.states].sort((a, b) => a.at - b.at).map((st) => ({ at: st.at, duration: st.duration ?? 0.8, to: st.to ?? null, shape: st.shape ?? null }));
+        const cam = input.camera === true ? { fill: 0.45 } : (input.camera || null);
+        const sound = input.sound === true ? 'whoosh' : (input.sound || null);
+        return `
+// Morph sequence: ${states.length} state(s)
+(function() {
+  const src = app.getItemById && app.getItemById(${S(input.itemId)});
+  if (!src) { return { success: false, error: ${S(input.itemId)} + ' is not on the canvas.' }; }
+  if (typeof app.addRelation !== 'function') { return { success: false, error: 'this studio cannot add relations.' }; }
+  const states = ${S(states)};
+  const done = [];
+  for (let i = 0; i < states.length; i++) {
+    const st = states[i];
+    let tid = st.to;
+    if (!tid) {
+      const p = Object.assign({}, st.shape.properties || {}, { x: st.shape.position.x, y: st.shape.position.y });
+      const made = app.create(st.shape.itemType, p);
+      tid = made && made.data && made.data.registryId;
+      if (!tid) { return { success: false, error: 'state ' + i + ': could not make the ' + st.shape.itemType + ' reference shape', states: done }; }
+    } else if (!(app.getItemById && app.getItemById(tid))) {
+      return { success: false, error: 'state ' + i + ': ' + tid + ' is not on the canvas', states: done };
+    }
+    const ok = app.addRelation(${S(input.itemId)}, tid, 'morphs_to', { duration: st.duration, delay: st.at, easing: ${S(input.easing ?? 'easeInOut')}, hideTarget: true });
+    if (ok === false) { return { success: false, error: 'state ' + i + ': the studio refused the morph into ' + tid, states: done }; }
+    done.push({ at: st.at, duration: st.duration, targetId: tid });
+  }
+  const res = { success: true, itemId: ${S(input.itemId)}, states: done, end: done[done.length - 1].at + done[done.length - 1].duration };
+  const n = app.getRelations ? app.getRelations(${S(input.itemId)}, 'morphs_to').length : null;
+  if (n !== null && n < done.length) res.warning = 'only ' + n + ' of ' + done.length + ' morphs are on the element.';
+${cam ? `  // The camera rides the SAME timing: framing each state as its morph lands.
+  {
+    const fr = (typeof app.exportFrameRect === 'function' && app.exportFrameRect()) || (app.getCanvasSize && app.getCanvasSize()) || { width: 1920, height: 1080 };
+    const fill = ${S(cam.fill ?? 0.45)};
+    const frameOf = function (it) { const b = it.bounds; return { focus: [b.center.x, b.center.y], zoom: Math.max(0.2, Math.min(8, fill * Math.min(fr.width / Math.max(1, b.width), fr.height / Math.max(1, b.height)))) }; };
+    const f0 = frameOf(src);
+    const kfs = [{ time: 0, zoom: f0.zoom, focus: f0.focus }];
+    done.forEach(function (d) {
+      const t = app.getItemById(d.targetId);
+      const f = frameOf(t);
+      const prev = kfs[kfs.length - 1];
+      kfs.push({ time: d.at, zoom: prev.zoom, focus: prev.focus });
+      kfs.push({ time: d.at + d.duration, zoom: f.zoom, focus: f.focus, easing: ${S(cam.easing ?? 'easeInOut')} });
+    });
+    // The SAME door pinepaper_camera_animate uses: app.camera.animate where the
+    // build has it, else the camera_animates relation — prod has only the
+    // relation, and probing app.camera.animate alone reported "no camera" there.
+    const r = app.camera && app.camera.animate
+      ? app.camera.animate(kfs, res.end, false, 0, {})
+      : app.addRelation('camera', 'camera', 'camera_animates', { keyframes: kfs, duration: res.end, loop: false, delay: 0 });
+    // Read the track back where the engine keeps it.
+    const rr = app.relationRegistry;
+    const written = rr && rr.getCameraAnimationParams ? rr.getCameraAnimationParams() : null;
+    if (r === false || (rr && rr.getCameraAnimationParams && !written)) {
+      res.warning = (res.warning ? res.warning + ' ' : '') + 'the camera track was not written; the morphs run without it.';
+    } else {
+      res.camera = { keyframes: kfs.length };
+    }
+  }
+` : ''}${sound ? `  // A sound on each morph (D68's placement, with its MP4-lead nudge).
+  const base = (app.sfxSpec && app.sfxSpec(${S(sound)})) || (app.percussionSpec && app.percussionSpec(${S(sound)}));
+  if (base && app.createSound) {
+    res.sounds = done.map(function (d) { const at = d.at < 0.06 ? 0.06 : d.at; const it = app.createSound(Object.assign({}, base), { startTime: at, duration: base.duration || 0.5 }); return { t: at, itemId: it && it.data && it.data.id }; });
+  } else { res.warning = (res.warning ? res.warning + ' ' : '') + ${S(`no sound placed: ${sound} is not in the catalogue, or this studio cannot place sounds.`)}; }
+` : ''}  return res;
+})();`.trim();
+    }
+    /**
+     * pinepaper_original_character (D66): app.createCharacter and its schema
+     * helpers. The helpers read the SAME table the validator uses, so a model
+     * reads the legal values (describe) before it guesses; a wrong one is
+     * refused by name and nothing is drawn.
+     */
+    generateOriginalCharacter(input) {
+        const S = (v) => JSON.stringify(v);
+        const guard = `if (typeof app.createCharacter !== 'function') { return { success: false, error: 'this studio has no original characters (app.createCharacter) — it predates FxTool D66.' }; }`;
+        switch (input.action) {
+            case 'bases':
+                return `(function() {\n  ${guard}\n  return { success: true, action: 'bases', bases: app.listCharacterBases() };\n})();`;
+            case 'describe':
+                return `(function() {\n  ${guard}\n  return { success: true, action: 'describe', schema: app.describeCharacterVariantSchema(${input.base ? S(input.base) : ''}) };\n})();`;
+            case 'random':
+                return `(function() {\n  ${guard}\n  const r = app.randomCharacterVariant(${S(input.base)}, ${S(input.seed)}${input.fixed ? `, { fixed: ${S(input.fixed)} }` : ''});\n  if (!r || r.ok === false) return { success: false, action: 'random', error: (r && r.errors && r.errors.join('; ')) || 'no variant' };\n  return { success: true, action: 'random', base: ${S(input.base)}, seed: ${S(input.seed)}, variant: r.variant };\n})();`;
+            default: {
+                const spec = { base: input.base, ...(input.variant ? { variant: input.variant } : {}), ...(input.at ? { x: input.at.x, y: input.at.y } : {}),
+                    ...(input.height !== undefined ? { height: input.height } : {}), ...(input.scale !== undefined ? { scale: input.scale } : {}), ...(input.rig !== undefined ? { rig: input.rig } : {}) };
+                return `
+// Original character: create
+(async function() {
+  ${guard}
+  const r = await app.createCharacter(${S(spec)});
+  if (!r || r.ok === false) return { success: false, action: 'create', errors: (r && r.errors) || [], error: (r && r.errors && r.errors.join('; ')) || 'the character was refused' };
+  return { success: true, action: 'create', itemId: r.id, rigId: r.rigId, parts: r.parts, name: r.name, base: r.base, look: r.look, variant: r.variant };
+})();`.trim();
+            }
+        }
+    }
+    /**
+     * pinepaper_look (D64): one look over an item, a subtree or the whole scene
+     * — ids, keys and relations kept, removable pixel for pixel. Every apply
+     * carries the look's own FIDELITY grade, and anything below 'convincing'
+     * says so in the reply, so a weak approximation is never handed over as
+     * the finished style.
+     */
+    generateLook(input) {
+        const S = (v) => JSON.stringify(v);
+        const guard = `if (typeof app.applyLook !== 'function') { return { success: false, error: 'this studio has no looks (app.applyLook) — it predates FxTool D64.' }; }`;
+        const target = S(input.target ?? 'scene');
+        switch (input.action) {
+            case 'list':
+                return `(function() {\n  ${guard}\n  return { success: true, action: 'list', looks: app.listLooks(), note: 'fidelity is the engine grade: native (the medium itself), faithful (close, approximations named), impression (an evocation, not the real style). Describe one before promising it.' };\n})();`;
+            case 'describe':
+                return `(function() {\n  ${guard}\n  const r = app.describeLook(${S(input.look)});\n  if (!r || r.ok === false) return { success: false, action: 'describe', error: (r && r.error) || 'unknown look', known: r && r.known };\n  return { success: true, action: 'describe', fidelity: r.look && r.look.fidelity, approximations: (r.look && r.look.approximations) || [], recipe: r.look, enginePaths: r.enginePaths, sceneOnly: r.sceneOnly };\n})();`;
+            case 'get':
+                return `(function() {\n  ${guard}\n  return { success: true, action: 'get', target: ${target}, look: app.getLook(${target}) || null };\n})();`;
+            case 'remove':
+                return `
+// Look: remove (restores what was there)
+(async function() {
+  ${guard}
+  const r = await app.removeLook(${target});
+  if (!r || r.ok === false) return { success: false, action: 'remove', error: (r && r.error) || 'nothing to remove' };
+  return { success: true, action: 'remove', target: ${target}, removed: r.removed, scene: r.scene };
+})();`.trim();
+            case 'grid':
+                return `
+// Look: a contact sheet of looks over the current scene
+(async function() {
+  ${guard}
+  const r = await app.renderLookGrid(${input.looks ? S(input.looks) : 'undefined'}, ${S({ ...(input.cols ? { cols: input.cols } : {}), ...(input.cellWidth ? { cellWidth: input.cellWidth } : {}), ...(input.t !== undefined ? { t: input.t } : {}) })});
+  if (!r || r.ok === false || !r.dataURL) return { success: false, action: 'grid', error: (r && r.error) || 'the grid did not render' };
+  return { success: true, action: 'grid', data: r.dataURL, mimeType: 'image/png', cells: (r.cells || []).map(function (c) { return { id: c.id, name: c.name, fidelity: c.fidelity }; }), cols: r.cols, rows: r.rows };
+})();`.trim();
+            default: {
+                const opts = input.scope ? { scope: input.scope } : {};
+                return `
+// Look: apply
+(async function() {
+  ${guard}
+  const d = app.describeLook(${S(input.look)});
+  const r = await app.applyLook(${target}, ${S(input.look)}, ${S(opts)});
+  if (!r || r.ok === false) return { success: false, action: 'apply', error: (r && r.error) || 'the look was refused', known: r && r.known };
+  const fidelity = (d && d.look && d.look.fidelity) || (r.look && r.look.fidelity) || null;
+  const res = { success: true, action: 'apply', target: ${target}, look: r.look && (r.look.id || r.look.name), fidelity: fidelity,
+    restyled: r.restyled, texts: r.texts, images: r.images, brushed: r.brushed, keyframes: r.keyframes, filters: r.filters, ids: r.ids,
+    approximations: r.approximations || [], warnings: r.warnings || [] };
+  // The engine's grades: native (the medium itself), faithful (close, with
+  // named approximations), impression (an evocation), custom (an ad-hoc spec).
+  const __approx = (res.approximations && res.approximations.length) ? res.approximations.join('; ') : '';
+  if (fidelity === 'impression') {
+    res.warning = 'this look is an IMPRESSION of the style (the engine\\'s grade)' + (__approx ? ' — it approximates: ' + __approx : '') + '. Present it as an approximation of the style, not the finished style.';
+  } else if (fidelity === 'faithful' && __approx) {
+    res.note = 'a faithful look; what it approximates: ' + __approx + '.';
+  } else if (fidelity === 'custom') {
+    res.note = 'a custom look spec: the engine has no fidelity grade for it.';
+  }
+  return res;
+})();`.trim();
+            }
+        }
+    }
+    /** pinepaper_emitter (D29): create('emitter', spec) / setEmitter(id, patch). */
+    generateEmitter(input) {
+        const S = (v) => JSON.stringify(v);
+        if (input.action === 'set') {
+            return `
+// Emitter: change a spec
+(function() {
+  if (typeof app.setEmitter !== 'function') { return { success: false, error: 'this studio has no emitter item (app.setEmitter) — it predates FxTool D29.' }; }
+  const r = app.setEmitter(${S(input.itemId)}, ${S(input.spec)});
+  if (!r || r.ok === false) { return { success: false, error: (r && r.error) || 'the emitter change was refused' }; }
+  return { success: true, action: 'set', itemId: ${S(input.itemId)}, spec: r.spec };
+})();`.trim();
+        }
+        return `
+// Emitter: create
+(function() {
+  if (typeof app.setEmitter !== 'function') { return { success: false, error: 'this studio has no emitter item (app.setEmitter) — it predates FxTool D29.' }; }
+  const it = app.create('emitter', ${S(input.spec)});
+  // A bad spec comes back null with an emitter-invalid warning; the reason
+  // reaches this reply through the governor's warnings.
+  if (!it) { return { success: false, error: 'the emitter spec was refused' }; }
+  const id = it.data && (it.data.registryId || it.data.id);
+  if (!id) { return { success: false, error: 'the emitter was made but not registered — no usable id' }; }
+  return { success: true, action: 'create', itemId: id };
+})();`.trim();
+    }
+    /** pinepaper_render_hook (D29): drawing saved as source, re-installed on load. */
+    generateRenderHook(input) {
+        const S = (v) => JSON.stringify(v);
+        const guard = `if (typeof app.registerRenderHook !== 'function') { return { success: false, error: 'this studio has no saved render hooks (app.registerRenderHook) — it predates FxTool D29.' }; }`;
+        if (input.action === 'list') {
+            return `(function() {\n  ${guard}\n  return { success: true, action: 'list', hooks: app.listRenderHooks() };\n})();`;
+        }
+        if (input.action === 'unregister') {
+            return `(function() {\n  ${guard}\n  const had = app.unregisterRenderHook(${S(input.id)});\n  if (!had) return { success: false, error: 'no render hook ' + ${S(input.id)} };\n  return { success: true, action: 'unregister', id: ${S(input.id)} };\n})();`;
+        }
+        const spec = { id: input.id, source: input.source, ...(input.layer ? { layer: input.layer } : {}), ...(input.deterministic !== undefined ? { deterministic: input.deterministic } : {}), ...(input.seed !== undefined ? { seed: input.seed } : {}) };
+        return `
+// Render hook: register (saved as source)
+(function() {
+  ${guard}
+  const r = app.registerRenderHook(${S(spec)});
+  if (!r || r.ok === false) { return { success: false, error: (r && r.error) || 'the render hook was refused' }; }
+  return { success: true, action: 'register', id: r.id, layer: r.layer, deterministic: r.deterministic, seed: r.seed };
+})();`.trim();
+    }
+    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 +11638,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 } : {}) };
   }
-  return { success: true, action: 'apply', medium: r.medium || ${S(input.medium)}, fidelity: r.fidelity, itemId: r.id, ...(r.note ? { note: r.note } : {}) };
+  // 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.filter ? { filter: r.filter } : {}), ...(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 +11923,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 +12079,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 +12119,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 +12136,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 +12192,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 +12374,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 +12484,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 +12512,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();
     }
     /**
@@ -11378,7 +12585,14 @@ ${needWorld}
      */
     generateStory(input) {
         const S = (v) => JSON.stringify(v);
-        const opts = S(input.options ?? {});
+        // nav decides the story's FORM (D109): 'scenes' = a scene chain (video),
+        // 'panels' = tabs (widget). storyFromText reads options.nav; a spec carries
+        // its own nav, which a top-level nav fills in when the spec has none.
+        const opts = S({ ...(input.options ?? {}), ...(input.nav ? { nav: input.nav } : {}) });
+        const spec = input.spec && input.nav && input.spec.nav === undefined ? { ...input.spec, nav: input.nav } : input.spec;
+        const cuts = input.nav === 'scenes'
+            ? `\n  // The video form's cut times (s), for checking the edit.\n  try { if (app.sceneManager && app.sceneManager.getChainCuts) __out.cuts = app.sceneManager.getChainCuts(); } catch (_) {}`
+            : '';
         switch (input.action) {
             case 'distill':
                 return `
@@ -11404,16 +12618,18 @@ ${needWorld}
   // fine in-page. Not a cycle; JSON.stringify succeeded on this the whole time.
   // The groups have to stay for in-page callers, so the wrapper takes what
   // travels: the spec, the ids, the count.
-  return { success: true, spec: r.spec, partIds: r.partIds, partCount: r.partCount, beats: r.beats };
+  const __out = { success: true, nav: (r.spec && r.spec.nav) || ${S(input.nav ?? 'panels')}, spec: r.spec, partIds: r.partIds, partCount: r.partCount, beats: r.beats };${cuts}
+  return __out;
 })();`.trim();
             case 'apply_spec':
                 return `
 // Story: assemble a spec you already have
 (async function() {
   if (typeof app.applyStorySpec !== 'function') { return { success: false, error: 'app.applyStorySpec unavailable — update FxTool' }; }
-  const r = await app.applyStorySpec(${S(input.spec)}, ${opts});
+  const r = await app.applyStorySpec(${S(spec)}, ${opts});
   if (!r || r.ok === false) { return { success: false, error: (r && (r.reason || r.error)) || 'the spec did not assemble' }; }
-  return { success: true, ...r };
+  const __out = { success: true, ...r };${cuts}
+  return __out;
 })();`.trim();
             case 'plan_book':
                 return `
@@ -11448,9 +12664,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 +12680,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 +12707,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 +12772,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 +12796,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 +12961,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 +13052,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 +13407,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 };`);
@@ -12380,7 +13648,7 @@ ${guard('unlockAllItems')}${pass('app.unlockAllItems()')}
     generateEvent(input) {
         if (input.action === 'create') {
             const nameJson = JSON.stringify(input.name);
-            const optsJson = JSON.stringify({ payloadType: input.payloadType, x: input.x, y: input.y });
+            const optsJson = JSON.stringify({ payloadType: input.payloadType, x: input.x, y: input.y, ...(input.at !== undefined ? { at: input.at } : {}) });
             return `
 // Create event: ${input.name}
 (function() {
@@ -12390,7 +13658,7 @@ ${guard('unlockAllItems')}${pass('app.unlockAllItems()')}
   const eventId = app.createEvent(${nameJson}, ${optsJson});
   if (!eventId) { return { success: false, error: 'Event creation failed' }; }
   if (app.historyManager) app.historyManager.saveState();
-  return { success: true, action: 'create', eventId };
+  return { success: true, action: 'create', eventId${input.at !== undefined ? `, at: ${JSON.stringify(input.at)}` : ''} };
 })();`.trim();
         }
         // pulse — a runtime fire, not a scene edit (no history save)