@pinepaper.studio/mcp-server 1.6.22 → 1.6.24

package/dist/types/code-generator.js

@@ -5,11 +5,13 @@
  * This code is designed to run in the browser context where window.PinePaper is available.
  */
 import { compileChoreography } from '../tools/choreograph.js';
+import { compileBatchTimelines, emitTimelineOpBody } from '../tools/timeline.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 { expandBatchMacros } from '../tools/batch-macros.js';
 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, 
@@ -26,7 +28,7 @@ GlobeEnableInputSchema, GlobeRotateToInputSchema, GlobeSpinInputSchema, WorldTou
 // Custom relation/code types
 RegisterCustomRelationInputSchema, ExecuteCustomCodeInputSchema, 
 // Mask types
-ApplyAnimatedMaskInputSchema, ApplyCustomMaskInputSchema, RemoveMaskInputSchema, SceneGraphInputSchema, SequenceInputSchema, StaggerInputSchema, FlipInputSchema, QueryCapabilitiesInputSchema, KEYFRAME_EASINGS, EASING_DESCRIPTIONS, MaskTypeSchema, MaskPresetSchema, } from './schemas.js';
+ApplyAnimatedMaskInputSchema, ApplyCustomMaskInputSchema, RemoveMaskInputSchema, SceneGraphInputSchema, SequenceInputSchema, StaggerInputSchema, PatternInputSchema, FlipInputSchema, QueryCapabilitiesInputSchema, KEYFRAME_EASINGS, EASING_DESCRIPTIONS, MaskTypeSchema, MaskPresetSchema, } from './schemas.js';
 import { OntologyCompiler } from '../ontology/ontology-compiler.js';
 // =============================================================================
 // HELPER FUNCTIONS
@@ -74,17 +76,43 @@ 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.
-    // 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(', ');
+    if (type === 'radial') {
+        // A RADIAL CORE BELONGS ON THE ITEM, NOT ON THE NUMBER ASKED FOR (17
+        // RADIALOFFSET). The origin was the REQUESTED position and the radius a
+        // fixed 50 px: whenever (x, y) placed the item as a corner (an anchor, a
+        // default position) the core landed up-left by half the item, and a 300 px
+        // circle got a 50 px core. Read from the created item's bounds instead —
+        // centre and right-centre, as the engine's own _parseColor does — with the
+        // request only as the fallback when the item has no bounds. An origin or
+        // destination the caller gave is kept as given.
+        const fx = position.x, fy = position.y;
+        const o = origin ? `[${origin[0]}, ${origin[1]}]` : `(__gb ? [__gb.x + __gb.width / 2, __gb.y + __gb.height / 2] : [${fx}, ${fy}])`;
+        const d = destination ? `[${destination[0]}, ${destination[1]}]`
+            : origin ? `(__gb ? [${origin[0]} + __gb.width / 2, ${origin[1]}] : [${origin[0]} + 50, ${origin[1]}])`
+                : `(__gb ? [__gb.x + __gb.width, __gb.y + __gb.height / 2] : [${fx + 50}, ${fy}])`;
+        return `
+${itemVarName}.${propertyName} = (function() {
+  const __b = ${itemVarName} && ${itemVarName}.bounds;
+  const __gb = __b && isFinite(__b.x) && isFinite(__b.y) && __b.width > 0 && __b.height > 0 ? __b : null;
+  return {
+    gradient: {
+      stops: [${stopsCode}],
+      radial: true
+    },
+    origin: ${o},
+    destination: ${d}
+  };
+})();`;
+    }
+    // Linear: a diagonal across a 100 px box at the requested position.
+    const defaultOrigin = origin || [position.x - 50, position.y - 50];
+    const defaultDestination = destination || [position.x + 50, position.y + 50];
     return `
 ${itemVarName}.${propertyName} = {
   gradient: {
     stops: [${stopsCode}],
-    radial: ${type === 'radial'}
+    radial: false
   },
   origin: [${defaultOrigin[0]}, ${defaultOrigin[1]}],
   destination: [${defaultDestination[0]}, ${defaultDestination[1]}]
@@ -172,6 +200,7 @@ function generateCreateItemCode(itemType, position, properties, dataFlags, posit
         textDirection.resolved = baseDirection(createProps.content);
     }
     const textTabular = itemType === 'text' && wantsTabular(createProps) === true;
+    const createFillOpacity = createProps.fillOpacity !== undefined;
     const textStrokePos = itemType === 'text' ? takeStrokePosition(createProps, false) : null;
     const params = {
         ...(omitXY ? {} : { x: position.x, y: position.y }),
@@ -282,7 +311,8 @@ if (item && item.data) { item.data.renderAs = ${JSON.stringify(itemType)}; item.
     const textOnly = (k) => TEXT_STYLE_KEYS.includes(k) || k === 'fit' || k === 'textDirection' || k === 'dir'
         || TABULAR_KEYS.includes(k) || k === 'strokePosition';
     const ignored = Object.keys(properties).filter((k) => itemType === 'text'
-        ? !CREATE_KNOWN_KEYS.has(k) && !textOnly(k) && !DIRECTION_KEYS.includes(k)
+        ? (!CREATE_KNOWN_KEYS.has(k) && !textOnly(k) && !DIRECTION_KEYS.includes(k))
+            || (k === 'letterSpacing' && letterSpacingCss(properties[k]) === undefined)
         : !CREATE_KNOWN_KEYS.has(k) || textOnly(k));
     // Build the code
     let code = `
@@ -337,6 +367,8 @@ const item = app.create('${itemType}', ${JSON.stringify(params, null, 2)});`;
         code += emitDirectionCheck('item', textDirection);
     if (textTabular)
         code += emitTabularCheck('item');
+    if (createFillOpacity)
+        code += emitFillOpacityCheck('item');
     if (textStrokePos)
         code += emitStrokePositionCheck('item', textStrokePos);
     if (textFit)
@@ -374,7 +406,7 @@ const itemId = item.data.registryId;
 app.historyManager.saveState();
 
 // Return item info
-({ itemId, type: '${itemType}'${textFit ? ', textFit: __textFit' : ''}${textDirection ? ', direction: __direction' : ''}${textTabular ? ', tabularFigures: __tabular' : ''}${textStrokePos ? ', strokePosition: __strokePos' : ''}, position: ${omitXY ? `(item.position ? { x: item.position.x, y: item.position.y } : null)` : `{ x: ${position.x}, y: ${position.y} }`}${hasLifetime ? ', lifetime: __lifetime' : ''}${loadsFont ? ', ...(__font ? { font: __font } : {})' : ''}${ignored.length > 0
+({ itemId, type: '${itemType}'${textFit ? ', textFit: __textFit' : ''}${textDirection ? ', direction: __direction' : ''}${textTabular ? ', tabularFigures: __tabular' : ''}${createFillOpacity ? ', fillOpacity: __fillOpacity' : ''}${textStrokePos ? ', strokePosition: __strokePos' : ''}, position: ${omitXY ? `(item.position ? { x: item.position.x, y: item.position.y } : null)` : `{ x: ${position.x}, y: ${position.y} }`}${hasLifetime ? ', lifetime: __lifetime' : ''}${loadsFont ? ', ...(__font ? { font: __font } : {})' : ''}${ignored.length > 0
         ? `, ignoredProperties: ${JSON.stringify(ignored)}, warning: ${JSON.stringify(`${ignored.join(', ')} ${ignored.length > 1 ? 'are' : 'is'} not read when creating an item, so ${ignored.length > 1 ? 'they had' : 'it had'} no effect. `
             + 'Check the spelling against this item type\'s documented properties.')}`
         : ''} });`;
@@ -398,7 +430,7 @@ const MODIFY_KNOWN_KEYS = new Set([
     ...NORMALIZE_PARAM_READS,
     'contentType', 'contentFormat', 'countdownTarget', 'countdownEndText',
     'audioGain', 'volume', 'gain', 'bornAt', 'ttl', 'smoothing',
-    'fontStyle', 'leading', 'lineHeight', 'skewX', 'skewY', 'matrix', 'fit', 'direction', 'textDirection', 'dir', 'tabularFigures', 'fontVariantNumeric', 'fontFeatures', 'strokePosition',
+    'fontStyle', 'leading', 'lineHeight', 'skewX', 'skewY', 'matrix', 'fit', 'direction', 'textDirection', 'dir', 'tabularFigures', 'fontVariantNumeric', 'fontFeatures', 'strokePosition', 'fillOpacity',
 ]);
 /** Spellings callers reach for, and the key the engine actually reads. */
 const MODIFY_DID_YOU_MEAN = {
@@ -419,6 +451,9 @@ const CREATE_KNOWN_KEYS = new Set([
     // Lifetimes, on ANY item: this generator applies them through app.setLifetime
     // (emitLifetime), whatever create() itself reads.
     'bornAt', 'ttl',
+    // A solid fill's own alpha (FxTool 12 STROKEFILL); confirmed per call by
+    // emitFillOpacityCheck, since an older studio ignores it.
+    'fillOpacity',
 ]);
 /**
  * Load a font family before text is drawn with it, and say if it still is not there.
@@ -566,15 +601,61 @@ function wantsTabular(p) {
     const list = Array.isArray(f) ? f.map(String) : typeof f === 'string' ? [f] : f && typeof f === 'object' ? Object.keys(f).filter((k) => f[k]) : [];
     return list.some((x) => /\btnum\b/.test(x));
 }
+/**
+ * Whether tabular figures CHANGED the layout is the engine's to measure: the
+ * request flag (data.tabularFigures) is set even when the font's digits are
+ * already one width, where the layout moves nothing (9 TABNUM: DejaVu Sans
+ * reported applied while every advance matched the control). A studio with
+ * app.tabularFiguresReport measures the item's own font, and only its answer
+ * is reported as applied. One without it can only say the flag was recorded:
+ * 'unverified', never true.
+ */
 function emitTabularCheck(itemExpr) {
     return `
 const __tabular = (function(it) {
   if (!it || it.className !== 'PointText') return { applied: false, note: 'tabular figures apply to text items only.' };
+  if (typeof app.tabularFiguresReport === 'function') {
+    let r = null;
+    try { r = app.tabularFiguresReport(it); } catch (e) { return { applied: 'unverified', note: 'the studio could not measure tabular figures on this text (' + ((e && e.message) || e) + ').' }; }
+    if (r && typeof r === 'object') {
+      const out = { applied: r.applied === true };
+      if (typeof r.steadyWidth === 'boolean') out.steadyWidth = r.steadyWidth;
+      if (r.reason) out.reason = r.reason;
+      if (r.note) out.note = r.note;
+      else if (r.reason === 'rtl') out.note = 'right-to-left text keeps proportional digits.';
+      else if (r.reason === 'not-requested') out.note = 'the studio did not record the request, so digits keep their proportional widths.';
+      if (typeof r.spread === 'number') out.digitSpread = r.spread;
+      if (r.width && typeof r.width === 'object') out.width = r.width;
+      return out;
+    }
+    return { applied: 'unverified', note: 'the studio returned no tabular-figures report for this text.' };
+  }
   return it.data && it.data.tabularFigures === true
-    ? { applied: true }
+    ? { applied: 'unverified', note: 'this studio recorded tabular figures but cannot measure whether they change the layout (it has no tabularFiguresReport): with a font whose digits are already one width they change nothing.' }
     : { applied: false, note: 'this studio does not lay out tabular figures (it needs an engine with them): digits keep their proportional widths. A monospaced font is the fallback.' };
 })(${itemExpr});`;
 }
+/**
+ * fillOpacity (FxTool 12 STROKEFILL): a solid fill's own alpha, apart from the
+ * item's opacity and its stroke, so an outline-only type is fillOpacity: 0.
+ * The engine records it on data.fillOpacity and re-applies it when a later
+ * modify changes the fill colour. A studio without it ignores the key, so the
+ * reply is read from the item: the recorded value and the fill's alpha.
+ */
+function emitFillOpacityCheck(itemExpr) {
+    return `
+const __fillOpacity = (function(it) {
+  if (!it) return { applied: false, note: 'no item to check.' };
+  const v = it.data && it.data.fillOpacity;
+  if (typeof v !== 'number') return { applied: false, note: 'this studio does not read fillOpacity (it needs an engine with it): the fill keeps its own alpha. opacity fades the whole item, stroke included; an rgba() fill sets the fill alone.' };
+  const c = it.fillColor;
+  if (!c) return { applied: true, value: v, note: 'the item has no fill now, so there is nothing to see; a fill colour set later with modify_item takes this alpha.' };
+  if (c.gradient) return { applied: false, value: v, note: 'a gradient fill keeps its own stop colours: put the alpha in the stops (rgba) instead.' };
+  return (typeof c.alpha === 'number' && Math.abs(c.alpha - v) > 0.01)
+    ? { applied: false, value: v, note: 'the studio recorded fillOpacity but the fill is drawn at alpha ' + c.alpha + '.' }
+    : { applied: true, value: v };
+})(${itemExpr});`;
+}
 function takeStrokePosition(props, allowNull) {
     if (!('strokePosition' in props))
         return null;
@@ -656,13 +737,26 @@ function authoringFrameJs(name) {
     return (typeof app.exportFrameRect === 'function' && app.exportFrameRect()) || cs || { width: 1920, height: 1080 };
   })();`;
 }
-const TEXT_STYLE_KEYS = ['fontWeight', 'fontStyle', 'leading', 'lineHeight', 'textAlign', 'align', 'text'];
+const TEXT_STYLE_KEYS = ['fontWeight', 'fontStyle', 'leading', 'lineHeight', 'letterSpacing', 'textAlign', 'align', 'text'];
+/**
+ * letterSpacing as the studio draws it, or undefined if it cannot be. create()
+ * and modifyItem() do not read it (B108); the studio draws the item's own
+ * letterSpacing, a CSS length, as its keyframes set it, and a number is px.
+ */
+function letterSpacingCss(v) {
+    if (typeof v === 'number' && Number.isFinite(v))
+        return `${v}px`;
+    if (typeof v === 'string' && /^-?\d*\.?\d+(px|em)?$/.test(v.trim()))
+        return /\d$/.test(v.trim()) ? `${v.trim()}px` : v.trim();
+    return undefined;
+}
 function emitTextStyle(itemExpr, props) {
     const weight = props.fontWeight;
     const italic = props.fontStyle === 'italic' || props.fontStyle === 'oblique';
     const lh = typeof props.lineHeight === 'number' ? props.lineHeight : undefined;
     const leading = typeof props.leading === 'number' ? props.leading : undefined;
-    if (weight === undefined && props.fontStyle === undefined && leading === undefined && lh === undefined)
+    const ls = letterSpacingCss(props.letterSpacing);
+    if (weight === undefined && props.fontStyle === undefined && leading === undefined && lh === undefined && ls === undefined)
         return '';
     return `
 (function(it) {
@@ -675,6 +769,7 @@ function emitTextStyle(itemExpr, props) {
         : ''}
   ${leading !== undefined ? `it.leading = ${leading};` : ''}
   ${lh !== undefined ? `it.leading = ${lh} <= 4 ? ${lh} * it.fontSize : ${lh};` : ''}
+  ${ls !== undefined ? `it.letterSpacing = ${JSON.stringify(ls)};` : ''}
   const b1 = it.bounds;
   it.position = it.position.add([ax - edge(b1), ay - b1.center.y]);
 })(${itemExpr});`;
@@ -853,6 +948,7 @@ function generateModifyItemCode(itemId, properties, dataFlags) {
         delete restProperties.fit;
     const modDirection = takeDirection(restProperties);
     const modTabular = wantsTabular(restProperties) === true;
+    const modFillOpacity = restProperties.fillOpacity !== undefined;
     const modStrokePos = takeStrokePosition(restProperties, true);
     // modifyItem(id, changes), NOT select() + modify().
     //
@@ -980,6 +1076,8 @@ 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).
+    if (textStyle && letterSpacingCss(properties.letterSpacing) !== undefined)
+        aliased.add('letterSpacing');
     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(''))}`;
@@ -992,8 +1090,8 @@ ${properties.content !== undefined ? `
 const __ctItem = app.getItemById('${itemId}');
 const __ctKeys = (__ctItem && __ctItem.data && Array.isArray(__ctItem.data.keyframes))
   ? __ctItem.data.keyframes.filter(function(k) { return k && k.properties && Object.prototype.hasOwnProperty.call(k.properties, 'content'); }).length : 0;` : ''}
-${modDirection ? emitDirectionCheck(`app.getItemById('${itemId}')`, modDirection) : ''}${modTabular ? emitTabularCheck(`app.getItemById('${itemId}')`) : ''}${modStrokePos ? emitStrokePositionCheck(`app.getItemById('${itemId}')`, modStrokePos) : ''}
-return { success: true, itemId: '${itemId}'${properties.content !== undefined ? `, ...(__ctKeys ? { contentTrackWarning: 'this text\\'s content is keyframed (' + __ctKeys + ' key(s)), so the track sets it on every frame and this edit does not show. Change the content keys with pinepaper_keyframe_animate (append: true replaces same-time keys), or animate another property.' } : {})` : ''}${modFit ? ', textFit: __textFit' : ''}${modDirection ? ', direction: __direction' : ''}${modTabular ? ', tabularFigures: __tabular' : ''}${modStrokePos ? ', strokePosition: __strokePos' : ''}${affine ? `, affine: ${JSON.stringify({ skewX, skewY, matrix, note: 'applied to the current shape: calling again compounds it. To undo, apply the inverse (negative skew, or the inverse matrix).' })}` : ''}${modLifetime ? ', lifetime: __lifetime' : ''}${modFont ? ', ...(__font ? { font: __font } : {})' : ''}${modWarning} };`;
+${modDirection ? emitDirectionCheck(`app.getItemById('${itemId}')`, modDirection) : ''}${modTabular ? emitTabularCheck(`app.getItemById('${itemId}')`) : ''}${modFillOpacity ? emitFillOpacityCheck(`app.getItemById('${itemId}')`) : ''}${modStrokePos ? emitStrokePositionCheck(`app.getItemById('${itemId}')`, modStrokePos) : ''}
+return { success: true, itemId: '${itemId}'${properties.content !== undefined ? `, ...(__ctKeys ? { contentTrackWarning: 'this text\\'s content is keyframed (' + __ctKeys + ' key(s)), so the track sets it on every frame and this edit does not show. Change the content keys with pinepaper_keyframe_animate (append: true replaces same-time keys), or animate another property.' } : {})` : ''}${modFit ? ', textFit: __textFit' : ''}${modDirection ? ', direction: __direction' : ''}${modTabular ? ', tabularFigures: __tabular' : ''}${modFillOpacity ? ', fillOpacity: __fillOpacity' : ''}${modStrokePos ? ', strokePosition: __strokePos' : ''}${affine ? `, affine: ${JSON.stringify({ skewX, skewY, matrix, note: 'applied to the current shape: calling again compounds it. To undo, apply the inverse (negative skew, or the inverse matrix).' })}` : ''}${modLifetime ? ', lifetime: __lifetime' : ''}${modFont ? ', ...(__font ? { font: __font } : {})' : ''}${modWarning} };`;
     // Wrapped, because the body now RETURNS early on a miss rather than falling
     // through to an unconditional success. Async only when a font must load
     // before modifyItem re-measures the text.
@@ -1035,6 +1133,15 @@ function generateDeleteItemCode(itemId) {
 /**
  * Template for adding relations
  */
+/**
+ * A JS expression: the studio's own reason for refusing a relation of `typeJs`,
+ * or null. addRelation answers a bare false; the WHY (B119: "relation
+ * 'spring_follow' is not loaded yet…") is recorded with app.noteWarning, which
+ * reaches the reply only as a governor warning. Read here without draining it.
+ */
+export function relationRefusalReasonJs(typeJs) {
+    return `(function(){ var ws = (app && app._engineWarnings) || []; for (var i = ws.length - 1; i >= 0; i--) { var w = ws[i]; if (w && w.relation === ${typeJs} && typeof w.message === 'string') return w.message; } return null; })()`;
+}
 function generateAddRelationCode(sourceId, targetId, relationType, params) {
     // AN UNKNOWN ENDPOINT IS REFUSED, NOT STORED (round 9 GG, 1.74). The engine
     // stores a relation to an id it cannot resolve, returns true, and says "it
@@ -1055,13 +1162,109 @@ function generateAddRelationCode(sourceId, targetId, relationType, params) {
   }
   const success = app.addRelation('${sourceId}', '${targetId}', '${relationType}', ${JSON.stringify(params, null, 2)});
   if (!success) {
-    return { success: false, relationType: '${relationType}', error: 'the studio refused the ${relationType} relation between ${sourceId} and ${targetId}.' };
+    const __why = ${relationRefusalReasonJs(JSON.stringify(relationType))};
+    return { success: false, relationType: '${relationType}', error: 'the studio refused the ${relationType} relation between ${sourceId} and ${targetId}' + (__why ? ': ' + __why : '.') };
   }
   app.historyManager.saveState();
   return { success: true, sourceId: '${sourceId}', targetId: '${targetId}', relationType: '${relationType}' };
 })();
 `.trim();
 }
+/**
+ * The per-burst particle cap of the CURRENT studio (FxTool ParticleEmitter
+ * MAX_BURST_COUNT, B144). Studios before that change capped at
+ * EMITTER_LEGACY_MAX_PER_BURST, in silence. Which one a studio has is read
+ * back from the spec it stored (generateEmitter), not assumed.
+ */
+export const EMITTER_MAX_PER_BURST = 10000;
+/** The cap of studios before B144 (normalizeLook clamped at 2000 without a word). */
+export const EMITTER_LEGACY_MAX_PER_BURST = 2000;
+/**
+ * Every count in an emitter spec (the spec's own and each burst's) that some
+ * studio may cap: above the legacy cap. `index` is null for the spec's own
+ * count (each burst without its own inherits it).
+ */
+export function emitterCountsToCheck(spec) {
+    const out = [];
+    if (!spec || typeof spec !== 'object')
+        return out;
+    const capped = (v) => typeof v === 'number' && Number.isFinite(v) && Math.round(v) > EMITTER_LEGACY_MAX_PER_BURST;
+    if (capped(spec.count))
+        out.push({ where: 'count', index: null, asked: Math.round(spec.count) });
+    if (Array.isArray(spec.bursts)) {
+        spec.bursts.forEach((b, i) => {
+            const c = b && typeof b === 'object' ? b.count : undefined;
+            if (capped(c))
+                out.push({ where: `bursts[${i}].count`, index: i, asked: Math.round(c) });
+        });
+    }
+    return out;
+}
+/**
+ * What can be said about the counts WITHOUT the studio's answer: above the
+ * current cap is capped on every studio; between the two caps depends on the
+ * studio. Used when the stored spec cannot be read back.
+ */
+export function emitterCountWarnings(spec) {
+    return emitterCountsToCheck(spec).map(({ where, asked }) => asked > EMITTER_MAX_PER_BURST
+        ? `${where} ${asked} is over the ${EMITTER_MAX_PER_BURST}-particle cap per burst of the current studio (${EMITTER_LEGACY_MAX_PER_BURST} on older studios), so it draws at most ${EMITTER_MAX_PER_BURST}. Split it into bursts at the same t for more.`
+        : `${where} ${asked} is over the ${EMITTER_LEGACY_MAX_PER_BURST}-particle cap per burst of studios before the ${EMITTER_MAX_PER_BURST} cap, and this studio did not report what it drew: on an older studio it draws ${EMITTER_LEGACY_MAX_PER_BURST}. Split it into bursts at the same t to be sure.`);
+}
+/**
+ * An emitter spec as the studio reads it, and what the reply says about it.
+ *
+ * The studio reads velocities and offsets as [x, y] pairs only and drops any
+ * other entry, so velocities: [{x, y}] made particles with no velocity and no
+ * word (VELOC23). Point objects are turned into pairs here. And a burst draws
+ * `count` particles, the i-th taking velocities[i % length]: with fewer
+ * velocities than particles the extras repeat a velocity and draw on top of an
+ * earlier particle, and with more the extras go unused, both in silence
+ * (VELOCMISMATCH23). That is said, not changed: cycling is the studio's rule.
+ * `assumeDefaultCount` is false for a set, whose spec is only the keys changed.
+ */
+export function normalizeEmitterSpec(spec, assumeDefaultCount = true) {
+    const warnings = [];
+    if (!spec || typeof spec !== 'object')
+        return { spec, warnings };
+    const pairs = (v) => (Array.isArray(v)
+        ? v.map((p) => (p && typeof p === 'object' && !Array.isArray(p) && ('x' in p || 'y' in p)
+            ? [Number(p.x ?? 0), Number(p.y ?? 0)]
+            : p))
+        : v);
+    const fix = (o) => {
+        const out = { ...o };
+        for (const k of ['velocities', 'offsets'])
+            if (out[k] !== undefined)
+                out[k] = pairs(out[k]);
+        return out;
+    };
+    const out = fix(spec);
+    if (Array.isArray(spec.bursts))
+        out.bursts = spec.bursts.map((b) => (b && typeof b === 'object' ? fix(b) : b));
+    // The studio's default count per burst (ParticleEmitter DEFAULT_LOOK).
+    const DEFAULT_COUNT = 12;
+    const mismatch = (where, count, velocities) => {
+        if (!Array.isArray(velocities) || !velocities.length)
+            return;
+        const n = typeof count === 'number' && Number.isFinite(count) ? Math.round(count) : (assumeDefaultCount ? DEFAULT_COUNT : null);
+        if (n === null || n === velocities.length)
+            return;
+        warnings.push(n > velocities.length
+            ? `${where}: count ${n} with ${velocities.length} velocities: particle i takes velocities[i % ${velocities.length}], so ${n - velocities.length} particles repeat an earlier particle's path and draw on top of it. Give one velocity per particle, or set count to ${velocities.length}.`
+            : `${where}: count ${n} with ${velocities.length} velocities: only the first ${n} velocities are used. Set count to ${velocities.length} to draw them all.`);
+    };
+    // The spec's own pair once; a burst only where it sets either itself (it inherits the rest).
+    const bursts = Array.isArray(out.bursts) ? out.bursts : [];
+    const inherited = bursts.some((b) => !b || typeof b !== 'object' || (b.count === undefined && b.velocities === undefined));
+    if (out.velocities !== undefined && (out.count !== undefined || inherited))
+        mismatch('spec', out.count, out.velocities);
+    bursts.forEach((b, i) => {
+        const own = (b && typeof b === 'object' ? b : {});
+        if (own.count !== undefined || own.velocities !== undefined)
+            mismatch(`bursts[${i}]`, own.count ?? out.count, own.velocities ?? out.velocities);
+    });
+    return { spec: out, warnings };
+}
 /**
  * moves_along_path, from the parameters a caller actually writes.
  *
@@ -1132,7 +1335,27 @@ function generateMovesAlongPathCode(sourceId, targetId, raw) {
     if (len > 0) params.speed = len / (150 * ${duration});
     if (params.closed === undefined) params.closed = false;
   }` : ''}
-  ${hasDelay ? `if (!params.window) params.window = { start: ${delay} };` : ''}
+  // AN EQUATION ROUTE WITH A DURATION (queue item 22, ORBITDUR). There are no
+  // points here to turn a duration into speed, so it was dropped and the curve
+  // ran at the default speed. A studio whose rule times an equation (FxTool
+  // claude/engine-core-queue: its equation param says duration times it) gets
+  // duration, and delay on the same playhead clock instead of a window (a
+  // window would start the timed ride part-way through). An older studio hands
+  // a timed equation to the arm that cannot read one and loses the curve, so it
+  // keeps today's untimed ride and is told.
+  const __warnings = [];
+  let __eqTimed = false;
+  ${hasDuration ? `if (params.equation && !hasPoints) {
+    const eqDesc = rule && rule.params && rule.params.equation && rule.params.equation.description;
+    if (typeof eqDesc === 'string' && /duration/.test(eqDesc)) {
+      __eqTimed = true;
+      params.duration = ${duration};
+      ${hasDelay ? `params.delay = ${delay};` : ''}
+    } else {
+      __warnings.push('duration ${duration} was not applied: this studio cannot time an equation route (a timed equation loses its curve there), so the route stays untimed at speed ' + (params.speed !== undefined ? params.speed : 1) + ' (1 = 150 px/s). Update the studio, or pass params.path as points.');
+    }
+  }` : ''}
+  ${hasDelay ? `if (!__eqTimed && !params.window) params.window = { start: ${delay} };` : ''}
   // Before its window opens the relation does not run, so the item stays where
   // it was left — the retest saw it parked at the path END. Put it at the start.
   if (Array.isArray(params.path) && params.path.length) {
@@ -1145,7 +1368,8 @@ function generateMovesAlongPathCode(sourceId, targetId, raw) {
   app.historyManager.saveState();
   return { success: true, sourceId: ${JSON.stringify(sourceId)}, relationType: 'moves_along_path', route: 'sampled-points',
     points: Array.isArray(params.path) ? params.path.length : 0, speed: params.speed, closed: params.closed,
-    ${ref ? `pathFrom: ${JSON.stringify(ref)},` : ''} window: params.window };
+    ${ref ? `pathFrom: ${JSON.stringify(ref)},` : ''} window: params.window,
+    ...(__eqTimed ? { duration: params.duration } : {}), ...(__warnings.length ? { warnings: __warnings } : {}) };
 })();`.trim();
 }
 /**
@@ -1327,7 +1551,35 @@ 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();
 }
-function generateKeyframeAnimateCode(itemId, keyframes, duration, loop = false, timeOffset, clipInPoint, clipOutPoint, timeUnits, append = false) {
+/**
+ * Text keys a studio may or may not animate (queue item 2, FxTool
+ * claude/engine-core-queue): fontStyle, textAlign, lineHeight and letterSpacing
+ * apply as keyframes on the current studio, which lists them (textAlign as
+ * justification, lineHeight as leading) in listAnimatableProperties. An older
+ * studio stores the keys and draws nothing, so the check runs IN THE PAGE
+ * against that list, and only the keys it does not name are reported.
+ */
+const TEXT_KEY_ENGINE_NAMES = {
+    fontStyle: ['fontStyle'],
+    textAlign: ['textAlign', 'justification'],
+    lineHeight: ['lineHeight', 'leading'],
+    letterSpacing: ['letterSpacing'],
+};
+/** A JS expression (run in the page) → the keys of `keys` this studio does not animate. '' when none are text keys. */
+function unanimatedTextKeysJs(keys) {
+    const spec = [...new Set(keys)].filter((k) => k in TEXT_KEY_ENGINE_NAMES).map((k) => ({ key: k, names: TEXT_KEY_ENGINE_NAMES[k] }));
+    if (!spec.length)
+        return '';
+    return `(function() {
+    let __l = null;
+    try { __l = typeof app.listAnimatableProperties === 'function' ? app.listAnimatableProperties() : null; } catch (_) { __l = null; }
+    const __names = ((__l && __l.properties) || []).map(function(p) { return p && p.name; });
+    return ${JSON.stringify(spec)}.filter(function(s) { return !s.names.some(function(n) { return __names.indexOf(n) >= 0; }); }).map(function(s) { return s.key; });
+  })()`;
+}
+/** The sentence for the keys unanimatedTextKeysJs found, built in the page. */
+const UNANIMATED_TEXT_KEYS_SENTENCE = `' is not an animatable property in this studio (app.listAnimatableProperties does not list it), so it had no effect. The current studio animates fontStyle, textAlign, lineHeight and letterSpacing; here, set a fixed value with pinepaper_modify_item, or animate fontSize or scaleX.'`;
+function generateKeyframeAnimateCode(itemId, keyframes, duration, loop = false, timeOffset, clipInPoint, clipOutPoint, timeUnits, append = false, easingAt) {
     const keyframesJson = JSON.stringify(normalizeKeyframePositions(keyframes), null, 2);
     const calculatedDuration = duration || Math.max(...keyframes.map(k => k.time));
     const opts = { duration: calculatedDuration, loop };
@@ -1343,6 +1595,11 @@ function generateKeyframeAnimateCode(itemId, keyframes, duration, loop = false,
     // 2475333b). An engine without merge ignores the option and replaces.
     if (append)
         opts.mode = 'merge';
+    // EASEPLACE (queue item 5): which side of a key its easing shapes. The
+    // current studio reads (and removes) the option; an older one leaves it on
+    // the options object, which is how the result can say it was not applied.
+    if (easingAt !== undefined)
+        opts.easingAt = easingAt;
     // A FADE ON AN AUDIO ITEM WAS ACCEPTED AND NEVER HEARD. addAnimation keyframes
     // the audio item's sentinel, and the mix reads one static audioGain per clip,
     // so {audioGain: 0→1} answered success, duration 15, and exported at a flat
@@ -1394,12 +1651,16 @@ function generateKeyframeAnimateCode(itemId, keyframes, duration, loop = false,
     const loopNote = loop
         ? `, loopNote: ${JSON.stringify('loop:true repeats in the editor, but has been measured playing ONCE in an exported video and then holding the last keyframe. For an export longer than one cycle, check a frame in the second cycle — if it holds, write the keyframes out per cycle, or use a loop preset (pinepaper_animate), which does cycle in export.')}`
         : '';
-    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 easingNote = easingAt !== 'departure' && first?.easing && first.easing !== 'linear'
+        ? `, note: ${JSON.stringify(`easing '${first.easing}' is on the first keyframe, where it has no effect by default: easing shapes the segment ARRIVING at a keyframe. Put it on the keyframe you are moving to, or pass easingAt: 'departure' to read every easing as the move LEAVING its key (current studio).`)}`
         : '';
-    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 textKeysJs = unanimatedTextKeysJs(keyframes.flatMap((k) => Object.keys(k.properties ?? {})));
+    const textKeyCheck = textKeysJs ? `
+  const __ignored = ${textKeysJs};
+  if (__ignored.length) __warn.push(__ignored.join(', ') + ${UNANIMATED_TEXT_KEYS_SENTENCE});` : '';
+    const easingAtCheck = easingAt !== undefined ? `
+  if (__opts && Object.prototype.hasOwnProperty.call(__opts, 'easingAt')) __warn.push('easingAt ' + ${JSON.stringify(JSON.stringify(easingAt))} + ' was not applied: this studio predates it, so every easing was read as the move ARRIVING at its key. Put each easing on the key the move goes to instead.');` : '';
+    const runtimeWarning = `${textKeysJs ? ', ...(__ignored.length ? { ignoredProperties: __ignored } : {})' : ''}, ...(__warn.length ? { warning: __warn.join(' ') } : {})`;
     const addAnimTarget = itemId.startsWith('$') ? '_targetId' : `'${itemId}'`;
     return `
 // Apply keyframe animation to ${itemId}
@@ -1410,7 +1671,9 @@ 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(${addAnimTarget}, ${keyframesJson}, ${JSON.stringify(opts)});
+  const __opts = ${JSON.stringify(opts)};
+  app.addAnimation(${addAnimTarget}, ${keyframesJson}, __opts);
+  const __warn = [];${easingAtCheck}${textKeyCheck}
   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
@@ -1423,7 +1686,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: ${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} };
+  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}${runtimeWarning} };
 })();
 `.trim();
 }
@@ -1855,9 +2118,11 @@ const remaining = app.itemRegistry ? app.itemRegistry.getAll().length : 0;
  */
 function generateExportSVGCode() {
     return `
-// Export animated SVG
+// Export animated SVG. An export that produced nothing is a failure, named, not a success with an empty string.
 const svgString = app.exportAnimatedSVG();
-({ success: true, svgString, hasAnimations: svgString.includes('<animate') });
+(typeof svgString !== 'string' || svgString.length === 0)
+  ? ({ success: false, step: 'export', error: 'export failed at the export step: exportAnimatedSVG returned ' + (svgString === '' ? 'an empty string' : (svgString === null ? 'null' : typeof svgString)) + ', so there is no SVG to return' })
+  : ({ success: true, svgString, hasAnimations: svgString.includes('<animate') });
 `.trim();
 }
 /**
@@ -2185,6 +2450,15 @@ ${itemSettersApplyJs(s, '__sid', '__res')}
   return __res;
 })();`;
 }
+/**
+ * A batch op's item reference as a JS expression: `$N` is the Nth item this
+ * batch created, anything else is an id, quoted. Only digits follow the `$` —
+ * the raw splice it replaces put `$1);…;(` straight into the snippet, and an id
+ * with a quote in it broke the batch's syntax.
+ */
+export function batchRef(raw) {
+    return typeof raw === 'string' && /^\$\d+$/.test(raw) ? `__ref(${raw.slice(1)})` : JSON.stringify(String(raw));
+}
 function asReturningBody(snippet) {
     const single = snippet.trim();
     if (single.startsWith('(async function()'))
@@ -2730,7 +3004,9 @@ export class PinePaperCodeGenerator {
         // 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);
+        const code = generateKeyframeAnimateCode(validated.itemId, validated.keyframes, validated.duration, validated.loop, validated.timeOffset, validated.clipInPoint, validated.clipOutPoint, validated.timeUnits, 
+        // mode: 'merge' is the studio's name for append (B147).
+        validated.append === true || validated.mode === 'merge', validated.easingAt);
         if (!holds)
             return code;
         return `(async function() {
@@ -3370,8 +3646,15 @@ if (typeof _gen === 'function') {
   const targetId = nameToId['${target}'];
   if (sourceId && targetId) {
     const params = ${paramsStr};
-    app.addRelation(sourceId, targetId, '${type}', params);
-    results.relations.push({ source: '${source}', target: '${target}', type: '${type}' });
+    // A refused relation is not listed as made (owner rule 1).
+    if (app.addRelation(sourceId, targetId, '${type}', params)) {
+      results.relations.push({ source: '${source}', target: '${target}', type: '${type}' });
+    } else {
+      const __why = ${relationRefusalReasonJs(JSON.stringify(type))};
+      (results.relationsRefused = results.relationsRefused || []).push({ source: '${source}', target: '${target}', type: '${type}', reason: __why || 'the studio refused it' });
+      results.success = false;
+      results.error = 'the studio refused ' + results.relationsRefused.length + ' relation(s): ' + results.relationsRefused.map(function(r) { return r.type + ' ' + r.source + ' -> ' + r.target + ' (' + r.reason + ')'; }).join('; ') + '. The items were created.';
+    }
   }
 })();
 `);
@@ -4067,11 +4350,16 @@ throw new Error('Unknown diagram mode action: ${action}');
      */
     generateAgentBatchExecute(input) {
         const validated = AgentBatchExecuteInputSchema.parse(input);
-        const { operations, atomic } = validated;
+        const { atomic } = validated;
+        // ring / grid / orbit / stagger / patch become the batch's own ops (batch-macros.ts).
+        const operations = expandBatchMacros(validated.operations);
         const isAtomic = atomic !== false;
         // Fold duplicate keyframe_animate targets so a later op can't silently
         // clobber an earlier track (app.addAnimation replaces, never merges).
         const mergePlan = planKeyframeMerges(operations);
+        // Timeline ops compile here, on the server: the handler refuses a batch whose timeline does not compile before
+        // anything runs; a direct caller gets the op's own failure instead.
+        const timelines = compileBatchTimelines(operations);
         let code = `
 // Batch execute ${operations.length} operations
 (async function() {
@@ -4100,11 +4388,32 @@ throw new Error('Unknown diagram mode action: ${action}');
   };
   const results = [];
   let success = true;
+  // A failure's words, never "undefined" for a thrown non-Error.
+  const _why = (e, fb) => (e && typeof e.message === 'string' && e.message.trim()) ? e.message
+    : (typeof e === 'string' && e.trim()) ? e : fb;
+  // THE SCENE LINT AFTER THE CODE (FxTool lintScene().warnings): what the scene will show wrong without anything
+  // failing (a centred title that runs out of the frame). Carried out under __ppLint; the server moves it beside the
+  // result. A studio without lintScene says nothing.
+  const __ppLintNow = function () {
+    try {
+      if (typeof app === 'undefined' || !app || typeof app.lintScene !== 'function') return [];
+      const r = app.lintScene();
+      return r && Array.isArray(r.warnings) ? r.warnings : [];
+    } catch (e) {
+      return [{ code: 'LINT_FAILED', severity: 'info', message: 'the scene lint could not run: ' + ((e && typeof e.message === 'string' && e.message) || 'no reason given') }];
+    }
+  };
+  // Every failed op as { step, itemId, reason }, beside the per-op results.
+  const _failures = () => results.filter((r) => !r.success).map((r) => ({ step: r.step, itemId: r.itemId, reason: r.reason }));
 
   try {
 `;
         operations.forEach((op, index) => {
-            const opCode = this.generateBatchOperationCode(op, index, mergePlan);
+            const opCode = op.type === 'timeline'
+                ? (timelines.plans.has(index)
+                    ? emitTimelineOpBody(timelines.plans.get(index), (t) => (t.startsWith('$') ? `__ref(${t.substring(1)})` : JSON.stringify(t)))
+                    : `return { success: false, error: ${JSON.stringify(timelines.errors.filter((e) => e.path.startsWith(`operations[${index}]`)).map((e) => `${e.path}: ${e.message}`).join('; ') || 'the timeline did not compile')} };`)
+                : this.generateBatchOperationCode(op, index, mergePlan);
             // $N variable references are documented as "items CREATED in earlier
             // operations" — only `create` results may extend the itemIds array.
             // animate/keyframe_animate/modify/delete also return { itemId } (the
@@ -4115,6 +4424,10 @@ throw new Error('Unknown diagram mode action: ${action}');
             // vehicles, 2026-07-30). `group` already follows this rule by
             // returning groupId instead of itemId.
             const claimsItemSlot = op.type === 'create';
+            // The item this op acts on, for a failure's itemId: its own id field, else what its result names.
+            const o = op;
+            const opItem = [o.itemId, o.targetId, o.sourceId, o.id].find((v) => typeof v === 'string') ?? null;
+            const opStep = typeof o._step === 'string' ? `op ${index}: ${o._step}` : `op ${index} (${op.type})`;
             code += `
     // Operation ${index}: ${op.type}
     try {
@@ -4131,7 +4444,7 @@ throw new Error('Unknown diagram mode action: ${action}');
       if (failed${index}) {
         // ATOMIC: throw WITHOUT recording, and let the catch below record it
         // once. Doing both put two entries in for one failed op.
-        ${isAtomic ? `throw new Error(failed${index});` : `results.push({ index: ${index}, success: false, error: failed${index}, result: result${index} });
+        ${isAtomic ? `const __e${index} = new Error(failed${index}); __e${index}.itemId = (result${index} && typeof result${index}.itemId === 'string') ? result${index}.itemId : ${JSON.stringify(opItem)}; throw __e${index};` : `results.push({ index: ${index}, success: false, step: ${JSON.stringify(opStep)}, itemId: (result${index} && typeof result${index}.itemId === 'string') ? result${index}.itemId : ${JSON.stringify(opItem)}, reason: failed${index}, error: failed${index}, result: result${index} });
         success = false;`}
       } else {
         results.push({ index: ${index}, success: true, result: result${index} });
@@ -4140,7 +4453,8 @@ throw new Error('Unknown diagram mode action: ${action}');
         }` : ''}
       }
     } catch (opError) {
-      results.push({ index: ${index}, success: false, error: opError.message });
+      const __r${index} = _why(opError, 'operation ${index} (${op.type}) threw with no message');
+      results.push({ index: ${index}, success: false, step: ${JSON.stringify(opStep)}, itemId: (opError && typeof opError.itemId === 'string') ? opError.itemId : ${JSON.stringify(opItem)}, reason: __r${index}, error: __r${index} });
       ${isAtomic ? 'throw opError;' : 'success = false;'}
     }
 `;
@@ -4160,15 +4474,19 @@ throw new Error('Unknown diagram mode action: ${action}');
     }
     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 } };
+      ...(_failed.length ? { error: _failed.map((r) => 'op ' + r.index + ': ' + r.error).join('; '), failures: _failures() } : {}),
+      canvasSize: { width: _cs.width || 800, height: _cs.height || 600 }, ...((function () { const l = __ppLintNow(); return l.length ? { __ppLint: l } : {}; })()) };
   } 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 } };
+    const __fails = _failures();
+    const __reason = _why(e, 'the batch failed with no message');
+    return { success: false, error: __reason, itemIds, results, operationCount: ${operations.length},
+      failures: __fails.length ? __fails : [{ step: 'batch', itemId: null, reason: __reason }],
+      canvasSize: { width: _cs.width || 800, height: _cs.height || 600 }, ...((function () { const l = __ppLintNow(); return l.length ? { __ppLint: l } : {}; })()) };
   }
 })();
 `;
@@ -4205,7 +4523,7 @@ throw new Error('Unknown diagram mode action: ${action}');
                     'backgroundColor', 'generatorName', 'generatorParams', 'generatorRegion',
                     'width', 'height', 'preset', 'keyframes', 'duration', 'loop',
                     'maskPreset', 'maskType', 'maskOptions', 'effectType', 'effectParams',
-                    'action', 'time', 'append'
+                    'action', 'time', 'append', '_step'
                 ]);
                 for (const [k, v] of Object.entries(anyOp)) {
                     if (!batchKeys.has(k) && v !== undefined && opProps[k] === undefined) {
@@ -4250,9 +4568,7 @@ return __created;
                 return createCode;
             }
             case 'modify': {
-                const itemRef = op.itemId?.startsWith('$')
-                    ? `__ref(${op.itemId.substring(1)})`
-                    : `'${op.itemId}'`;
+                const itemRef = batchRef(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
                 // level, no-fill, lifetimes, smoothing and the unread-property report.
@@ -4265,15 +4581,21 @@ return __created;
                     .replace(/;\s*$/, '');
                 return `
 const __mid = ${itemRef};
+if (app.itemRegistry && app.itemRegistry.getItem && !app.itemRegistry.getItem(__mid) && typeof app.getItemsByName === 'function') {
+  // A NAME HELD BY SEVERAL ITEMS is refused, not resolved: getItemById answers
+  // the first holder, so a patch by name would change whichever came first.
+  const __held = app.getItemsByName(__mid) || [];
+  if (__held.length > 1) {
+    return { success: false, itemId: __mid, error: __held.length + ' items are named ' + JSON.stringify(__mid) + ' (' + __held.map(function (h) { return (h && h.data && h.data.id) || '?'; }).join(', ') + '); pass one of their ids.' };
+  }
+}
 const __r = await ${single};
 if (__r && __r.success !== false) __r.modified = true;
 return __r;
 `;
             }
             case 'animate':
-                const animItemRef = op.itemId?.startsWith('$')
-                    ? `__ref(${op.itemId.substring(1)})`
-                    : `'${op.itemId}'`;
+                const animItemRef = batchRef(op.itemId);
                 const animOpts = JSON.stringify(op.animationOptions || {});
                 return `
 const targetId = ${animItemRef};
@@ -4283,12 +4605,8 @@ app.animate(item, { animationType: '${op.animationType}', ...${animOpts} });
 return { itemId: targetId, animationType: '${op.animationType}' };
 `;
             case 'relation':
-                const srcRef = op.sourceId?.startsWith('$')
-                    ? `__ref(${op.sourceId.substring(1)})`
-                    : `'${op.sourceId}'`;
-                const tgtRef = op.targetId?.startsWith('$')
-                    ? `__ref(${op.targetId.substring(1)})`
-                    : `'${op.targetId}'`;
+                const srcRef = batchRef(op.sourceId);
+                const tgtRef = batchRef(op.targetId);
                 const relOpts = JSON.stringify(op.relationOptions || {});
                 return `
 const sourceId = ${srcRef};
@@ -4298,12 +4616,19 @@ const target = app.getItemById(targetId);
 if (!source) throw new Error('Source not found: ' + sourceId);
 if (!target) throw new Error('Target not found: ' + targetId);
 const relationId = app.addRelation(source, target, '${op.relationType}', ${relOpts});
+// NOT BOUND IS NOT A SUCCESS (owner rule 1, B119). addRelation answers false
+// when it refuses — spring_follow "not loaded yet" — and this op returned
+// { relationId: false } with nothing marking it failed, so the batch said
+// success over a relation that does not exist.
+if (!relationId) {
+  const __why = ${relationRefusalReasonJs(JSON.stringify(op.relationType))};
+  return { success: false, relationId: false, sourceId, targetId, relationType: ${JSON.stringify(op.relationType)},
+    error: 'the studio refused the ' + ${JSON.stringify(op.relationType)} + ' relation between ' + sourceId + ' and ' + targetId + ' — nothing was bound' + (__why ? ': ' + __why : '.') };
+}
 return { relationId, sourceId, targetId, relationType: '${op.relationType}' };
 `;
             case 'delete':
-                const delRef = op.itemId?.startsWith('$')
-                    ? `__ref(${op.itemId.substring(1)})`
-                    : `'${op.itemId}'`;
+                const delRef = batchRef(op.itemId);
                 return `
 const targetId = ${delRef};
 const item = app.getItemById(targetId);
@@ -4314,7 +4639,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('$') ? `__ref(${ref.substring(1)})` : `'${ref}'`);
+                const refs = (op.itemIds || []).map((ref) => batchRef(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.
@@ -4326,8 +4651,8 @@ return (function() {${this.groupCodeBody(idsArrayExpr, nameExpr)}
             case 'set_background':
                 const bgColor = op.backgroundColor || op.color || op.properties?.backgroundColor || op.properties?.color || '#000000';
                 return `
-app.setBackgroundColor('${bgColor}');
-return { success: true, backgroundColor: '${bgColor}' };
+app.setBackgroundColor(${JSON.stringify(String(bgColor))});
+return { success: true, backgroundColor: ${JSON.stringify(String(bgColor))} };
 `;
             case 'execute_generator':
                 const genName = op.generatorName || 'drawSunburst';
@@ -4358,14 +4683,12 @@ 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('$') ? `__ref(${op.itemId.substring(1)})` : `'${op.itemId}'`}, merged: true, mergedInto: ${foldTarget} };
+return { itemId: ${batchRef(op.itemId)}, merged: true, mergedInto: ${foldTarget} };
 `;
                 }
                 const mergedPayload = mergePlan?.merged.get(index);
                 const rawItemId = String(op.itemId ?? op.id ?? op.properties?.itemId ?? op.properties?.id);
-                const kfItemRef = rawItemId?.startsWith('$')
-                    ? `__ref(${rawItemId.substring(1)})`
-                    : `'${rawItemId}'`;
+                const kfItemRef = batchRef(rawItemId);
                 const kfSource = mergedPayload
                     ? mergedPayload.keyframes
                     : (op.keyframes || (op.properties && op.properties.keyframes) || (op.params && op.params.keyframes) || []);
@@ -4375,7 +4698,10 @@ return { itemId: ${op.itemId?.startsWith('$') ? `__ref(${op.itemId.substring(1)}
                     : (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;
+                // mode: 'merge' is the studio's spelling (its keyframe_track_replaced
+                // warning names it), so it means append here too (B147).
+                const kfAppend = op.append === true || op.properties?.append === true
+                    || op.mode === 'merge' || op.properties?.mode === 'merge';
                 // Batch ops are passthrough, so these arrive unvalidated: numbers only, and timeUnits from its enum.
                 const kfExtra = [];
                 for (const key of ['timeOffset', 'clipInPoint', 'clipOutPoint']) {
@@ -4387,9 +4713,9 @@ return { itemId: ${op.itemId?.startsWith('$') ? `__ref(${op.itemId.substring(1)}
                 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.`)}`;
+                const kfTextKeysJs = unanimatedTextKeysJs((kfSource || []).flatMap((k) => Object.keys(k.properties ?? {})));
+                const kfTextCheck = kfTextKeysJs ? `\nconst _kfIgnored = ${kfTextKeysJs};` : '';
+                const kfIgnored = kfTextKeysJs ? `, ...(_kfIgnored.length ? { ignoredProperties: _kfIgnored, warning: _kfIgnored.join(', ') + ${UNANIMATED_TEXT_KEYS_SENTENCE} } : {})` : '';
                 return `
 const targetId = ${kfItemRef};
 const _target = (app.getItemById && app.getItemById(targetId))
@@ -4399,14 +4725,12 @@ if (!_target) {
 }
 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} });
+app.addAnimation(targetId, ${kfJson}, { duration: ${kfDuration}, loop: ${kfLoop}${kfAppend ? ", mode: 'merge'" : ''}${kfExtraStr} });${kfTextCheck}
 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('$')
-                    ? `__ref(${op.itemId.substring(1)})`
-                    : `'${op.itemId}'`;
+                const maskItemRef = batchRef(op.itemId);
                 const maskOpts = JSON.stringify(op.maskOptions || {});
                 const preset = op.maskPreset || op.maskType || 'wipeLeft';
                 return `
@@ -4423,9 +4747,7 @@ return { success: !!maskedGroup, itemId: targetId, preset: '${preset}' };
 `;
             }
             case 'apply_effect': {
-                const effItemRef = op.itemId?.startsWith('$')
-                    ? `__ref(${op.itemId.substring(1)})`
-                    : `'${op.itemId}'`;
+                const effItemRef = batchRef(op.itemId);
                 const effParams = JSON.stringify(op.effectParams || {});
                 return `
 const targetId = ${effItemRef};
@@ -4910,6 +5232,19 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
   // cannot be kept accurate — it breaks on any edit above it — so this repo
   // does not use them. Camera animation still
   // drives motion during export — framing only fixes the output frame.
+  // THE SCENE LINT, BEFORE THE EXPORT (FxTool lintScene().warnings): what the file will show wrong without
+  // anything failing — a centre-anchored text that runs out of the frame exports as "IGNAL" for "SIGNAL". Read from the
+  // scene as it is, never a refusal; a studio without the rule says nothing, a lint that throws says so.
+  const __lint = (function () {
+    if (typeof app.lintScene !== 'function') return null;
+    try {
+      const r = app.lintScene();
+      return r && Array.isArray(r.warnings) ? r.warnings : null;
+    } catch (e) {
+      return [{ code: 'LINT_FAILED', severity: 'info', message: 'the scene lint could not run before the export: ' + ((e && typeof e.message === 'string' && e.message) || 'no reason given') }];
+    }
+  })();
+
   let cameraDims = null;
   if (framing === 'camera') {
     if (!['gif', 'apng', 'mp4', 'webm'].includes(format)) {
@@ -5458,7 +5793,7 @@ ${stillTime !== undefined ? `
                     if (typeof fr.embedded === 'number') __tl.fonts.embedded = fr.embedded; // cumulative for the document
                     if (typeof fr.hiddenTextItems === 'number') __tl.fonts.hiddenTextItems = (__tl.fonts.hiddenTextItems || 0) + fr.hiddenTextItems;
                   }
-                } catch (e) { if (!__tl.fonts) __tl.fonts = { embedded: 0, reason: e && e.message }; }
+                } catch (e) { if (!__tl.fonts) __tl.fonts = { embedded: 0, reason: (e && typeof e.message === 'string' && e.message) || 'embedding the text fonts failed with no reason given' }; }
               }
               if (jpg) doc.addImage(jpg, 'JPEG', 0, 0, wMM, hMM); else doc.addImage(png, 'PNG', 0, 0, wMM, hMM);
               if (__layer) {
@@ -5466,7 +5801,7 @@ ${stillTime !== undefined ? `
                   const tr = await app.exportEngine.addTextLayer(doc, { x: 0, y: 0, width: wMM, height: hMM });
                   if (tr && tr.ok !== false) { __tl.written += tr.linesWritten || 0; __tl.skipped += tr.linesSkipped || 0; }
                   else __tl.reasons.push(id + ': ' + ((tr && tr.reason) || 'refused'));
-                } catch (e) { __tl.reasons.push(id + ': ' + e.message); }
+                } catch (e) { __tl.reasons.push(id + ': ' + ((e && typeof e.message === 'string' && e.message) || 'the text layer failed with no reason given')); }
               }
               pagesOut.push({ sceneId: id, widthMM: Math.round(wMM * 10) / 10, heightMM: Math.round(hMM * 10) / 10 });
             }
@@ -5529,7 +5864,7 @@ ${stillTime !== undefined ? `
         result = { success: false, error: 'Unknown format: ' + format };
     }
   } catch (e) {
-    result = { success: false, error: e.message, platform, format };
+    result = { success: false, error: (e && typeof e.message === 'string' && e.message) || (typeof e === 'string' && e) || ('the ' + format + ' export threw with no message'), platform, format };
   }
 
   // One site, after every branch has set its result: a successful export says
@@ -5567,13 +5902,44 @@ ${stillTime !== undefined ? `
         result = Object.assign({}, result, { format, data: encoded, mimeType: mime, size: Math.round(String(encoded).length * 0.75), encodeQuality: settings.compression });
       }
     } catch (e) {
-      result = { success: false, platform, format, error: (e && e.message) || String(e) };
+      result = { success: false, platform, format, error: (e && typeof e.message === 'string' && e.message) || (typeof e === 'string' && e) || ('re-encoding the still as ' + format + ' failed with no message') };
     }
   }
 
   if (result && result.success) Object.assign(result, fidelity(format));
+  if (result && result.success && __lint && __lint.length && !result.lintWarnings) {
+    result.lintWarnings = __lint;
+    result.fidelity = result.fidelity || { warnings: [] };
+    result.fidelity.warnings = (result.fidelity.warnings || []).concat(__lint.map(function (w) {
+      return { code: String(w.code || 'lint'), message: String(w.message || w.code || 'scene lint warning'), ...(w.itemId ? { items: [w.itemId] } : {}) };
+    }));
+    if (result.fidelity.note) delete result.fidelity.note;
+  }
   if (result && result.success && __fit) result.platformFit = __fit;
-  // A LANDSCAPE CANVAS FOR A PORTRAIT PLATFORM (or the reverse) is not an
+${usesCanvasSize ? '' : `  // A PRESET SIZE IS NOT THE CANVAS SIZE, AND THAT IS SAID (21 PLATFORMOVERRIDE).
+  // A named platform renders the FILE at the preset's size; the canvas is not
+  // resized, so the scene keeps the canvas's layout, scaled to fill the file.
+  // A 640x360 canvas under youtube came back 1920x1080 with nothing said. The
+  // size the route reports is compared with the canvas; the current studio's
+  // video report warns about an upscale too, but as plain text this reply does
+  // not pass on, so it is said here for every studio.
+  // Not said for camera framing (the camera chooses that frame) or an
+  // unbounded canvas (its stills crop to the artwork, said on their own), and
+  // a scale the caller asked for is theirs, not the preset's.
+  if (result && result.success && framing !== 'camera' && __cv && !__cv.unbounded && __cv.width > 0 && __cv.height > 0
+    && result.dimensions && typeof result.dimensions === 'object' && result.dimensions.width > 0 && result.dimensions.height > 0) {
+    const __fw = result.dimensions.width, __fh = result.dimensions.height;
+    const __us = ${scale !== undefined ? scale : 1};
+    if (Math.abs(__fw - __cv.width * __us) > 2 || Math.abs(__fh - __cv.height * __us) > 2) {
+      const __k = Math.round((__fw / __cv.width) * 1000) / 1000;
+      result.platformSize = { preset: __presetBox.width + 'x' + __presetBox.height, canvas: __cv.width + 'x' + __cv.height, file: __fw + 'x' + __fh, scale: __k, canvasResized: false };
+      result.fidelity = result.fidelity || { warnings: [] };
+      result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'platform_size_differs_from_canvas',
+        message: 'the ' + platform + ' preset made the file ' + __fw + 'x' + __fh + ' while the canvas is ' + __cv.width + 'x' + __cv.height + ': the scene is drawn ' + (__k > 1 ? 'larger' : 'smaller') + ' (x' + __k + ') with the canvas\\'s layout, and the canvas itself is unchanged. For a file at the canvas size, export with platform: \\'auto\\'; for a scene laid out at ' + __fw + 'x' + __fh + ', resize the canvas (pinepaper_set_canvas_size) and re-lay it.' }]);
+      if (result.fidelity.note) delete result.fidelity.note;
+    }
+  }
+`}  // A LANDSCAPE CANVAS FOR A PORTRAIT PLATFORM (or the reverse) is not an
   // aspect nuance but the wrong deliverable: tiktok on a 16:9 canvas came out
   // 1920x1080 with only a note (round 10, 10.7). Said where a caller looks.
   if (result && result.success && __fit) {
@@ -7480,14 +7846,39 @@ ${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) {
         // An async IIFE is still a `(`-led expression statement, so the governor
         // captures its value, and executeCode's eval fallback already resolves a
         // returned promise. Both paths await it; neither needed changing.
+        //
+        // The code runs inside its own async arrow so its `return` is still its value; the value comes back under
+        // __ppValue with the scene lint beside it, and a throw comes back as { step, itemId, reason }, never a bare
+        // message (and never "undefined" for a thrown non-Error).
         return `
 // ${description}
 (async function() {
+  // THE SCENE LINT AFTER THE CODE (FxTool lintScene().warnings): what the scene will show wrong without anything
+  // failing (a centred title that runs out of the frame). Carried out under __ppLint; the server moves it beside the
+  // result. A studio without lintScene says nothing.
+  const __ppLintNow = function () {
+    try {
+      if (typeof app === 'undefined' || !app || typeof app.lintScene !== 'function') return [];
+      const r = app.lintScene();
+      return r && Array.isArray(r.warnings) ? r.warnings : [];
+    } catch (e) {
+      return [{ code: 'LINT_FAILED', severity: 'info', message: 'the scene lint could not run: ' + ((e && typeof e.message === 'string' && e.message) || 'no reason given') }];
+    }
+  };
+  let __ppValue;
   try {
+    __ppValue = await (async () => {
     ${validated.code}
+    })();
   } catch (error) {
-    return { success: false, error: error.message };
-  }
+    const __ppReason = (error && typeof error.message === 'string' && error.message.trim()) ? error.message
+      : (typeof error === 'string' && error.trim()) ? error : 'the custom code threw with no message';
+    return { success: false, step: 'execute_custom_code', itemId: (error && typeof error.itemId === 'string') ? error.itemId : null,
+      reason: __ppReason, error: __ppReason, ...((function () { const l = __ppLintNow(); return l.length ? { __ppLint: l } : {}; })()) };
+  }
+  // Only wrapped when the lint has something to say: otherwise the value is returned exactly as before.
+  const __ppL = __ppLintNow();
+  return __ppL.length ? { __ppValue: __ppValue, __ppLint: __ppL } : __ppValue;
 })();
 `.trim();
     }
@@ -7818,7 +8209,17 @@ ${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) {
 `.trim();
     }
     generateImportImage(input) {
-        const { url, position, maxWidth, maxHeight, mask, smoothing, maxEdge, nativeSize } = input;
+        const { url, position, maxWidth, maxHeight, mask, smoothing, maxEdge, nativeSize, shadowColor, shadowBlur, shadowOffset } = input;
+        // IMPORTSHADOW: the shadow keys, applied through the engine's own modify
+        // door once the image is placed (and masked) — the route modify_item takes.
+        const shadow = {};
+        if (shadowColor !== undefined)
+            shadow.shadowColor = shadowColor;
+        if (shadowBlur !== undefined)
+            shadow.shadowBlur = shadowBlur;
+        if (shadowOffset !== undefined)
+            shadow.shadowOffset = shadowOffset;
+        const hasShadow = Object.keys(shadow).length > 0;
         // Each fragment used to be written with a LEADING comma, as if it followed
         // an entry that no longer exists — so the first one opened the object with
         // `{, position: …}` and the emitted code was a syntax error. Passing any
@@ -7916,6 +8317,16 @@ ${mask ? `    // A MASK REPLACES THE RASTER (round 8 DD, 4.10). applyMask builds
     }
     if (app.itemRegistry && typeof app.itemRegistry.rebind === 'function') app.itemRegistry.rebind(itemId, masked);
     placed = masked;
+` : ''}${hasShadow ? `    // The shadow goes on what is DRAWN, after a mask has replaced the raster.
+    let __shadow = null;
+    {
+      const __want = ${JSON.stringify(shadow)};
+      let __ok = false;
+      try { __ok = app.modifyItem(itemId, __want) !== false; } catch (_) { __ok = false; }
+      __shadow = __ok
+        ? { applied: true, shadowColor: placed.shadowColor ? String(placed.shadowColor.toCSS ? placed.shadowColor.toCSS(true) : placed.shadowColor) : null, shadowBlur: placed.shadowBlur }
+        : { applied: false, warning: 'the image was imported but its shadow was not applied — set it with pinepaper_modify_item on ' + itemId + '.' };
+    }
 ` : ''}    const b = placed.bounds;
     if (!b || !(b.width > 0) || !(b.height > 0)) {
       return { success: false, itemId: itemId, error: 'the image was placed with no size (' + (b ? b.width + 'x' + b.height : 'no bounds') + ') — it may not have loaded. Nothing visible was drawn.' };
@@ -7924,7 +8335,7 @@ ${mask ? `    // A MASK REPLACES THE RASTER (round 8 DD, 4.10). applyMask builds
       success: true,
       itemId: itemId,
       message: 'Image imported and placed on canvas.',
-      bounds: { x: b.x, y: b.y, width: b.width, height: b.height }${mask ? `,\n      mask: '${mask}'` : ''},
+      bounds: { x: b.x, y: b.y, width: b.width, height: b.height }${mask ? `,\n      mask: '${mask}'` : ''}${hasShadow ? ',\n      shadow: __shadow' : ''},
       // Stored smaller than its source (the studio's cap): said, with the
       // way to keep every pixel. The studio reports native size where it can.
       ...((entry && entry.nativeWidth && entry.width && entry.nativeWidth > entry.width)
@@ -8275,6 +8686,53 @@ ${input.cutSound !== undefined ? `  const __cuts = (__cr && __cr.cuts) || (app.s
   };
 })();
 `.trim();
+    }
+    /**
+     * pinepaper_pattern (AR-2 P2): one stored declaration moves many items (FxTool app.addPattern / modifyPattern /
+     * removePattern / listPatterns / getPattern). No keyframes are written; the engine evaluates the node per frame.
+     */
+    generatePattern(input) {
+        const v = PatternInputSchema.parse(input);
+        const S = (x) => JSON.stringify(x);
+        const need = (fn) => `if (typeof app.${fn} !== 'function') return { success: false, error: 'app.${fn} unavailable — this studio predates patterns (FxTool AR-2 P1); update it' };`;
+        const idNeeded = v.action !== 'list' && !v.id ? `return { success: false, error: '${v.action} needs the pattern id' };` : '';
+        let body;
+        switch (v.action) {
+            case 'create': {
+                const spec = { id: v.id, kind: v.kind, members: v.members, params: v.params || {}, ...(v.window ? { window: v.window } : {}) };
+                body = `${need('addPattern')}
+  if (!${S(v.kind ?? null)}) return { success: false, error: 'create needs kind: phase_wave or stagger' };
+  if (!${S(v.members ?? null)}) return { success: false, error: 'create needs members: { names: [...] }, { ids: [...] }, { tag } or an array' };
+  const r = app.addPattern(${S(spec)});
+  return Object.assign({ success: !!(r && r.ok) }, r || {}, app.lastReceipt ? { receipt: app.lastReceipt } : {});`;
+                break;
+            }
+            case 'modify': {
+                const ch = { ...(v.params ? { params: v.params } : {}), ...(v.members ? { members: v.members } : {}), ...(v.window !== undefined ? { window: v.window } : {}) };
+                body = `${need('modifyPattern')}
+  const r = app.modifyPattern(${S(v.id)}, ${S(ch)});
+  return Object.assign({ success: !!(r && r.ok) }, r || {}, app.lastReceipt ? { receipt: app.lastReceipt } : {});`;
+                break;
+            }
+            case 'remove':
+                body = `${need('removePattern')}
+  const had = app.removePattern(${S(v.id)});
+  return had ? { success: true, removed: ${S(v.id)} } : { success: false, error: 'no pattern ' + ${S(JSON.stringify(v.id ?? ''))} };`;
+                break;
+            case 'get':
+                body = `${need('getPattern')}
+  const p = app.getPattern(${S(v.id)});
+  return p ? Object.assign({ success: true }, p) : { success: false, error: 'no pattern ' + ${S(JSON.stringify(v.id ?? ''))} };`;
+                break;
+            default:
+                body = `${need('listPatterns')}
+  const list = app.listPatterns();
+  return { success: true, count: list.length, patterns: list };`;
+        }
+        return `(function() {
+  ${idNeeded}
+  ${body}
+})();`;
     }
     generateStagger(input) {
         const validated = StaggerInputSchema.parse(input);
@@ -10115,6 +10573,9 @@ if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
 (async function() {
   if (!app.exportEngine || !app.exportEngine.exportWidget) return { error: 'Widget export not available' };
   const result = await app.exportEngine.exportWidget(${JSON.stringify(opts)});
+  if (!result || typeof result.json !== 'string' || result.json.length === 0) {
+    return { success: false, step: 'export', error: 'export failed at the export step: exportWidget returned no scene JSON' + (result && result.error ? ' (' + result.error + ')' : '') };
+  }
   // THE EMBED BOX WAS ALWAYS 16:9, AND IT IS NOT SELF-CONTAINED (round 9 GG,
   // 8.32). The engine writes aspect-ratio: 16/9 and max-width: 800px whatever
   // the scene, so a 300x250 ad sat letterboxed in a wide box. The box is sized
@@ -10150,6 +10611,9 @@ if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
 (async function() {
   if (!app.exportEngine || !app.exportEngine.exportWidgetHTML) return { error: 'Widget HTML export not available' };
   const result = await app.exportEngine.exportWidgetHTML(${JSON.stringify(opts)});
+  if (!result || typeof result.html !== 'string' || result.html.length === 0) {
+    return { success: false, step: 'export', error: 'export failed at the export step: exportWidgetHTML returned no page' + (result && result.error ? ' (' + result.error + ')' : '') };
+  }
   ${input.lang || input.dir || input.alt ? `// lang / dir / alt on the engine's page (it writes <html lang="en"> and no
   // text alternative). Applied as string edits on the one <html> tag and the
   // first <canvas>; the result says which landed.
@@ -11043,7 +11507,9 @@ ${checks.includes('contrast') ? `  // SAMPLED OVER TIME (round 12, 12.9): text i
         app.create(op.type, { id: op.id, x: op.x, y: op.y, width: op.width, height: op.height });
         itemIds.push(op.id);
       } else if (op.op === 'addRelation') {
-        app.addRelation(op.from, op.to, op.relation, op.params || {});
+        if (!app.addRelation(op.from, op.to, op.relation, op.params || {})) {
+          errors.push({ op: op.op, id: op.from + '->' + op.to, error: 'the studio refused the ' + op.relation + ' relation' });
+        }
       }
     } catch (e) {
       errors.push({ op: op.op, id: op.id || (op.from + '->' + op.to), error: e && e.message });
@@ -11070,7 +11536,10 @@ ${checks.includes('contrast') ? `  // SAMPLED OVER TIME (round 12, 12.9): text i
     return { success: false, error: 'app.lintScene unavailable — update FxTool to a build with the relational linter (S12-E2)' };
   }
   const result = app.lintScene(${optsJson});
-  return { success: true, density: result.density, suggestions: result.suggestions };
+  // warnings: what the engine's own rules found (TEXT_CLIPS_FRAME: a centre-anchored text running past the
+  // frame edge). Passed through when the studio reports them; an older studio has none to pass.
+  return { success: true, density: result.density, suggestions: result.suggestions,
+    ...(Array.isArray(result.warnings) && result.warnings.length ? { warnings: result.warnings } : {}) };
 })();`.trim();
     }
     /**
@@ -11592,9 +12061,41 @@ ${guard}
   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 };
+  // THE ACTOR AT THE FIRST BEAT, not where the playhead left it (B154 /
+  // HOOKCLOCK3). Live values of a keyframed item depend on the playhead, so a
+  // second call anchored at +0 / +57 / +22 / +43 px from session to session
+  // and multiplied scales the first track had applied. app.poseAt (FxTool,
+  // claude/engine-core-queue) answers at a track time; older studios fall back
+  // to the live read.
+  const __at0 = ${S(Math.min(...input.beats.map((b) => Number(b && b.at) || 0)))};
+  // A track that already keys the beat properties defines the pose before the
+  // first beat; the B109 hold key at 0 would overwrite its key there. A track
+  // of other properties (a colour) still needs the hold key.
+  const __beatProps = ['x', 'y', 'scaleX', 'scaleY', 'scale', 'rotation', 'opacity', 'position'];
+  const __hasTrack = !!(__it.data && Array.isArray(__it.data.keyframes) && __it.data.keyframes.some(function (k) {
+    return Object.keys((k && k.properties) || {}).some(function (p) { return __beatProps.indexOf(p) >= 0; });
+  }));
+  let __pose = null;
+  let __poseErr = null;
+  if (typeof app.poseAt === 'function') {
+    try { __pose = app.poseAt(__it, __at0); } catch (e) { __poseErr = (e && e.message) || String(e); }
+    if (__pose && !(isFinite(__pose.x) && isFinite(__pose.y) && __pose.width > 0 && __pose.height > 0)) __pose = null;
+  }
+  const __anchorWarnings = [];
+  if (!__pose && __hasTrack) {
+    __anchorWarnings.push((__poseErr ? 'app.poseAt failed (' + __poseErr + ')' : 'this studio has no app.poseAt')
+      + ', so the beats start from the actor\\'s LIVE transform, which on a keyframed actor is wherever the playhead left it: the first move can jump. Update the studio, or seek to ' + __at0 + ' s before choreographing.');
+  }
+  if (!__pose && __it.className === 'Raster' && ${S(input.beats.some((b) => b && b.verb === 'roll'))}) {
+    __anchorWarnings.push((__poseErr ? 'app.poseAt failed' : 'this studio has no app.poseAt')
+      + ', so the roll turns on the picture\\'s half-box, not its drawn radius: a picture with a transparent margin slides as it rolls.');
+  }
+  const __actor = __pose
+    ? { x: __pose.x, y: __pose.y, w: __pose.width, h: __pose.height, sx: __pose.scaleX || 1, sy: __pose.scaleY || 1, rot: isFinite(__pose.rotation) ? __pose.rotation : (__it.rotation || 0) + __baked, hasTrack: __hasTrack,
+        rollRadius: __pose.drawnHeight ? __pose.drawnHeight / 2 : undefined }
+    : { 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, hasTrack: __hasTrack };
   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 : [];
@@ -11603,7 +12104,7 @@ ${guard}
   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();
+  const __warnings = __anchorWarnings.concat(__r.warnings || []);
   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.');
   }
@@ -11964,29 +12465,56 @@ ${cam ? `  // The camera rides the SAME timing: framing each state as its morph
         }
     }
     /** pinepaper_emitter (D29): create('emitter', spec) / setEmitter(id, patch). */
-    generateEmitter(input) {
+    generateEmitter(raw) {
         const S = (v) => JSON.stringify(v);
+        const normalized = normalizeEmitterSpec(raw.spec, raw.action !== 'set');
+        const input = { ...raw, spec: normalized.spec };
+        // A COUNT OVER THE CAP IS SAID (B144). The cap is 10000 a burst on the
+        // current studio and was 2000 before it, clamped in silence (2300 drew
+        // ~1940). Which applies is read from the spec the studio STORED — its
+        // normalised count is what it draws — so the reply names the number
+        // actually drawn on whichever studio ran it. Only when nothing can be read
+        // back does it fall back to what is known without the studio.
+        const checks = emitterCountsToCheck(input.spec);
+        const fallback = emitterCountWarnings(input.spec);
+        const capFn = checks.length ? `
+  function __capWarnings(stored) {
+    const checks = ${S(checks)};
+    if (!stored || typeof stored !== 'object') return ${S(fallback)};
+    const out = [];
+    for (const c of checks) {
+      const b = c.index === null ? null : (Array.isArray(stored.bursts) ? stored.bursts[c.index] : null);
+      const drawn = b && typeof b.count === 'number' ? b.count : stored.count;
+      if (typeof drawn !== 'number') return ${S(fallback)};
+      if (drawn < c.asked) out.push(c.where + ' ' + c.asked + ' is over this studio\\'s per-burst cap, so it draws ' + drawn + '. Split it into bursts at the same t for more.');
+    }
+    return out;
+  }` : '';
+        const fixed = normalized.warnings;
+        const capJs = (stored) => checks.length || fixed.length
+            ? `, ...((function(w) { return w.length ? { warnings: w } : {}; })(${S(fixed)}.concat(${checks.length ? `__capWarnings(${stored})` : '[]'})))`
+            : '';
         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.' }; }
+  if (typeof app.setEmitter !== 'function') { return { success: false, error: 'this studio has no emitter item (app.setEmitter) — it predates FxTool D29.' }; }${capFn}
   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 };
+  return { success: true, action: 'set', itemId: ${S(input.itemId)}, spec: r.spec${capJs('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.' }; }
+  if (typeof app.setEmitter !== 'function') { return { success: false, error: 'this studio has no emitter item (app.setEmitter) — it predates FxTool D29.' }; }${capFn}
   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 };
+  return { success: true, action: 'create', itemId: id${capJs('it.data && it.data.emitter')} };
 })();`.trim();
     }
     /** pinepaper_render_hook (D29): drawing saved as source, re-installed on load. */
@@ -12982,7 +13510,7 @@ ${needWorld}
      * already decided by a pure function, so nothing is left for the page to
      * work out.
      */
-    generateDesignCompose(scene, ops, style, sizeWarning) {
+    generateDesignCompose(scene, ops, style, sizeWarning, report = {}) {
         const S = (v) => JSON.stringify(v);
         return `
 // Design: compose a ${style} scene — ${ops.length} items, laid out server-side
@@ -13012,7 +13540,7 @@ ${needWorld}
   // success is worse than a poster that says which four elements are missing.
   return { success: failed.length === 0, style: ${S(style)}, itemIds: ids, itemCount: ids.length, failed: failed,
     ...(canvasResized ? { canvasResized: canvasResized, note: 'the canvas was resized to the composition' + (${S(sizeWarning ?? '')} ? '' : '; pass width and height to compose at your canvas size') } : {}),
-    ...(${S(sizeWarning ?? '')} ? { warning: ${S(sizeWarning ?? '')} } : {}) };
+    ...(${S(sizeWarning ?? '')} ? { warning: ${S(sizeWarning ?? '')} } : {}), ...${S(report)} };
 })();`.trim();
     }
     /**
@@ -13253,10 +13781,15 @@ ${guard('exportPNGSequence')}
     return Object.assign({ success: true, format: 'png-sequence', data: dataUrl, mimeType: out.type || 'application/zip', size: out.size }, __pngSeqDefaults);
   }
   if (Array.isArray(out)) {
-    return { success: true, format: 'png-sequence', frames: out.length,
+    // NOT A SAVED FILE, and said so in fields: file null, and why.
+    return { success: true, format: 'png-sequence', frames: out.length, file: null,
+      why: 'the frames stayed in the page: the studio returned them as a list of frames, not a file, so no file was written. Pass download: true to have the browser download them as a zip.',
       note: 'the frames stayed in the page — pass download: true to write them out.' };
   }
-  return { success: true, format: 'png-sequence', result: out };
+  // download: true — the studio handed the zip to the BROWSER's download, so no bytes reached this server and no file
+  // was written by it. Said in fields, so it cannot be read as a saved file.
+  return { success: true, format: 'png-sequence', result: out, file: null,
+    why: 'the studio handed the zip to the browser as a download (download: true): it went to the browser\\'s download folder, no bytes reached the MCP server, and the server wrote no file.' };
 })();`.trim();
         }
     }