@pinepaper.studio/mcp-server 1.6.19 → 1.6.21

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
@@ -73,9 +74,11 @@ function normalizeGradientSpec(v, key) {
  */
 function generateGradientCode(gradient, itemVarName, position, propertyName = 'fillColor') {
     const { type, stops, origin, destination } = gradient;
-    // Calculate default origin/destination based on item position
-    const defaultOrigin = origin || [position.x - 50, position.y - 50];
-    const defaultDestination = destination || [position.x + 50, position.y + 50];
+    // Calculate default origin/destination based on item position.
+    // For radial gradients, origin defaults to the item center (position.x, position.y),
+    // not an offset (-50, -50), and destination to the radius edge (B88).
+    const defaultOrigin = origin || (type === 'radial' ? [position.x, position.y] : [position.x - 50, position.y - 50]);
+    const defaultDestination = destination || (type === 'radial' ? [position.x + 50, position.y] : [position.x + 50, position.y + 50]);
     const stopsCode = stops.map(s => `['${s.color}', ${s.offset}]`).join(', ');
     return `
 ${itemVarName}.${propertyName} = {
@@ -129,6 +132,18 @@ function generateCreateItemCode(itemType, position, properties, dataFlags, posit
             properties = { ...properties, [key]: g.gradient };
         }
     }
+    // Aliases for text items: text -> content (B66), textAlign / align -> justification (B89)
+    if (properties.content === undefined && properties.text !== undefined) {
+        properties = { ...properties, content: properties.text };
+    }
+    if (properties.justification === undefined) {
+        if (properties.textAlign !== undefined) {
+            properties = { ...properties, justification: properties.textAlign };
+        }
+        else if (properties.align !== undefined) {
+            properties = { ...properties, justification: properties.align };
+        }
+    }
     // Extract special properties that need separate handling
     const { color, fillColor, strokeColor, shadowColor, shadowBlur, shadowOffset, blendMode, opacity, contentType, contentFormat, countdownTarget, countdownEndText, ...baseProperties } = properties;
     // A PATH KEEPS ITS OWN COORDINATES WHEN NO POSITION WAS ASKED FOR (round 9
@@ -193,18 +208,15 @@ function generateCreateItemCode(itemType, position, properties, dataFlags, posit
     if (strokeColor && !isGradient(strokeColor)) {
         params.strokeColor = strokeColor;
     }
-    // RENDER-TIME SURFACES DEGRADE, THEY DO NOT FAIL.
-    //
-    // `shader` and `field` are drawn per pixel by the cloud rasterizer from the
-    // scene document; the browser engine has no such item type and answers
-    // `create('shader')` with "unknown type — nothing was created". Emitting that
-    // call would hand every local user a silent hole where their backdrop was.
+    // RENDER-TIME SURFACES ARE A TAGGED PLATE.
     //
-    // So locally they become a plate: a rectangle carrying the same id, position,
-    // size and colour, which keeps the composition readable and the item
-    // addressable by every later call. The scene document still says `shader`, so
-    // a cloud render draws the real surface. The divergence is declared here
-    // rather than discovered in a frame.
+    // `shader` and `field` are drawn per pixel from the scene document. What is
+    // created is a rectangle carrying the id, position, size and colour, tagged
+    // data.renderAs + data.renderParams. The studio adopts that plate and draws
+    // the surface over it in the live view, stills and every export (FxTool D19);
+    // the cloud rasterizer draws it from the same tags. A studio too old to adopt
+    // it still shows a readable, addressable plate rather than a hole, which is
+    // why this does not call create('shader').
     if (itemType === 'shader' || itemType === 'field') {
         const plate = {
             x: position.x,
@@ -218,8 +230,7 @@ function generateCreateItemCode(itemType, position, properties, dataFlags, posit
         if (params.opacity != null)
             plate.opacity = params.opacity;
         return `
-// ${itemType} — a render-time surface. Drawn per pixel by the cloud renderer;
-// stood in for locally by a flat plate so the layout still reads.
+// ${itemType} — a render-time surface: a plate tagged with what to draw over it.
 const item = app.create('rectangle', ${JSON.stringify(plate, null, 2)});
 if (item && item.data) { item.data.renderAs = ${JSON.stringify(itemType)}; item.data.renderParams = ${JSON.stringify(params)}; }
 // The snippet's value is its last statement's, which was the assignment above:
@@ -228,10 +239,8 @@ if (item && item.data) { item.data.renderAs = ${JSON.stringify(itemType)}; item.
 // \`}\` as a statement end, so a bare ternary of object literals is not wrapped
 // and its value is lost.
 ((item && item.data)
-  ? { itemId: item.data.registryId, type: ${JSON.stringify(itemType)}, position: { x: ${position.x}, y: ${position.y} },
-      localStandIn: true,
-      note: 'drawn here as a flat plate; the ${itemType} itself appears only in a cloud render. A local export shows the plate.' }
-  : { success: false, error: 'the stand-in plate for this ${itemType} was not created.' });`;
+  ? { itemId: item.data.registryId, type: ${JSON.stringify(itemType)}, position: { x: ${position.x}, y: ${position.y} } }
+  : { success: false, error: 'the plate for this ${itemType} was not created.' });`;
     }
     // AN UNKNOWN ANCHOR IS INVISIBLE OVER MCP.
     //
@@ -333,9 +342,14 @@ const item = app.create('${itemType}', ${JSON.stringify(params, null, 2)});`;
     if (textFit)
         code += `\nlet __textFit = null;${emitTextFit('item', textFit, JSON.stringify(anchorHold(properties.anchor ?? properties.origin) ?? null))}`;
     // After opacity, so the "on" level of the lifetime is the item's own.
-    const hasLifetime = properties.bornAt !== undefined || properties.ttl !== undefined;
+    // A numeric `lifetime` is the studio's alias of ttl on create (FxTool B125;
+    // emitters, where it means each particle's life, are not made here).
+    // Resolved here too: with bornAt beside it, passing ttl undefined would reset
+    // the item to "until the end" after create() had set the alias.
+    const createTtl = properties.ttl ?? (typeof properties.lifetime === 'number' ? properties.lifetime : undefined);
+    const hasLifetime = properties.bornAt !== undefined || createTtl !== undefined;
     if (hasLifetime) {
-        code += `\nlet __lifetime = null;${emitLifetime('item', properties.bornAt, properties.ttl)}`;
+        code += `\nlet __lifetime = null;${emitLifetime('item', properties.bornAt, createTtl)}`;
     }
     // Ensure item is visible above backgrounds/generators
     code += `\nif (item.bringToFront) item.bringToFront();`;
@@ -402,9 +416,8 @@ const CREATE_KNOWN_KEYS = new Set([
     // withRadiusAxes, gradients / shadow / blend / opacity emitted here, and
     // setDynamicContent for text.
     'radiusX', 'radiusY', 'contentType', 'contentFormat', 'countdownTarget', 'countdownEndText',
-    // Lifetimes. The editor's create() does not read them, but they are
-    // documented on ANY item and the scene renderer schedules by them — calling
-    // them "no effect" would steer a caller off the only way to cut between shots.
+    // Lifetimes, on ANY item: this generator applies them through app.setLifetime
+    // (emitLifetime), whatever create() itself reads.
     'bornAt', 'ttl',
 ]);
 /**
@@ -625,7 +638,25 @@ if (typeof app.fitText === 'function') {
  *
  * lineHeight is the CSS habit: <= 4 is a multiple of fontSize, above that px.
  */
-const TEXT_STYLE_KEYS = ['fontWeight', 'fontStyle', 'leading', 'lineHeight'];
+/**
+ * THE FRAME A MOTION IS AUTHORED AGAINST.
+ *
+ * app.exportFrameRect() is the export frame. On a bounded canvas that is the
+ * artboard. On an UNBOUNDED canvas (prod's default) it is the region the items
+ * currently occupy, padded: with one actor on the canvas it is the actor
+ * itself, so choreograph called every move "off screen" and the morph camera
+ * framed against the hero alone. An unbounded canvas has no fixed frame, so
+ * motion is checked against its nominal artboard instead, flagged unbounded so
+ * the caller can say so.
+ */
+function authoringFrameJs(name) {
+    return `const ${name} = (function() {
+    const cs = app.getCanvasSize && app.getCanvasSize();
+    if (cs && cs.unbounded && cs.width > 0 && cs.height > 0) return { x: 0, y: 0, width: cs.width, height: cs.height, unbounded: true };
+    return (typeof app.exportFrameRect === 'function' && app.exportFrameRect()) || cs || { width: 1920, height: 1080 };
+  })();`;
+}
+const TEXT_STYLE_KEYS = ['fontWeight', 'fontStyle', 'leading', 'lineHeight', 'textAlign', 'align', 'text'];
 function emitTextStyle(itemExpr, props) {
     const weight = props.fontWeight;
     const italic = props.fontStyle === 'italic' || props.fontStyle === 'oblique';
@@ -710,10 +741,11 @@ function resolveChartFields(chartType, data, options) {
  * same way for the same reason. A 1-microsecond tolerance makes a hand-off at
  * an exact frame time show exactly one item.
  *
- * Runtime-only: a scene saved and reopened keeps data.bornAt / ttl (the cloud
- * renderer reads those) but not the callback, until the studio reads the
- * fields itself — the result says so. Lifetimes applied the old way are
- * migrated: their tagged opacity keys are removed.
+ * The callback is the FALLBACK, for a studio without app.setLifetime: it is
+ * not saved, so a reopened scene keeps data.bornAt / ttl (the cloud renderer
+ * reads those) but not the hiding. app.setLifetime persists; the result's
+ * lifetime field says which ran. Lifetimes applied the old way are migrated:
+ * their tagged opacity keys are removed.
  */
 function emitLifetime(itemExpr, bornAt, ttl) {
     const b = Number(bornAt);
@@ -792,6 +824,27 @@ function emitLifetime(itemExpr, bornAt, ttl) {
  */
 function generateModifyItemCode(itemId, properties, dataFlags) {
     const { contentType, contentFormat, countdownTarget, countdownEndText, ...restProperties } = properties;
+    // Aliases for text items: text -> content (B66), textAlign / align -> justification (B89).
+    // A key consumed here was applied, so the unread-key report below must not
+    // call it "no effect".
+    const aliased = new Set();
+    if (restProperties.justification === undefined) {
+        if (restProperties.textAlign !== undefined) {
+            restProperties.justification = restProperties.textAlign;
+            delete restProperties.textAlign;
+            aliased.add('textAlign');
+        }
+        else if (restProperties.align !== undefined) {
+            restProperties.justification = restProperties.align;
+            delete restProperties.align;
+            aliased.add('align');
+        }
+    }
+    if (restProperties.content === undefined && restProperties.text !== undefined) {
+        restProperties.content = restProperties.text;
+        delete restProperties.text;
+        aliased.add('text');
+    }
     // A new fit box is applied here (emitTextFit, with the hold carried over),
     // not by modifyItem: the engine's modify fits it with no hold, overwriting
     // the one this reads back. fit: null still goes through — that is the
@@ -927,7 +980,7 @@ if (_flagged && _flagged.item && _flagged.item.data) Object.assign(_flagged.item
     // AN UNREAD KEY HAD NO EFFECT, AND THE CALL SAID SUCCESS. {scaling: 8} on a
     // raster answered success and left it 16 px; the engine reads `scale`. Same
     // report create_item gives, against the engine's modify path (generated).
-    const modIgnored = Object.keys(properties).filter((k) => !MODIFY_KNOWN_KEYS.has(k));
+    const modIgnored = Object.keys(properties).filter((k) => !MODIFY_KNOWN_KEYS.has(k) && !aliased.has(k));
     const modWarning = modIgnored.length === 0 ? '' : `, ignoredProperties: ${JSON.stringify(modIgnored)}, warning: ${JSON.stringify(`${modIgnored.join(', ')} ${modIgnored.length > 1 ? 'are' : 'is'} not read when modifying an item, so ${modIgnored.length > 1 ? 'they had' : 'it had'} no effect.`
         + modIgnored.filter((k) => MODIFY_DID_YOU_MEAN[k]).map((k) => ` Did you mean ${MODIFY_DID_YOU_MEAN[k]} (not ${k})?`).join(''))}`;
     code += `
@@ -1224,10 +1277,22 @@ app.animate(item, {
  */
 function normalizeKeyframePositions(keyframes) {
     return (keyframes || []).map((kf) => {
-        const props = kf?.properties;
-        const p = props?.position;
-        if (p && !Array.isArray(p) && typeof p === 'object' && 'x' in p && 'y' in p) {
-            return { ...kf, properties: { ...props, position: [p.x, p.y] } };
+        const rawProps = kf?.properties;
+        const props = rawProps && typeof rawProps === 'object' ? rawProps : {};
+        const p = props.position ?? kf?.position;
+        if (p) {
+            if (Array.isArray(p) && p.length >= 2) {
+                return { ...kf, properties: { ...props, position: [p[0], p[1]] } };
+            }
+            if (typeof p === 'object' && 'x' in p && 'y' in p) {
+                return { ...kf, properties: { ...props, position: [p.x, p.y] } };
+            }
+        }
+        if (kf?.x !== undefined && kf?.y !== undefined && props.position === undefined && props.x === undefined && props.y === undefined) {
+            return { ...kf, properties: { ...props, position: [kf.x, kf.y] } };
+        }
+        if (rawProps === undefined && Object.keys(props).length > 0) {
+            return { ...kf, properties: props };
         }
         return kf;
     });
@@ -1250,9 +1315,14 @@ function normalizeKeyframePositions(keyframes) {
  * "item_7 is not on the canvas" is actionable, silence is not.
  */
 function requireItem(itemId, what) {
+    const isRef = typeof itemId === 'string' && itemId.startsWith('$');
+    const targetExpr = isRef
+        ? `((typeof window !== 'undefined' && window.__pinepaper_batch_item_ids && window.__pinepaper_batch_item_ids[${itemId.substring(1)}]) || '${itemId}')`
+        : `'${itemId}'`;
     return `
-const _target = (app.getItemById && app.getItemById(${JSON.stringify(itemId)}))
-  || (app.itemRegistry && app.itemRegistry.get && app.itemRegistry.get(${JSON.stringify(itemId)}));
+const _targetId = ${targetExpr};
+const _target = (app.getItemById && app.getItemById(_targetId))
+  || (app.itemRegistry && app.itemRegistry.get && app.itemRegistry.get(_targetId));
 if (!_target) {
   return { success: false, error: ${JSON.stringify(itemId)} + ' is not on the canvas, so ' + ${JSON.stringify(what)} + ' would have done nothing. Check the id with pinepaper_get_items — create returns the registry id, not the Paper id.' };
 }`.trim();
@@ -1286,7 +1356,7 @@ function generateKeyframeAnimateCode(itemId, keyframes, duration, loop = false,
     // is the feature check: a key it names for audio passes through, anything
     // else on an audio item is still refused (prod, until that build ships).
     const audioLevelGuard = levelKeys.length === 0 ? '' : `
-  const __ae = app.itemRegistry && app.itemRegistry.get('${itemId}');
+  const __ae = app.itemRegistry && app.itemRegistry.get(_targetId);
   let __audioKeyed = [];
   try {
     const __l = typeof app.listAnimatableProperties === 'function' ? app.listAnimatableProperties() : null;
@@ -1294,7 +1364,7 @@ function generateKeyframeAnimateCode(itemId, keyframes, duration, loop = false,
   } catch (_) { /* treat as unsupported */ }
   const __unsupported = ${JSON.stringify(levelKeys)}.filter(function(k) { return __audioKeyed.indexOf(k) === -1; });
   if (__ae && __ae.type === 'audio' && __unsupported.length) {
-    return { success: false, itemId: '${itemId}', error: __unsupported.join(', ') + ' cannot be keyframed on an audio item in this studio: it mixes each audio clip at one fixed level, so a fade would be accepted and not heard. Nothing was added. '
+    return { success: false, itemId: _targetId, error: __unsupported.join(', ') + ' cannot be keyframed on an audio item in this studio: it mixes each audio clip at one fixed level, so a fade would be accepted and not heard. Nothing was added. '
       + (__audioKeyed.length ? 'Keyable on audio here: ' + __audioKeyed.join(', ') + '. ' : '')
       + 'Set a static level with pinepaper_modify_item {audioGain: 0..1}.' };
   }`;
@@ -1327,6 +1397,10 @@ function generateKeyframeAnimateCode(itemId, keyframes, duration, loop = false,
     const easingNote = first?.easing && first.easing !== 'linear'
         ? `, note: ${JSON.stringify(`easing '${first.easing}' is on the first keyframe, where it has no effect: easing shapes the segment ARRIVING at a keyframe. Put it on the keyframe you are moving to.`)}`
         : '';
+    const unsupportedKeys = [...new Set(keyframes.flatMap((k) => Object.keys(k.properties ?? {})))]
+        .filter((k) => k === 'letterSpacing');
+    const letterSpacingWarning = unsupportedKeys.length === 0 ? '' : `, ignoredProperties: ${JSON.stringify(unsupportedKeys)}, warning: ${JSON.stringify(`${unsupportedKeys.join(', ')} is not an animatable property in this engine (app.listAnimatableProperties does not list it), so it had no effect. Set a fixed value with pinepaper_modify_item, or animate fontSize or scaleX.`)}`;
+    const addAnimTarget = itemId.startsWith('$') ? '_targetId' : `'${itemId}'`;
     return `
 // Apply keyframe animation to ${itemId}
 (function() {
@@ -1336,7 +1410,7 @@ function generateKeyframeAnimateCode(itemId, keyframes, duration, loop = false,
   // merge support — an older engine takes the option and replaces anyway.
   const __ki = _target && (_target.item || _target);
   const __prev = (__ki && __ki.data && Array.isArray(__ki.data.keyframes)) ? __ki.data.keyframes.map(function(k) { return k && k.time; }) : [];
-  app.addAnimation('${itemId}', ${keyframesJson}, ${JSON.stringify(opts)});
+  app.addAnimation(${addAnimTarget}, ${keyframesJson}, ${JSON.stringify(opts)});
   const __now = (__ki && __ki.data && Array.isArray(__ki.data.keyframes)) ? __ki.data.keyframes.map(function(k) { return k && k.time; }) : [];
   const __kept = __prev.every(function(t) { return __now.indexOf(t) >= 0; });${append ? `
   // Property gaps across the merged track (the same check a single call makes
@@ -1349,7 +1423,7 @@ function generateKeyframeAnimateCode(itemId, keyframes, duration, loop = false,
       ? { appended: true, previousKeys: __prev.length, keys: __now.length }
       : { appended: false, replaced: true, previousKeys: __prev.length, warning: 'append was asked for, but this studio replaced the existing track (' + __prev.length + ' key(s)) instead of adding to it: it has no merge mode. Put every key in one keyframe_animate call.' })`
         : `{ replaced: true, previousKeys: __prev.length, note: 'the item already had a keyframe track (' + __prev.length + ' key(s)); this call replaced it. To add keys to it instead, pass append: true.' }`};
-  return { success: true, itemId: '${itemId}', duration: ${calculatedDuration}, loop: ${loop}${append ? ', append: true' : ''}, ...(__track ? { track: __track } : {})${append ? `, ...(__gaps.length ? { propertyGaps: __gaps.slice(0, 10), gapWarning: __gaps.length + ' key(s) of the merged track leave out a property other keys animate (' + __gaps.reduce(function(a, g) { g.missing.forEach(function(p) { if (a.indexOf(p) < 0) a.push(p); }); return a; }, []).join(', ') + '). The engine can break that property at such a key; give each key the full set — hold a value by repeating it.' } : {})` : ''}${timeOffset !== undefined ? `, timeOffset: ${timeOffset}` : ''}${clipInPoint !== undefined ? `, clipInPoint: ${clipInPoint}` : ''}${clipOutPoint !== undefined ? `, clipOutPoint: ${clipOutPoint}` : ''}${easingNote}${loopNote}${gapNote} };
+  return { success: true, itemId: ${addAnimTarget}, duration: ${calculatedDuration}, loop: ${loop}${append ? ', append: true' : ''}, ...(__track ? { track: __track } : {})${append ? `, ...(__gaps.length ? { propertyGaps: __gaps.slice(0, 10), gapWarning: __gaps.length + ' key(s) of the merged track leave out a property other keys animate (' + __gaps.reduce(function(a, g) { g.missing.forEach(function(p) { if (a.indexOf(p) < 0) a.push(p); }); return a; }, []).join(', ') + '). The engine can break that property at such a key; give each key the full set — hold a value by repeating it.' } : {})` : ''}${timeOffset !== undefined ? `, timeOffset: ${timeOffset}` : ''}${clipInPoint !== undefined ? `, clipInPoint: ${clipInPoint}` : ''}${clipOutPoint !== undefined ? `, clipOutPoint: ${clipOutPoint}` : ''}${easingNote}${loopNote}${gapNote}${letterSpacingWarning} };
 })();
 `.trim();
 }
@@ -1895,6 +1969,54 @@ export function isCoordinateBuilt(itemType, props) {
             return false;
     }
 }
+/** A keyframe's properties, with the flat spellings (x, opacity, ...) lifted in beside `properties`. */
+function extractKfPropsMap(kf) {
+    const props = (kf && kf.properties && typeof kf.properties === 'object') ? { ...kf.properties } : {};
+    if (kf) {
+        const flat = kf;
+        for (const key of ['x', 'y', 'opacity', 'scale', 'scaleX', 'scaleY', 'rotation', 'position', 'fill', 'fillColor', 'stroke', 'strokeColor', 'width', 'height', 'radius', 'lineHeight']) {
+            if (flat[key] !== undefined && props[key] === undefined)
+                props[key] = flat[key];
+        }
+    }
+    return props;
+}
+/**
+ * One op's track sampled at time t: held before its first key and after its last, linear in between
+ * (numbers and equal-length number arrays; anything else holds until the next key is reached).
+ */
+function sampleOpTrack(kfs, t) {
+    if (!kfs.length)
+        return {};
+    if (kfs.length === 1 || t <= kfs[0].time)
+        return extractKfPropsMap(kfs[0]);
+    if (t >= kfs[kfs.length - 1].time)
+        return extractKfPropsMap(kfs[kfs.length - 1]);
+    let i = 0;
+    for (let j = 0; j < kfs.length - 1; j++) {
+        if (t >= kfs[j].time && t <= kfs[j + 1].time) {
+            i = j;
+            break;
+        }
+    }
+    const k0 = kfs[i], k1 = kfs[i + 1];
+    const p0 = extractKfPropsMap(k0), p1 = extractKfPropsMap(k1);
+    const f = Math.max(0, Math.min(1, (t - k0.time) / (k1.time - k0.time || 1)));
+    const out = {};
+    for (const k of new Set([...Object.keys(p0), ...Object.keys(p1)])) {
+        const v0 = p0[k], v1 = p1[k];
+        if (typeof v0 === 'number' && typeof v1 === 'number') {
+            out[k] = v0 + (v1 - v0) * f;
+        }
+        else if (Array.isArray(v0) && Array.isArray(v1) && v0.length === v1.length && typeof v0[0] === 'number') {
+            out[k] = v0.map((n, idx) => Number(n) + (Number(v1[idx]) - Number(n)) * f);
+        }
+        else {
+            out[k] = (v1 !== undefined && f >= 1) ? v1 : (v0 !== undefined ? v0 : v1);
+        }
+    }
+    return out;
+}
 /**
  * app.addAnimation() REPLACES data.keyframes wholesale, so two
  * keyframe_animate ops targeting one item meant the first track was silently
@@ -1922,28 +2044,34 @@ export function planKeyframeMerges(operations) {
         if (indices.length < 2)
             continue;
         const first = indices[0];
-        // Union keyframes by time; later ops shallow-merge over earlier ones.
-        const byTime = new Map();
         let duration = 0;
         let loop = false;
         for (const i of indices) {
             const op = operations[i];
-            for (const kf of op.keyframes || []) {
-                const prev = byTime.get(kf.time);
-                byTime.set(kf.time, {
-                    time: kf.time,
-                    properties: { ...(prev?.properties || {}), ...(kf.properties || {}) },
-                    ...((kf.easing ?? prev?.easing) !== undefined ? { easing: kf.easing ?? prev?.easing } : {}),
-                });
-            }
             const opMax = op.keyframes?.length ? Math.max(...op.keyframes.map(k => k.time)) : 0;
             duration = Math.max(duration, op.duration || opMax);
             loop = loop || op.loop === true;
             if (i !== first)
                 plan.foldedInto.set(i, first);
         }
+        // B120: at every key time of ANY op, each op contributes its own track SAMPLED there (held outside
+        // its keys, interpolated between them), later ops winning. A plain union by timestamp left a key
+        // holding only one op's properties, so the engine broke the other op's channel at that key.
+        const allTimes = [...new Set(indices.flatMap((i) => (operations[i].keyframes || []).map((k) => k.time)))].sort((a, b) => a - b);
+        const mergedKeyframes = allTimes.map((t) => {
+            let properties = {};
+            let easing;
+            for (const i of indices) {
+                const kfs = operations[i].keyframes || [];
+                properties = { ...properties, ...sampleOpTrack(kfs, t) };
+                const exact = kfs.find((k) => k.time === t);
+                if (exact && exact.easing !== undefined)
+                    easing = exact.easing;
+            }
+            return { time: t, properties, ...(easing !== undefined ? { easing } : {}) };
+        });
         plan.merged.set(first, {
-            keyframes: [...byTime.values()].sort((a, b) => a.time - b.time),
+            keyframes: mergedKeyframes,
             duration: duration || 5,
             loop,
         });
@@ -1955,6 +2083,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()'))
@@ -2398,17 +2628,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);
+        }
+        // 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 generateModifyItemCode(validated.itemId, validated.properties, validated.data);
+        return withItemSetters(generateModifyItemCode(validated.itemId, props, validated.data), setters, idExpr);
     }
     /**
      * Generate code for deleting an item
@@ -2452,7 +2692,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
@@ -2478,7 +2726,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
@@ -2726,6 +2986,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 || [],
@@ -3596,6 +3865,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
@@ -3815,8 +4086,19 @@ throw new Error('Unknown diagram mode action: ${action}');
       || (typeof v.reason === 'string' && v.reason)
       || 'the operation reported failure without naming a reason';
   };
-  const results = [];
+  // $N is the Nth item THIS batch created (the documented contract). The
+  // previous batch's ids are kept only to name the right id when a $N reaches
+  // past what this batch has made: picking it silently shifted every $N in a
+  // batch that also creates (B115 follow-up).
   const itemIds = [];
+  const __prevBatchIds = ((typeof window !== 'undefined' && window.__pinepaper_batch_item_ids) || []).slice();
+  const __ref = function (n) {
+    if (itemIds[n] !== undefined) return itemIds[n];
+    const prev = __prevBatchIds[n];
+    throw new Error('$' + n + ' is the item number ' + n + ' THIS batch created, and it has created ' + itemIds.length + ' so far.'
+      + (prev ? ' In the previous batch $' + n + ' was ' + prev + ' — pass that id instead.' : ' Put the create ops first, or pass the item id.'));
+  };
+  const results = [];
   let success = true;
 
   try {
@@ -3872,11 +4154,19 @@ throw new Error('Unknown diagram mode action: ${action}');
     // 60-op batch should not have to scan sixty entries to learn that op 41
     // could not find a preset.
     const _failed = results.filter((r) => !r.success);
+    // A batch that created nothing keeps the previous batch's ids on record.
+    if (typeof window !== 'undefined' && itemIds.length) {
+      window.__pinepaper_batch_item_ids = itemIds;
+    }
     return { success, itemIds, results, operationCount: ${operations.length},
       failedCount: _failed.length,
       ...(_failed.length ? { error: _failed.map((r) => 'op ' + r.index + ': ' + r.error).join('; ') } : {}),
       canvasSize: { width: _cs.width || 800, height: _cs.height || 600 } };
   } catch (e) {
+    // A batch that created nothing keeps the previous batch's ids on record.
+    if (typeof window !== 'undefined' && itemIds.length) {
+      window.__pinepaper_batch_item_ids = itemIds;
+    }
     const _cs = app.getCanvasSize ? app.getCanvasSize() : { width: 800, height: 600 };
     return { success: false, error: e.message, itemIds, results, operationCount: ${operations.length}, canvasSize: { width: _cs.width || 800, height: _cs.height || 600 } };
   }
@@ -3899,13 +4189,47 @@ throw new Error('Unknown diagram mode action: ${action}');
                 // for a 12 s MP4 (round 8 DD, 1.67). It now runs generateCreateItemCode,
                 // 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 anyOp = op;
+                let pos = op.position;
+                if (!pos && (typeof anyOp.x === 'number' || typeof anyOp.y === 'number')) {
+                    pos = { x: anyOp.x ?? 400, y: anyOp.y ?? 300 };
+                }
+                if (!pos) {
+                    pos = { x: 400, y: 300 };
+                }
+                const opProps = { ...(op.properties || {}) };
+                const batchKeys = new Set([
+                    'type', 'itemType', 'position', 'properties', 'screenSpace', 'stepTiming', 'counter',
+                    'itemId', 'itemIds', 'groupName', 'animationType', 'animationOptions',
+                    'sourceId', 'targetId', 'relationType', 'relationOptions',
+                    'backgroundColor', 'generatorName', 'generatorParams', 'generatorRegion',
+                    'width', 'height', 'preset', 'keyframes', 'duration', 'loop',
+                    'maskPreset', 'maskType', 'maskOptions', 'effectType', 'effectParams',
+                    'action', 'time', 'append'
+                ]);
+                for (const [k, v] of Object.entries(anyOp)) {
+                    if (!batchKeys.has(k) && v !== undefined && opProps[k] === undefined) {
+                        opProps[k] = v;
+                    }
+                }
+                if (opProps.content === undefined && opProps.text !== undefined) {
+                    opProps.content = opProps.text;
+                }
+                if (opProps.fillColor === undefined && opProps.color !== undefined) {
+                    opProps.fillColor = opProps.color;
+                }
+                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 || typeof anyOp.x === 'number' || typeof anyOp.y === 'number'), 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
@@ -3913,7 +4237,7 @@ ${returning}
                 // caller explicitly asked for a position. Guarded on an explicit
                 // op.position so absolute-coordinate geometry (the common case, which
                 // passes no position) is never snapped to the injected default.
-                if (op.position && isCoordinateBuilt(op.itemType, createProps)) {
+                if ((op.position || typeof anyOp.x === 'number' || typeof anyOp.y === 'number') && isCoordinateBuilt(op.itemType, createProps)) {
                     createCode += `
 // create() builds this item type from its own coordinates and ignores
 // params.position — apply the caller's explicit position after the fact.
@@ -3927,7 +4251,7 @@ return __created;
             }
             case 'modify': {
                 const itemRef = op.itemId?.startsWith('$')
-                    ? `itemIds[${op.itemId.substring(1)}]`
+                    ? `__ref(${op.itemId.substring(1)})`
                     : `'${op.itemId}'`;
                 // modify_item's own emitter, as create is create_item's (see above):
                 // the batch's modifyItem call missed text styles, font loading, audio
@@ -3948,7 +4272,7 @@ return __r;
             }
             case 'animate':
                 const animItemRef = op.itemId?.startsWith('$')
-                    ? `itemIds[${op.itemId.substring(1)}]`
+                    ? `__ref(${op.itemId.substring(1)})`
                     : `'${op.itemId}'`;
                 const animOpts = JSON.stringify(op.animationOptions || {});
                 return `
@@ -3960,10 +4284,10 @@ return { itemId: targetId, animationType: '${op.animationType}' };
 `;
             case 'relation':
                 const srcRef = op.sourceId?.startsWith('$')
-                    ? `itemIds[${op.sourceId.substring(1)}]`
+                    ? `__ref(${op.sourceId.substring(1)})`
                     : `'${op.sourceId}'`;
                 const tgtRef = op.targetId?.startsWith('$')
-                    ? `itemIds[${op.targetId.substring(1)}]`
+                    ? `__ref(${op.targetId.substring(1)})`
                     : `'${op.targetId}'`;
                 const relOpts = JSON.stringify(op.relationOptions || {});
                 return `
@@ -3978,7 +4302,7 @@ return { relationId, sourceId, targetId, relationType: '${op.relationType}' };
 `;
             case 'delete':
                 const delRef = op.itemId?.startsWith('$')
-                    ? `itemIds[${op.itemId.substring(1)}]`
+                    ? `__ref(${op.itemId.substring(1)})`
                     : `'${op.itemId}'`;
                 return `
 const targetId = ${delRef};
@@ -3990,7 +4314,7 @@ return { itemId: targetId, deleted: true };
 `;
             case 'group': {
                 // Resolve each ref ($N → itemIds[N]; literal → quoted id) into a JS array.
-                const refs = (op.itemIds || []).map((ref) => ref?.startsWith('$') ? `itemIds[${ref.substring(1)}]` : `'${ref}'`);
+                const refs = (op.itemIds || []).map((ref) => ref?.startsWith('$') ? `__ref(${ref.substring(1)})` : `'${ref}'`);
                 const idsArrayExpr = `[${refs.join(', ')}]`;
                 const nameExpr = op.groupName !== undefined ? JSON.stringify(op.groupName) : 'undefined';
                 // Returns { groupId, ... } (no itemId) so it does NOT shift $N indices — like relation.
@@ -4000,7 +4324,7 @@ return (function() {${this.groupCodeBody(idsArrayExpr, nameExpr)}
 `;
             }
             case 'set_background':
-                const bgColor = op.backgroundColor || op.properties?.color || '#000000';
+                const bgColor = op.backgroundColor || op.color || op.properties?.backgroundColor || op.properties?.color || '#000000';
                 return `
 app.setBackgroundColor('${bgColor}');
 return { success: true, backgroundColor: '${bgColor}' };
@@ -4034,28 +4358,54 @@ return { success: true, width: (_cs && _cs.width) || ${w}, height: (_cs && _cs.h
                     return `
 // Keyframes merged into operation ${foldTarget} (same target). A keyframe track
 // is replaced wholesale, so emitting both here would silently drop one.
-return { itemId: ${op.itemId?.startsWith('$') ? `itemIds[${op.itemId.substring(1)}]` : `'${op.itemId}'`}, merged: true, mergedInto: ${foldTarget} };
+return { itemId: ${op.itemId?.startsWith('$') ? `__ref(${op.itemId.substring(1)})` : `'${op.itemId}'`}, merged: true, mergedInto: ${foldTarget} };
 `;
                 }
                 const mergedPayload = mergePlan?.merged.get(index);
-                const kfItemRef = op.itemId?.startsWith('$')
-                    ? `itemIds[${op.itemId.substring(1)}]`
-                    : `'${op.itemId}'`;
-                const kfSource = mergedPayload ? mergedPayload.keyframes : (op.keyframes || []);
+                const rawItemId = String(op.itemId ?? op.id ?? op.properties?.itemId ?? op.properties?.id);
+                const kfItemRef = rawItemId?.startsWith('$')
+                    ? `__ref(${rawItemId.substring(1)})`
+                    : `'${rawItemId}'`;
+                const kfSource = mergedPayload
+                    ? mergedPayload.keyframes
+                    : (op.keyframes || (op.properties && op.properties.keyframes) || (op.params && op.params.keyframes) || []);
                 const kfJson = JSON.stringify(normalizeKeyframePositions(kfSource));
                 const kfDuration = mergedPayload
                     ? mergedPayload.duration
-                    : (op.duration || (op.keyframes?.length ? Math.max(...op.keyframes.map(k => k.time)) : 5));
-                const kfLoop = mergedPayload ? mergedPayload.loop : (op.loop ?? false);
+                    : (op.duration || op.properties?.duration || (kfSource.length ? Math.max(...kfSource.map((k) => Number(k.time) || 0)) : 5));
+                const kfLoop = mergedPayload ? mergedPayload.loop : (op.loop ?? op.properties?.loop ?? false);
+                // Same contract as pinepaper_keyframe_animate: replace unless append.
+                const kfAppend = op.append === true || op.properties?.append === true;
+                // Batch ops are passthrough, so these arrive unvalidated: numbers only, and timeUnits from its enum.
+                const kfExtra = [];
+                for (const key of ['timeOffset', 'clipInPoint', 'clipOutPoint']) {
+                    const v = Number(op[key]);
+                    if (op[key] !== undefined && Number.isFinite(v))
+                        kfExtra.push(`${key}: ${v}`);
+                }
+                const kfUnits = op.timeUnits;
+                if (kfUnits === 'seconds' || kfUnits === 'ms')
+                    kfExtra.push(`timeUnits: '${kfUnits}'`);
+                const kfExtraStr = kfExtra.length > 0 ? `, ${kfExtra.join(', ')}` : '';
+                const kfUnsupported = [...new Set((kfSource || []).flatMap((k) => Object.keys(k.properties ?? {})))]
+                    .filter((k) => k === 'letterSpacing');
+                const kfIgnored = kfUnsupported.length === 0 ? '' : `, ignoredProperties: ${JSON.stringify(kfUnsupported)}, warning: ${JSON.stringify(`${kfUnsupported.join(', ')} is not an animatable property in this engine (app.listAnimatableProperties does not list it), so it had no effect. Set a fixed value with pinepaper_modify_item, or animate fontSize or scaleX.`)}`;
                 return `
 const targetId = ${kfItemRef};
-app.addAnimation(targetId, ${kfJson}, { duration: ${kfDuration}, loop: ${kfLoop} });
-return { itemId: targetId, duration: ${kfDuration}, loop: ${kfLoop} };
+const _target = (app.getItemById && app.getItemById(targetId))
+  || (app.itemRegistry && app.itemRegistry.get && app.itemRegistry.get(targetId));
+if (!_target) {
+  return { success: false, itemId: targetId, error: 'Item not found: ' + targetId };
+}
+const _kfItem = _target.item || _target;
+const _prevKeys = (_kfItem.data && Array.isArray(_kfItem.data.keyframes)) ? _kfItem.data.keyframes.length : 0;
+app.addAnimation(targetId, ${kfJson}, { duration: ${kfDuration}, loop: ${kfLoop}${kfAppend ? ", mode: 'merge'" : ''}${kfExtraStr} });
+return { success: true, itemId: targetId, duration: ${kfDuration}, loop: ${kfLoop}${kfAppend ? ', append: true' : ''}${kfAppend ? '' : `, ...(_prevKeys ? { track: { replaced: true, previousKeys: _prevKeys, note: 'the item already had a keyframe track; this op replaced it. To add keys to it instead, pass append: true.' } } : {})`}${kfIgnored} };
 `;
             }
             case 'apply_mask': {
                 const maskItemRef = op.itemId?.startsWith('$')
-                    ? `itemIds[${op.itemId.substring(1)}]`
+                    ? `__ref(${op.itemId.substring(1)})`
                     : `'${op.itemId}'`;
                 const maskOpts = JSON.stringify(op.maskOptions || {});
                 const preset = op.maskPreset || op.maskType || 'wipeLeft';
@@ -4074,7 +4424,7 @@ return { success: !!maskedGroup, itemId: targetId, preset: '${preset}' };
             }
             case 'apply_effect': {
                 const effItemRef = op.itemId?.startsWith('$')
-                    ? `itemIds[${op.itemId.substring(1)}]`
+                    ? `__ref(${op.itemId.substring(1)})`
                     : `'${op.itemId}'`;
                 const effParams = JSON.stringify(op.effectParams || {});
                 return `
@@ -4459,34 +4809,7 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
   // warnings:[] plus a note when it checked and found nothing, and the
   // warnings themselves otherwise. The note carries the caveat that absence
   // was standing in for.
-  //
-  // STAND-INS ARE THIS TOOL'S OWN DOING, SO THIS TOOL REPORTS THEM. create_item
-  // draws 'shader' and 'field' locally as a flat plate tagged data.renderAs; the
-  // engine's check sees an ordinary rectangle and cannot know a surface was
-  // meant. So a local export of a sea came out a flat blue slab with nothing
-  // said. Reported whatever the engine check can or cannot do.
-  function standIns() {
-    try {
-      // Probed with === : a studio without it degrades to "no stand-ins".
-      const canList = app.itemRegistry && typeof app.itemRegistry.getAll === 'function';
-      if (!canList) return [];
-      const found = {};
-      for (const entry of app.itemRegistry.getAll()) {
-        const kind = entry && entry.item && entry.item.data && entry.item.data.renderAs;
-        if (kind === 'shader' || kind === 'field') (found[kind] = found[kind] || []).push(entry.itemId);
-      }
-      return Object.keys(found).map(function(kind) {
-        const ids = found[kind];
-        return {
-          code: 'render_time_surface_stand_in',
-          message: ids.length + ' ' + kind + ' item' + (ids.length > 1 ? 's are' : ' is')
-            + ' exported as the flat plate that stands in for ' + (ids.length > 1 ? 'them' : 'it')
-            + ' on a local canvas. The surface itself is drawn only by a cloud render.',
-          items: ids.slice(0, 6),
-        };
-      });
-    } catch (e) { return []; }
-  }
+
   // TRANSPARENCY THE FORMAT CANNOT CARRY. A scene with no background exported
   // to webm came out on BLACK while the engine's check said it lost nothing
   // (round 7, 8.12). Only said when the scene is evidently transparent — no
@@ -4525,7 +4848,7 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
     } catch (e) { return []; }
   }
   function fidelity(fmt) {
-    const own = standIns().concat(alphaLoss(fmt), textOverflow());
+    const own = alphaLoss(fmt).concat(textOverflow());
     try {
       if (!app.exportEngine || typeof app.exportEngine.exportFidelity !== 'function') {
         return { fidelity: { available: false, reason: 'this studio cannot check export fidelity — update PinePaper Studio.', ...(own.length ? { warnings: own } : {}) } };
@@ -5481,6 +5804,34 @@ ${(() => {
         })()}
 ${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') {
@@ -6792,7 +7143,11 @@ ${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) {
   if (typeof app.captureProjectDocument !== 'function') { return { success: false, error: 'app.captureProjectDocument unavailable — update FxTool' }; }
   ${SCENE_COUNTS_JS}
   const doc = app.captureProjectDocument(${JSON.stringify(name ? { name } : {})});
-  return { success: true, json: JSON.stringify(doc), counts: __ppSceneCounts() };
+  // 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. */
@@ -7709,13 +8064,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();
             }
@@ -8143,6 +8507,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}`);
@@ -8667,8 +9057,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 `
@@ -8685,7 +9075,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':
@@ -8698,7 +9088,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:
@@ -9380,6 +9770,181 @@ ${resolve}
         }
     }
     // ===========================================================================
+    // HAND-DRAWN SKETCHY ANIMATION & JITTER
+    // ===========================================================================
+    generateHandDrawn(input) {
+        const S = (v) => JSON.stringify(v);
+        // style carries no schema default: with one, `mode` (its alias) was never read.
+        const requested = input.style ?? input.mode ?? 'sketchy';
+        const style = requested === 'ink_reveal' ? 'reveal' : requested;
+        const roughness = input.roughness ?? 2;
+        const bowing = input.bowing ?? 1;
+        const fps = input.fps ?? input.posterizeFps ?? 12;
+        const seed = input.seed ?? 1;
+        const duration = input.duration ?? 2;
+        // WOBBLE AND STOP_MOTION ANSWERED SUCCESS AND EXPORTED NOTHING. The engine's
+        // wobble draws one frame per call (updateHandDrawnWobble(item, frameIndex)),
+        // so a single call is a static jitter; stop_motion is a per-frame timing
+        // helper with no item to apply to, and applyHandDrawnStyle throws for it by
+        // name. The fallback hung an onFrame on the path, which is neither saved
+        // nor exported. The boiling line the studio does save and export is the ink
+        // medium, so the refusal hands over that call with these arguments.
+        if (style === 'wobble' || style === 'stop_motion') {
+            const use = {
+                tool: 'pinepaper_design_medium',
+                args: { action: 'apply', itemId: input.itemId ?? '<itemId>', medium: 'ink', options: { keepColor: true, fps, seed, amplitude: roughness } },
+            };
+            const error = `'${style}' has no animated form this studio saves or exports, so it would have shown in the editor and not in a video. Nothing was changed. For a hand-drawn line that boils frame to frame in exports, call pinepaper_design_medium with the arguments in \`use\` (fps is the boil rate). For a one-off rough line, use style 'sketchy'.`;
+            return `(function() { return { success: false, style: ${S(style)}, error: ${S(error)}, use: ${S(use)} }; })();`;
+        }
+        // REVEAL WAS AN onFrame DASH ANIMATION, which no export plays. A draw-on the
+        // studio saves is a trimEnd 0 -> 1 keyframe track, merged so the item's
+        // other keyframes survive.
+        if (style === 'reveal') {
+            if (!input.itemId) {
+                return `(function() { return { success: false, style: 'reveal', error: 'reveal needs an itemId: it keyframes that item\\'s stroke. Nothing was changed.' }; })();`;
+            }
+            // A trimEnd track on text or an image is kept and draws nothing (measured
+            // on prod: a PointText answered success and never changed), so the item
+            // is checked for a stroke first.
+            const track = generateKeyframeAnimateCode(input.itemId, [
+                { time: 0, properties: { trimEnd: 0 }, easing: 'linear' },
+                { time: duration, properties: { trimEnd: 1 }, easing: 'linear' },
+            ], duration, false, undefined, undefined, undefined, undefined, true).replace(/;\s*$/, '');
+            return `
+// Hand-drawn draw-on: a trimEnd track on a stroked path
+(function() {
+  const found = app.getItemById(${S(input.itemId)}) || (app.itemRegistry && app.itemRegistry.get(${S(input.itemId)}));
+  const it = found && found.item ? found.item : found;
+  const isPath = function(p) { return !!(p && p.segments && p.segments.length); };
+  if (it && !isPath(it) && !(it.children && it.children.some(isPath))) {
+    return { success: false, itemId: ${S(input.itemId)}, error: 'reveal draws a stroke on, and this item has no path to draw (' + (it.className || 'not a path') + '). Nothing was changed. For words that write themselves on, use pinepaper_text_style cursive with animate: true.' };
+  }
+  return (
+${track}
+  );
+})();`.trim();
+        }
+        const targetId = input.itemId ? S(input.itemId) : 'null';
+        return `
+// Hand-drawn sketchy stroke jitter
+(function() {
+  const targetId = ${targetId};
+  const found = targetId ? (app.getItemById(targetId) || (app.itemRegistry && app.itemRegistry.get(targetId))) : (app.selectedItems && app.selectedItems[0]);
+  const item = found && found.item ? found.item : found;
+  if (!item) {
+    return { success: false, error: 'Target item not found for hand-drawn styling' };
+  }
+  // The registry id, which every other tool takes — not Paper's numeric item.id.
+  const itemId = targetId || (item.data && (item.data.registryId || item.data.id)) || null;
+
+  // 1. The engine's own sketchy jitter.
+  if (typeof HandDrawn !== 'undefined' && HandDrawn && typeof HandDrawn.applyHandDrawnStyle === 'function') {
+    try {
+      HandDrawn.applyHandDrawnStyle(item, 'sketchy', { roughness: ${roughness}, bowing: ${bowing}, seed: ${seed} });
+      if (app._scheduleRepaint) app._scheduleRepaint();
+      if (app.historyManager) app.historyManager.saveState();
+      return { success: true, itemId: itemId, style: 'sketchy', engine: 'HandDrawn' };
+    } catch (e) {
+      console.warn('[HandDrawn] Engine error, falling back to procedural jitter:', e);
+    }
+  }
+
+  if (typeof app.applyHandDrawnJitter === 'function') {
+    app.applyHandDrawnJitter(item, { roughness: ${roughness}, bowing: ${bowing}, seed: ${seed} });
+    if (app._scheduleRepaint) app._scheduleRepaint();
+    if (app.historyManager) app.historyManager.saveState();
+    return { success: true, itemId: itemId, style: 'sketchy', engine: 'app.applyHandDrawnJitter' };
+  }
+
+  // 2. Procedural mulberry32 PRNG vertex jitter fallback
+  function mulberry32(a) {
+    return function() {
+      var t = a += 0x6D2B79F5;
+      t = Math.imul(t ^ t >>> 15, t | 1);
+      t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+      return ((t ^ t >>> 14) >>> 0) / 4294967296;
+    };
+  }
+
+  const targets = (item.children && item.children.length) ? item.children : [item];
+  let moved = 0;
+  targets.forEach((t, itemIdx) => {
+    if (!t.segments || !t.segments.length) return;
+    const rand = mulberry32(${seed} + itemIdx * 777);
+    for (let i = 0; i < t.segments.length; i++) {
+      const seg = t.segments[i];
+      seg.point.x += (rand() - 0.5) * ${roughness} * 2;
+      seg.point.y += (rand() - 0.5) * ${roughness} * 2;
+      if (seg.handleIn && (seg.handleIn.x !== 0 || seg.handleIn.y !== 0)) {
+        seg.handleIn.x += (rand() - 0.5) * ${bowing} * 1.5;
+        seg.handleIn.y += (rand() - 0.5) * ${bowing} * 1.5;
+      }
+      if (seg.handleOut && (seg.handleOut.x !== 0 || seg.handleOut.y !== 0)) {
+        seg.handleOut.x += (rand() - 0.5) * ${bowing} * 1.5;
+        seg.handleOut.y += (rand() - 0.5) * ${bowing} * 1.5;
+      }
+      moved++;
+    }
+  });
+  if (!moved) {
+    return { success: false, itemId: itemId, error: 'sketchy moves path points, and this item has none (text or an image?). Nothing was changed.' };
+  }
+
+  if (app._scheduleRepaint) app._scheduleRepaint();
+  if (app.historyManager) app.historyManager.saveState();
+  return { success: true, itemId: itemId, style: 'sketchy', roughness: ${roughness}, points: moved };
+})();`.trim();
+    }
+    // ===========================================================================
+    // PEN FIGURES
+    // ===========================================================================
+    generatePenFigure(input) {
+        const S = (v) => JSON.stringify(v);
+        const missing = `if (typeof app.listFigures !== 'function' || typeof app.createFigure !== 'function') {
+    return { success: false, error: 'This studio has no pen figures (app.createFigure). Nothing was drawn.' };
+  }`;
+        if (input.action === 'list') {
+            return `
+// The pen figure catalogue
+(function() {
+  ${missing}
+  const figures = app.listFigures();
+  return { success: true, action: 'list', count: figures.length, figures: figures };
+})();`.trim();
+        }
+        if (input.figure === undefined) {
+            return `(function() { return { success: false, error: "figure is required: a catalogue id (action 'list' names them) or an inline figure spec. Nothing was drawn." }; })();`;
+        }
+        const opts = {};
+        for (const k of ['box', 'margin', 'duration', 'delay', 'loop', 'pen', 'strokeColor', 'penColor', 'strokeWidth']) {
+            if (input[k] !== undefined)
+                opts[k] = input[k];
+        }
+        // createFigure answers null for an unknown id or a bad spec, and says why
+        // only in a console.warn, which production strips. The refusal is built
+        // here instead, naming the catalogue.
+        return `
+// Draw a figure with a pen (draws_figure)
+(function() {
+  ${missing}
+  const figure = ${S(input.figure)};
+  const out = app.createFigure(figure, ${S(opts)});
+  if (!out || !out.ink) {
+    const known = app.listFigures().map(function(f) { return f.id; });
+    return { success: false, error: (typeof figure === 'string' && known.indexOf(figure) < 0
+      ? 'No figure "' + figure + '". Known: ' + known.join(', ') + '.'
+      : 'The figure spec could not be drawn (it produced no strokes or did not parse).') + ' Nothing was drawn.' };
+  }
+  if (app._scheduleRepaint) app._scheduleRepaint();
+  if (app.historyManager) app.historyManager.saveState();
+  return out.pen
+    ? { success: true, inkId: out.ink, penId: out.pen, title: out.title, strokes: out.strokes, duration: ${S(input.duration ?? 6)},
+        note: 'The pen draws the ink over duration seconds (relation draws_figure, pen → ink).' }
+    : { success: true, inkId: out.ink, penId: null, title: out.title, strokes: out.strokes, note: 'pen: false — the ink is fully drawn, with no pen and no animation.' };
+})();`.trim();
+    }
+    // ===========================================================================
     // SPRITE SHEETS
     // ===========================================================================
     generateSpriteSheet(input) {
@@ -9753,8 +10318,9 @@ if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
 // Add physics body
 (function() {
   ${guard}
-  const entry = app.itemRegistry.get(${itemIdStr});
-  if (!entry || !entry.item) return { error: 'Item not found: ' + ${itemIdStr} };
+  const entry = (app.getItemById && app.getItemById(${itemIdStr})) || (app.itemRegistry && (app.itemRegistry.getItem ? app.itemRegistry.getItem(${itemIdStr}) : app.itemRegistry.get(${itemIdStr})));
+  const it = entry && (entry.item || entry);
+  if (!it) return { error: 'Item not found: ' + ${itemIdStr} };
   const ok = app.physicsWorld.addBody(${itemIdStr}, ${JSON.stringify(config)});
   return { success: ok, action: 'add_body', itemId: ${itemIdStr}, bodyType: ${JSON.stringify(input.bodyType || 'dynamic')} };
 })();`.trim();
@@ -11006,6 +11572,443 @@ ${guard}
      * 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;
+  ${authoringFrameJs('__fr')}
+  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 + '].');
+  if (__fr.unbounded && __warnings.some(function (w) { return /off screen/.test(w); })) __warnings.push('the canvas is unbounded, so it has no fixed frame: on-screen was checked against its nominal ' + __fr.width + 'x' + __fr.height + ' artboard. Set a canvas size or preset to fix the frame.');
+  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);
+      if (made) { made.visible = false; }
+      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.
+  {
+    ${authoringFrameJs('fr')}
+    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();
+            }
+        }
+    }
+    /**
+     * Character tool aliases (pinepaper_create_character, pinepaper_character_action, pinepaper_character_pose)
+     * Routing on-device / local model calls cleanly to the engine.
+     */
+    generateCreateCharacter(input) {
+        const S = (v) => JSON.stringify(v);
+        const charId = S(input.characterId || input.name || `char_${Date.now()}`);
+        const posX = typeof input.x === 'number' ? input.x : 400;
+        const posY = typeof input.y === 'number' ? input.y : 300;
+        const scale = typeof input.scale === 'number' ? input.scale : 1;
+        const name = S(input.name || input.characterId || 'Character');
+        const base = input.base ? S(input.base) : 'null';
+        const preset = input.preset || input.concept ? S(input.preset || input.concept) : 'null';
+        return `
+// Create Character
+(async function() {
+  const charId = ${charId};
+  const posX = ${posX};
+  const posY = ${posY};
+  const scale = ${scale};
+  const name = ${name};
+  const base = ${base};
+  const preset = ${preset};
+
+  // 1. If original character base is specified and app.createCharacter exists
+  if (base && typeof app.createCharacter === 'function') {
+    const r = await app.createCharacter({ base: base, at: { x: posX, y: posY }, scale: scale });
+    if (r && r.ok !== false) {
+      return { success: true, characterId: charId, itemId: r.id, parts: r.parts };
+    }
+  }
+
+  // 2. Try app.create
+  let groupId = null;
+  if (typeof app.create === 'function') {
+    const group = app.create('circle', { x: posX, y: posY, radius: 35 * scale, color: '#7C3AED' });
+    if (group) {
+      group.data = group.data || {};
+      group.data.ppType = 'pp:Character';
+      group.data.characterId = charId;
+      group.name = name;
+      groupId = group.id || (group.data && group.data.id) || charId;
+    }
+  } else {
+    const p = typeof paper !== 'undefined' ? paper : ((typeof window !== 'undefined' ? window : globalThis).paper);
+    if (p && p.Path) {
+      const body = new p.Path.Circle({ center: [posX, posY], radius: 35 * scale, fillColor: '#7C3AED' });
+      const head = new p.Path.Circle({ center: [posX, posY - 45 * scale], radius: 20 * scale, fillColor: '#EC4899' });
+      const group = new p.Group([body, head]);
+      group.name = name;
+      if (app.textItemGroup) group.parent = app.textItemGroup;
+      group.data = { isUserGroup: true, isLayeredCharacter: true, ppType: 'pp:Character', characterId: charId };
+      const reg = app.itemRegistry;
+      groupId = reg ? reg.register(group, 'group', { source: 'mcp_create_character' }, 'mcp') : charId;
+      group.data.id = groupId;
+    }
+  }
+
+  if (app._scheduleRepaint) app._scheduleRepaint();
+  if (app.historyManager) app.historyManager.saveState();
+  return { success: true, characterId: charId, itemId: groupId };
+})();`.trim();
+    }
+    generateCharacterAction(input) {
+        const S = (v) => JSON.stringify(v);
+        const targetId = input.characterId || input.itemId;
+        const act = String(input.action || 'walk').toLowerCase();
+        const speed = input.speed || 100;
+        return `
+// Character Action
+(function() {
+  const targetId = ${S(targetId)};
+  const act = ${S(act)};
+  const speed = ${speed};
+
+  const charItem = targetId
+    ? (app.getItemById(targetId) || (app.getAllItems && app.getAllItems().find(i => (i.data && i.data.characterId === targetId) || i.name === targetId)))
+    : (app.selectedItems && app.selectedItems[0]);
+
+  if (!charItem) {
+    return { success: false, error: 'Character not found: ' + targetId };
+  }
+
+  const itemId = charItem.id || (charItem.data && charItem.data.id) || targetId;
+  const skelId = (charItem.data && charItem.data.characterId) ? 'character_' + charItem.data.characterId : null;
+
+  if (act === 'walk' || act === 'run' || act === 'locomotion') {
+    if (typeof app.addRelation === 'function') {
+      app.addRelation(itemId, null, 'locomotion', {
+        skeletonId: skelId,
+        speed: speed,
+        cycleDistance: 150,
+      });
+    }
+  } else if (app.riggingSystem) {
+    const rs = app.riggingSystem;
+    if (skelId && rs.skeletons && rs.skeletons.has(skelId)) {
+      if (typeof rs.applyBoneAngles === 'function') {
+        rs.applyBoneAngles(skelId, { spine: 0.1, left_arm: -0.5, right_arm: 0.5 });
+        if (typeof rs.solveFK === 'function') rs.solveFK(skelId);
+      }
+    }
+  }
+
+  if (typeof app.animate === 'function' && (act === 'wave' || act === 'dance' || act === 'jump' || act === 'idle')) {
+    app.animate(charItem, { animationType: act === 'jump' ? 'bounce' : (act === 'idle' ? 'breathe' : 'wobble') });
+  }
+
+  if (app._scheduleRepaint) app._scheduleRepaint();
+  return { success: true, characterId: targetId || itemId, action: act };
+})();`.trim();
+    }
+    generateCharacterPose(input) {
+        const S = (v) => JSON.stringify(v);
+        const targetId = input.characterId || input.itemId;
+        const expr = String(input.expression || 'smile').toLowerCase();
+        const duration = input.duration !== undefined ? input.duration : null;
+        const interval = input.interval !== undefined ? input.interval : null;
+        return `
+// Character Pose / Expression
+(function() {
+  const targetId = ${S(targetId)};
+  const expr = ${S(expr)};
+
+  const charItem = targetId
+    ? (app.getItemById(targetId) || (app.getAllItems && app.getAllItems().find(i => (i.data && i.data.characterId === targetId) || i.name === targetId)))
+    : (app.selectedItems && app.selectedItems[0]);
+
+  if (!charItem) {
+    return { success: false, error: 'Character not found: ' + targetId };
+  }
+
+  const itemId = charItem.id || (charItem.data && charItem.data.id) || targetId;
+
+  // Touch riggingSystem first to ensure expression rules are initialized
+  const rs = app.riggingSystem;
+  if (typeof app.addRelation === 'function') {
+    app.addRelation(itemId, null, 'expresses', {
+      expression: expr,
+      duration: ${duration === null ? 'null' : duration},
+      interval: ${interval === null ? 'null' : interval},
+    });
+  }
+
+  if (app._scheduleRepaint) app._scheduleRepaint();
+  return { success: true, characterId: targetId || itemId, expression: expr };
+})();`.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.' }; }`;
@@ -11151,7 +12154,7 @@ ${body}
     }
     return { success: true, action: 'apply', medium: ${S(input.medium)}, fidelity: r.fidelity, itemId: r.id || ${S(input.itemId)}, inPlace: true, styled: __styled, ...(r.note ? { note: r.note } : {}) };
   }
-  return { success: true, action: 'apply', medium: r.medium || ${S(input.medium)}, fidelity: r.fidelity, itemId: r.id, ...(r.note ? { note: r.note } : {}) };
+  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
@@ -12080,7 +13083,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 `
@@ -12106,16 +13116,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 `
@@ -13134,7 +14146,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() {
@@ -13144,7 +14156,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)