@pinepaper.studio/mcp-server 1.6.24 → 1.6.25

package/dist/types/code-generator.js

@@ -7,9 +7,11 @@
 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, 
@@ -146,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];
@@ -213,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
@@ -337,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
@@ -401,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.
@@ -437,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.
  *
@@ -475,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
@@ -487,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.' };
   }
 }`;
@@ -572,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});`;
 }
@@ -678,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 `
@@ -696,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
@@ -765,11 +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 = ${JSON.stringify(ls)};` : ''}
+  ${ls !== undefined ? `it.letterSpacing = ${jsLiteral(ls)};` : ''}
   const b1 = it.bounds;
   it.position = it.position.add([ax - edge(b1), ay - b1.center.y]);
 })(${itemExpr});`;
@@ -918,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
@@ -961,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 {
@@ -990,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
@@ -1003,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);
 }`;
     }
@@ -1017,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
@@ -1043,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);` : ''}
@@ -1054,23 +1066,23 @@ 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
@@ -1079,7 +1091,7 @@ if (_flagged && _flagged.item && _flagged.item.data) Object.assign(_flagged.item
     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();
@@ -1087,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.
@@ -1104,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 —
@@ -1122,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();
 }
@@ -1142,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
@@ -1162,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();
@@ -1210,6 +1309,14 @@ 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.
  *
@@ -1246,6 +1353,9 @@ export function normalizeEmitterSpec(spec, assumeDefaultCount = true) {
     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;
@@ -1263,6 +1373,32 @@ export function normalizeEmitterSpec(spec, assumeDefaultCount = true) {
         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 };
 }
 /**
@@ -1415,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
@@ -1439,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.
@@ -1461,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}',
@@ -1483,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();
 }
@@ -1539,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))
@@ -1580,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 };
@@ -1661,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
@@ -1763,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();
 }
 /**
@@ -2082,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
  */
@@ -2105,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();
 
@@ -2355,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;
@@ -2963,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 ?? {}));
         }
@@ -3639,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() {
@@ -3650,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.';
@@ -4068,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) {
@@ -4311,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 {
@@ -4319,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) {
@@ -4374,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).
@@ -4383,9 +4569,11 @@ 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.
@@ -4397,7 +4585,7 @@ throw new Error('Unknown diagram mode action: ${action}');
   const __ppLintNow = function () {
     try {
       if (typeof app === 'undefined' || !app || typeof app.lintScene !== 'function') return [];
-      const r = app.lintScene();
+      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') }];
@@ -4421,12 +4609,14 @@ 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}
@@ -4444,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 ? `const __e${index} = new Error(failed${index}); __e${index}.itemId = (result${index} && typeof result${index}.itemId === 'string') ? result${index}.itemId : ${JSON.stringify(opItem)}; throw __e${index};` : `results.push({ index: ${index}, success: false, step: ${JSON.stringify(opStep)}, itemId: (result${index} && typeof result${index}.itemId === 'string') ? result${index}.itemId : ${JSON.stringify(opItem)}, reason: failed${index}, error: failed${index}, result: result${index} });
+        ${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} });
@@ -4454,7 +4644,7 @@ throw new Error('Unknown diagram mode action: ${action}');
       }
     } catch (opError) {
       const __r${index} = _why(opError, 'operation ${index} (${op.type}) threw with no message');
-      results.push({ index: ${index}, success: false, step: ${JSON.stringify(opStep)}, itemId: (opError && typeof opError.itemId === 'string') ? opError.itemId : ${JSON.stringify(opItem)}, reason: __r${index}, error: __r${index} });
+      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;'}
     }
 `;
@@ -4576,7 +4766,7 @@ 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 `
@@ -4601,13 +4791,18 @@ return __r;
 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 = 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};
@@ -4615,17 +4810,17 @@ 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 = batchRef(op.itemId);
@@ -4642,7 +4837,7 @@ return { itemId: targetId, deleted: true };
                 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)}
 })();
@@ -5238,7 +5433,7 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
   const __lint = (function () {
     if (typeof app.lintScene !== 'function') return null;
     try {
-      const r = app.lintScene();
+      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') }];
@@ -5325,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:
@@ -5341,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) {
@@ -5387,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
@@ -5444,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,
@@ -6168,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) {
@@ -6897,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
@@ -6910,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
@@ -7859,7 +8081,7 @@ ${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) {
   const __ppLintNow = function () {
     try {
       if (typeof app === 'undefined' || !app || typeof app.lintScene !== 'function') return [];
-      const r = app.lintScene();
+      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') }];
@@ -7877,8 +8099,10 @@ ${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) {
       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 ? { __ppValue: __ppValue, __ppLint: __ppL } : __ppValue;
+  return __ppL.length ? { __ppWrapped: true, __ppValue: __ppValue, __ppLint: __ppL } : __ppValue;
 })();
 `.trim();
     }
@@ -8209,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 = {};
@@ -8327,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.' };
@@ -8334,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.
@@ -8701,7 +8930,7 @@ ${input.cutSound !== undefined ? `  const __cuts = (__cr && __cr.cuts) || (app.s
             case 'create': {
                 const spec = { id: v.id, kind: v.kind, members: v.members, params: v.params || {}, ...(v.window ? { window: v.window } : {}) };
                 body = `${need('addPattern')}
-  if (!${S(v.kind ?? null)}) return { success: false, error: 'create needs kind: phase_wave or stagger' };
+  if (!${S(v.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 } : {});`;
@@ -9367,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';
@@ -9378,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': {
@@ -9410,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': {
@@ -9431,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:
@@ -10231,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;
@@ -10620,7 +10857,7 @@ if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
   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
@@ -10649,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 `
@@ -11135,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 };`;
     }
     /**
@@ -11443,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);
@@ -12466,7 +12711,7 @@ ${cam ? `  // The camera rides the SAME timing: framing each state as its morph
     }
     /** pinepaper_emitter (D29): create('emitter', spec) / setEmitter(id, patch). */
     generateEmitter(raw) {
-        const S = (v) => JSON.stringify(v);
+        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