@pinepaper.studio/mcp-server 1.6.20 → 1.6.21

package/dist/types/code-generator.js

@@ -74,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} = {
@@ -130,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
@@ -194,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,
@@ -219,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:
@@ -229,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.
     //
@@ -334,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();`;
@@ -403,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',
 ]);
 /**
@@ -626,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';
@@ -711,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);
@@ -793,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
@@ -928,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 += `
@@ -1225,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;
     });
@@ -1251,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();
@@ -1287,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;
@@ -1295,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}.' };
   }`;
@@ -1328,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() {
@@ -1337,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
@@ -1350,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();
 }
@@ -1896,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
@@ -1923,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,
         });
@@ -3959,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 {
@@ -4016,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 } };
   }
@@ -4043,13 +4189,40 @@ 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 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), op.itemType, opBrand));
+                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}
@@ -4064,7 +4237,7 @@ ${itemSettersApplyJs(opSetters, '__created.itemId', '__created')}
                 // 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.
@@ -4078,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
@@ -4099,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 `
@@ -4111,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 `
@@ -4129,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};
@@ -4141,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.
@@ -4151,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}' };
@@ -4185,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';
@@ -4225,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 `
@@ -4610,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
@@ -4676,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 } : {}) } };
@@ -9598,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) {
@@ -9971,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();
@@ -11242,7 +11590,7 @@ ${guard}
   const __sc = __it.scaling || { x: 1, y: 1 };
   const __b = __it.bounds;
   const __baked = (__it.data && typeof __it.data._bakedRotation === 'number') ? __it.data._bakedRotation : 0;
-  const __fr = (typeof app.exportFrameRect === 'function' && app.exportFrameRect()) || (app.getCanvasSize && app.getCanvasSize()) || { width: 1920, height: 1080 };
+  ${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),
@@ -11263,6 +11611,7 @@ ${guard}
     __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
@@ -11322,6 +11671,7 @@ ${input.sound ? `  // SOUND ON THE ACTION (D68): one placed sound per moment the
     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))) {
@@ -11336,7 +11686,7 @@ ${input.sound ? `  // SOUND ON THE ACTION (D68): one placed sound per moment the
   if (n !== null && n < done.length) res.warning = 'only ' + n + ' of ' + done.length + ' morphs are on the element.';
 ${cam ? `  // The camera rides the SAME timing: framing each state as its morph lands.
   {
-    const fr = (typeof app.exportFrameRect === 'function' && app.exportFrameRect()) || (app.getCanvasSize && app.getCanvasSize()) || { width: 1920, height: 1080 };
+    ${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);
@@ -11401,6 +11751,154 @@ ${cam ? `  // The camera rides the SAME timing: framing each state as its morph
             }
         }
     }
+    /**
+     * 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