@pinepaper.studio/mcp-server 1.6.23 → 1.6.24

package/dist/types/code-generator.js

@@ -5,11 +5,13 @@
  * This code is designed to run in the browser context where window.PinePaper is available.
  */
 import { compileChoreography } from '../tools/choreograph.js';
+import { compileBatchTimelines, emitTimelineOpBody } from '../tools/timeline.js';
 import { normalizeSvgSize } from '../utils/svg-size.js';
 import { WORLD3D_COLOR_PATHS } from '../tools/engine-lists.js';
 import { REQUIRED_ENGINE_METHODS, OPTIONAL_ENGINE_METHODS } from '../tools/engine-methods.js';
 import { ACCEPTED_CREATE_PARAMS, NORMALIZE_PARAM_READS, MODIFY_CHANGE_READS } from '../tools/shape-params.js';
 import { generateP5DrawCode } from '../tools/p5-compat/p5-helpers.js';
+import { expandBatchMacros } from '../tools/batch-macros.js';
 import { CreateItemInputSchema, ScreenSpaceSchema, StepTimingSchema, CounterSchema, ImportMotionCaptureInputSchema, ModifyItemInputSchema, AddRelationInputSchema, AnimateItemInputSchema, KeyframeAnimateInputSchema, ExecuteGeneratorInputSchema, ApplyEffectInputSchema, SetBackgroundColorInputSchema, SetCanvasSizeInputSchema, CreateGlossySphereInputSchema, CreateDiagonalStripesInputSchema, BatchCreateInputSchema, BatchModifyInputSchema, CreateGridInputSchema, CreateSceneInputSchema, 
 // Diagram types
 CreateDiagramShapeInputSchema, ConnectInputSchema, ConnectPortsInputSchema, AddPortsInputSchema, AutoLayoutInputSchema, GetDiagramShapesInputSchema, UpdateConnectorInputSchema, RemoveConnectorInputSchema, DiagramModeInputSchema, 
@@ -26,7 +28,7 @@ GlobeEnableInputSchema, GlobeRotateToInputSchema, GlobeSpinInputSchema, WorldTou
 // Custom relation/code types
 RegisterCustomRelationInputSchema, ExecuteCustomCodeInputSchema, 
 // Mask types
-ApplyAnimatedMaskInputSchema, ApplyCustomMaskInputSchema, RemoveMaskInputSchema, SceneGraphInputSchema, SequenceInputSchema, StaggerInputSchema, FlipInputSchema, QueryCapabilitiesInputSchema, KEYFRAME_EASINGS, EASING_DESCRIPTIONS, MaskTypeSchema, MaskPresetSchema, } from './schemas.js';
+ApplyAnimatedMaskInputSchema, ApplyCustomMaskInputSchema, RemoveMaskInputSchema, SceneGraphInputSchema, SequenceInputSchema, StaggerInputSchema, PatternInputSchema, FlipInputSchema, QueryCapabilitiesInputSchema, KEYFRAME_EASINGS, EASING_DESCRIPTIONS, MaskTypeSchema, MaskPresetSchema, } from './schemas.js';
 import { OntologyCompiler } from '../ontology/ontology-compiler.js';
 // =============================================================================
 // HELPER FUNCTIONS
@@ -309,7 +311,8 @@ if (item && item.data) { item.data.renderAs = ${JSON.stringify(itemType)}; item.
     const textOnly = (k) => TEXT_STYLE_KEYS.includes(k) || k === 'fit' || k === 'textDirection' || k === 'dir'
         || TABULAR_KEYS.includes(k) || k === 'strokePosition';
     const ignored = Object.keys(properties).filter((k) => itemType === 'text'
-        ? !CREATE_KNOWN_KEYS.has(k) && !textOnly(k) && !DIRECTION_KEYS.includes(k)
+        ? (!CREATE_KNOWN_KEYS.has(k) && !textOnly(k) && !DIRECTION_KEYS.includes(k))
+            || (k === 'letterSpacing' && letterSpacingCss(properties[k]) === undefined)
         : !CREATE_KNOWN_KEYS.has(k) || textOnly(k));
     // Build the code
     let code = `
@@ -734,13 +737,26 @@ function authoringFrameJs(name) {
     return (typeof app.exportFrameRect === 'function' && app.exportFrameRect()) || cs || { width: 1920, height: 1080 };
   })();`;
 }
-const TEXT_STYLE_KEYS = ['fontWeight', 'fontStyle', 'leading', 'lineHeight', 'textAlign', 'align', 'text'];
+const TEXT_STYLE_KEYS = ['fontWeight', 'fontStyle', 'leading', 'lineHeight', 'letterSpacing', 'textAlign', 'align', 'text'];
+/**
+ * letterSpacing as the studio draws it, or undefined if it cannot be. create()
+ * and modifyItem() do not read it (B108); the studio draws the item's own
+ * letterSpacing, a CSS length, as its keyframes set it, and a number is px.
+ */
+function letterSpacingCss(v) {
+    if (typeof v === 'number' && Number.isFinite(v))
+        return `${v}px`;
+    if (typeof v === 'string' && /^-?\d*\.?\d+(px|em)?$/.test(v.trim()))
+        return /\d$/.test(v.trim()) ? `${v.trim()}px` : v.trim();
+    return undefined;
+}
 function emitTextStyle(itemExpr, props) {
     const weight = props.fontWeight;
     const italic = props.fontStyle === 'italic' || props.fontStyle === 'oblique';
     const lh = typeof props.lineHeight === 'number' ? props.lineHeight : undefined;
     const leading = typeof props.leading === 'number' ? props.leading : undefined;
-    if (weight === undefined && props.fontStyle === undefined && leading === undefined && lh === undefined)
+    const ls = letterSpacingCss(props.letterSpacing);
+    if (weight === undefined && props.fontStyle === undefined && leading === undefined && lh === undefined && ls === undefined)
         return '';
     return `
 (function(it) {
@@ -753,6 +769,7 @@ function emitTextStyle(itemExpr, props) {
         : ''}
   ${leading !== undefined ? `it.leading = ${leading};` : ''}
   ${lh !== undefined ? `it.leading = ${lh} <= 4 ? ${lh} * it.fontSize : ${lh};` : ''}
+  ${ls !== undefined ? `it.letterSpacing = ${JSON.stringify(ls)};` : ''}
   const b1 = it.bounds;
   it.position = it.position.add([ax - edge(b1), ay - b1.center.y]);
 })(${itemExpr});`;
@@ -1059,6 +1076,8 @@ if (_flagged && _flagged.item && _flagged.item.data) Object.assign(_flagged.item
     // AN UNREAD KEY HAD NO EFFECT, AND THE CALL SAID SUCCESS. {scaling: 8} on a
     // raster answered success and left it 16 px; the engine reads `scale`. Same
     // report create_item gives, against the engine's modify path (generated).
+    if (textStyle && letterSpacingCss(properties.letterSpacing) !== undefined)
+        aliased.add('letterSpacing');
     const modIgnored = Object.keys(properties).filter((k) => !MODIFY_KNOWN_KEYS.has(k) && !aliased.has(k));
     const modWarning = modIgnored.length === 0 ? '' : `, ignoredProperties: ${JSON.stringify(modIgnored)}, warning: ${JSON.stringify(`${modIgnored.join(', ')} ${modIgnored.length > 1 ? 'are' : 'is'} not read when modifying an item, so ${modIgnored.length > 1 ? 'they had' : 'it had'} no effect.`
         + modIgnored.filter((k) => MODIFY_DID_YOU_MEAN[k]).map((k) => ` Did you mean ${MODIFY_DID_YOU_MEAN[k]} (not ${k})?`).join(''))}`;
@@ -1191,6 +1210,61 @@ 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.`);
 }
+/**
+ * An emitter spec as the studio reads it, and what the reply says about it.
+ *
+ * The studio reads velocities and offsets as [x, y] pairs only and drops any
+ * other entry, so velocities: [{x, y}] made particles with no velocity and no
+ * word (VELOC23). Point objects are turned into pairs here. And a burst draws
+ * `count` particles, the i-th taking velocities[i % length]: with fewer
+ * velocities than particles the extras repeat a velocity and draw on top of an
+ * earlier particle, and with more the extras go unused, both in silence
+ * (VELOCMISMATCH23). That is said, not changed: cycling is the studio's rule.
+ * `assumeDefaultCount` is false for a set, whose spec is only the keys changed.
+ */
+export function normalizeEmitterSpec(spec, assumeDefaultCount = true) {
+    const warnings = [];
+    if (!spec || typeof spec !== 'object')
+        return { spec, warnings };
+    const pairs = (v) => (Array.isArray(v)
+        ? v.map((p) => (p && typeof p === 'object' && !Array.isArray(p) && ('x' in p || 'y' in p)
+            ? [Number(p.x ?? 0), Number(p.y ?? 0)]
+            : p))
+        : v);
+    const fix = (o) => {
+        const out = { ...o };
+        for (const k of ['velocities', 'offsets'])
+            if (out[k] !== undefined)
+                out[k] = pairs(out[k]);
+        return out;
+    };
+    const out = fix(spec);
+    if (Array.isArray(spec.bursts))
+        out.bursts = spec.bursts.map((b) => (b && typeof b === 'object' ? fix(b) : b));
+    // The studio's default count per burst (ParticleEmitter DEFAULT_LOOK).
+    const DEFAULT_COUNT = 12;
+    const mismatch = (where, count, velocities) => {
+        if (!Array.isArray(velocities) || !velocities.length)
+            return;
+        const n = typeof count === 'number' && Number.isFinite(count) ? Math.round(count) : (assumeDefaultCount ? DEFAULT_COUNT : null);
+        if (n === null || n === velocities.length)
+            return;
+        warnings.push(n > velocities.length
+            ? `${where}: count ${n} with ${velocities.length} velocities: particle i takes velocities[i % ${velocities.length}], so ${n - velocities.length} particles repeat an earlier particle's path and draw on top of it. Give one velocity per particle, or set count to ${velocities.length}.`
+            : `${where}: count ${n} with ${velocities.length} velocities: only the first ${n} velocities are used. Set count to ${velocities.length} to draw them all.`);
+    };
+    // The spec's own pair once; a burst only where it sets either itself (it inherits the rest).
+    const bursts = Array.isArray(out.bursts) ? out.bursts : [];
+    const inherited = bursts.some((b) => !b || typeof b !== 'object' || (b.count === undefined && b.velocities === undefined));
+    if (out.velocities !== undefined && (out.count !== undefined || inherited))
+        mismatch('spec', out.count, out.velocities);
+    bursts.forEach((b, i) => {
+        const own = (b && typeof b === 'object' ? b : {});
+        if (own.count !== undefined || own.velocities !== undefined)
+            mismatch(`bursts[${i}]`, own.count ?? out.count, own.velocities ?? out.velocities);
+    });
+    return { spec: out, warnings };
+}
 /**
  * moves_along_path, from the parameters a caller actually writes.
  *
@@ -2044,9 +2118,11 @@ const remaining = app.itemRegistry ? app.itemRegistry.getAll().length : 0;
  */
 function generateExportSVGCode() {
     return `
-// Export animated SVG
+// Export animated SVG. An export that produced nothing is a failure, named, not a success with an empty string.
 const svgString = app.exportAnimatedSVG();
-({ success: true, svgString, hasAnimations: svgString.includes('<animate') });
+(typeof svgString !== 'string' || svgString.length === 0)
+  ? ({ success: false, step: 'export', error: 'export failed at the export step: exportAnimatedSVG returned ' + (svgString === '' ? 'an empty string' : (svgString === null ? 'null' : typeof svgString)) + ', so there is no SVG to return' })
+  : ({ success: true, svgString, hasAnimations: svgString.includes('<animate') });
 `.trim();
 }
 /**
@@ -2374,6 +2450,15 @@ ${itemSettersApplyJs(s, '__sid', '__res')}
   return __res;
 })();`;
 }
+/**
+ * A batch op's item reference as a JS expression: `$N` is the Nth item this
+ * batch created, anything else is an id, quoted. Only digits follow the `$` —
+ * the raw splice it replaces put `$1);…;(` straight into the snippet, and an id
+ * with a quote in it broke the batch's syntax.
+ */
+export function batchRef(raw) {
+    return typeof raw === 'string' && /^\$\d+$/.test(raw) ? `__ref(${raw.slice(1)})` : JSON.stringify(String(raw));
+}
 function asReturningBody(snippet) {
     const single = snippet.trim();
     if (single.startsWith('(async function()'))
@@ -4265,11 +4350,16 @@ throw new Error('Unknown diagram mode action: ${action}');
      */
     generateAgentBatchExecute(input) {
         const validated = AgentBatchExecuteInputSchema.parse(input);
-        const { operations, atomic } = validated;
+        const { atomic } = validated;
+        // ring / grid / orbit / stagger / patch become the batch's own ops (batch-macros.ts).
+        const operations = expandBatchMacros(validated.operations);
         const isAtomic = atomic !== false;
         // Fold duplicate keyframe_animate targets so a later op can't silently
         // clobber an earlier track (app.addAnimation replaces, never merges).
         const mergePlan = planKeyframeMerges(operations);
+        // Timeline ops compile here, on the server: the handler refuses a batch whose timeline does not compile before
+        // anything runs; a direct caller gets the op's own failure instead.
+        const timelines = compileBatchTimelines(operations);
         let code = `
 // Batch execute ${operations.length} operations
 (async function() {
@@ -4298,11 +4388,32 @@ throw new Error('Unknown diagram mode action: ${action}');
   };
   const results = [];
   let success = true;
+  // A failure's words, never "undefined" for a thrown non-Error.
+  const _why = (e, fb) => (e && typeof e.message === 'string' && e.message.trim()) ? e.message
+    : (typeof e === 'string' && e.trim()) ? e : fb;
+  // THE SCENE LINT AFTER THE CODE (FxTool lintScene().warnings): what the scene will show wrong without anything
+  // failing (a centred title that runs out of the frame). Carried out under __ppLint; the server moves it beside the
+  // result. A studio without lintScene says nothing.
+  const __ppLintNow = function () {
+    try {
+      if (typeof app === 'undefined' || !app || typeof app.lintScene !== 'function') return [];
+      const r = app.lintScene();
+      return r && Array.isArray(r.warnings) ? r.warnings : [];
+    } catch (e) {
+      return [{ code: 'LINT_FAILED', severity: 'info', message: 'the scene lint could not run: ' + ((e && typeof e.message === 'string' && e.message) || 'no reason given') }];
+    }
+  };
+  // Every failed op as { step, itemId, reason }, beside the per-op results.
+  const _failures = () => results.filter((r) => !r.success).map((r) => ({ step: r.step, itemId: r.itemId, reason: r.reason }));
 
   try {
 `;
         operations.forEach((op, index) => {
-            const opCode = this.generateBatchOperationCode(op, index, mergePlan);
+            const opCode = op.type === 'timeline'
+                ? (timelines.plans.has(index)
+                    ? emitTimelineOpBody(timelines.plans.get(index), (t) => (t.startsWith('$') ? `__ref(${t.substring(1)})` : JSON.stringify(t)))
+                    : `return { success: false, error: ${JSON.stringify(timelines.errors.filter((e) => e.path.startsWith(`operations[${index}]`)).map((e) => `${e.path}: ${e.message}`).join('; ') || 'the timeline did not compile')} };`)
+                : this.generateBatchOperationCode(op, index, mergePlan);
             // $N variable references are documented as "items CREATED in earlier
             // operations" — only `create` results may extend the itemIds array.
             // animate/keyframe_animate/modify/delete also return { itemId } (the
@@ -4313,6 +4424,10 @@ throw new Error('Unknown diagram mode action: ${action}');
             // vehicles, 2026-07-30). `group` already follows this rule by
             // returning groupId instead of itemId.
             const claimsItemSlot = op.type === 'create';
+            // The item this op acts on, for a failure's itemId: its own id field, else what its result names.
+            const o = op;
+            const opItem = [o.itemId, o.targetId, o.sourceId, o.id].find((v) => typeof v === 'string') ?? null;
+            const opStep = typeof o._step === 'string' ? `op ${index}: ${o._step}` : `op ${index} (${op.type})`;
             code += `
     // Operation ${index}: ${op.type}
     try {
@@ -4329,7 +4444,7 @@ throw new Error('Unknown diagram mode action: ${action}');
       if (failed${index}) {
         // ATOMIC: throw WITHOUT recording, and let the catch below record it
         // once. Doing both put two entries in for one failed op.
-        ${isAtomic ? `throw new Error(failed${index});` : `results.push({ index: ${index}, success: false, error: failed${index}, result: result${index} });
+        ${isAtomic ? `const __e${index} = new Error(failed${index}); __e${index}.itemId = (result${index} && typeof result${index}.itemId === 'string') ? result${index}.itemId : ${JSON.stringify(opItem)}; throw __e${index};` : `results.push({ index: ${index}, success: false, step: ${JSON.stringify(opStep)}, itemId: (result${index} && typeof result${index}.itemId === 'string') ? result${index}.itemId : ${JSON.stringify(opItem)}, reason: failed${index}, error: failed${index}, result: result${index} });
         success = false;`}
       } else {
         results.push({ index: ${index}, success: true, result: result${index} });
@@ -4338,7 +4453,8 @@ throw new Error('Unknown diagram mode action: ${action}');
         }` : ''}
       }
     } catch (opError) {
-      results.push({ index: ${index}, success: false, error: opError.message });
+      const __r${index} = _why(opError, 'operation ${index} (${op.type}) threw with no message');
+      results.push({ index: ${index}, success: false, step: ${JSON.stringify(opStep)}, itemId: (opError && typeof opError.itemId === 'string') ? opError.itemId : ${JSON.stringify(opItem)}, reason: __r${index}, error: __r${index} });
       ${isAtomic ? 'throw opError;' : 'success = false;'}
     }
 `;
@@ -4358,15 +4474,19 @@ throw new Error('Unknown diagram mode action: ${action}');
     }
     return { success, itemIds, results, operationCount: ${operations.length},
       failedCount: _failed.length,
-      ...(_failed.length ? { error: _failed.map((r) => 'op ' + r.index + ': ' + r.error).join('; ') } : {}),
-      canvasSize: { width: _cs.width || 800, height: _cs.height || 600 } };
+      ...(_failed.length ? { error: _failed.map((r) => 'op ' + r.index + ': ' + r.error).join('; '), failures: _failures() } : {}),
+      canvasSize: { width: _cs.width || 800, height: _cs.height || 600 }, ...((function () { const l = __ppLintNow(); return l.length ? { __ppLint: l } : {}; })()) };
   } catch (e) {
     // A batch that created nothing keeps the previous batch's ids on record.
     if (typeof window !== 'undefined' && itemIds.length) {
       window.__pinepaper_batch_item_ids = itemIds;
     }
     const _cs = app.getCanvasSize ? app.getCanvasSize() : { width: 800, height: 600 };
-    return { success: false, error: e.message, itemIds, results, operationCount: ${operations.length}, canvasSize: { width: _cs.width || 800, height: _cs.height || 600 } };
+    const __fails = _failures();
+    const __reason = _why(e, 'the batch failed with no message');
+    return { success: false, error: __reason, itemIds, results, operationCount: ${operations.length},
+      failures: __fails.length ? __fails : [{ step: 'batch', itemId: null, reason: __reason }],
+      canvasSize: { width: _cs.width || 800, height: _cs.height || 600 }, ...((function () { const l = __ppLintNow(); return l.length ? { __ppLint: l } : {}; })()) };
   }
 })();
 `;
@@ -4403,7 +4523,7 @@ throw new Error('Unknown diagram mode action: ${action}');
                     'backgroundColor', 'generatorName', 'generatorParams', 'generatorRegion',
                     'width', 'height', 'preset', 'keyframes', 'duration', 'loop',
                     'maskPreset', 'maskType', 'maskOptions', 'effectType', 'effectParams',
-                    'action', 'time', 'append'
+                    'action', 'time', 'append', '_step'
                 ]);
                 for (const [k, v] of Object.entries(anyOp)) {
                     if (!batchKeys.has(k) && v !== undefined && opProps[k] === undefined) {
@@ -4448,9 +4568,7 @@ return __created;
                 return createCode;
             }
             case 'modify': {
-                const itemRef = op.itemId?.startsWith('$')
-                    ? `__ref(${op.itemId.substring(1)})`
-                    : `'${op.itemId}'`;
+                const itemRef = batchRef(op.itemId);
                 // modify_item's own emitter, as create is create_item's (see above):
                 // the batch's modifyItem call missed text styles, font loading, audio
                 // level, no-fill, lifetimes, smoothing and the unread-property report.
@@ -4463,15 +4581,21 @@ return __created;
                     .replace(/;\s*$/, '');
                 return `
 const __mid = ${itemRef};
+if (app.itemRegistry && app.itemRegistry.getItem && !app.itemRegistry.getItem(__mid) && typeof app.getItemsByName === 'function') {
+  // A NAME HELD BY SEVERAL ITEMS is refused, not resolved: getItemById answers
+  // the first holder, so a patch by name would change whichever came first.
+  const __held = app.getItemsByName(__mid) || [];
+  if (__held.length > 1) {
+    return { success: false, itemId: __mid, error: __held.length + ' items are named ' + JSON.stringify(__mid) + ' (' + __held.map(function (h) { return (h && h.data && h.data.id) || '?'; }).join(', ') + '); pass one of their ids.' };
+  }
+}
 const __r = await ${single};
 if (__r && __r.success !== false) __r.modified = true;
 return __r;
 `;
             }
             case 'animate':
-                const animItemRef = op.itemId?.startsWith('$')
-                    ? `__ref(${op.itemId.substring(1)})`
-                    : `'${op.itemId}'`;
+                const animItemRef = batchRef(op.itemId);
                 const animOpts = JSON.stringify(op.animationOptions || {});
                 return `
 const targetId = ${animItemRef};
@@ -4481,12 +4605,8 @@ app.animate(item, { animationType: '${op.animationType}', ...${animOpts} });
 return { itemId: targetId, animationType: '${op.animationType}' };
 `;
             case 'relation':
-                const srcRef = op.sourceId?.startsWith('$')
-                    ? `__ref(${op.sourceId.substring(1)})`
-                    : `'${op.sourceId}'`;
-                const tgtRef = op.targetId?.startsWith('$')
-                    ? `__ref(${op.targetId.substring(1)})`
-                    : `'${op.targetId}'`;
+                const srcRef = batchRef(op.sourceId);
+                const tgtRef = batchRef(op.targetId);
                 const relOpts = JSON.stringify(op.relationOptions || {});
                 return `
 const sourceId = ${srcRef};
@@ -4508,9 +4628,7 @@ if (!relationId) {
 return { relationId, sourceId, targetId, relationType: '${op.relationType}' };
 `;
             case 'delete':
-                const delRef = op.itemId?.startsWith('$')
-                    ? `__ref(${op.itemId.substring(1)})`
-                    : `'${op.itemId}'`;
+                const delRef = batchRef(op.itemId);
                 return `
 const targetId = ${delRef};
 const item = app.getItemById(targetId);
@@ -4521,7 +4639,7 @@ return { itemId: targetId, deleted: true };
 `;
             case 'group': {
                 // Resolve each ref ($N → itemIds[N]; literal → quoted id) into a JS array.
-                const refs = (op.itemIds || []).map((ref) => ref?.startsWith('$') ? `__ref(${ref.substring(1)})` : `'${ref}'`);
+                const refs = (op.itemIds || []).map((ref) => batchRef(ref));
                 const idsArrayExpr = `[${refs.join(', ')}]`;
                 const nameExpr = op.groupName !== undefined ? JSON.stringify(op.groupName) : 'undefined';
                 // Returns { groupId, ... } (no itemId) so it does NOT shift $N indices — like relation.
@@ -4533,8 +4651,8 @@ return (function() {${this.groupCodeBody(idsArrayExpr, nameExpr)}
             case 'set_background':
                 const bgColor = op.backgroundColor || op.color || op.properties?.backgroundColor || op.properties?.color || '#000000';
                 return `
-app.setBackgroundColor('${bgColor}');
-return { success: true, backgroundColor: '${bgColor}' };
+app.setBackgroundColor(${JSON.stringify(String(bgColor))});
+return { success: true, backgroundColor: ${JSON.stringify(String(bgColor))} };
 `;
             case 'execute_generator':
                 const genName = op.generatorName || 'drawSunburst';
@@ -4565,14 +4683,12 @@ return { success: true, width: (_cs && _cs.width) || ${w}, height: (_cs && _cs.h
                     return `
 // Keyframes merged into operation ${foldTarget} (same target). A keyframe track
 // is replaced wholesale, so emitting both here would silently drop one.
-return { itemId: ${op.itemId?.startsWith('$') ? `__ref(${op.itemId.substring(1)})` : `'${op.itemId}'`}, merged: true, mergedInto: ${foldTarget} };
+return { itemId: ${batchRef(op.itemId)}, merged: true, mergedInto: ${foldTarget} };
 `;
                 }
                 const mergedPayload = mergePlan?.merged.get(index);
                 const rawItemId = String(op.itemId ?? op.id ?? op.properties?.itemId ?? op.properties?.id);
-                const kfItemRef = rawItemId?.startsWith('$')
-                    ? `__ref(${rawItemId.substring(1)})`
-                    : `'${rawItemId}'`;
+                const kfItemRef = batchRef(rawItemId);
                 const kfSource = mergedPayload
                     ? mergedPayload.keyframes
                     : (op.keyframes || (op.properties && op.properties.keyframes) || (op.params && op.params.keyframes) || []);
@@ -4614,9 +4730,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 +4747,7 @@ return { success: !!maskedGroup, itemId: targetId, preset: '${preset}' };
 `;
             }
             case 'apply_effect': {
-                const effItemRef = op.itemId?.startsWith('$')
-                    ? `__ref(${op.itemId.substring(1)})`
-                    : `'${op.itemId}'`;
+                const effItemRef = batchRef(op.itemId);
                 const effParams = JSON.stringify(op.effectParams || {});
                 return `
 const targetId = ${effItemRef};
@@ -5120,6 +5232,19 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
   // cannot be kept accurate — it breaks on any edit above it — so this repo
   // does not use them. Camera animation still
   // drives motion during export — framing only fixes the output frame.
+  // THE SCENE LINT, BEFORE THE EXPORT (FxTool lintScene().warnings): what the file will show wrong without
+  // anything failing — a centre-anchored text that runs out of the frame exports as "IGNAL" for "SIGNAL". Read from the
+  // scene as it is, never a refusal; a studio without the rule says nothing, a lint that throws says so.
+  const __lint = (function () {
+    if (typeof app.lintScene !== 'function') return null;
+    try {
+      const r = app.lintScene();
+      return r && Array.isArray(r.warnings) ? r.warnings : null;
+    } catch (e) {
+      return [{ code: 'LINT_FAILED', severity: 'info', message: 'the scene lint could not run before the export: ' + ((e && typeof e.message === 'string' && e.message) || 'no reason given') }];
+    }
+  })();
+
   let cameraDims = null;
   if (framing === 'camera') {
     if (!['gif', 'apng', 'mp4', 'webm'].includes(format)) {
@@ -5668,7 +5793,7 @@ ${stillTime !== undefined ? `
                     if (typeof fr.embedded === 'number') __tl.fonts.embedded = fr.embedded; // cumulative for the document
                     if (typeof fr.hiddenTextItems === 'number') __tl.fonts.hiddenTextItems = (__tl.fonts.hiddenTextItems || 0) + fr.hiddenTextItems;
                   }
-                } catch (e) { if (!__tl.fonts) __tl.fonts = { embedded: 0, reason: e && e.message }; }
+                } catch (e) { if (!__tl.fonts) __tl.fonts = { embedded: 0, reason: (e && typeof e.message === 'string' && e.message) || 'embedding the text fonts failed with no reason given' }; }
               }
               if (jpg) doc.addImage(jpg, 'JPEG', 0, 0, wMM, hMM); else doc.addImage(png, 'PNG', 0, 0, wMM, hMM);
               if (__layer) {
@@ -5676,7 +5801,7 @@ ${stillTime !== undefined ? `
                   const tr = await app.exportEngine.addTextLayer(doc, { x: 0, y: 0, width: wMM, height: hMM });
                   if (tr && tr.ok !== false) { __tl.written += tr.linesWritten || 0; __tl.skipped += tr.linesSkipped || 0; }
                   else __tl.reasons.push(id + ': ' + ((tr && tr.reason) || 'refused'));
-                } catch (e) { __tl.reasons.push(id + ': ' + e.message); }
+                } catch (e) { __tl.reasons.push(id + ': ' + ((e && typeof e.message === 'string' && e.message) || 'the text layer failed with no reason given')); }
               }
               pagesOut.push({ sceneId: id, widthMM: Math.round(wMM * 10) / 10, heightMM: Math.round(hMM * 10) / 10 });
             }
@@ -5739,7 +5864,7 @@ ${stillTime !== undefined ? `
         result = { success: false, error: 'Unknown format: ' + format };
     }
   } catch (e) {
-    result = { success: false, error: e.message, platform, format };
+    result = { success: false, error: (e && typeof e.message === 'string' && e.message) || (typeof e === 'string' && e) || ('the ' + format + ' export threw with no message'), platform, format };
   }
 
   // One site, after every branch has set its result: a successful export says
@@ -5777,11 +5902,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
@@ -7713,14 +7846,39 @@ ${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) {
         // An async IIFE is still a `(`-led expression statement, so the governor
         // captures its value, and executeCode's eval fallback already resolves a
         // returned promise. Both paths await it; neither needed changing.
+        //
+        // The code runs inside its own async arrow so its `return` is still its value; the value comes back under
+        // __ppValue with the scene lint beside it, and a throw comes back as { step, itemId, reason }, never a bare
+        // message (and never "undefined" for a thrown non-Error).
         return `
 // ${description}
 (async function() {
+  // THE SCENE LINT AFTER THE CODE (FxTool lintScene().warnings): what the scene will show wrong without anything
+  // failing (a centred title that runs out of the frame). Carried out under __ppLint; the server moves it beside the
+  // result. A studio without lintScene says nothing.
+  const __ppLintNow = function () {
+    try {
+      if (typeof app === 'undefined' || !app || typeof app.lintScene !== 'function') return [];
+      const r = app.lintScene();
+      return r && Array.isArray(r.warnings) ? r.warnings : [];
+    } catch (e) {
+      return [{ code: 'LINT_FAILED', severity: 'info', message: 'the scene lint could not run: ' + ((e && typeof e.message === 'string' && e.message) || 'no reason given') }];
+    }
+  };
+  let __ppValue;
   try {
+    __ppValue = await (async () => {
     ${validated.code}
+    })();
   } catch (error) {
-    return { success: false, error: error.message };
-  }
+    const __ppReason = (error && typeof error.message === 'string' && error.message.trim()) ? error.message
+      : (typeof error === 'string' && error.trim()) ? error : 'the custom code threw with no message';
+    return { success: false, step: 'execute_custom_code', itemId: (error && typeof error.itemId === 'string') ? error.itemId : null,
+      reason: __ppReason, error: __ppReason, ...((function () { const l = __ppLintNow(); return l.length ? { __ppLint: l } : {}; })()) };
+  }
+  // Only wrapped when the lint has something to say: otherwise the value is returned exactly as before.
+  const __ppL = __ppLintNow();
+  return __ppL.length ? { __ppValue: __ppValue, __ppLint: __ppL } : __ppValue;
 })();
 `.trim();
     }
@@ -8528,6 +8686,53 @@ ${input.cutSound !== undefined ? `  const __cuts = (__cr && __cr.cuts) || (app.s
   };
 })();
 `.trim();
+    }
+    /**
+     * pinepaper_pattern (AR-2 P2): one stored declaration moves many items (FxTool app.addPattern / modifyPattern /
+     * removePattern / listPatterns / getPattern). No keyframes are written; the engine evaluates the node per frame.
+     */
+    generatePattern(input) {
+        const v = PatternInputSchema.parse(input);
+        const S = (x) => JSON.stringify(x);
+        const need = (fn) => `if (typeof app.${fn} !== 'function') return { success: false, error: 'app.${fn} unavailable — this studio predates patterns (FxTool AR-2 P1); update it' };`;
+        const idNeeded = v.action !== 'list' && !v.id ? `return { success: false, error: '${v.action} needs the pattern id' };` : '';
+        let body;
+        switch (v.action) {
+            case 'create': {
+                const spec = { id: v.id, kind: v.kind, members: v.members, params: v.params || {}, ...(v.window ? { window: v.window } : {}) };
+                body = `${need('addPattern')}
+  if (!${S(v.kind ?? null)}) return { success: false, error: 'create needs kind: phase_wave or stagger' };
+  if (!${S(v.members ?? null)}) return { success: false, error: 'create needs members: { names: [...] }, { ids: [...] }, { tag } or an array' };
+  const r = app.addPattern(${S(spec)});
+  return Object.assign({ success: !!(r && r.ok) }, r || {}, app.lastReceipt ? { receipt: app.lastReceipt } : {});`;
+                break;
+            }
+            case 'modify': {
+                const ch = { ...(v.params ? { params: v.params } : {}), ...(v.members ? { members: v.members } : {}), ...(v.window !== undefined ? { window: v.window } : {}) };
+                body = `${need('modifyPattern')}
+  const r = app.modifyPattern(${S(v.id)}, ${S(ch)});
+  return Object.assign({ success: !!(r && r.ok) }, r || {}, app.lastReceipt ? { receipt: app.lastReceipt } : {});`;
+                break;
+            }
+            case 'remove':
+                body = `${need('removePattern')}
+  const had = app.removePattern(${S(v.id)});
+  return had ? { success: true, removed: ${S(v.id)} } : { success: false, error: 'no pattern ' + ${S(JSON.stringify(v.id ?? ''))} };`;
+                break;
+            case 'get':
+                body = `${need('getPattern')}
+  const p = app.getPattern(${S(v.id)});
+  return p ? Object.assign({ success: true }, p) : { success: false, error: 'no pattern ' + ${S(JSON.stringify(v.id ?? ''))} };`;
+                break;
+            default:
+                body = `${need('listPatterns')}
+  const list = app.listPatterns();
+  return { success: true, count: list.length, patterns: list };`;
+        }
+        return `(function() {
+  ${idNeeded}
+  ${body}
+})();`;
     }
     generateStagger(input) {
         const validated = StaggerInputSchema.parse(input);
@@ -10368,6 +10573,9 @@ if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
 (async function() {
   if (!app.exportEngine || !app.exportEngine.exportWidget) return { error: 'Widget export not available' };
   const result = await app.exportEngine.exportWidget(${JSON.stringify(opts)});
+  if (!result || typeof result.json !== 'string' || result.json.length === 0) {
+    return { success: false, step: 'export', error: 'export failed at the export step: exportWidget returned no scene JSON' + (result && result.error ? ' (' + result.error + ')' : '') };
+  }
   // THE EMBED BOX WAS ALWAYS 16:9, AND IT IS NOT SELF-CONTAINED (round 9 GG,
   // 8.32). The engine writes aspect-ratio: 16/9 and max-width: 800px whatever
   // the scene, so a 300x250 ad sat letterboxed in a wide box. The box is sized
@@ -10403,6 +10611,9 @@ if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
 (async function() {
   if (!app.exportEngine || !app.exportEngine.exportWidgetHTML) return { error: 'Widget HTML export not available' };
   const result = await app.exportEngine.exportWidgetHTML(${JSON.stringify(opts)});
+  if (!result || typeof result.html !== 'string' || result.html.length === 0) {
+    return { success: false, step: 'export', error: 'export failed at the export step: exportWidgetHTML returned no page' + (result && result.error ? ' (' + result.error + ')' : '') };
+  }
   ${input.lang || input.dir || input.alt ? `// lang / dir / alt on the engine's page (it writes <html lang="en"> and no
   // text alternative). Applied as string edits on the one <html> tag and the
   // first <canvas>; the result says which landed.
@@ -11325,7 +11536,10 @@ ${checks.includes('contrast') ? `  // SAMPLED OVER TIME (round 12, 12.9): text i
     return { success: false, error: 'app.lintScene unavailable — update FxTool to a build with the relational linter (S12-E2)' };
   }
   const result = app.lintScene(${optsJson});
-  return { success: true, density: result.density, suggestions: result.suggestions };
+  // warnings: what the engine's own rules found (TEXT_CLIPS_FRAME: a centre-anchored text running past the
+  // frame edge). Passed through when the studio reports them; an older studio has none to pass.
+  return { success: true, density: result.density, suggestions: result.suggestions,
+    ...(Array.isArray(result.warnings) && result.warnings.length ? { warnings: result.warnings } : {}) };
 })();`.trim();
     }
     /**
@@ -12251,8 +12465,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) {
+    generateEmitter(raw) {
         const S = (v) => JSON.stringify(v);
+        const normalized = normalizeEmitterSpec(raw.spec, raw.action !== 'set');
+        const input = { ...raw, spec: normalized.spec };
         // A COUNT OVER THE CAP IS SAID (B144). The cap is 10000 a burst on the
         // current studio and was 2000 before it, clamped in silence (2300 drew
         // ~1940). Which applies is read from the spec the studio STORED — its
@@ -12274,7 +12490,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 +13781,15 @@ ${guard('exportPNGSequence')}
     return Object.assign({ success: true, format: 'png-sequence', data: dataUrl, mimeType: out.type || 'application/zip', size: out.size }, __pngSeqDefaults);
   }
   if (Array.isArray(out)) {
-    return { success: true, format: 'png-sequence', frames: out.length,
+    // NOT A SAVED FILE, and said so in fields: file null, and why.
+    return { success: true, format: 'png-sequence', frames: out.length, file: null,
+      why: 'the frames stayed in the page: the studio returned them as a list of frames, not a file, so no file was written. Pass download: true to have the browser download them as a zip.',
       note: 'the frames stayed in the page — pass download: true to write them out.' };
   }
-  return { success: true, format: 'png-sequence', result: out };
+  // download: true — the studio handed the zip to the BROWSER's download, so no bytes reached this server and no file
+  // was written by it. Said in fields, so it cannot be read as a saved file.
+  return { success: true, format: 'png-sequence', result: out, file: null,
+    why: 'the studio handed the zip to the browser as a download (download: true): it went to the browser\\'s download folder, no bytes reached the MCP server, and the server wrote no file.' };
 })();`.trim();
         }
     }