@pinepaper.studio/mcp-server 1.6.23 → 1.6.25

package/dist/types/code-generator.js

@@ -5,11 +5,15 @@
  * 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 { WORLD3D_COLOR_PATHS, PATTERN_KINDS } 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 { NORMALIZE_PARAM_READS, MODIFY_CHANGE_READS } from '../tools/shape-params.js';
+import { CREATE_KNOWN_KEYS } from '../tools/create-known-keys.js';
+import { jsLiteral } from '../utils/js-literal.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 +30,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
@@ -144,7 +148,16 @@ function generateBlendModeCode(itemVarName, blendMode) {
 /**
  * Template for creating items with support for gradients, shadows, and blend modes
  */
+const UNSAFE_ID_CHARS = /['"`\\\n\r\u2028\u2029]/;
 function generateCreateItemCode(itemType, position, properties, dataFlags, positionGiven = true) {
+    // AN ID OF YOUR OWN IS SPLICED INTO LATER CALLS' CODE. Most tools now quote it,
+    // not all yet, so an id carrying a quote, a backslash or a line break would
+    // break those later calls: refused here, by name, before anything is made.
+    if (typeof properties.id === 'string' && UNSAFE_ID_CHARS.test(properties.id)) {
+        return `
+// Create ${itemType} — refused: an id later calls could not address
+({ success: false, error: ${jsLiteral(`properties.id ${JSON.stringify(properties.id)} has a quote, backslash or line break, so later calls could not address the item. Nothing was made. Use letters, digits, spaces, - and _ (e.g. "bobs-hat").`)} });`.trim();
+    }
     // Colour objects are gradient specs: normalised, or refused by name.
     for (const key of ['color', 'fillColor', 'strokeColor']) {
         const v = properties[key];
@@ -211,6 +224,10 @@ function generateCreateItemCode(itemType, position, properties, dataFlags, posit
     // All three now mean no fill, applied after the item exists.
     const noFill = (v) => v === null || (typeof v === 'string' && /^(transparent|none)$/i.test(v.trim()));
     const clearFill = (fillColor !== undefined && noFill(fillColor)) || (fillColor === undefined && color !== undefined && noFill(color));
+    // A STROKE WITH NO FILL IS AN OUTLINE (issue #29 O7). A closed shape given
+    // only a strokeColor took the engine's default fill, so a ring came out as a
+    // blue disc with a red rim. Naming a stroke and no fill now means no fill.
+    const outlineOnly = isStrokeOnly(itemType, properties) && !clearFill;
     // `color` ON A CLOSED PATH IS ITS FILL.
     //
     // The engine's path branch paints `color` as the STROKE whenever no fillColor
@@ -309,7 +326,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 = `
@@ -334,7 +352,7 @@ const item = app.create('${itemType}', ${JSON.stringify(params, null, 2)});`;
     if (blendMode) {
         code += '\n' + generateBlendModeCode('item', blendMode);
     }
-    if (clearFill)
+    if (clearFill || outlineOnly)
         code += `\nitem.fillColor = null;`;
     // DASHES, CAPS AND JOINS FOR EVERY SHAPE (round 7 Z, 1.54). create() applies
     // them only in its path / line / pattern branches; the shared tail sets a
@@ -398,15 +416,27 @@ const item = app.create('${itemType}', ${JSON.stringify(params, null, 2)});`;
         code += `\nif (app.setDynamicContent) app.setDynamicContent(item, '${contentType}', ${JSON.stringify(opts)});`;
     }
     const loadsFont = itemType === 'text' && typeof properties.fontFamily === 'string' && properties.fontFamily.trim() !== '';
+    // A LINE WITH `from` IS DRAWN WHERE from AND to SAY (issue #29 O8). They are
+    // canvas coordinates, so position does not move it, and the result reported
+    // the position asked for while the line sat at the top-left: a line from
+    // [0, 0] to [200, 0] "created at (400, 300)". The result reads where it is.
+    const lineIgnoresPosition = itemType === 'line' && properties.from !== undefined && positionGiven;
+    const reportActualPosition = omitXY || lineIgnoresPosition;
+    const warnings = [];
+    if (ignored.length > 0) {
+        warnings.push(`${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.');
+    }
+    if (lineIgnoresPosition) {
+        warnings.push('a line runs from `from` to `to` in canvas coordinates, so position did not move it: position is where the line is now. Give the endpoints where the line goes.');
+    }
     code += `
 const itemId = item.data.registryId;
 app.historyManager.saveState();
 
 // Return item info
-({ 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.')}`
-        : ''} });`;
+({ itemId, type: '${itemType}'${outlineOnly ? `, fill: ${JSON.stringify(OUTLINE_NOTE)}` : ''}${textFit ? ', textFit: __textFit' : ''}${textDirection ? ', direction: __direction' : ''}${textTabular ? ', tabularFigures: __tabular' : ''}${createFillOpacity ? ', fillOpacity: __fillOpacity' : ''}${textStrokePos ? ', strokePosition: __strokePos' : ''}, position: ${reportActualPosition ? `(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)}` : ''}${warnings.length > 0 ? `, warning: ${JSON.stringify(warnings.join(' '))}` : ''} });`;
     // Loading a font is async, and it has to happen BEFORE create() measures the
     // text — so only this case becomes an async IIFE; every other create stays a
     // plain snippet ending in its (-led result.
@@ -434,24 +464,6 @@ const MODIFY_DID_YOU_MEAN = {
     scaling: 'scale', size: 'width / height', rotate: 'rotation', angle: 'rotation', shear: 'skewX / skewY', skew: 'skewX / skewY',
     alpha: 'opacity', text: 'content', stroke_width: 'strokeWidth', lineWidth: 'strokeWidth',
 };
-/**
- * Every `properties` key create_item can act on: what the engine's create()
- * and normalizeParams() read (generated — see shape-params.ts), plus the keys
- * generateCreateItemCode consumes itself before the engine sees them.
- */
-const CREATE_KNOWN_KEYS = new Set([
-    ...ACCEPTED_CREATE_PARAMS,
-    ...NORMALIZE_PARAM_READS,
-    // withRadiusAxes, gradients / shadow / blend / opacity emitted here, and
-    // setDynamicContent for text.
-    'radiusX', 'radiusY', 'contentType', 'contentFormat', 'countdownTarget', 'countdownEndText',
-    // 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.
  *
@@ -472,11 +484,11 @@ export function emitEnsureFont(family) {
     return `
 let __font = null;
 if (typeof app.checkFont === 'function') {
-  const __v0 = app.checkFont(${JSON.stringify(family)});
+  const __v0 = app.checkFont(${jsLiteral(family)});
   if (__v0 && __v0.available === false) {
     if (typeof app.ensureFontsLoaded === 'function') { try { await app.ensureFontsLoaded('all'); } catch (_) { /* reported below */ } }
-    try { if (typeof document !== 'undefined' && document.fonts) await document.fonts.load('16px ' + ${JSON.stringify(JSON.stringify(primary))}); } catch (_) { /* reported below */ }
-    let __v1 = app.checkFont(${JSON.stringify(family)});
+    try { if (typeof document !== 'undefined' && document.fonts) await document.fonts.load('16px ' + ${jsLiteral(jsLiteral(primary))}); } catch (_) { /* reported below */ }
+    let __v1 = app.checkFont(${jsLiteral(family)});
     let __via = 'studio';
     // Not in the studio's own sheets (Monoton, a common neon face, is not):
     // the page's CSP allows fonts.googleapis.com stylesheets and
@@ -484,21 +496,21 @@ if (typeof app.checkFont === 'function') {
     if (!(__v1 && __v1.available === true) && typeof document !== 'undefined' && document.head) {
       __via = 'google-fonts';
       await new Promise(function(res) {
-        const id = 'pp-gf-' + ${JSON.stringify(primary)}.replace(/[^a-z0-9]+/gi, '-');
+        const id = 'pp-gf-' + ${jsLiteral(primary)}.replace(/[^a-z0-9]+/gi, '-');
         if (document.getElementById(id)) return res();
         const l = document.createElement('link');
         l.id = id; l.rel = 'stylesheet';
-        l.href = 'https://fonts.googleapis.com/css2?family=' + encodeURIComponent(${JSON.stringify(primary)}).replace(/%20/g, '+') + '&display=swap';
+        l.href = 'https://fonts.googleapis.com/css2?family=' + encodeURIComponent(${jsLiteral(primary)}).replace(/%20/g, '+') + '&display=swap';
         l.onload = res; l.onerror = res; setTimeout(res, 5000);
         document.head.appendChild(l);
       });
-      try { if (document.fonts) await document.fonts.load('16px ' + ${JSON.stringify(JSON.stringify(primary))}); } catch (_) { /* reported below */ }
-      __v1 = app.checkFont(${JSON.stringify(family)});
+      try { if (document.fonts) await document.fonts.load('16px ' + ${jsLiteral(jsLiteral(primary))}); } catch (_) { /* reported below */ }
+      __v1 = app.checkFont(${jsLiteral(family)});
     }
     __font = (__v1 && __v1.available === true)
-      ? { family: ${JSON.stringify(primary)}, available: true, loadedNow: true, via: __via }
-      : { family: ${JSON.stringify(primary)}, available: false,
-          warning: ${JSON.stringify(primary)} + ' could not be loaded, so this text is drawn in a fallback face. '
+      ? { family: ${jsLiteral(primary)}, available: true, loadedNow: true, via: __via }
+      : { family: ${jsLiteral(primary)}, available: false,
+          warning: ${jsLiteral(primary)} + ' could not be loaded, so this text is drawn in a fallback face. '
             + ((__v1 && __v1.reason) || '') + ' font list_available names the families this studio can load.' };
   }
 }`;
@@ -569,13 +581,13 @@ function takeDirection(props) {
 function emitDirectionCheck(itemExpr, req) {
     if ('error' in req)
         return `
-const __direction = ${JSON.stringify({ applied: false, error: req.error })};`;
-    const v = JSON.stringify(req.value);
+const __direction = ${jsLiteral({ applied: false, error: req.error })};`;
+    const v = jsLiteral(req.value);
     return `
 const __direction = (function(it) {
   if (!it || it.className !== 'PointText') return { applied: false, note: 'direction applies to text items only.' };
   return it.data && it.data.direction === ${v}
-    ? { applied: true, value: ${v}${req.resolved ? `, resolved: ${JSON.stringify(req.resolved)}` : ''} }
+    ? { applied: true, value: ${v}${req.resolved ? `, resolved: ${jsLiteral(req.resolved)}` : ''} }
     : { applied: false, note: 'this studio does not set a paragraph direction (it needs an engine with RTL text support): the text is laid out left-to-right.' };
 })(${itemExpr});`;
 }
@@ -675,7 +687,7 @@ function takeStrokePosition(props, allowNull) {
 }
 function emitStrokePositionCheck(itemExpr, req) {
     if ('error' in req)
-        return `\nconst __strokePos = ${JSON.stringify({ applied: false, error: req.error })};`;
+        return `\nconst __strokePos = ${jsLiteral({ applied: false, error: req.error })};`;
     if (req.value === 'center')
         return `\nconst __strokePos = { applied: true, value: 'center' };`;
     return `
@@ -693,7 +705,7 @@ function anchorHold(anchor) {
 function emitTextFit(itemExpr, box, holdFallback = 'undefined') {
     return `
 if (typeof app.fitText === 'function') {
-  const __fbox = ${JSON.stringify(box)};
+  const __fbox = ${jsLiteral(box)};
   if (__fbox.hold === undefined) { const __h = ${holdFallback}; if (__h) __fbox.hold = __h; }
   const __fr = app.fitText(${itemExpr}, __fbox);
   __textFit = __fr && __fr.ok !== false
@@ -734,13 +746,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) {
@@ -749,10 +774,11 @@ function emitTextStyle(itemExpr, props) {
   const edge = function(b) { return j === 'left' ? b.left : j === 'right' ? b.right : b.center.x; };
   const b0 = it.bounds, ax = edge(b0), ay = b0.center.y;
   ${weight !== undefined || props.fontStyle !== undefined
-        ? `it.fontWeight = ${JSON.stringify(`${italic ? 'italic ' : ''}${weight ?? 'normal'}`)};`
+        ? `it.fontWeight = ${jsLiteral(`${italic ? 'italic ' : ''}${weight ?? 'normal'}`)};`
         : ''}
   ${leading !== undefined ? `it.leading = ${leading};` : ''}
   ${lh !== undefined ? `it.leading = ${lh} <= 4 ? ${lh} * it.fontSize : ${lh};` : ''}
+  ${ls !== undefined ? `it.letterSpacing = ${jsLiteral(ls)};` : ''}
   const b1 = it.bounds;
   it.position = it.position.add([ax - edge(b1), ay - b1.center.y]);
 })(${itemExpr});`;
@@ -901,6 +927,9 @@ function emitLifetime(itemExpr, bornAt, ttl) {
  * Template for modifying items
  */
 function generateModifyItemCode(itemId, properties, dataFlags) {
+    // The id as a quoted literal everywhere below: an id is caller text ("Bob's hat" is a valid properties.id), and a
+    // quote spliced raw ended the string and broke the whole call.
+    const ID = jsLiteral(itemId);
     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
@@ -944,23 +973,23 @@ function generateModifyItemCode(itemId, properties, dataFlags) {
     // The warning the engine logs on that path is console.warn, which production
     // strips, so the failure was invisible twice over.
     let code = `
-// Modify item ${itemId}
+// Modify item ${ID}
 let _modified = true;`;
     if (Object.keys(restProperties).length > 0) {
         code += `
-_modified = app.modifyItem('${itemId}', ${JSON.stringify(restProperties, null, 2)}) !== false;
-if (!_modified) { return { success: false, error: 'no item ${itemId} — nothing was modified' }; }`;
+_modified = app.modifyItem(${ID}, ${jsLiteral(restProperties, 2)}) !== false;
+if (!_modified) { return { success: false, error: 'no item ' + ${ID} + ' — nothing was modified' }; }`;
     }
     else {
         code += `
-if (!app.getItemById('${itemId}')) { return { success: false, error: 'no item ${itemId}' }; }`;
+if (!app.getItemById(${ID})) { return { success: false, error: 'no item ' + ${ID} }; }`;
     }
     // Handle dynamic content type changes
     if (contentType !== undefined) {
         if (contentType === null || contentType === 'none' || contentType === '') {
             // Remove dynamic content
             code += `
-const entry = app.itemRegistry.get('${itemId}');
+const entry = app.itemRegistry.get(${ID});
 if (entry && entry.item && app.removeDynamicContent) app.removeDynamicContent(entry.item);`;
         }
         else {
@@ -973,8 +1002,8 @@ if (entry && entry.item && app.removeDynamicContent) app.removeDynamicContent(en
             if (countdownEndText)
                 opts.countdownEndText = countdownEndText;
             code += `
-const entry = app.itemRegistry.get('${itemId}');
-if (entry && entry.item && app.setDynamicContent) app.setDynamicContent(entry.item, '${contentType}', ${JSON.stringify(opts)});`;
+const entry = app.itemRegistry.get(${ID});
+if (entry && entry.item && app.setDynamicContent) app.setDynamicContent(entry.item, '${contentType}', ${jsLiteral(opts)});`;
         }
     }
     // AN AUDIO ITEM'S LEVEL IS NOT AN ITEM PROPERTY. modifyItem applies changes
@@ -986,13 +1015,13 @@ if (entry && entry.item && app.setDynamicContent) app.setDynamicContent(entry.it
     if (levelKey) {
         const level = Math.max(0, Math.min(1, properties[levelKey]));
         code += `
-const _ae = app.itemRegistry.get('${itemId}');
+const _ae = app.itemRegistry.get(${ID});
 if (_ae && _ae.type === 'audio') {
   _ae.properties = _ae.properties || {};
   _ae.properties.audioGain = ${level};
   _ae.properties.gain = ${level};
   const _A = (typeof window !== 'undefined') && window.PinePaperAgent;
-  const _m = _A && typeof _A.listMedia === 'function' ? _A.listMedia().find(function(x) { return x.registryId === '${itemId}'; }) : null;
+  const _m = _A && typeof _A.listMedia === 'function' ? _A.listMedia().find(function(x) { return x.registryId === ${ID}; }) : null;
   if (_m && app.audioLayer && typeof app.audioLayer.setVolume === 'function') app.audioLayer.setVolume(${level}, _m.id);
 }`;
     }
@@ -1000,17 +1029,17 @@ if (_ae && _ae.type === 'audio') {
     // does not pass on; applied to a raster, or to the raster an image group holds.
     if (typeof properties.smoothing === 'string') {
         code += `
-const _sm = app.itemRegistry.get('${itemId}');
+const _sm = app.itemRegistry.get(${ID});
 const _smR = _sm && _sm.item && (_sm.item.className === 'Raster' ? _sm.item
   : (typeof _sm.item.getItem === 'function' ? _sm.item.getItem({ className: 'Raster' }) : null));
-if (_smR) _smR.smoothing = ${JSON.stringify(properties.smoothing)};`;
+if (_smR) _smR.smoothing = ${jsLiteral(properties.smoothing)};`;
     }
     // No fill on modify too: null / 'transparent' / 'none' clear it outright,
     // after modifyItem, which would otherwise read 'transparent' as black.
     const fillNone = (v) => v === null || (typeof v === 'string' && /^(transparent|none)$/i.test(v.trim()));
     if (fillNone(properties.fillColor) || (properties.fillColor === undefined && properties.color !== undefined && fillNone(properties.color))) {
         code += `
-const _nf = app.itemRegistry.get('${itemId}');
+const _nf = app.itemRegistry.get(${ID});
 if (_nf && _nf.item) _nf.item.fillColor = null;`;
     }
     // SKEW AND AFFINE, FOR MOCKUPS (round 9 HH). A box face or a phone screen in
@@ -1026,7 +1055,7 @@ if (_nf && _nf.item) _nf.item.fillColor = null;`;
     const affine = skewX !== 0 || skewY !== 0 || matrix !== null;
     if (affine) {
         code += `
-const _af = app.itemRegistry.get('${itemId}');
+const _af = app.itemRegistry.get(${ID});
 const _afi = _af && _af.item;
 if (_afi) {
   ${skewX !== 0 || skewY !== 0 ? `_afi.shear(Math.tan(${skewX} * Math.PI / 180), Math.tan(${skewY} * Math.PI / 180), _afi.bounds.center);` : ''}
@@ -1037,30 +1066,32 @@ if (_afi) {
     if (modFit) {
         code += `
 let __textFit = null;
-const _tf = app.itemRegistry.get('${itemId}');${emitTextFit('_tf && _tf.item', modFit, JSON.stringify(anchorHold(properties.anchor ?? properties.origin) ?? null) + " || (_tf && _tf.item && _tf.item.data && _tf.item.data.fitBox && _tf.item.data.fitBox.hold)")}`;
+const _tf = app.itemRegistry.get(${ID});${emitTextFit('_tf && _tf.item', modFit, jsLiteral(anchorHold(properties.anchor ?? properties.origin) ?? null) + " || (_tf && _tf.item && _tf.item.data && _tf.item.data.fitBox && _tf.item.data.fitBox.hold)")}`;
     }
     const textStyle = emitTextStyle('_ts && _ts.item', properties);
     if (textStyle) {
         code += `
-const _ts = app.itemRegistry.get('${itemId}');${textStyle}`;
+const _ts = app.itemRegistry.get(${ID});${textStyle}`;
     }
     const modLifetime = properties.bornAt !== undefined || properties.ttl !== undefined;
     if (modLifetime) {
         code += `
 let __lifetime = null;
-const _lt = app.itemRegistry.get('${itemId}');${emitLifetime('_lt && _lt.item', properties.bornAt, properties.ttl)}`;
+const _lt = app.itemRegistry.get(${ID});${emitLifetime('_lt && _lt.item', properties.bornAt, properties.ttl)}`;
     }
     if (dataFlags && Object.keys(dataFlags).length > 0) {
         code += `
-const _flagged = app.itemRegistry.get('${itemId}');
-if (_flagged && _flagged.item && _flagged.item.data) Object.assign(_flagged.item.data, ${JSON.stringify(dataFlags)});`;
+const _flagged = app.itemRegistry.get(${ID});
+if (_flagged && _flagged.item && _flagged.item.data) Object.assign(_flagged.item.data, ${jsLiteral(dataFlags)});`;
     }
     const modFont = typeof properties.fontFamily === 'string' && properties.fontFamily.trim() !== '';
     // 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.`
+    const modWarning = modIgnored.length === 0 ? '' : `, ignoredProperties: ${jsLiteral(modIgnored)}, warning: ${jsLiteral(`${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 += `
 app.historyManager.saveState();
@@ -1068,11 +1099,11 @@ ${properties.content !== undefined ? `
 // CONTENT UNDER A CONTENT TRACK (round 10, 10.13): the keyframes set the text
 // on every frame, so a direct edit is overwritten at once — it answered
 // success and changed nothing visible.
-const __ctItem = app.getItemById('${itemId}');
+const __ctItem = app.getItemById(${ID});
 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}')`) : ''}${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} };`;
+${modDirection ? emitDirectionCheck(`app.getItemById(${ID})`, modDirection) : ''}${modTabular ? emitTabularCheck(`app.getItemById(${ID})`) : ''}${modFillOpacity ? emitFillOpacityCheck(`app.getItemById(${ID})`) : ''}${modStrokePos ? emitStrokePositionCheck(`app.getItemById(${ID})`, modStrokePos) : ''}
+return { success: true, itemId: ${ID}${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: ${jsLiteral({ 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.
@@ -1085,8 +1116,9 @@ return { success: true, itemId: '${itemId}'${properties.content !== undefined ?
  * Template for deleting items
  */
 function generateDeleteItemCode(itemId) {
+    const ID = jsLiteral(itemId); // caller text: a quoted literal, never spliced raw
     return `
-// Delete item ${itemId}
+// Delete item ${ID}
 //
 // Delegate to app.deleteItem rather than hand-rolling the removal. The old
 // inline version called \`app.itemRegistry.remove(...)\`, which does not exist —
@@ -1103,11 +1135,11 @@ function generateDeleteItemCode(itemId) {
   if (typeof app.deleteItem !== 'function') {
     return { success: false, error: 'app.deleteItem unavailable — update FxTool' };
   }
-  const ok = app.deleteItem('${itemId}');
+  const ok = app.deleteItem(${ID});
   if (!ok) {
-    return { success: false, error: 'Item not found: ${itemId}' };
+    return { success: false, error: 'Item not found: ' + ${ID} };
   }
-  return { success: true, itemId: '${itemId}' };
+  return { success: true, itemId: ${ID} };
 })();
 `.trim();
 }
@@ -1123,6 +1155,92 @@ function generateDeleteItemCode(itemId) {
 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; })()`;
 }
+/**
+ * on_event_fire_if FAILS SILENTLY ON A BAD SPEC (1.6.24 probe). The engine
+ * evaluates params.predicate with the ExpressionIR interpreter, which is total:
+ * a string such as "1 > 0" has no `op`, evaluates to 0 and takes the else
+ * branch without a warning. And it pulses params.event, never the target, so a
+ * relation with no event fires nothing at all. Both are refused here with the
+ * shape that works. Only the predicate ops' own fields are checked; any other
+ * op passes, so an op the engine adds later is not refused by a stale list.
+ */
+export function fireIfProblem(params) {
+    const p = params ?? {};
+    const example = 'e.g. predicate: { op: "cmp", cmp: "eq", a: { op: "graph", read: "data", item: "item_3", property: "score" }, b: { op: "const", value: 3 } }, event: "<event to fire when it holds>"';
+    const walk = (n, path, depth) => {
+        if (depth > 32)
+            return `${path} nests deeper than 32 levels`;
+        if (!n || typeof n !== 'object' || Array.isArray(n) || typeof n.op !== 'string') {
+            return `${path} must be an ExpressionIR node (an object with an "op"), got ${JSON.stringify(n)}`;
+        }
+        const node = n;
+        if (node.op === 'cmp') {
+            if (!['eq', 'neq', 'gt', 'gte', 'lt', 'lte'].includes(node.cmp))
+                return `${path}.cmp must be eq, neq, gt, gte, lt or lte, got ${JSON.stringify(node.cmp)}`;
+            return walk(node.a, `${path}.a`, depth + 1) ?? walk(node.b, `${path}.b`, depth + 1);
+        }
+        if (node.op === 'logic') {
+            if (!['and', 'or', 'not'].includes(node.logic))
+                return `${path}.logic must be and, or or not, got ${JSON.stringify(node.logic)}`;
+            if (!Array.isArray(node.args) || !node.args.length)
+                return `${path}.args must be a non-empty array of nodes`;
+            for (let i = 0; i < node.args.length; i++) {
+                const bad = walk(node.args[i], `${path}.args[${i}]`, depth + 1);
+                if (bad)
+                    return bad;
+            }
+            return null;
+        }
+        if (node.op === 'graph') {
+            if (!['data', 'active', 'visible'].includes(node.read))
+                return `${path}.read must be data, active or visible, got ${JSON.stringify(node.read)}`;
+            if (typeof node.item !== 'string' || !node.item)
+                return `${path}.item must name the item to read`;
+            if (node.read === 'data' && (typeof node.property !== 'string' || !node.property))
+                return `${path}.property must name the item.data key to read`;
+        }
+        return null;
+    };
+    const bad = walk(p.predicate, 'params.predicate', 0);
+    if (bad)
+        return `${bad}. ${example}.`;
+    const named = (v) => typeof v === 'string' && v.length > 0;
+    if (!named(p.event) && !named(p.else)) {
+        return 'params.event is missing, so nothing would fire: on_event_fire_if pulses params.event when the predicate holds (and params.else when it does not), never its target. '
+            + 'Make the event to fire with pinepaper_event and pass its id as params.event.';
+    }
+    return null;
+}
+/**
+ * fireIfProblem for any relation a tool is about to add: an on_event_fire_if
+ * itself, or one an on_event_add_relation will add when its event fires
+ * (params.type / params.params). Every path that adds relations asks this, so
+ * the check does not depend on which tool built the relation.
+ */
+export function relationSpecProblem(relationType, params) {
+    const p = (params && typeof params === 'object' ? params : {});
+    if (relationType === 'on_event_fire_if')
+        return fireIfProblem(p);
+    if (typeof relationType === 'string' && VISIBILITY_REACTION.test(relationType))
+        return visibilityProblem(relationType, p);
+    if (relationType === 'on_event_add_relation' && (p.type === 'on_event_fire_if' || (typeof p.type === 'string' && VISIBILITY_REACTION.test(p.type)))) {
+        const innerParams = (p.params && typeof p.params === 'object' ? p.params : {});
+        const inner = p.type === 'on_event_fire_if' ? fireIfProblem(innerParams) : visibilityProblem(p.type, innerParams);
+        return inner ? `the ${String(p.type)} it adds: ${inner.replace(/params\./g, 'params.params.')}` : null;
+    }
+    return null;
+}
+const VISIBILITY_REACTION = /^on_(event|enter|exit)_set_visibility$/;
+/**
+ * A visibility reaction reads params.visible and nothing else: absent means show. `value`, which the other set_*
+ * reactions take, was ignored, so {value: false} SHOWED the item and a hide did nothing (issue #29 O4).
+ */
+function visibilityProblem(relationType, p) {
+    if (p.visible !== undefined || !('value' in p))
+        return null;
+    return `${relationType} reads params.visible (true shows, false hides; absent shows), not params.value, so this would `
+        + `${p.value === false || p.value === 0 || p.value === 'hidden' ? 'show the item instead of hiding it' : 'do nothing the value says'}. Pass params.visible: ${JSON.stringify(p.value === false || p.value === 0 || p.value === 'hidden' ? false : true)}.`;
+}
 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
@@ -1143,7 +1261,7 @@ function generateAddRelationCode(sourceId, targetId, relationType, params) {
   }
   const success = app.addRelation('${sourceId}', '${targetId}', '${relationType}', ${JSON.stringify(params, null, 2)});
   if (!success) {
-    const __why = ${relationRefusalReasonJs(JSON.stringify(relationType))};
+    const __why = ${relationRefusalReasonJs(jsLiteral(relationType))};
     return { success: false, relationType: '${relationType}', error: 'the studio refused the ${relationType} relation between ${sourceId} and ${targetId}' + (__why ? ': ' + __why : '.') };
   }
   app.historyManager.saveState();
@@ -1191,6 +1309,98 @@ export function emitterCountWarnings(spec) {
         ? `${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.`);
 }
+/**
+ * The scene lint every batch and custom-code call runs asks for warnings only.
+ * Only lintScene().warnings (the text-clipping rule) is used, and a full
+ * lintScene first runs RelationalLinter.analyze, a pairwise pass over every
+ * item, whose result was thrown away. FxTool #220 added { warningsOnly: true },
+ * which skips it and returns the same warnings; a studio before that ignores
+ * the option and runs the full lint, as it always did.
+ */
+/**
+ * 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;
+        // A count given as a range is not read (said below); comparing it as the default 12 would be a false warning.
+        if (Array.isArray(count))
+            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);
+    });
+    // A RANGE WHERE THE STUDIO READS ONE NUMBER is not drawn as a range (1.6.24
+    // probe: gravity [100, 300] fell to 0, opacity [0.2, 1] to 1, no word). What
+    // it draws instead depends on the studio build: older ones take num()'s
+    // fallback (count [a, b] → 0, so nothing is drawn); FxTool #228 draws the
+    // middle and says so (emitter-range-not-read). Only size, speed, angle,
+    // spawn, lifetime and spin go through range(). The text says what holds on
+    // both, so it is true whichever studio the server is pointed at.
+    const SCALAR_ONLY = ['gravity', 'drag', 'friction', 'opacity', 'fadeIn', 'fadeOut', 'strokeWidth', 'jitter', 'jitterHz', 'aspect', 'sizeEnd', 'count'];
+    const SPEC_ONLY = ['rate', 'start', 'end', 'seed'];
+    const OUTCOME = {
+        count: 'an older studio reads a range here as 0 and draws no particles',
+    };
+    const scalarRanges = (where, o, keys) => {
+        for (const k of keys) {
+            const v = o[k];
+            if (Array.isArray(v) && v.length >= 2) {
+                warnings.push(`${where}.${k} ${JSON.stringify(v)} is not drawn as a range: ${k} takes one number, so the studio draws one value for every particle (its default, or the middle of the range, depending on the build${OUTCOME[k] ? `; ${OUTCOME[k]}` : ''}). Pass the single value you want. Only size, speed, angle, spawn, lifetime and spin take a [min, max] range.`);
+            }
+        }
+        const f = o.fade;
+        if (f && typeof f === 'object' && !Array.isArray(f))
+            scalarRanges(`${where}.fade`, f, ['in', 'out']);
+    };
+    scalarRanges('spec', out, [...SCALAR_ONLY, ...SPEC_ONLY]);
+    bursts.forEach((b, i) => { if (b && typeof b === 'object')
+        scalarRanges(`bursts[${i}]`, b, SCALAR_ONLY); });
+    return { spec: out, warnings };
+}
 /**
  * moves_along_path, from the parameters a caller actually writes.
  *
@@ -1341,15 +1551,16 @@ app.historyManager.saveState();
  * Template for querying relations
  */
 function generateQueryRelationsCode(itemId, relationType, direction = 'outgoing') {
+    const ID = jsLiteral(itemId); // caller text: a quoted literal, never spliced raw
     if (direction === 'outgoing') {
         const typeArg = relationType ? `'${relationType}'` : 'undefined';
         return `
-// Query outgoing relations for ${itemId}
-const relations = app.getRelations('${itemId}', ${typeArg});
+// Query outgoing relations for ${ID}
+const relations = app.getRelations(${ID}, ${typeArg});
 
 // Format results
 const formatted = relations.map(r => ({
-  sourceId: r.sourceId || '${itemId}',
+  sourceId: r.sourceId || ${ID},
   // RelationRegistry.getAssociations returns { relation, target, params } —
   // there is no \`targetId\` on it. Reading the wrong field made EVERY edge come
   // back with an undefined destination, so the graph was unreadable through
@@ -1365,13 +1576,13 @@ const formatted = relations.map(r => ({
     else {
         const typeArg = relationType ? `'${relationType}'` : 'undefined';
         return `
-// Query incoming relations for ${itemId}
-const results = app.queryByRelationTarget('${itemId}', ${typeArg});
+// Query incoming relations for ${ID}
+const results = app.queryByRelationTarget(${ID}, ${typeArg});
 
 // Format results
 const relations = results.map(r => ({
   sourceId: r.itemId,
-  targetId: '${itemId}',
+  targetId: ${ID},
   // queryByTarget returns the real relation name on each result. Hardcoding
   // the filter string labelled every edge 'unknown' on an unfiltered query —
   // which is exactly the query you make when exploring an unfamiliar graph.
@@ -1387,13 +1598,14 @@ const relations = results.map(r => ({
  * Template for simple animation
  */
 function generateAnimateCode(itemId, animationType, speed, intensity, delay) {
+    const ID = jsLiteral(itemId); // caller text: a quoted literal, never spliced raw
     const extra = (intensity !== undefined ? `,\n  animationIntensity: ${intensity}` : '') +
         (delay !== undefined ? `,\n  animationDelay: ${delay}` : '');
     return `
-// Apply ${animationType} animation to ${itemId}
-const item = app.getItemById('${itemId}');
+// Apply ${animationType} animation to ${ID}
+const item = app.getItemById(${ID});
 if (!item) {
-  throw new Error('Item not found: ${itemId}');
+  throw new Error('Item not found: ' + ${ID});
 }
 app.animate(item, {
   animationType: '${animationType}',
@@ -1409,13 +1621,13 @@ app.animate(item, {
   if (r) {
     return {
       success: false,
-      itemId: '${itemId}',
+      itemId: ${ID},
       error: 'Unknown animationType "' + r.requested + '" — nothing will move.',
       requested: r.requested,
       known: r.known,
     };
   }
-  return { success: true, itemId: '${itemId}', animationType: '${animationType}' };
+  return { success: true, itemId: ${ID}, animationType: '${animationType}' };
 })();
 `.trim();
 }
@@ -1465,10 +1677,11 @@ function normalizeKeyframePositions(keyframes) {
  * "item_7 is not on the canvas" is actionable, silence is not.
  */
 function requireItem(itemId, what) {
+    const ID = jsLiteral(itemId); // caller text: a quoted literal, never spliced raw
     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}'`;
+        ? `((typeof window !== 'undefined' && window.__pinepaper_batch_item_ids && window.__pinepaper_batch_item_ids[${itemId.substring(1)}]) || ${ID})`
+        : `${ID}`;
     return `
 const _targetId = ${targetExpr};
 const _target = (app.getItemById && app.getItemById(_targetId))
@@ -1506,6 +1719,7 @@ function unanimatedTextKeysJs(keys) {
 /** 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 ID = jsLiteral(itemId); // caller text: a quoted literal, never spliced raw
     const keyframesJson = JSON.stringify(normalizeKeyframePositions(keyframes), null, 2);
     const calculatedDuration = duration || Math.max(...keyframes.map(k => k.time));
     const opts = { duration: calculatedDuration, loop };
@@ -1587,9 +1801,9 @@ function generateKeyframeAnimateCode(itemId, keyframes, duration, loop = false,
     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}'`;
+    const addAnimTarget = itemId.startsWith('$') ? '_targetId' : `${ID}`;
     return `
-// Apply keyframe animation to ${itemId}
+// Apply keyframe animation to ${ID}
 (function() {
   ${requireItem(itemId, 'the animation')}${audioLevelGuard}
   // The track as it was, so the result can say what happened to it: merged
@@ -1689,15 +1903,16 @@ function emitGeneratorRun(generatorName, paramsJson, region) {
  * Template for applying effects
  */
 function generateApplyEffectCode(itemId, effectType, params) {
+    const ID = jsLiteral(itemId); // caller text: a quoted literal, never spliced raw
     return `
-// Apply ${effectType} effect to ${itemId}
-const item = app.getItemById('${itemId}');
+// Apply ${effectType} effect to ${ID}
+const item = app.getItemById(${ID});
 if (!item) {
-  throw new Error('Item not found: ${itemId}');
+  throw new Error('Item not found: ' + ${ID});
 }
 app.applyEffect(item, '${effectType}', ${JSON.stringify(params, null, 2)});
 
-({ success: true, itemId: '${itemId}', effectType: '${effectType}' });
+({ success: true, itemId: ${ID}, effectType: '${effectType}' });
 `.trim();
 }
 /**
@@ -2008,6 +2223,25 @@ const MEDIA_PURGE = `
   if (__PA && typeof __PA.listMedia === 'function' && typeof __PA.removeMedia === 'function') {
     __PA.listMedia().forEach(function(m) { try { if (__PA.removeMedia(m.id)) __mediaRemoved++; } catch (_) { /* keep clearing */ } });
   }`;
+/**
+ * THE ITEM-ID COUNTER STARTS AGAIN AFTER A CLEAR (O1, mcp-server#29). Run after clearCanvas.
+ *
+ * The studio's clearCanvas keeps uploaded clips, so it calls itemRegistry.clear with preserveTypes, and that branch
+ * never resets nextId: a batch that made item_1 made item_2 when replayed after a clear. The rule: the next id is one
+ * past the highest item_N still registered, so 1 on an empty canvas and never an id a kept clip holds. (An undo of
+ * the clear restores the old items through rebuildFromCanvas, which moves nextId past them, as the studio's own
+ * full clear already relies on.) The previous batch's $N ids named items that are gone, so they are forgotten too.
+ */
+const ID_COUNTER_RESET = `
+  if (app.itemRegistry && typeof app.itemRegistry.nextId === 'number' && typeof app.itemRegistry.getAll === 'function') {
+    let __maxLive = 0;
+    app.itemRegistry.getAll().forEach(function (e) {
+      const m = /^item_(\\d+)$/.exec((e && (e.id || e.itemId || (e.item && e.item.data && (e.item.data.registryId || e.item.data.id)))) || '');
+      if (m) __maxLive = Math.max(__maxLive, Number(m[1]));
+    });
+    app.itemRegistry.nextId = __maxLive + 1;
+  }
+  if (typeof window !== 'undefined') window.__pinepaper_batch_item_ids = [];`;
 /**
  * Template for clearing all items from canvas
  */
@@ -2031,6 +2265,7 @@ if (typeof app.clearCanvas === 'function') {
   if (app.itemRegistry) app.itemRegistry.clear();
   if (app.relationRegistry) app.relationRegistry.clear();
 }
+${ID_COUNTER_RESET}
 
 if (app.historyManager) app.historyManager.saveState();
 
@@ -2044,9 +2279,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();
 }
 /**
@@ -2279,13 +2516,23 @@ export function planKeyframeMerges(operations) {
  * through modifyItem after create, so the engine's own bookkeeping runs.
  */
 const BRAND_FILL_TYPES = new Set(['circle', 'star', 'rectangle', 'triangle', 'polygon', 'ellipse', 'pentagon', 'hexagon', 'diamond', 'arrow', 'heart']);
+/** A closed shape given a stroke colour and no fill of any spelling: drawn as an outline (issue #29 O7). */
+function isStrokeOnly(itemType, props) {
+    if (!BRAND_FILL_TYPES.has(itemType))
+        return false;
+    if (props.strokeColor === undefined || props.strokeColor === null)
+        return false;
+    return ['color', 'fillColor', 'fill', 'gradient'].every((k) => props[k] === undefined);
+}
+const OUTLINE_NOTE = 'none: a strokeColor with no fill draws an outline. Pass fillColor to fill it.';
 function withBrandDefaults(code, itemType, props) {
     if (props.noBrand === true)
         return code;
     const isText = itemType === 'text';
     if (!isText && !BRAND_FILL_TYPES.has(itemType))
         return code;
-    const hasColor = ['color', 'fillColor', 'fill'].some((k) => props[k] !== undefined);
+    // An outline is a colour choice: the brand does not fill it in.
+    const hasColor = ['color', 'fillColor', 'fill'].some((k) => props[k] !== undefined) || isStrokeOnly(itemType, props);
     const hasFont = props.fontFamily !== undefined;
     if (hasColor && (!isText || hasFont))
         return code;
@@ -2374,6 +2621,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()'))
@@ -2878,6 +3134,11 @@ export class PinePaperCodeGenerator {
   return { success: true, presetId: ${JSON.stringify(validated.presetId)}, relationType: r.relationType, params: r.params, values: r.values };
 })();`.trim();
         }
+        {
+            const problem = relationSpecProblem(validated.relationType, validated.params);
+            if (problem)
+                return `(function() { return { success: false, relationType: ${jsLiteral(validated.relationType)}, error: ${jsLiteral(problem)} }; })();`;
+        }
         if (validated.relationType === 'moves_along_path') {
             return generateMovesAlongPathCode(validated.sourceId, validated.targetId ?? undefined, (validated.params ?? {}));
         }
@@ -3554,6 +3815,15 @@ if (typeof _gen === 'function') {
         for (const relation of relations) {
             const { source, target, type, params = {} } = relation;
             const paramsStr = JSON.stringify(params);
+            const specProblem = relationSpecProblem(type, params);
+            if (specProblem) {
+                codeParts.push(`
+// Refused relation: ${source} ${type} ${target}
+(results.relationsRefused = results.relationsRefused || []).push(${JSON.stringify({ source, target, type, reason: specProblem })});
+results.success = false;
+results.error = '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.';`);
+                continue;
+            }
             codeParts.push(`
 // Add relation: ${source} ${type} ${target}
 (function() {
@@ -3565,7 +3835,7 @@ if (typeof _gen === 'function') {
     if (app.addRelation(sourceId, targetId, '${type}', params)) {
       results.relations.push({ source: '${source}', target: '${target}', type: '${type}' });
     } else {
-      const __why = ${relationRefusalReasonJs(JSON.stringify(type))};
+      const __why = ${relationRefusalReasonJs(jsLiteral(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.';
@@ -3983,7 +4253,7 @@ throw new Error('Unknown diagram mode action: ${action}');
     if (app.patternGroup) app.patternGroup.removeChildren();
     if (app.itemRegistry) app.itemRegistry.clear();
     if (app.relationRegistry) app.relationRegistry.clear();
-  }
+  }${ID_COUNTER_RESET}
 `;
         }
         if (canvasPreset) {
@@ -4226,7 +4496,7 @@ throw new Error('Unknown diagram mode action: ${action}');
     if (app.patternGroup) app.patternGroup.removeChildren();
     if (app.itemRegistry) app.itemRegistry.clear();
     if (app.relationRegistry) app.relationRegistry.clear();
-  }
+  }${ID_COUNTER_RESET}
 `;
         }
         else {
@@ -4234,7 +4504,7 @@ throw new Error('Unknown diagram mode action: ${action}');
   // Clear items but preserve background
   if (app.textItemGroup) app.textItemGroup.removeChildren();
   if (app.itemRegistry) app.itemRegistry.clear();
-  if (app.relationRegistry) app.relationRegistry.clear();
+  if (app.relationRegistry) app.relationRegistry.clear();${ID_COUNTER_RESET}
 `;
         }
         if (canvasPreset) {
@@ -4265,11 +4535,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() {
@@ -4284,7 +4559,8 @@ throw new Error('Unknown diagram mode action: ${action}');
       || (typeof v.reason === 'string' && v.reason)
       || 'the operation reported failure without naming a reason';
   };
-  // $N is the Nth item THIS batch created (the documented contract). The
+  // $N is the Nth item THIS batch made (the documented contract): create and group ops take a slot each, in op
+  // order (O2, mcp-server#29: a group is an item every later op addresses, and it had no slot). 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).
@@ -4293,16 +4569,39 @@ throw new Error('Unknown diagram mode action: ${action}');
   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.'));
+    throw new Error('$' + n + ' is item number ' + n + ' THIS batch made (create and group ops are numbered, in op order, from $0), and it has made ' + itemIds.length + ' so far.'
+      + (prev ? ' In the previous batch $' + n + ' was ' + prev + ' — pass that id instead.' : ' Put the ops that make it first, or pass the item id.'));
   };
+  // A failure names the item, not the "$1" that addressed it; the ref as written when the batch never made it.
+  const __refName = function (n) { return itemIds[n] !== undefined ? itemIds[n] : '$' + n; };
   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({ warningsOnly: true });
+      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
@@ -4310,9 +4609,15 @@ throw new Error('Unknown diagram mode action: ${action}');
             // $N reference: a batch of [create ×5, keyframe_animate ×5, create ×5,
             // keyframe_animate ×5] silently re-animated the FIRST five items and
             // left the second five without keyframes (mis-oriented/mis-animated
-            // vehicles, 2026-07-30). `group` already follows this rule by
-            // returning groupId instead of itemId.
-            const claimsItemSlot = op.type === 'create';
+            // vehicles, 2026-07-30). A `group` MAKES an item (the group), so it
+            // claims a slot too (O2, mcp-server#29): [create, create, group,
+            // keyframe_animate "$2"] keys the group.
+            const claimsItemSlot = op.type === 'create' || op.type === 'group';
+            // 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 opItemJs = typeof opItem === 'string' && /^\$\d+$/.test(opItem) ? `__refName(${opItem.slice(1)})` : JSON.stringify(opItem);
+            const opStep = typeof o._step === 'string' ? `op ${index}: ${o._step}` : `op ${index} (${op.type})`;
             code += `
     // Operation ${index}: ${op.type}
     try {
@@ -4329,7 +4634,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 : ${opItemJs}; throw __e${index};` : `results.push({ index: ${index}, success: false, step: ${JSON.stringify(opStep)}, itemId: (result${index} && typeof result${index}.itemId === 'string') ? result${index}.itemId : ${opItemJs}, reason: failed${index}, error: failed${index}, result: result${index} });
         success = false;`}
       } else {
         results.push({ index: ${index}, success: true, result: result${index} });
@@ -4338,7 +4643,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 : ${opItemJs}, reason: __r${index}, error: __r${index} });
       ${isAtomic ? 'throw opError;' : 'success = false;'}
     }
 `;
@@ -4358,15 +4664,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 } : {}; })()) };
   }
 })();
 `;
@@ -4403,7 +4713,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) {
@@ -4448,9 +4758,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.
@@ -4458,36 +4766,43 @@ return __created;
                 // at run time, so it is generated with a placeholder and the runtime
                 // variable put in its place.
                 const single = generateModifyItemCode('__MID__', (op.properties || {})).trim()
-                    .replace(/'__MID__'/g, '__mid')
+                    .replace(/"__MID__"/g, '__mid')
                     .replace(/__MID__/g, "' + __mid + '")
                     .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};
 const item = app.getItemById(targetId);
 if (!item) throw new Error('Item not found: ' + targetId);
-app.animate(item, { animationType: '${op.animationType}', ...${animOpts} });
-return { itemId: targetId, animationType: '${op.animationType}' };
+app.animate(item, { animationType: ${JSON.stringify(String(op.animationType))}, ...${animOpts} });
+return { itemId: targetId, animationType: ${JSON.stringify(String(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 || {});
+                const fireIf = relationSpecProblem(op.relationType, op.relationOptions);
+                if (fireIf)
+                    return `
+throw new Error(${JSON.stringify(String(op.relationType) + ': ' + fireIf)});
+`;
                 return `
 const sourceId = ${srcRef};
 const targetId = ${tgtRef};
@@ -4495,22 +4810,20 @@ const source = app.getItemById(sourceId);
 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});
+const relationId = app.addRelation(source, target, ${JSON.stringify(String(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))};
+  const __why = ${relationRefusalReasonJs(jsLiteral(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}' };
+return { relationId, sourceId, targetId, relationType: ${JSON.stringify(String(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);
@@ -4521,10 +4834,10 @@ 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.
+                // Returns { groupId, itemId }: the group takes the next $N slot (O2), as a create does.
                 return `
 return (function() {${this.groupCodeBody(idsArrayExpr, nameExpr)}
 })();
@@ -4533,8 +4846,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';
@@ -4565,14 +4878,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) || []);
@@ -4614,9 +4925,7 @@ return { success: true, itemId: targetId, duration: ${kfDuration}, loop: ${kfLoo
 `;
             }
             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 `
@@ -4633,9 +4942,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};
@@ -5120,6 +5427,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({ warningsOnly: true });
+      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)) {
@@ -5200,14 +5520,36 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
   });
 
   let result = { success: false, platform, format, quality, framing };
-  // A STILL SHOWS WHAT IS ALIVE AT ITS MOMENT. Lifetimes that fall back to the
+  // THE MOMENT A STILL SHOWS (issue #29 O6). With no time, a still of a scene
+  // that is playing was whatever frame the live playhead had reached when the
+  // call landed: an orbiting planet sat at a different angle on every run, and
+  // nowhere near its place in the video's first frame. A playing scene's still
+  // is now its first frame (time 0), and the result says so; a stopped
+  // playhead is a moment someone chose, and is kept.
+  let __stillT = ${stillTime !== undefined ? stillTime : 'null'};
+  let __stillTimeNote = null;
+${stillTime === undefined ? `  if (['png', 'jpg', 'webp', 'svg', 'pdf'].indexOf(format) !== -1 && typeof app.setPlaybackTime === 'function') {
+    const __tr = app.transport;
+    let __playing = !!(__tr && __tr.isPlaying) || !!(app.isPlayingKeyframes && !app.isAnimationPaused);
+    if (!__playing && typeof app.playbackTime === 'number') {
+      // The flags are not the only clock: watch the playhead for two frames.
+      const __t0 = app.playbackTime;
+      await new Promise((r) => { if (typeof requestAnimationFrame === 'function') requestAnimationFrame(() => requestAnimationFrame(r)); else setTimeout(r, 40); });
+      __playing = app.playbackTime !== __t0;
+    }
+    if (__playing) {
+      __stillT = 0;
+      __stillTimeNote = 'the scene was playing, so this still is its first frame (time 0), the frame a video starts on. Pass time for another moment.';
+    }
+  }
+` : ''}  // A STILL SHOWS WHAT IS ALIVE AT ITS MOMENT. Lifetimes that fall back to the
   // MCP's frame callback are applied by the frame loop, and a seek does not run
   // it — so a png at time 0.8 s drew nothing staged at 0.8 s, and an item past
   // its ttl still showed (retest). The visibility pass runs here for stills.
   if (['png', 'jpg', 'webp', 'svg', 'pdf'].indexOf(format) !== -1) {
     const __L = globalThis.__ppMcp;
     if (__L && __L.lifetimeApp === app && typeof __L.applyLifetimes === 'function') {
-      try { __L.applyLifetimes(${stillTime !== undefined ? stillTime : "typeof app.playbackTime === 'number' ? app.playbackTime : 0"}); } catch (_) { /* the still renders either way */ }
+      try { __L.applyLifetimes(__stillT !== null ? __stillT : (typeof app.playbackTime === 'number' ? app.playbackTime : 0)); } catch (_) { /* the still renders either way */ }
     }
   }
   // The engine's report on the audio track of THIS export (FxTool b41860aa:
@@ -5216,18 +5558,19 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
   const __vx = app.exportEngine && app.exportEngine.videoExporter;
   if (__vx && 'lastAudioReport' in __vx) __vx.lastAudioReport = null;
   if (__vx && 'lastVideoReport' in __vx) __vx.lastVideoReport = null;
-${stillTime !== undefined ? `
   // A STILL AT A CHOSEN MOMENT (round 7 X, 1.57). Without this a png is
   // whatever frame the playhead is on — two identical builds gave PNGs that
   // differed in the animated streak while their MP4s were byte-identical.
   // Seek, render, and put the playhead back afterwards.
   const __prevT = typeof app.playbackTime === 'number' ? app.playbackTime : 0;
-  if (typeof app.setPlaybackTime !== 'function') {
-    return { success: false, platform, format, error: 'app.setPlaybackTime unavailable — this studio cannot render a still at a chosen time.' };
+  if (__stillT !== null) {
+    if (typeof app.setPlaybackTime !== 'function') {
+      return { success: false, platform, format, error: 'app.setPlaybackTime unavailable — this studio cannot render a still at a chosen time.' };
+    }
+    app.setPlaybackTime(__stillT);
+    if (typeof paper !== 'undefined' && paper.view && typeof paper.view.update === 'function') paper.view.update();
   }
-  app.setPlaybackTime(${stillTime});
-  if (typeof paper !== 'undefined' && paper.view && typeof paper.view.update === 'function') paper.view.update();
-` : ''}
+
   try {
     // jpg / webp render as png, then re-encode below.
     switch ((format === 'jpg' || format === 'webp') ? 'png' : format) {
@@ -5262,7 +5605,7 @@ ${stillTime !== undefined ? `
           if ('lastRegionExcluded' in app) app.lastRegionExcluded = null;
           // A video in the region is waited for at this time (round 12, 12.5):
           // the render drew before the clip's seek landed.
-          if (typeof app.awaitMediaAt === 'function') await app.awaitMediaAt(${stillTime !== undefined ? stillTime : "typeof app.playbackTime === 'number' ? app.playbackTime : 0"});
+          if (typeof app.awaitMediaAt === 'function') await app.awaitMediaAt(__stillT !== null ? __stillT : (typeof app.playbackTime === 'number' ? app.playbackTime : 0));
           const regionUrl = app.renderRegionToDataURL(new paper.Rectangle(${region.x}, ${region.y}, ${region.width}, ${region.height}), rw, rh${region.excludeForeign === false ? '' : ', { excludeForeign: true }'});
           const __excluded = Array.isArray(app.lastRegionExcluded) ? app.lastRegionExcluded.filter(function(id) { return id; }) : null;
           // ITEMS THAT CROSS THE REGION'S EDGE (round 9 II, 1.78). In the sheet
@@ -5319,7 +5662,9 @@ ${stillTime !== undefined ? `
             || app.canvasSize
             || { width: dimensions.width, height: dimensions.height };
           const pngScale = pngBoard.width > 0 ? dimensions.width / pngBoard.width : 1;
-          const png = await app.exportEngine.exportPNG({ scale: pngScale });
+          // The engine evaluates the scene at time itself (keyframes, relations, loops); without it, a playing
+          // scene's still is left as the live frame.
+          const png = await app.exportEngine.exportPNG({ scale: pngScale, ...(__stillT !== null ? { time: __stillT } : {}) });
           const dataUrl = (png && png.dataUrl) ? png.dataUrl : png;
           result = {
             success: true,
@@ -5668,7 +6013,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) {
@@ -5676,7 +6021,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 });
             }
@@ -5739,7 +6084,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
@@ -5777,11 +6122,19 @@ ${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;
 ${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
@@ -6035,8 +6388,10 @@ ${(() => {
                 warning: `${frames} frames at ${Math.round(fps * 1000) / 1000} fps is ${actual.toFixed(3)} s — ${((actual - videoDuration) * 1000).toFixed(1)} ms over the ${videoDuration} s asked for. For a hard cap (e.g. a 6 s bumper) use duration ${fit.toFixed(4)} (${Math.floor(videoDuration * fps)} frames).`,
             })};\n`;
         })()}
-${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) { /* the still is already rendered */ }
-  if (result && result.success) result.time = ${stillTime};` : ''}
+  if (__stillT !== null) {
+    try { app.setPlaybackTime(__prevT); } catch (_) { /* the still is already rendered */ }
+    if (result && result.success) { result.time = __stillT; if (__stillTimeNote) result.stillTimeNote = __stillTimeNote; }
+  }
   // SCREEN-SPACE ITEMS (FxTool D20): SVG and Lottie write geometry, not the
   // camera's frame map, so a HUD item is placed as if the camera had not moved.
   if (result && result.success && typeof app.screenSpaceItems === 'function' && ['svg', 'lottie', 'dotlottie'].indexOf(${JSON.stringify(format)}) !== -1) {
@@ -6764,7 +7119,7 @@ ${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) {
         // unchanged. The map itself cannot be moved without breaking geoToCanvas
         // (it projects against the untransformed map, so markers would land in the
         // wrong place). Until the engine has a map view transform, say so.
-        return `(function() { return { success: false, error: ${JSON.stringify(MAP_VIEW_REFUSAL('pan'))} }; })();`;
+        return `(function() { return { success: false, error: ${jsLiteral(MAP_VIEW_REFUSAL('pan'))} }; })();`;
     }
     /**
      * Generate code to zoom the map
@@ -6777,7 +7132,7 @@ ${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) {
         if (validated.duration !== undefined)
             options.duration = validated.duration;
         // Refused for the same reason as pan (see generatePanMap).
-        return `(function() { return { success: false, error: ${JSON.stringify(MAP_VIEW_REFUSAL('zoom'))} }; })();`;
+        return `(function() { return { success: false, error: ${jsLiteral(MAP_VIEW_REFUSAL('zoom'))} }; })();`;
     }
     /**
      * Generate code to export map configuration
@@ -7713,14 +8068,41 @@ ${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({ warningsOnly: true });
+      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.
+  // __ppWrapped marks the wrapper itself: a code that returned undefined loses the __ppValue key on its way out
+  // of the page (JSON drops undefined), and without the mark the server read the bare wrapper as the value, {}.
+  const __ppL = __ppLintNow();
+  return __ppL.length ? { __ppWrapped: true, __ppValue: __ppValue, __ppLint: __ppL } : __ppValue;
 })();
 `.trim();
     }
@@ -8051,7 +8433,7 @@ ${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) {
 `.trim();
     }
     generateImportImage(input) {
-        const { url, position, maxWidth, maxHeight, mask, smoothing, maxEdge, nativeSize, shadowColor, shadowBlur, shadowOffset } = input;
+        const { url, position, maxWidth, maxHeight, mask, smoothing, maxEdge, nativeSize, shadowColor, shadowBlur, shadowOffset, name } = 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 = {};
@@ -8169,6 +8551,11 @@ ${mask ? `    // A MASK REPLACES THE RASTER (round 8 DD, 4.10). applyMask builds
         ? { 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 + '.' };
     }
+` : ''}${name ? `    // PATCHIMG24: an image had no name, so a batch patch (which addresses by
+    // name) could not reach it. Set where the registry's name lookup reads it,
+    // on what is drawn (the mask group when masked).
+    placed.name = ${JSON.stringify(name)};
+    if (placed.data) placed.data.name = ${JSON.stringify(name)};
 ` : ''}    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.' };
@@ -8176,7 +8563,7 @@ ${mask ? `    // A MASK REPLACES THE RASTER (round 8 DD, 4.10). applyMask builds
     return {
       success: true,
       itemId: itemId,
-      message: 'Image imported and placed on canvas.',
+      message: 'Image imported and placed on canvas.',${name ? `\n      name: ${JSON.stringify(name)},` : ''}
       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.
@@ -8528,6 +8915,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: ${S('create needs kind: ' + PATTERN_KINDS.join(', '))} };
+  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);
@@ -9162,6 +9596,8 @@ ${resolveSource}
 })();`.trim();
     }
     generateTransform(input) {
+        // Every id is a quoted literal: an id with a quote in it was a syntax error, and an id is caller text.
+        const ID = JSON.stringify(input.itemId || '');
         switch (input.action) {
             case 'fit': {
                 const mode = input.mode || 'contain';
@@ -9173,31 +9609,37 @@ ${resolveSource}
   // id space from canvas item ids. PinePaperAgent.fitToFrame resolves either.
   const A = (typeof window !== 'undefined') && window.PinePaperAgent;
   if (A && typeof A.fitToFrame === 'function') {
-    const ok = A.fitToFrame(${JSON.stringify(input.itemId || '')}, '${mode}');
+    const ok = A.fitToFrame(${ID}, ${JSON.stringify(mode)});
     return ok
-      ? { success: true, action: 'fit', itemId: '${input.itemId}', mode: '${mode}' }
-      : { success: false, error: 'Item not found or not fittable: ${input.itemId}' };
+      ? { success: true, action: 'fit', itemId: ${ID}, mode: ${JSON.stringify(mode)} }
+      : { success: false, error: 'Item not found or not fittable: ' + ${ID} };
   }
   if (typeof app.fitToFrame !== 'function') {
     return { success: false, error: 'fitToFrame unavailable — update FxTool' };
   }
-  const ok = app.fitToFrame(${JSON.stringify(input.itemId || '')}, '${mode}');
+  const ok = app.fitToFrame(${ID}, ${JSON.stringify(mode)});
   return ok
-    ? { success: true, action: 'fit', itemId: '${input.itemId}', mode: '${mode}' }
-    : { success: false, error: 'Item not found: ${input.itemId}' };
+    ? { success: true, action: 'fit', itemId: ${ID}, mode: ${JSON.stringify(mode)} }
+    : { success: false, error: 'Item not found: ' + ${ID} };
 })();`.trim();
             }
             case 'nudge': {
-                const dx = input.dx ?? 0;
-                const dy = input.dy ?? 0;
+                const dx = Number(input.dx ?? 0);
+                const dy = Number(input.dy ?? 0);
+                // THROUGH modifyItem (issue #29 O8). Writing item.position directly
+                // skipped the engine's bookkeeping: an item with a loop animation kept
+                // its old home (data.originalPosition), and the change check, which
+                // reads authored state, reported the move as no change.
                 return `
 // Nudge item position
 (function() {
-  const entry = app.itemRegistry.get(${JSON.stringify(input.itemId || '')});
-  if (!entry || !entry.item) return { error: 'Item not found: ${input.itemId}' };
-  entry.item.position.x += ${dx};
-  entry.item.position.y += ${dy};
-  return { success: true, action: 'nudge', itemId: '${input.itemId}', dx: ${dx}, dy: ${dy}, position: { x: entry.item.position.x, y: entry.item.position.y } };
+  const entry = app.itemRegistry.get(${ID});
+  if (!entry || !entry.item) return { error: 'Item not found: ' + ${ID} };
+  const x = entry.item.position.x + ${dx};
+  const y = entry.item.position.y + ${dy};
+  if (typeof app.modifyItem === 'function') app.modifyItem(${ID}, { x: x, y: y });
+  else { entry.item.position.x = x; entry.item.position.y = y; }
+  return { success: true, action: 'nudge', itemId: ${ID}, dx: ${dx}, dy: ${dy}, position: { x: entry.item.position.x, y: entry.item.position.y } };
 })();`.trim();
             }
             case 'flip': {
@@ -9205,10 +9647,10 @@ ${resolveSource}
                 return `
 // Flip item ${dir}ly
 (function() {
-  const entry = app.itemRegistry.get(${JSON.stringify(input.itemId || '')});
-  if (!entry || !entry.item) return { error: 'Item not found: ${input.itemId}' };
+  const entry = app.itemRegistry.get(${ID});
+  if (!entry || !entry.item) return { error: 'Item not found: ' + ${ID} };
   ${dir === 'horizontal' ? 'entry.item.scale(-1, 1);' : 'entry.item.scale(1, -1);'}
-  return { success: true, action: 'flip', itemId: '${input.itemId}', direction: '${dir}' };
+  return { success: true, action: 'flip', itemId: ${ID}, direction: ${JSON.stringify(dir)} };
 })();`.trim();
             }
             case 'reorder': {
@@ -9226,20 +9668,20 @@ ${resolveSource}
                     return `
 // Reorder item: ${order}
 (function() {
-  const entry = app.itemRegistry.get(${JSON.stringify(input.itemId || '')});
-  if (!entry || !entry.item) return { error: 'Item not found: ${input.itemId}' };
+  const entry = app.itemRegistry.get(${ID});
+  if (!entry || !entry.item) return { error: 'Item not found: ' + ${ID} };
   const sibling = ${siblingExpr};
   if (sibling) entry.item.${method}(sibling);
-  return { success: true, action: 'reorder', itemId: '${input.itemId}', order: '${order}' };
+  return { success: true, action: 'reorder', itemId: ${ID}, order: ${JSON.stringify(order)} };
 })();`.trim();
                 }
                 return `
 // Reorder item: ${order}
 (function() {
-  const entry = app.itemRegistry.get(${JSON.stringify(input.itemId || '')});
-  if (!entry || !entry.item) return { error: 'Item not found: ${input.itemId}' };
+  const entry = app.itemRegistry.get(${ID});
+  if (!entry || !entry.item) return { error: 'Item not found: ' + ${ID} };
   entry.item.${method}();
-  return { success: true, action: 'reorder', itemId: '${input.itemId}', order: '${order}' };
+  return { success: true, action: 'reorder', itemId: ${ID}, order: ${JSON.stringify(order)} };
 })();`.trim();
             }
             default:
@@ -10026,7 +10468,7 @@ ${resolve}
     // HAND-DRAWN SKETCHY ANIMATION & JITTER
     // ===========================================================================
     generateHandDrawn(input) {
-        const S = (v) => JSON.stringify(v);
+        const S = jsLiteral;
         // 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;
@@ -10368,6 +10810,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
@@ -10403,13 +10848,16 @@ 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.
   const __esc = function(v) { return String(v).replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;'); };
   let __html = String(result.html || '');
   const __applied = [];
-  ${input.lang || input.dir ? `__html = __html.replace(/<html\\b[^>]*>/i, function() { __applied.push('html'); return '<html lang="' + __esc(${JSON.stringify(input.lang ?? 'en')}) + '"' + ${JSON.stringify(input.dir ? ` dir="${input.dir}"` : '')} + '>'; });` : ''}
+  ${input.lang || input.dir ? `__html = __html.replace(/<html\\b[^>]*>/i, function() { __applied.push('html'); return '<html lang="' + __esc(${jsLiteral(input.lang ?? 'en')}) + '"' + ${jsLiteral(input.dir ? ` dir="${input.dir}"` : '')} + '>'; });` : ''}
   ${input.alt ? `// The engine's widget draws its canvas from script, so there is no <canvas>
   // tag to label (prod retest): its accessible name is div#w's aria-label,
   // mirrored in the screen-reader text #w-desc. Both carry the alt; a literal
@@ -10438,7 +10886,7 @@ if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
                     return `(function() { return { error: 'data is required for create' }; })();`;
                 const fields = resolveChartFields(input.chartType, input.data, input.options || {});
                 if ('error' in fields)
-                    return `(function() { return { success: false, error: ${JSON.stringify(fields.error)} }; })();`;
+                    return `(function() { return { success: false, error: ${jsLiteral(fields.error)} }; })();`;
                 const dataStr = JSON.stringify(input.data);
                 const optsStr = JSON.stringify(fields.options);
                 return `
@@ -10924,8 +11372,8 @@ if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
   if (app.historyManager) app.historyManager.saveState();
   const groupId = (group.data && (group.data.registryId || group.data.groupId)) || null;
   // itemId too (round 8 BB, 1.70): every other create answers itemId, and a
-  // group is an item every other tool addresses by that id. In a batch this
-  // does not claim a $N slot — only create ops do.
+  // group is an item every other tool addresses by that id. In a batch it
+  // claims the next $N slot, as a create does (O2).
   return { success: true, groupId: groupId, itemId: groupId, groupName: group.data && group.data.groupName, itemCount: items.length };`;
     }
     /**
@@ -11232,6 +11680,14 @@ ${checks.includes('contrast') ? `  // SAMPLED OVER TIME (round 12, 12.9): text i
             canvas: input.canvas,
             defaultGeometry: input.defaultGeometry,
         }).compile(input.doc);
+        // A fire_if the doc declares is checked before anything is built: refused, the whole document is, with every reason.
+        const specProblems = ops
+            .filter((o) => o.op === 'addRelation')
+            .map((o) => { const r = o; const why = relationSpecProblem(r.relation, r.params); return why ? `${r.from} -> ${r.to} (${r.relation}): ${why}` : null; })
+            .filter((x) => !!x);
+        if (specProblems.length) {
+            return `(function() { return { success: false, error: ${jsLiteral('nothing was built: ' + specProblems.join(' | '))} }; })();`;
+        }
         const opsJson = JSON.stringify(ops, null, 2);
         const diagJson = JSON.stringify(diagnostics);
         const docJson = JSON.stringify(input.doc);
@@ -11325,7 +11781,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();
     }
     /**
@@ -12251,8 +12710,10 @@ ${cam ? `  // The camera rides the SAME timing: framing each state as its morph
         }
     }
     /** pinepaper_emitter (D29): create('emitter', spec) / setEmitter(id, patch). */
-    generateEmitter(input) {
-        const S = (v) => JSON.stringify(v);
+    generateEmitter(raw) {
+        const S = jsLiteral;
+        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
@@ -12274,7 +12735,10 @@ ${cam ? `  // The camera rides the SAME timing: framing each state as its morph
     }
     return out;
   }` : '';
-        const capJs = (stored) => checks.length ? `, ...((function(w) { return w.length ? { warnings: w } : {}; })(__capWarnings(${stored})))` : '';
+        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
@@ -13562,10 +14026,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();
         }
     }