@pinepaper.studio/mcp-server 1.6.35 → 1.6.37

package/dist/types/code-generator.js

@@ -502,13 +502,14 @@ const __scale = (function(it) {
     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 += ("\nconst itemId = item.data.registryId;\napp.historyManager.saveState();\n\n// Return item info\n({ itemId, type: " +
+    code += ("\nconst itemId = item.data.registryId;\n// Debounced where the studio has it: a full snapshot per create made one-call-per-item building O(items) a call.\napp.historyManager[app.historyManager.saveStateDebounced ? 'saveStateDebounced' : 'saveState']();\n\n// Return item info\n({ itemId, type: " +
 String(jsLiteral(itemType)) +
 String(outlineOnly ? `, fill: ${JSON.stringify(OUTLINE_NOTE)}` : '') +
 String(textFit ? ', textFit: __textFit' : '') +
 String(textDirection ? ', direction: __direction' : '') +
 String(textTabular ? ', tabularFigures: __tabular' : '') +
-String(textTypography.length ? ', typography: __typography' : '') + String(createFillOpacity ? ', fillOpacity: __fillOpacity' : '') + String(textStrokePos ? ', strokePosition: __strokePos' : '') + String(hasCreateScale ? ', scale: __scale' : '') + ", position: " + String(reportActualPosition ? `(item.position ? { x: item.position.x, y: item.position.y } : null)` : `{ x: ${position.x}, y: ${position.y} }`) + String(hasLifetime ? ', lifetime: __lifetime' : '') + String(loadsFont ? ', ...(__font ? { font: __font } : {})' : '') + String(ignored.length > 0
+String(textTypography.length ? ', typography: __typography' : '') +
+String(createFillOpacity ? ', fillOpacity: __fillOpacity' : '') + String(textStrokePos ? ', strokePosition: __strokePos' : '') + String(hasCreateScale ? ', scale: __scale' : '') + ", position: " + String(reportActualPosition ? `(item.position ? { x: item.position.x, y: item.position.y } : null)` : `{ x: ${position.x}, y: ${position.y} }`) + String(hasLifetime ? ', lifetime: __lifetime' : '') + String(loadsFont ? ', ...(__font ? { font: __font } : {})' : '') + String(ignored.length > 0
         ? `, ignoredProperties: ${JSON.stringify(ignored)}` : '') + String(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
@@ -1577,15 +1578,19 @@ const EVENT_PULSING_RELATIONS = new Set(['on_complete', 'at_beat']);
 function eventNameResolveJs(relationType, paramsVar) {
     if (!EVENT_PULSING_RELATIONS.has(String(relationType)))
         return 'const __ev = {};';
-    return `const __ev = {};
-  (function(p) {
-    if (!p || typeof p.event !== 'string' || !p.event || app.getItemById(p.event)) return;
-    const ids = (app.itemRegistry && app.itemRegistry.getAll ? app.itemRegistry.getAll() : [])
-      .filter(function(e) { return e && e.item && e.item.data && e.item.data.isEvent && e.item.data.eventName === p.event; })
-      .map(function(e) { return e.id || e.itemId; });
-    if (ids.length === 1) { __ev.eventResolvedFrom = p.event; __ev.eventResolvedTo = ids[0]; p.event = ids[0]; }
-    else if (ids.length > 1) __ev.warning = ids.length + ' events are named ' + JSON.stringify(p.event) + ' (' + ids.join(', ') + '), so params.event cannot say which one: it pulses the literal name, which no reaction bound to an event hears. Pass one event id as params.event.';
-  })(${paramsVar});`;
+    return ("const __ev = {};\n  (function(p) {\n    if (!p || typeof p.event !== 'string' || !p.event) return;\n    // An id, not a name: getItemById also finds an item by its NAME, so a hit alone said 'done' was an id and the\n    // name was never resolved (ONCOMP35: no eventResolvedTo in eight sessions). Only an exact registry id counts.\n    const __hit = app.getItemById(p.event);\n    if (__hit && __hit.data && (__hit.data.registryId === p.event || __hit.data.id === p.event)) return;\n    const ids = (app.itemRegistry && app.itemRegistry.getAll ? app.itemRegistry.getAll() : [])\n      .filter(function(e) { return e && e.item && e.item.data && e.item.data.isEvent && e.item.data.eventName === p.eve" +
+"nt; })\n      .map(function(e) { return e.id || e.itemId; });\n    if (ids.length === 1) { __ev.eventResolvedFrom = p.event; __ev.eventResolvedTo = ids[0]; p.event = ids[0]; }\n    else if (ids.length > 1) __ev.warning = ids.length + ' events are named ' + JSON.stringify(p.event) + ' (' + ids.join(', ') + '), so params.event cannot say which one: it pulses the literal name, which no reaction bound to an event hears. Pass one event id as params.event.';\n  })(" +
+String(paramsVar) +
+");"
+
+
+
+
+
+
+
+
+);
 }
 /** Spread into a reply after its own fields: the resolve fields, with an event warning joined onto any warning. */
 const EV_MERGE_JS = (replyVar, key = 'warning') => `Object.keys(__ev).forEach(function(k) { if (k !== 'warning') ${replyVar}[k] = __ev[k]; });
@@ -1745,6 +1750,17 @@ export function normalizeEmitterSpec(spec, assumeDefaultCount = true) {
         if (own.count !== undefined || own.velocities !== undefined)
             mismatch(`bursts[${i}]`, own.count ?? out.count, own.velocities ?? out.velocities);
     });
+    // SPAWN IS A BOX ON THE CANVAS AXES (ParticleEmitter: x += (u - 0.5) * spawn[0], y += (u - 0.5) * spawn[1]), not a
+    // range and not along the burst's angle. spawn [0, 200] beside angle 0 drew a vertical column of particles that
+    // then flew right (SPAWNAX36). Said once, where a spawn box meets an aimed angle.
+    const fullCircle = (a) => a === undefined || (Array.isArray(a) && Number(a[1]) - Number(a[0]) >= 360);
+    const aimed = [{ where: 'spec', own: out }, ...bursts.map((b, i) => ({ where: `bursts[${i}]`, own: (b && typeof b === 'object' ? b : {}) }))]
+        .find(({ own }) => (own.spawn ?? out.spawn) !== undefined && !fullCircle(own.angle ?? out.angle));
+    if (aimed) {
+        const sp = aimed.own.spawn ?? out.spawn;
+        const box = Array.isArray(sp) ? `${sp[0]} wide and ${sp[1]} tall` : `${sp} by ${sp}`;
+        warnings.push(`${aimed.where}: spawn is a box on the canvas axes centred on the burst point (here ${box}), not a range and not turned to the burst's angle: particles start anywhere in it and fly along angle. To spread them across the direction of travel, size the box on that axis (spawn [w, 0] spreads along x, [0, h] along y).`);
+    }
     // A RANGE WHERE THE STUDIO READS ONE NUMBER is not drawn as a range (1.6.24
     // probe: count [a, b] → 0 on older studios, the middle on FxTool #228). Only
     // the keys that take one number on EVERY build are named here. gravity, drag,
@@ -2204,6 +2220,58 @@ function keyframeResultNotes(keyframes, { loop = false, append = false, easingAt
         : '';
     return `${easingNote}${sizekeyPairNote}${gapNote}`;
 }
+/**
+ * READ BACK THE KEY TIMES (LONGKEY36). A studio that rescales keyframe times (one that reads any time over 100 as
+ * milliseconds, whatever timeUnits says) stored a 120 s track as 0.12 s, and the export froze at its end state from
+ * the first half second while every reply said success. After the write, each asked time must be on the stored
+ * track. If it is not: a track that spans 100 s or less is rewritten from 0 with its first key as the clip's
+ * timeOffset (which the studio keeps), so it plays at the asked times; otherwise the earlier track is put back and
+ * the call fails with the times asked and stored. A studio that keeps the times passes on the first read.
+ *
+ * `before` goes just before the addAnimation call, `after` just after it (it may `return` a failure), and `field`
+ * is spread into the success reply.
+ */
+function keyTimeGuard(a) {
+    const scale = a.timeUnits === 'ms' ? 0.001 : 1;
+    const asked = a.keyframes.map((k) => (Number(k.time) || 0) * scale).sort((x, y) => x - y);
+    const first = asked.length ? asked[0] : 0;
+    const end = asked.length ? asked[asked.length - 1] : 0;
+    const canShift = !a.append && !a.timeOffsetGiven && first > 0 && end - first <= 100;
+    const shiftedKfs = canShift ? normalizeKeyframePositions(a.keyframes.map((k) => ({ ...k, time: (Number(k.time) || 0) * scale - first }))) : [];
+    const shiftedOpts = canShift ? { ...a.opts, timeUnits: 'seconds', timeOffset: first, duration: Math.max(end - first, (Number(a.duration) || 0) * scale - first) } : {};
+    const advice = end - first > 100
+        ? 'This studio cannot hold a keyframe track whose keys span more than 100 s. Split the motion: key the first part on this item and the rest on a copy that starts later (timeOffset), or keep each track within 100 s.'
+        : a.append
+            ? 'This studio cannot hold a key past 100 s in a merged track. Key the late part on its own track with timeOffset instead of appending.'
+            : 'Keep each track within 100 s, or start it later with timeOffset.';
+    const it = a.item;
+    const before = `
+  // The whole earlier track, so a write the studio got wrong can be undone.
+  const __prevKfs = (${it} && ${it}.data && Array.isArray(${it}.data.keyframes)) ? ${it}.data.keyframes.map(function(k) { return Object.assign({}, k, { properties: Object.assign({}, k && k.properties) }); }) : [];`;
+    const after = ("\n  const __asked = " +
+String(JSON.stringify(asked)) +
+";\n  const __storedTimes = function() { return (" +
+String(it) +
+" && " +
+String(it) +
+".data && Array.isArray(" +
+String(it) +
+".data.keyframes)) ? " +
+String(it) +
+".data.keyframes.map(function(k) { return k && k.time; }) : []; };\n  const __landed = function(shift) { const st = __storedTimes(); return __asked.every(function(t) { return st.some(function(x) { return Math.abs(x + shift - t) < 1e-6; }); }); };\n  let __shifted = null;\n  // Only a track the studio wrote and this can read is checked; one stored elsewhere is not judged.\n  if (" +
+String(it) +
+" && __storedTimes().length && !__landed(0)) {\n    const __wrong = __storedTimes();\n    " +
+String(canShift ? `app.addAnimation(${a.target}, ${JSON.stringify(shiftedKfs)}, ${JSON.stringify(shiftedOpts)});
+    if (__landed(${first}) && Math.abs((Number(${it}.data.timeOffset) || 0) - ${first}) < 1e-6) {
+      __shifted = { by: ${first}, note: 'this studio cannot hold a key past 100 s in one track, so the keys were written from 0 and the track starts at ${first} s (timeOffset). It plays at the times asked.' };
+    } else ` : '') +
+"{\n      if (__prevKfs.length) app.addAnimation(" +
+String(a.target) +
+", __prevKfs, { timeUnits: 'seconds', loop: " +
+String(a.loop === true) +
+" });\n      else if (typeof app.clearKeyframes === 'function') app.clearKeyframes(" + String(it) + ");\n      return { success: false, itemId: " + String(a.target) + ", code: 'keyframe_times_not_kept',\n        error: 'the studio did not keep the key times: asked ' + __asked[0] + '..' + __asked[__asked.length - 1] + ' s, it stored ' + __wrong.slice(0, 3).join(', ') + (__wrong.length > 3 ? ', ...' : '') + ' s. ' + " + String(JSON.stringify(advice)) + " + (__prevKfs.length ? ' The earlier track was put back.' : ' The track was removed.'),\n        askedTimes: __asked.slice(0, 20), storedTimes: __wrong.slice(0, 20) };\n    }\n  }");
+    return { before, after, field: ', ...(__shifted ? { shifted: __shifted } : {})' };
+}
 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);
@@ -2215,8 +2283,10 @@ function generateKeyframeAnimateCode(itemId, keyframes, duration, loop = false,
         opts.clipInPoint = clipInPoint;
     if (clipOutPoint !== undefined)
         opts.clipOutPoint = clipOutPoint;
-    if (timeUnits !== undefined)
-        opts.timeUnits = timeUnits;
+    // TIMES ARE SECONDS UNLESS THE CALLER SAYS ms. Left unset, the studio guesses (TimeUnits.js): any time over 100
+    // made it read EVERY time as milliseconds, so a 120 s track ran in 0.12 s and the export showed its end state from
+    // the first half second, reported as a success (GRIEF). The tool documents seconds, so the server says seconds.
+    opts.timeUnits = timeUnits ?? 'seconds';
     // addAnimation SETS the item's track; mode 'merge' adds to it (FxTool
     // 2475333b). An engine without merge ignores the option and replaces.
     if (append)
@@ -2266,29 +2336,47 @@ String(JSON.stringify(levelKeys)) +
     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 || ' : ''}__filterIgnored.length ? { ignoredProperties: ${textKeysJs ? '__ignored.concat(__filterIgnored)' : '__filterIgnored'} } : {}), ...(__warn.length ? { warning: __warn.join(' ') } : {})`;
+    // Said where the old guess would have read this track differently: a time over 100 with no unit given.
+    const __lastTime = Math.max(0, ...keyframes.map((k) => Number(k.time) || 0), Number(duration) || 0);
+    const unitsNote = timeUnits === undefined && __lastTime > 100
+        ? `\n  __warn.push(${JSON.stringify(`times are read as seconds: the track ends at ${__lastTime} s (${(__lastTime / 60).toFixed(1)} min). If you meant milliseconds, pass timeUnits: 'ms'.`)});`
+        : '';
     const addAnimTarget = itemId.startsWith('$') ? '_targetId' : `${ID}`;
+    const guard = keyTimeGuard({ target: addAnimTarget, item: '__ki', keyframes, timeUnits, append, timeOffsetGiven: timeOffset !== undefined, loop, opts, duration: calculatedDuration });
     return ("\n// Apply keyframe animation to " +
 String(ID) +
 "\n(function() {\n  " +
 String(requireItem(itemId, 'the animation')) +
 String(audioLevelGuard) +
-"\n  // The track as it was, so the result can say what happened to it: merged\n  // (every earlier key still there) or replaced. That is the evidence of\n  // merge support — an older engine takes the option and replaces anyway.\n  const __ki = _target && (_target.item || _target);\n  const __prev = (__ki && __ki.data && Array.isArray(__ki.data.keyframes)) ? __ki.data.keyframes.map(function(k) { return k && k.time; }) : [];\n  const __opts = " +
+"\n  // The track as it was, so the result can say what happened to it: merged\n  // (every earlier key still there) or replaced. That is the evidence of\n  // merge support — an older engine takes the option and replaces anyway.\n  const __ki = _target && (_target.item || _target);\n  const __prev = (__ki && __ki.data && Array.isArray(__ki.data.keyframes)) ? __ki.data.keyframes.map(function(k) { return k && k.time; }) : [];\n  // SQUASH35: a merge whose new key lands on an existing key's time takes the new key's easing, in silence. The\n  // earlier keys' easings, by time, so a collision that changed one can be named.\n  const __prevEase = (__ki && __ki.data && Array.isArray(__ki.data.keyf" +
+"rames)) ? __ki.data.keyframes.map(function(k) { return [k && k.time, (k && k.easing) || 'linear']; }) : [];\n  const __opts = " +
 String(JSON.stringify(opts)) +
-";\n  app.addAnimation(" +
+";\n" +
+String(guard.before) +
+"\n  app.addAnimation(" +
 String(addAnimTarget) +
 ", " +
 String(keyframesJson) +
 ", __opts);\n  const __warn = [];" +
+String(unitsNote) +
+"\n" +
+String(guard.after) +
 String(easingAtCheck) +
 String(textKeyCheck) +
 String(filterKeyCheck) +
 "\n  const __now = (__ki && __ki.data && Array.isArray(__ki.data.keyframes)) ? __ki.data.keyframes.map(function(k) { return k && k.time; }) : [];\n  const __kept = __prev.every(function(t) { return __now.indexOf(t) >= 0; });" +
-String(append ? `
-  // Property gaps across the merged track (the same check a single call makes
-  // on its own keys at generation time).
-  const __all = (__ki && __ki.data && Array.isArray(__ki.data.keyframes)) ? __ki.data.keyframes : [];
-  const __props = __all.reduce(function(acc, k) { Object.keys((k && k.properties) || {}).forEach(function(p) { if (acc.indexOf(p) < 0) acc.push(p); }); return acc; }, []);
-  const __gaps = __all.length > 1 ? __all.map(function(k) { const have = Object.keys((k && k.properties) || {}); return { time: k && k.time, missing: __props.filter(function(p) { return have.indexOf(p) < 0; }) }; }).filter(function(g) { return g.missing.length; }) : [];` : '') +
+String(append ? ("\n  // Property gaps across the merged track (the same check a single call makes\n  // on its own keys at generation time).\n  const __all = (__ki && __ki.data && Array.isArray(__ki.data.keyframes)) ? __ki.data.keyframes : [];\n  const __props = __all.reduce(function(acc, k) { Object.keys((k && k.properties) || {}).forEach(function(p) { if (acc.indexOf(p) < 0) acc.push(p); }); return acc; }, []);\n  const __collide = __prevEase.map(function(pe) {\n    const k = __all.find(function(n) { return n && n.time === pe[0]; });\n    const ne = k ? (k.easing || 'linear') : null;\n    return (ne && ne !== pe[1]) ? { time: pe[0], was: pe[1], now: ne } : null;\n  }).filter(Boolean);\n  if (__collide.le" +
+"ngth) __warn.push('append: ' + __collide.length + ' new key(s) landed on the time of an existing key and replaced its easing (' + __collide.slice(0, 5).map(function(c) { return 't=' + c.time + ' ' + c.was + ' -> ' + c.now; }).join(', ') + '). Pass the easing you want on the colliding key, or move the new key off that time.');\n  const __gaps = __all.length > 1 ? __all.map(function(k) { const have = Object.keys((k && k.properties) || {}); return { time: k && k.time, missing: __props.filter(function(p) { return have.indexOf(p) < 0; }) }; }).filter(function(g) { return g.missing.length; }) : [];"
+
+
+
+
+
+
+
+
+
+) : '') +
 "\n  const __track = !__prev.length ? null\n    : " +
 String(append ? `(__kept
       ? { appended: true, previousKeys: __prev.length, keys: __now.length }
@@ -2301,7 +2389,12 @@ String(calculatedDuration) +
 ", loop: " +
 String(loop) +
 String(append ? ', append: true' : '') +
-", ...(__track ? { track: __track } : {})" + String(append ? `, ...(__gaps.length ? { propertyGaps: __gaps.slice(0, 10), gapWarning: __gaps.length + ' key(s) of the merged track leave out a property other keys animate (' + __gaps.reduce(function(a, g) { g.missing.forEach(function(p) { if (a.indexOf(p) < 0) a.push(p); }); return a; }, []).join(', ') + '). The engine can break that property at such a key; give each key the full set — hold a value by repeating it.' } : {})` : '') + String(timeOffset !== undefined ? `, timeOffset: ${timeOffset}` : '') + String(clipInPoint !== undefined ? `, clipInPoint: ${clipInPoint}` : '') + String(clipOutPoint !== undefined ? `, clipOutPoint: ${clipOutPoint}` : '') + String(__notes) + String(runtimeWarning) + " };\n})();\n").trim();
+String(guard.field) +
+", ...(__track ? { track: __track } : {})" +
+String(append ? `, ...(__gaps.length ? { propertyGaps: __gaps.slice(0, 10), gapWarning: __gaps.length + ' key(s) of the merged track leave out a property other keys animate (' + __gaps.reduce(function(a, g) { g.missing.forEach(function(p) { if (a.indexOf(p) < 0) a.push(p); }); return a; }, []).join(', ') + '). The engine can break that property at such a key; give each key the full set — hold a value by repeating it.' } : {})` : '') +
+String(timeOffset !== undefined ? `, timeOffset: ${timeOffset}` : '') +
+String(clipInPoint !== undefined ? `, clipInPoint: ${clipInPoint}` : '') +
+String(clipOutPoint !== undefined ? `, clipOutPoint: ${clipOutPoint}` : '') + String(__notes) + String(runtimeWarning) + " };\n})();\n").trim();
 }
 /**
  * Template for executing generators
@@ -2392,15 +2485,26 @@ String(itemId ? `
     if (!__si) return { success: false, error: ${JSON.stringify(`region.shape names no item "${itemId}" — nothing was drawn. List items with pinepaper_get_items.`)} };
     if (__si.className !== 'Path' && __si.className !== 'CompoundPath') return { success: false, error: ${JSON.stringify(`region.shape item "${itemId}" is a `)} + __si.className + ', and a clip needs a path (a shape, not text, a group or an image) — nothing was drawn.' };
   }` : '') +
-"\n  await app.executeGenerator(" +
-String(jsLiteral(generatorName)) +
-", " +
+"\n  // FOREGROUND GENERATORS DEFAULT TO EDITABLE PARTS (owner, 2026-11-14). The studio files ui, infographics and\n  // captions generators as foreground; with interactive on, each part (a bubble, a button, a label) is its own item,\n  // which is what a phone frame or a chat thread is for, and what pinepaper_group ungroup releases. The studio's\n  // own default is false for every generator, so unless the caller says, a foreground one runs with true.\n  const __gp = " +
 String(paramsJson) +
-", " +
+";\n  let __interactiveDefault = false;\n  if (__gp && __gp.interactive === undefined && app.generatorRegistry && app.generatorRegistry.get) {\n    const __gd = app.generatorRegistry.get(" +
+String(jsLiteral(generatorName)) +
+");\n    const __gc = __gd && __gd.category;\n    if (__gc === 'ui' || __gc === 'infographics' || __gc === 'captions') { __gp.interactive = true; __interactiveDefault = true; }\n  }\n  await app.executeGenerator(" +
+String(jsLiteral(generatorName)) +
+", __gp, " +
 String(options) +
 ");" +
 String(shaped ? `
-  const __shapes = !!(app.generatorRegistry && typeof app.generatorRegistry._regionClipPath === 'function');` : '') + "\n  return { success: true, generator: " + String(jsLiteral(generatorName)) + String(region ? `, region: ${JSON.stringify(region)}` : '') + String(shaped ? `, ...(__shapes ? {} : { regionShapeApplied: false, warning: ${JSON.stringify(`this studio does not clip generator regions to a shape, so ${typeof region.shape === 'object' ? 'the region had no box and the generator drew across the whole canvas' : `the ${region.shape} was drawn as a rectangle`}. It needs an engine with region shapes.`)} })` : '') + " };");
+  const __shapes = !!(app.generatorRegistry && typeof app.generatorRegistry._regionClipPath === 'function');` : '') +
+"\n  return { success: true, generator: " +
+String(jsLiteral(generatorName)) +
+", ...(__interactiveDefault ? { interactive: true, interactiveNote: 'a foreground generator: its parts are editable items (interactive: true by default for ui, infographics and captions generators). Pass params.interactive: false for one flattened composition.' } : {})" +
+String(region ? `, region: ${JSON.stringify(region)}` : '') +
+String(shaped ? `, ...(__shapes ? {} : { regionShapeApplied: false, warning: ${JSON.stringify(`this studio does not clip generator regions to a shape, so ${typeof region.shape === 'object' ? 'the region had no box and the generator drew across the whole canvas' : `the ${region.shape} was drawn as a rectangle`}. It needs an engine with region shapes.`)} })` : '') +
+" };"
+
+
+);
 }
 /**
  * Template for applying effects
@@ -3172,6 +3276,15 @@ function asReturningBody(snippet) {
  * out, and the batch saves once at the end, which is what batchCreate was
  * for. An item that fails is reported by index; the rest are still created.
  */
+/**
+ * A create inside a batch skips the engine's per-item select, snapshot and redraw (`_bulkCreate`, the template
+ * loader's path); the batch saves and draws once at the end. A governed run gets this from the engine already, but a
+ * batch over the governor's size limit runs ungoverned, and there every create redrew the whole scene: 400 creates
+ * on 2,000 items spent 2 of 5 s in full redraws.
+ */
+function asBulkCreate(code) {
+    return code.replace(/(const item = app\.create\((?:\x22[^\x22\n]*\x22|\x27[^\x27\n]*\x27), )\{/g, '$1{ _bulkCreate: true, ');
+}
 function generateBatchCreateCode(items) {
     const blocks = items.map((it, i) => {
         const { x, y, position, ...props } = (it.params || {});
@@ -3179,8 +3292,8 @@ function generateBatchCreateCode(items) {
             : (position && typeof position === 'object') ? { x: Number(position.x), y: Number(position.y) }
                 : { x: typeof x === 'number' ? x : 400, y: typeof y === 'number' ? y : 300 };
         const given = position !== undefined || typeof x === 'number' || typeof y === 'number';
-        const body = asReturningBody(generateCreateItemCode(it.type, p, props, undefined, given))
-            .replace(/app\.historyManager\.saveState\(\);/g, '');
+        const body = asBulkCreate(asReturningBody(generateCreateItemCode(it.type, p, props, undefined, given)))
+            .replace(/app\.historyManager(?:\.saveState\(\)|\[app\.historyManager\.saveStateDebounced \? 'saveStateDebounced' : 'saveState'\]\(\));/g, '');
         return `
   try {
     const r${i} = await (async function() {
@@ -3197,6 +3310,8 @@ ${body}
   const errors = [];
 ${blocks.join('\n')}
   if (app.historyManager) app.historyManager.saveState();
+  // Bulk creates skipped their redraws: one for the batch.
+  try { if (typeof paper !== 'undefined' && paper.view) paper.view.draw(); } catch (_) { /* the frame loop draws */ }
   return { success: errors.length === 0, items: results, count: results.length, errors: errors };
 })();`.trim();
 }
@@ -5092,7 +5207,41 @@ String(oneLine(operations.length)) +
 "t): create and group ops take a slot each, in op\n  // order (O2, mcp-server#29: a group is an item every later op addresses, and it had no slot). The\n  // previous batch's ids are kept only to name the right id when a $N reaches\n  // past what this batch has made: picking it silently shifted every $N in a\n  // batch that also creates (B115 follow-up).\n  const itemIds = [];\n  const __prevBatchIds = ((typeof window !== 'undefined' && window.__pinepaper_batch_item_ids) || []).slice();\n  const __ref = function (n) {\n    if (itemIds[n] !== undefined) return itemIds[n];\n    const prev = __prevBatchIds[n];\n    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.'\n      + (prev ? ' In the previous batch $' + n + ' was ' + prev + ' — pass that id instead.' : ' Put the ops that make it first, or pass the item id.'));\n  };\n  // A failure names the item, not the \"$1\" that addressed it; the ref as written when the batch never made it.\n  const __refName = function (n) { return itemIds[n] !== undefined ? itemIds[n] : '$' + n; };\n  const results = [];\n  let success = true;\n  // A failure's words, never \"undefined\" for a thrown non-Error.\n  const _why = (e, fb) => (e && typeof e.message === 'string' && e.message.trim()) ? e.message\n    : (typeof e " +
 "=== 'string' && e.trim()) ? e : fb;\n  // THE SCENE LINT AFTER THE CODE (FxTool lintScene().warnings): what the scene will show wrong without anything\n  // failing (a centred title that runs out of the frame). Carried out under __ppLint; the server moves it beside the\n  // result. A studio without lintScene says nothing.\n  const __ppLintNow = function () {\n    try {\n      if (typeof app === 'undefined' || !app || typeof app.lintScene !== 'function') return [];\n      const r = app.lintScene({ warningsOnly: true });\n      return r && Array.isArray(r.warnings) ? r.warnings : [];\n    } catch (e) {\n      return [{ code: 'LINT_FAILED', severity: 'info', message: 'the scene lint could no" +
-"t run: ' + ((e && typeof e.message === 'string' && e.message) || 'no reason given') }];\n    }\n  };\n  // Every failed op as { step, itemId, reason }, beside the per-op results.\n  const _failures = () => results.filter((r) => !r.success).map((r) => ({ step: r.step, itemId: r.itemId, reason: r.reason }));\n\n  try {\n"
+"t run: ' + ((e && typeof e.message === 'string' && e.message) || 'no reason given') }];\n    }\n  };\n  // Every failed op as { step, itemId, reason }, beside the per-op results.\n  const _failures = () => results.filter((r) => !r.success).map((r) => ({ step: r.step, itemId: r.itemId, reason: r.reason }));\n  // ONE UNDO SNAPSHOT FOR THE BATCH, NOT ONE PER OP. Each create saved a full-project snapshot\n  // (exportJSON), so a batch on a big scene cost O(items) per op: 200 creates on 2,000 items took\n  // 14 s against 0.76 s for the bare creates. History batch mode skips the per-op saves; the batch\n  // saves once at the end, as it always did.\n  const __hm = app.historyManager && app.his" +
+"toryManager.beginBatch ? app.historyManager : null;\n  if (__hm) __hm.beginBatch();\n  let __hmOpen = !!__hm;\n  const __hmEnd = () => {\n    if (__hmOpen) { __hmOpen = false; __hm.endBatch(false); }\n    // Bulk creates skipped their redraws: one for the batch.\n    try { if (typeof paper !== 'undefined' && paper.view) paper.view.draw(); } catch (_) { /* the frame loop draws */ }\n  };\n\n  try {\n  // ONE WRAPPER FOR EVERY OP.\n  // Not throwing is not succeeding: an op that RETURNS { success: false } (a guard that found a facade missing, a\n  // preset the engine does not have) raises nothing, and was recorded as a success. Atomic: throw WITHOUT\n  // recording and let the catch record " +
+"it once (doing both put two entries in for one failed op).\n  const __op = async (index, type, step, opItem, claims, fn) => {\n    try {\n      const result = await fn();\n      const failed = _opFailure(result);\n      if (failed) {\n        const itemId = (result && typeof result.itemId === 'string') ? result.itemId : opItem();\n        " +
+String(isAtomic ? "const e = new Error(failed); e.itemId = itemId; throw e;" : "results.push({ index, success: false, step, itemId, reason: failed, error: failed, result }); success = false;") +
+"\n      } else {\n        results.push({ index, success: true, result });\n        if (claims && result && result.itemId) itemIds.push(result.itemId);\n      }\n    } catch (opError) {\n      const r = _why(opError, 'operation ' + index + ' (' + type + ') threw with no message');\n      results.push({ index, success: false, step, itemId: (opError && typeof opError.itemId === 'string') ? opError.itemId : opItem(), reason: r, error: r });\n      " +
+String(isAtomic ? 'throw opError;' : 'success = false;') +
+"\n    }\n  };\n\n"
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 
 
 
@@ -5159,44 +5308,19 @@ String(oneLine(operations.length)) +
             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 += ("\n    // Operation " +
-String(oneLine(index)) +
-": " +
-String(oneLine(op.type)) +
-"\n    try {\n      const result" +
-String(index) +
-" = await (async () => {\n        " +
-String(opCode) +
-"\n      })();\n      // NOT THROWING IS NOT SUCCEEDING. An op that RETURNS { success: false }\n      // — a guard that found a facade missing, a preset the engine does not\n      // have, a precondition unmet — raises nothing, so this recorded it as a\n      // success and the batch reported success over it. Measured on\n      // applyAnimatedMask(item, 'star'): the per-op error was perfectly good\n      // and the batch still said everything worked.\n      const failed" +
-String(index) +
-" = _opFailure(result" +
-String(index) +
-");\n      if (failed" +
-String(index) +
-") {\n        // ATOMIC: throw WITHOUT recording, and let the catch below record it\n        // once. Doing both put two entries in for one failed op.\n        " +
-String(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;`) +
-"\n      } else {\n        results.push({ index: " +
-String(index) +
-", success: true, result: result" +
-String(index) +
-" });\n        " +
-String(claimsItemSlot ? `if (result${index} && result${index}.itemId) {
-          itemIds.push(result${index}.itemId);
-        }` : '') +
-"\n      }\n    } catch (opError) {\n      const __r" +
-String(index) +
-" = _why(opError, 'operation " +
-String(index) +
-" (" +
-String(op.type) +
-") threw with no message');\n      results.push({ index: " +
-String(index) + ", success: false, step: " + String(JSON.stringify(opStep)) + ", itemId: (opError && typeof opError.itemId === 'string') ? opError.itemId : " + String(opItemJs) + ", reason: __r" + String(index) + ", error: __r" + String(index) + " });\n      " + String(isAtomic ? 'throw opError;' : 'success = false;') + "\n    }\n");
+            // The wrapper is the shared __op helper (emitted once, below the history batch), not a copy per op: the
+            // copied try/catch and its comments were ~1.5 KB of every op, 4.8 MB of code for 2,000 creates.
+            code += `
+    // Operation ${oneLine(index)}: ${oneLine(op.type)}
+    await __op(${index}, ${JSON.stringify(op.type)}, ${JSON.stringify(opStep)}, () => ${opItemJs}, ${claimsItemSlot}, async () => {
+        ${opCode}
+    });
+`;
         });
-        code += ("\n    // Save state\n    if (app.historyManager) app.historyManager.saveState();\n\n    const _cs = app.getCanvasSize ? app.getCanvasSize() : { width: 800, height: 600 };\n    // Name WHICH ops failed on the result itself. A caller reading a failed\n    // 60-op batch should not have to scan sixty entries to learn that op 41\n    // could not find a preset.\n    const _failed = results.filter((r) => !r.success);\n    // A batch that created nothing keeps the previous batch's ids on record.\n    if (typeof window !== 'undefined' && itemIds.length) {\n      window.__pinepaper_batch_item_ids = itemIds;\n    }\n    return { success, itemIds, results, operationCount: " +
+        code += ("\n    // Save state\n    __hmEnd();\n    if (app.historyManager) app.historyManager.saveState();\n\n    const _cs = app.getCanvasSize ? app.getCanvasSize() : { width: 800, height: 600 };\n    // Name WHICH ops failed on the result itself. A caller reading a failed\n    // 60-op batch should not have to scan sixty entries to learn that op 41\n    // could not find a preset.\n    const _failed = results.filter((r) => !r.success);\n    // A batch that created nothing keeps the previous batch's ids on record.\n    if (typeof window !== 'undefined' && itemIds.length) {\n      window.__pinepaper_batch_item_ids = itemIds;\n    }\n    return { success, itemIds, results, operationCount: " +
 String(operations.length) +
-",\n      failedCount: _failed.length,\n      ...(_failed.length ? { error: _failed.map((r) => 'op ' + r.index + ': ' + r.error).join('; '), failures: _failures() } : {}),\n      canvasSize: { width: _cs.width || 800, height: _cs.height || 600 }, ...((function () { const l = __ppLintNow(); return l.length ? { __ppLint: l } : {}; })()) };\n  } catch (e) {\n    // A batch that created nothing keeps the previous batch's ids on record.\n    if (typeof window !== 'undefined' && itemIds.length) {\n      window.__pinepaper_batch_item_ids = itemIds;\n    }\n    const _cs = app.getCanvasSize ? app.getCanvasSize() : { width: 800, height: 600 };\n    const __fails = _failures();\n    const __reason = " +
-"_why(e, 'the batch failed with no message');\n    return { success: false, error: __reason, itemIds, results, operationCount: " +
+",\n      failedCount: _failed.length,\n      ...(_failed.length ? { error: _failed.map((r) => 'op ' + r.index + ': ' + r.error).join('; '), failures: _failures() } : {}),\n      canvasSize: { width: _cs.width || 800, height: _cs.height || 600 }, ...((function () { const l = __ppLintNow(); return l.length ? { __ppLint: l } : {}; })()) };\n  } catch (e) {\n    __hmEnd();\n    // A batch that created nothing keeps the previous batch's ids on record.\n    if (typeof window !== 'undefined' && itemIds.length) {\n      window.__pinepaper_batch_item_ids = itemIds;\n    }\n    const _cs = app.getCanvasSize ? app.getCanvasSize() : { width: 800, height: 600 };\n    const __fails = _failures();\n    c" +
+"onst __reason = _why(e, 'the batch failed with no message');\n    return { success: false, error: __reason, itemIds, results, operationCount: " +
 String(operations.length) +
 ",\n      failures: __fails.length ? __fails : [{ step: 'batch', itemId: null, reason: __reason }],\n      canvasSize: { width: _cs.width || 800, height: _cs.height || 600 }, ...((function () { const l = __ppLintNow(); return l.length ? { __ppLint: l } : {}; })()) };\n  }\n})();\n"
 
@@ -5220,6 +5344,8 @@ String(operations.length) +
 
 
 
+
+
 
 
 
@@ -5274,7 +5400,7 @@ String(operations.length) +
                 const createProps = withRadiusAxes(opProps);
                 const opBrand = { ...opProps };
                 delete opProps.noBrand;
-                const returning = asReturningBody(withBrandDefaults(generateCreateItemCode(op.itemType, pos, { ...opProps }, undefined, op.position !== undefined || typeof anyOp.x === 'number' || typeof anyOp.y === 'number'), op.itemType, opBrand));
+                const returning = asBulkCreate(asReturningBody(withBrandDefaults(generateCreateItemCode(op.itemType, pos, { ...opProps }, undefined, op.position !== undefined || typeof anyOp.x === 'number' || typeof anyOp.y === 'number'), op.itemType, opBrand)));
                 let createCode = `${hasItemSetters(opSetters) ? `\n${itemSettersPreflightJs(opSetters)}` : ''}
 const __created = await (async function() {
 ${returning}
@@ -5559,17 +5685,27 @@ return { itemId: ${batchRef(op.itemId)}, merged: true, mergedInto: ${foldTarget}
                     if (op[key] !== undefined && Number.isFinite(v))
                         kfExtra.push(`${key}: ${v}`);
                 }
-                const kfUnits = op.timeUnits;
-                if (kfUnits === 'seconds' || kfUnits === 'ms')
-                    kfExtra.push(`timeUnits: ${jsLiteral(kfUnits)}`);
+                // Seconds unless the op says ms: the studio's own guess read every time as ms once one passed 100 (GRIEF).
+                const kfUnitsGiven = op.timeUnits === 'seconds' || op.timeUnits === 'ms';
+                const kfUnits = kfUnitsGiven ? op.timeUnits : 'seconds';
+                kfExtra.push(`timeUnits: ${jsLiteral(kfUnits)}`);
+                const kfLast = Math.max(0, ...(kfSource || []).map((k) => Number(k && k.time) || 0), Number(kfDuration) || 0);
+                const kfUnitsNote = !kfUnitsGiven && kfLast > 100
+                    ? `, timeUnitsNote: ${JSON.stringify(`times are read as seconds: the track ends at ${kfLast} s (${(kfLast / 60).toFixed(1)} min). If you meant milliseconds, pass timeUnits: 'ms'.`)}`
+                    : '';
                 const kfExtraStr = kfExtra.length > 0 ? `, ${kfExtra.join(', ')}` : '';
+                const kfGuard = keyTimeGuard({ target: 'targetId', item: '_kfItem', keyframes: (kfSource || []), timeUnits: kfUnits,
+                    append: kfAppend, timeOffsetGiven: op.timeOffset !== undefined, loop: kfLoop,
+                    opts: { duration: kfDuration, loop: kfLoop, ...(kfAppend ? { mode: 'merge' } : {}) }, duration: kfDuration });
                 const kfTextKeysJs = unanimatedTextKeysJs((kfSource || []).flatMap((k) => Object.keys(k.properties ?? {})));
                 const kfFilterKeysJs = unanimatedFilterKeysJs((kfSource || []).flatMap((k) => Object.keys(k.properties ?? {})));
                 const kfTextCheck = `\nconst _kfIgnored = ${kfTextKeysJs || '[]'};\nconst _kfFilterIgnored = ${kfFilterKeysJs};`;
                 const kfIgnored = `, ...(_kfIgnored.length || _kfFilterIgnored.length ? { ignoredProperties: _kfIgnored.concat(_kfFilterIgnored), warning: [_kfIgnored.length ? _kfIgnored.join(', ') + ${UNANIMATED_TEXT_KEYS_SENTENCE} : '', _kfFilterIgnored.length ? _kfFilterIgnored.join(', ') + ${UNANIMATED_FILTER_KEYS_SENTENCE} : ''].filter(Boolean).join(' ') } : {})`;
                 return ("\nconst targetId = " +
 String(kfItemRef) +
-";\nconst _target = (app.getItemById && app.getItemById(targetId))\n  || (app.itemRegistry && app.itemRegistry.get && app.itemRegistry.get(targetId));\nif (!_target) {\n  return { success: false, itemId: targetId, error: 'Item not found: ' + targetId };\n}\nconst _kfItem = _target.item || _target;\nconst _prevKeys = (_kfItem.data && Array.isArray(_kfItem.data.keyframes)) ? _kfItem.data.keyframes.length : 0;\napp.addAnimation(targetId, " +
+";\nconst _target = (app.getItemById && app.getItemById(targetId))\n  || (app.itemRegistry && app.itemRegistry.get && app.itemRegistry.get(targetId));\nif (!_target) {\n  return { success: false, itemId: targetId, error: 'Item not found: ' + targetId };\n}\nconst _kfItem = _target.item || _target;\nconst _prevKeys = (_kfItem.data && Array.isArray(_kfItem.data.keyframes)) ? _kfItem.data.keyframes.length : 0;\n" +
+String(kfGuard.before) +
+"\napp.addAnimation(targetId, " +
 String(kfJson) +
 ", { duration: " +
 String(kfDuration) +
@@ -5577,8 +5713,7 @@ String(kfDuration) +
 String(kfLoop) +
 String(kfAppend ? ", mode: 'merge'" : '') +
 String(kfExtraStr) +
-" });" +
-String(kfTextCheck) + "\nreturn { success: true, itemId: targetId, duration: " + String(kfDuration) + ", loop: " + String(kfLoop) + String(kfAppend ? ', append: true' : '') + String(keyframeResultNotes(kfSource, { loop: kfLoop === true, append: kfAppend })) + String(kfAppend ? '' : `, ...(_prevKeys ? { track: { replaced: true, previousKeys: _prevKeys, note: 'the item already had a keyframe track; this op replaced it. To add keys to it instead, pass append: true.' } } : {})`) + String(kfIgnored) + " };\n");
+" });" + String(kfGuard.after) + String(kfTextCheck) + "\nreturn { success: true, itemId: targetId, duration: " + String(kfDuration) + ", loop: " + String(kfLoop) + String(kfAppend ? ', append: true' : '') + String(kfGuard.field) + String(keyframeResultNotes(kfSource, { loop: kfLoop === true, append: kfAppend })) + String(kfAppend ? '' : `, ...(_prevKeys ? { track: { replaced: true, previousKeys: _prevKeys, note: 'the item already had a keyframe track; this op replaced it. To add keys to it instead, pass append: true.' } } : {})`) + String(kfUnitsNote) + String(kfIgnored) + " };\n");
             }
             case 'apply_mask': {
                 const maskItemRef = batchRef(op.itemId);
@@ -6439,7 +6574,10 @@ String(deterministic ? ("  // DETERMINISTIC: the container timestamps are pinned
 "  // LUMA OUTSIDE 16-235 (8.35, FxTool 4f1ec3ae). The broadcast encode is\n  // decoded back and measured: H.264 ringing at hard edges puts a fraction of\n  // a percent of samples out of range, which QC rejects. broadcastHeadroom\n  // cuts it but never to zero, so a legaliser pass is the requirement.\n  if (result && result.success && __vr && __vr.luma && __vr.luma.outOfRange > 0 && result.fidelity) {\n    result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'luma_out_of_range',\n      message: 'broadcast QC will reject this as delivered: ' + ((__vr.luma.outOfRangeFraction || 0) * 100).toFixed(3) + '% of decoded luma is outside 16-235 (min ' + __vr.luma.min + ', ma" +
 "x ' + __vr.luma.max + ', broadcastHeadroom ' + (typeof __vr.headroom === 'number' ? __vr.headroom : " +
 String(JSON.stringify(broadcastHeadroom ?? 12)) +
-") + '). First re-export with a larger broadcastHeadroom (12 measured clean on hard white-on-black edges; up to 40). Otherwise a legaliser pass is REQUIRED before delivery — clip into a NARROWER band and re-encode at high quality, because a plain 16-235 clip followed by a re-encode brings the edge overshoot back: ffmpeg -i in.mp4 -vf \"lutyuv=y=clip(val\\\\,28\\\\,223):u=clip(val\\\\,16\\\\,240):v=clip(val\\\\,16\\\\,240)\" -c:v libx264 -crf 18 -color_range tv -colorspace bt709 -color_primaries bt709 -color_trc bt709 -c:a copy out.mp4 (measured 20-229). Verify the luma range after re-encoding.' }]);\n    if (result.fidelity.note) delete result.fidelity.note;\n  }\n" +
+") + '). ' + (function () { const __h = typeof __vr.headroom === 'number' ? __vr.headroom : " +
+String(JSON.stringify(broadcastHeadroom ?? 12)) +
+"; return __h < 40 ? 'First re-export with broadcastHeadroom ' + Math.min(40, __h + 12) + ' (above the ' + __h + ' this used; 40 is the most): each step leaves fewer samples out of range and narrows the luma range of the picture, so check the result. ' : 'broadcastHeadroom is already at its most (40). '; })() + 'Otherwise a legaliser pass is REQUIRED before delivery — clip into a NARROWER band and re-encode at high quality, because a plain 16-235 clip followed by a re-encode brings the edge overshoot back: ffmpeg -i in.mp4 -vf \"lutyuv=y=clip(val\\\\,28\\\\,223):u=clip(val\\\\,16\\\\,240):v=clip(val\\\\,16\\\\,240)\" -c:v libx264 -crf 18 -color_range tv -colorspace bt709 -color_primaries bt" +
+"709 -color_trc bt709 -c:a copy out.mp4 (measured 20-229). Verify the luma range after re-encoding.' }]);\n    if (result.fidelity.note) delete result.fidelity.note;\n  }\n" +
 String(Object.keys(videoEncodeOpts).length ? ("  if (result && result.success) {\n    const __asked = " +
 String(JSON.stringify(videoEncodeOpts)) +
 ";\n    const __vw = [];\n    // The engine joins its warnings into one string (bitrate floor, then\n    // luma), so each is raised from its own numbers, not from that text.\n    // The studio's own measured bitrate_not_honoured, where it sends one,\n    // replaces this estimate.\n    const __engineBitrate = !!(__vr && Array.isArray(__vr.warnings) && __vr.warnings.some(function(w) { return w && w.code === 'bitrate_not_honoured'; }));\n    if (!__engineBitrate && __vr && typeof __vr.achievedBitrate === 'number' && typeof __vr.bitrateFloor === 'number' && __vr.achievedBitrate < __vr.bitrateFloor * 0.95) {\n      __vw.push({ code: 'bitrate_below_floor', message: 'achieved ' + (__vr.achievedB" +
@@ -7609,9 +7747,6 @@ String(jsLiteral(format)) +
 
 
 
-
-
-
 
 
 
@@ -11701,15 +11836,23 @@ String(warmArg) +
                 if (input.steps !== undefined)
                     params.steps = input.steps;
                 const itemIdStr = JSON.stringify(input.itemId);
-                return `
-// Apply deformation preset
-(function() {
-  ${guard}
-  const entry = app.itemRegistry.get(${itemIdStr});
-  if (!entry || !entry.item) return { error: 'Item not found: ' + ${itemIdStr} };
-  app.deformPresets.apply(entry.item, ${jsLiteral(input.preset)}, ${JSON.stringify(params)});
-  return { success: true, action: 'apply', itemId: ${itemIdStr}, preset: ${jsLiteral(input.preset)} };
-})();`.trim();
+                return ("\n// Apply deformation preset\n(function() {\n  " +
+String(guard) +
+"\n  const entry = app.itemRegistry.get(" +
+String(itemIdStr) +
+");\n  if (!entry || !entry.item) return { error: 'Item not found: ' + " +
+String(itemIdStr) +
+" };\n  // The engine refuses by name (deform-unknown-preset, deform-no-item, deform-no-geometry), in its return and in the\n  // receipt. The return was ignored, so a refused deform said success.\n  const __r = app.deformPresets.apply(entry.item, " +
+String(jsLiteral(input.preset)) +
+", " +
+String(JSON.stringify(params)) +
+");\n  const __rw = (app.lastReceipt && Array.isArray(app.lastReceipt.warnings) ? app.lastReceipt.warnings : [])\n    .filter(function (w) { return w && /^deform-/.test(String(w.kind || w.code || '')); });\n  if (__r === false || (__r && (__r.ok === false || __r.success === false)) || __rw.length) {\n    const __why = (__r && (__r.reason || __r.error)) || __rw.map(function (w) { return w.message || w.reason || w.kind || w.code; }).join(' ') || 'the studio did not apply the deform';\n    return { success: false, action: 'apply', itemId: " +
+String(itemIdStr) +
+", preset: " +
+String(jsLiteral(input.preset)) +
+", error: __why, ...(__rw.length ? { code: __rw[0].kind || __rw[0].code } : {}) };\n  }\n  return { success: true, action: 'apply', itemId: " +
+String(itemIdStr) +
+", preset: " + String(jsLiteral(input.preset)) + " };\n})();").trim();
             }
             case 'trigger': {
                 if (!input.itemId)
@@ -12711,17 +12854,28 @@ String(idExpr) +
         }
         if (input.action === 'ungroup') {
             const idExpr = JSON.stringify(input.groupId || '');
-            return `
-// Ungroup ${oneLine(input.groupId || '')}
-(function() {
-  if (!app.groupManager) return { success: false, error: 'GroupManager not available — update FxTool' };
-  const gid = ${idExpr};
-  const group = app.getItemById(gid) || (app.groupManager.getGroupById ? app.groupManager.getGroupById(gid) : null);
-  if (!group) return { success: false, error: 'Group not found: ' + gid };
-  app.groupManager.ungroupAll(group);
-  if (app.historyManager) app.historyManager.saveState();
-  return { success: true, ungrouped: true, groupId: gid };
-})();`.trim();
+            return ("\n// Ungroup " +
+String(oneLine(input.groupId || '')) +
+"\n(function() {\n  if (!app.groupManager) return { success: false, error: 'GroupManager not available — update FxTool' };\n  const gid = " +
+String(idExpr) +
+";\n  const group = app.getItemById(gid) || (app.groupManager.getGroupById ? app.groupManager.getGroupById(gid) : null);\n  if (!group) return { success: false, error: 'Group not found: ' + gid };\n  // A FOREGROUND GENERATOR'S OUTPUT (a chat thread, a phone frame) is a generator composition, not a user group:\n  // the studio releases it into ordinary items through releaseParts (what Ungroup / app.ungroupSelection does).\n  // The group manager's ungroup does not know its parts.\n  const __gd = group.data || {};\n  if ((__gd.generatorParts === true || (__gd.generatorPart && __gd.generatorPart !== 'text')) && app.generatorRegistry && app.generatorRegistry.releaseParts) {\n    const r = app." +
+"generatorRegistry.releaseParts(group);\n    if (!r || !r.ok) return { success: false, error: (r && r.reason) || 'the studio did not release the generator composition' };\n    if (app.historyManager) app.historyManager.saveState();\n    const ids = (r.items || []).map(function (it) { return it && it.data && (it.data.registryId || it.data.id); }).filter(Boolean);\n    return { success: true, ungrouped: true, groupId: gid, generator: true, itemIds: ids, count: ids.length };\n  }\n  app.groupManager.ungroupAll(group);\n  if (app.historyManager) app.historyManager.saveState();\n  return { success: true, ungrouped: true, groupId: gid };\n})();"
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+).trim();
         }
         const idsArrayExpr = JSON.stringify(input.itemIds ?? []);
         const nameExpr = input.groupName !== undefined ? JSON.stringify(input.groupName) : 'undefined';
@@ -13792,9 +13946,9 @@ String(S(input.beats)) +
 String(id) +
 ", error: __r.error }; }\n  const __prev = (__it.data && Array.isArray(__it.data.keyframes)) ? __it.data.keyframes : [];\n  const __prevTimes = __prev.map(function (k) { return k && k.time; });\n  const __ours = ['x', 'y', 'scaleX', 'scaleY', 'rotation', 'opacity'];\n  const __other = __prev.reduce(function (acc, k) { Object.keys((k && k.properties) || {}).forEach(function (p) { if (__ours.indexOf(p) < 0 && acc.indexOf(p) < 0) acc.push(p); }); return acc; }, []);\n  app.addAnimation(" +
 String(id) +
-", __r.keyframes, { duration: Math.max(__r.end, __prev.reduce(function (m, k) { return Math.max(m, (k && k.time) || 0); }, 0)), loop: false, mode: 'merge' });\n  const __now = (__it.data && Array.isArray(__it.data.keyframes)) ? __it.data.keyframes.map(function (k) { return k && k.time; }) : [];\n  const __warnings = __anchorWarnings.concat(__r.warnings || []);\n  if (__prevTimes.length && !__prevTimes.every(function (t) { return __now.indexOf(t) >= 0; })) {\n    __warnings.push('this studio replaced the existing track of the actor (' + __prevTimes.length + ' key(s)) instead of merging: put the other keys in after choreographing.');\n  }\n  if (__other.length) {\n    __warnings.push('the act" +
-"or already animates ' + __other.join(', ') + '; the beat keys leave those out, which the engine can break at the beat keys. Re-key ' + __other.join(', ') + ' with every key carrying them, after choreographing.');\n  }\n  if (__r.final && !__r.final.onScreen) __warnings.push('after the last beat the actor is off screen at [' + __r.final.x + ', ' + __r.final.y + '].');\n  if (__fr.unbounded && __warnings.some(function (w) { return /off screen/.test(w); })) __warnings.push('the canvas is unbounded, so it has no fixed frame: on-screen was checked against its nominal ' + __fr.width + 'x' + __fr.height + ' artboard. Set a canvas size or preset to fix the frame.');\n  const __res = { success: tru" +
-"e, itemId: " +
+", __r.keyframes, { duration: Math.max(__r.end, __prev.reduce(function (m, k) { return Math.max(m, (k && k.time) || 0); }, 0)), loop: false, mode: 'merge', timeUnits: 'seconds' });\n  const __now = (__it.data && Array.isArray(__it.data.keyframes)) ? __it.data.keyframes.map(function (k) { return k && k.time; }) : [];\n  const __warnings = __anchorWarnings.concat(__r.warnings || []);\n  if (__prevTimes.length && !__prevTimes.every(function (t) { return __now.indexOf(t) >= 0; })) {\n    __warnings.push('this studio replaced the existing track of the actor (' + __prevTimes.length + ' key(s)) instead of merging: put the other keys in after choreographing.');\n  }\n  if (__other.length) {\n    __" +
+"warnings.push('the actor already animates ' + __other.join(', ') + '; the beat keys leave those out, which the engine can break at the beat keys. Re-key ' + __other.join(', ') + ' with every key carrying them, after choreographing.');\n  }\n  if (__r.final && !__r.final.onScreen) __warnings.push('after the last beat the actor is off screen at [' + __r.final.x + ', ' + __r.final.y + '].');\n  if (__fr.unbounded && __warnings.some(function (w) { return /off screen/.test(w); })) __warnings.push('the canvas is unbounded, so it has no fixed frame: on-screen was checked against its nominal ' + __fr.width + 'x' + __fr.height + ' artboard. Set a canvas size or preset to fix the frame.');\n  const " +
+"__res = { success: true, itemId: " +
 String(id) +
 ", beats: " +
 String(input.beats.length) +
@@ -14036,63 +14190,52 @@ String(sound ? `  // A sound on each morph (D68's placement, with its MP4-lead n
      * Character tool aliases (pinepaper_create_character, pinepaper_character_action, pinepaper_character_pose)
      * Routing on-device / local model calls cleanly to the engine.
      */
+    /**
+     * pinepaper_create_character's last door: no layered bundle, and no concept the design graph can draw. It used to
+     * draw a purple placeholder circle and say success. It now makes a RIGGED character (app.createCharacter), the
+     * owner's rule for anything that should move: a base named outright, or one mapped from the request (a pigeon is
+     * a bird, a kitten a cat, a hero a person). A request that maps to no rigged base is refused with the five, never
+     * fitted onto the nearest rig in silence (a dog on the cat rig is a product call, not this function's).
+     */
     generateCreateCharacter(input) {
         const S = (v) => JSON.stringify(v);
-        const charId = S(input.characterId || input.name || `char_${Date.now()}`);
-        const posX = typeof input.x === 'number' ? input.x : 400;
-        const posY = typeof input.y === 'number' ? input.y : 300;
-        const scale = typeof input.scale === 'number' ? input.scale : 1;
-        const name = S(input.name || input.characterId || 'Character');
-        const base = input.base ? S(input.base) : 'null';
-        const preset = input.preset || input.concept ? S(input.preset || input.concept) : 'null';
-        return ("\n// Create Character\n(async function() {\n  const charId = " +
-String(charId) +
-";\n  const posX = " +
-String(posX) +
-";\n  const posY = " +
-String(posY) +
-";\n  const scale = " +
-String(scale) +
-";\n  const name = " +
-String(name) +
-";\n  const base = " +
-String(base) +
-";\n  const preset = " +
-String(preset) +
-";\n\n  // 1. If original character base is specified and app.createCharacter exists\n  if (base && typeof app.createCharacter === 'function') {\n    const r = await app.createCharacter({ base: base, at: { x: posX, y: posY }, scale: scale });\n    if (r && r.ok !== false) {\n      return { success: true, characterId: charId, itemId: r.id, parts: r.parts };\n    }\n  }\n\n  // 2. Try app.create\n  let groupId = null;\n  if (typeof app.create === 'function') {\n    const group = app.create('circle', { x: posX, y: posY, radius: 35 * scale, color: '#7C3AED' });\n    if (group) {\n      group.data = group.data || {};\n      group.data.ppType = 'pp:Character';\n      group.data.characterId = char" +
-"Id;\n      group.name = name;\n      groupId = group.id || (group.data && group.data.id) || charId;\n    }\n  } else {\n    const p = typeof paper !== 'undefined' ? paper : ((typeof window !== 'undefined' ? window : globalThis).paper);\n    if (p && p.Path) {\n      const body = new p.Path.Circle({ center: [posX, posY], radius: 35 * scale, fillColor: '#7C3AED' });\n      const head = new p.Path.Circle({ center: [posX, posY - 45 * scale], radius: 20 * scale, fillColor: '#EC4899' });\n      const group = new p.Group([body, head]);\n      group.name = name;\n      if (app.textItemGroup) group.parent = app.textItemGroup;\n      group.data = { isUserGroup: true, isLayeredCharacter: true, ppType" +
-": 'pp:Character', characterId: charId };\n      const reg = app.itemRegistry;\n      groupId = reg ? reg.register(group, 'group', { source: 'mcp_create_character' }, 'mcp') : charId;\n      group.data.id = groupId;\n    }\n  }\n\n  if (app._scheduleRepaint) app._scheduleRepaint();\n  if (app.historyManager) app.historyManager.saveState();\n  return { success: true, characterId: charId, itemId: groupId };\n})();"
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+        const asked = String(input.base || input.preset || input.concept || '').trim();
+        const word = asked.replace(/^pp:/i, '').toLowerCase();
+        const MAP = [
+            [/^(person|people|human|character|child|kid|hero|heroine|man|woman|boy|girl|figure|adult|player)$/, 'person'],
+            [/^(robot|bot|android|mech|droid|cyborg)$/, 'robot'],
+            [/^(cat|kitten|kitty|feline)$/, 'cat'],
+            [/^(bird|pigeon|crow|raven|sparrow|parrot|robin|owl|seagull|gull|finch|duck|chick)$/, 'bird'],
+            [/^(blob|slime|jelly)$/, 'blob'],
+        ];
+        // An explicit base goes to the studio as written (it refuses an unknown one with its list); a concept is mapped.
+        const base = input.base ? String(input.base) : (!word ? 'person' : (MAP.find(([re]) => re.test(word)) || [null, null])[1]);
+        if (!base) {
+            return `(function() { return { success: false, error: ${S(`no rigged character fits "${asked}": the rigged bases are person, robot, cat, bird and blob. Pass base: one of those (with variant for its look), or for a figure that does not need to move, a concept pinepaper_query_ontology lists.`)} }; })();`;
+        }
+        const spec = { base };
+        if (typeof input.x === 'number')
+            spec.x = input.x;
+        if (typeof input.y === 'number')
+            spec.y = input.y;
+        if (typeof input.scale === 'number')
+            spec.scale = input.scale;
+        if (input.variant)
+            spec.variant = input.variant;
+        if (input.name)
+            spec.name = input.name;
+        const mapped = input.base ? null : (word ? { from: asked, to: base } : null);
+        return ("\n// Create a rigged character (base " +
+String(oneLine(base)) +
+")\n(async function() {\n  // @engine-methods createCharacter\n  if (typeof app.createCharacter !== 'function') { return { success: false, error: 'this studio has no rigged characters (app.createCharacter): update PinePaper Studio' }; }\n  const r = await app.createCharacter(" +
+String(S(spec)) +
+");\n  if (!r || r.ok === false) { return { success: false, error: (r && Array.isArray(r.errors) && r.errors.join('; ')) || (r && r.reason) || 'the studio made no character from that spec' }; }\n  if (app.historyManager) app.historyManager.saveState();\n  return { success: true, characterId: " +
+String(S(input.characterId || input.name || null)) +
+" || r.id, itemId: r.id, rigId: r.rigId || null, base: r.base || " +
+String(S(base)) +
+", parts: r.parts" +
+String(mapped ? `, baseFrom: ${S(mapped)}` : '') +
+",\n    ...(r.rigId ? {} : { warning: 'the character was drawn but its rig failed, so it cannot walk, pose or act: treat it as still artwork' }),\n    note: 'y is where the feet stand' };\n})();"
 ).trim();
     }
     generateCharacterAction(input) {
@@ -14106,12 +14249,10 @@ String(S(targetId)) +
 String(S(act)) +
 ";\n  const speed = " +
 String(speed) +
-";\n\n  const charItem = targetId\n    ? (app.getItemById(targetId) || (app.getAllItems && app.getAllItems().find(i => (i.data && i.data.characterId === targetId) || i.name === targetId)))\n    : (app.selectedItems && app.selectedItems[0]);\n\n  if (!charItem) {\n    return { success: false, error: 'Character not found: ' + targetId };\n  }\n\n  const itemId = charItem.id || (charItem.data && charItem.data.id) || targetId;\n  const skelId = (charItem.data && charItem.data.characterId) ? 'character_' + charItem.data.characterId : null;\n\n  if (act === 'walk' || act === 'run' || act === 'locomotion') {\n    if (typeof app.addRelation === 'function') {\n      app.addRelation(itemId, null, 'lo" +
-"comotion', {\n        skeletonId: skelId,\n        speed: speed,\n        cycleDistance: 150,\n      });\n    }\n  } else if (app.riggingSystem) {\n    const rs = app.riggingSystem;\n    if (skelId && rs.skeletons && rs.skeletons.has(skelId)) {\n      if (typeof rs.applyBoneAngles === 'function') {\n        rs.applyBoneAngles(skelId, { spine: 0.1, left_arm: -0.5, right_arm: 0.5 });\n        if (typeof rs.solveFK === 'function') rs.solveFK(skelId);\n      }\n    }\n  }\n\n  if (typeof app.animate === 'function' && (act === 'wave' || act === 'dance' || act === 'jump' || act === 'idle')) {\n    app.animate(charItem, { animationType: act === 'jump' ? 'bounce' : (act === 'idle' ? 'breathe' : 'w" +
-"obble') });\n  }\n\n  if (app._scheduleRepaint) app._scheduleRepaint();\n  return { success: true, characterId: targetId || itemId, action: act };\n})();"
-
-
-
+";\n\n  const charItem = targetId\n    ? (app.getItemById(targetId) || (app.getAllItems && app.getAllItems().find(i => (i.data && i.data.characterId === targetId) || i.name === targetId)))\n    : (app.selectedItems && app.selectedItems[0]);\n\n  if (!charItem) {\n    return { success: false, error: 'Character not found: ' + targetId };\n  }\n\n  const itemId = charItem.id || (charItem.data && charItem.data.id) || targetId;\n  const skelId = (charItem.data && charItem.data.characterId) ? 'character_' + charItem.data.characterId : null;\n\n  // WHAT WAS APPLIED, NOT ASSUMED. A concept character (pinepaper_character) has parts and keyframes but no\n  // skeleton, so the skeleton branch did not" +
+"hing and the call still said success.\n  const rs = app.riggingSystem;\n  const hasSkeleton = !!(skelId && rs && rs.skeletons && rs.skeletons.has(skelId));\n  const applied = [];\n  if (act === 'walk' || act === 'run' || act === 'locomotion') {\n    if (typeof app.addRelation === 'function' && app.addRelation(itemId, null, 'locomotion', { skeletonId: skelId, speed: speed, cycleDistance: 150 })) applied.push('locomotion relation');\n  } else if (hasSkeleton && typeof rs.applyBoneAngles === 'function') {\n    rs.applyBoneAngles(skelId, { spine: 0.1, left_arm: -0.5, right_arm: 0.5 });\n    if (typeof rs.solveFK === 'function') rs.solveFK(skelId);\n    applied.push('bone angles');\n  }\n\n  if" +
+" (typeof app.animate === 'function' && (act === 'wave' || act === 'dance' || act === 'jump' || act === 'idle')) {\n    app.animate(charItem, { animationType: act === 'jump' ? 'bounce' : (act === 'idle' ? 'breathe' : 'wobble') });\n    applied.push('whole-figure ' + (act === 'jump' ? 'bounce' : (act === 'idle' ? 'breathe' : 'wobble')));\n  }\n\n  if (app._scheduleRepaint) app._scheduleRepaint();\n  const note = hasSkeleton ? null : 'this character has no skeleton (a concept character is parts and keyframes), so bone actions and rigging calls on it act on nothing' + (applied.length ? '; what ran: ' + applied.join(', ') : '') + '. For a figure that walks, poses and acts, make it with pinepape" +
+"r_original_character (rigged); pinepaper_character directs a concept through its channels (beats).';\n  if (!applied.length) return { success: false, characterId: targetId || itemId, action: act, error: note || ('nothing was applied for action ' + act) };\n  return { success: true, characterId: targetId || itemId, action: act, applied: applied, skeleton: hasSkeleton, ...(note ? { warning: note } : {}) };\n})();"
 
 
 
@@ -14275,14 +14416,19 @@ String(target) +
             ? `, ...((function(w) { return w.length ? { warnings: w } : {}; })(${S(fixed)}.concat(${checks.length ? `__capWarnings(${stored})` : '[]'})))`
             : '';
         if (input.action === 'set') {
-            return `
-// Emitter: change a spec
-(function() {
-  if (typeof app.setEmitter !== 'function') { return { success: false, error: 'this studio has no emitter item (app.setEmitter) — it predates FxTool D29.' }; }${capFn}
-  const r = app.setEmitter(${S(input.itemId)}, ${S(input.spec)});
-  if (!r || r.ok === false) { return { success: false, error: (r && r.error) || 'the emitter change was refused' }; }
-  return { success: true, action: 'set', itemId: ${S(input.itemId)}, spec: r.spec${capJs('r.spec')} };
-})();`.trim();
+            return ("\n// Emitter: change a spec\n(function() {\n  if (typeof app.setEmitter !== 'function') { return { success: false, error: 'this studio has no emitter item (app.setEmitter) — it predates FxTool D29.' }; }" +
+String(capFn) +
+"\n  // set merges the spec's TOP-LEVEL keys; an array it names (bursts) replaces the old one whole (EMSETBURST36).\n  const __b0 = (function () { try { const it = app.getItemById(" +
+String(S(input.itemId)) +
+"); const b = it && it.data && it.data.emitter && it.data.emitter.bursts; return Array.isArray(b) ? b.length : null; } catch (_) { return null; } })();\n  const r = app.setEmitter(" +
+String(S(input.itemId)) +
+", " +
+String(S(input.spec)) +
+");\n  if (!r || r.ok === false) { return { success: false, error: (r && r.error) || 'the emitter change was refused' }; }\n  const __b1 = r.spec && Array.isArray(r.spec.bursts) ? r.spec.bursts.length : null;\n  return { success: true, action: 'set', itemId: " +
+String(S(input.itemId)) +
+", spec: r.spec" +
+String(capJs('r.spec')) + String(Array.isArray(input.spec?.bursts) ? `,
+    burstsReplaced: { before: __b0, after: __b1, note: 'bursts replaces the whole array: the emitter now has only the bursts this call passed. To add one, pass the existing bursts with it.' }` : '') + " };\n})();").trim();
         }
         return `
 // Emitter: create
@@ -15321,7 +15467,7 @@ ${needWorld}
      * already decided by a pure function, so nothing is left for the page to
      * work out.
      */
-    generateDesignCompose(scene, ops, style, sizeWarning, report = {}) {
+    generateDesignCompose(scene, ops, style, sizeWarning, report = {}, fitTo) {
         const S = (v) => JSON.stringify(v);
         return ("\n// Design: compose a " +
 String(oneLine(style)) +
@@ -15329,17 +15475,36 @@ String(oneLine(style)) +
 String(oneLine(ops.length)) +
 " items, laid out server-side\n(function() {\n  if (typeof app.create !== 'function') { return { success: false, error: 'app.create unavailable — update FxTool' }; }\n  const size = " +
 String(S({ width: scene.width, height: scene.height })) +
-";\n  // The layout was computed for this size, so the canvas is set to it — and\n  // the result SAYS so: a 1080x1080 canvas became 1280x720 silently (gate C).\n  const __before = app.getCanvasSize ? app.getCanvasSize() : null;\n  if (typeof app.setCanvasSize === 'function') { try { app.setCanvasSize({ width: size.width, height: size.height }); } catch (_) { /* a fixed canvas is not a failure */ } }\n  const __after = app.getCanvasSize ? app.getCanvasSize() : null;\n  const canvasResized = __before && __after && (__before.width !== __after.width || __before.height !== __after.height)\n    ? { from: { width: __before.width, height: __before.height }, to: { width: __after.width, height: __af" +
-"ter.height } } : null;\n  " +
+";\n  // The layout was computed for this size, so the canvas is set to it — and\n  // the result SAYS so: a 1080x1080 canvas became 1280x720 silently (gate C).\n  const __before = app.getCanvasSize ? app.getCanvasSize() : null;\n  " +
+String(fitTo ? `// FIT, NOT RESIZE (RISO-RESIZE): this style lays out only at its own size, and the canvas is the caller's, so the
+  // canvas is kept and the composition is scaled to fit it, centred, below.
+  const __fit = ${S(fitTo)};` : `if (typeof app.setCanvasSize === 'function') { try { app.setCanvasSize({ width: size.width, height: size.height }); } catch (_) { /* a fixed canvas is not a failure */ } }`) +
+"\n  const __after = app.getCanvasSize ? app.getCanvasSize() : null;\n  const canvasResized = __before && __after && (__before.width !== __after.width || __before.height !== __after.height)\n    ? { from: { width: __before.width, height: __before.height }, to: { width: __after.width, height: __after.height } } : null;\n  " +
 String(scene.backgroundHex ? `if (typeof app.setBackgroundColor === 'function') { try { app.setBackgroundColor(${S(scene.backgroundHex)}); } catch (_) { /* ditto */ } }` : '// this style paints no background of its own') +
 "\n  const ops = " +
 String(S(ops)) +
-";\n  const ids = [];\n  const failed = [];\n  for (const op of ops) {\n    const { type, note, name, ...props } = op;\n    try {\n      const item = app.create(type, props);\n      if (item) { ids.push(item.data && item.data.id); } else { failed.push({ name: name, type: type, reason: 'create returned nothing' }); }\n    } catch (e) { failed.push({ name: name, type: type, reason: (e && e.message) || String(e) }); }\n  }\n  if (app.historyManager) app.historyManager.saveState();\n  // A partial composition is reported as one. Half a poster that claims\n  // success is worse than a poster that says which four elements are missing.\n  return { success: failed.length === 0, style: " +
+";\n  const ids = [];\n  const failed = [];\n  for (const op of ops) {\n    const { type, note, name, ...props } = op;\n    try {\n      const item = app.create(type, props);\n      if (item) { ids.push(item.data && item.data.id); } else { failed.push({ name: name, type: type, reason: 'create returned nothing' }); }\n    } catch (e) { failed.push({ name: name, type: type, reason: (e && e.message) || String(e) }); }\n  }\n" +
+String(fitTo ? ("  const __k = Math.min(__fit.width / size.width, __fit.height / size.height);\n  const __dx = (__fit.width - size.width * __k) / 2, __dy = (__fit.height - size.height * __k) / 2;\n  let __fitted = 0;\n  for (const id of ids) {\n    const it = id && app.getItemById ? app.getItemById(id) : null;\n    if (it && typeof it.scale === 'function' && typeof it.translate === 'function' && typeof paper !== 'undefined') {\n      it.scale(__k, new paper.Point(0, 0)); it.translate(new paper.Point(__dx, __dy)); __fitted++;\n    }\n  }\n  const __fitReport = { canvas: __fit.width + 'x' + __fit.height, layout: size.width + 'x' + size.height, scale: Math.round(__k * 1000) / 1000, itemsFitted: __fitted,\n   " +
+" note: 'this style lays out only at ' + size.width + 'x' + size.height + ', so it was drawn at that size and scaled to fit your ' + __fit.width + 'x' + __fit.height + ' canvas, centred; the canvas was kept. Pass width and height for the style at its own size (the canvas is then resized).' };\n  if (typeof paper !== 'undefined' && paper.view) paper.view.draw();\n"
+
+
+
+
+
+
+
+
+
+
+) : '') +
+"  if (app.historyManager) app.historyManager.saveState();\n  // A partial composition is reported as one. Half a poster that claims\n  // success is worse than a poster that says which four elements are missing.\n  return { success: failed.length === 0, style: " +
 String(S(style)) +
-", itemIds: ids, itemCount: ids.length, failed: failed,\n    ...(canvasResized ? { canvasResized: canvasResized, note: 'the canvas was resized to the composition' + (" +
+", itemIds: ids, itemCount: ids.length, failed: failed," +
+String(fitTo ? ' fittedToCanvas: __fitReport,' : '') +
+"\n    ...(canvasResized ? { canvasResized: canvasResized, note: 'the canvas was resized to the composition' + (" +
 String(S(sizeWarning ?? '')) +
 " ? '' : '; pass width and height to compose at your canvas size') } : {}),\n    ...(" +
-String(S(sizeWarning ?? '')) +
+String(S(fitTo ? '' : (sizeWarning ?? ''))) +
 " ? { warning: " +
 String(S(sizeWarning ?? '')) +
 " } : {}), ..." +
@@ -15352,6 +15517,15 @@ String(S(report)) +
 
 
 
+
+
+
+
+
+
+
+
+
 ).trim();
     }
     /**
@@ -15361,6 +15535,66 @@ String(S(report)) +
      * reassembled into it. Naming them individually is the point: the kit's
      * options were discoverable only by reading FxTool's source.
      */
+    /**
+     * pinepaper_instances — a swarm of up to a million marks as one item. Every field passes through to the
+     * engine, which validates it and names a bad one; the reply carries describeInstances, so a subsampled or
+     * capped swarm says so (drawn vs count) in the call that made it.
+     */
+    generateInstances(input) {
+        const S = (v) => JSON.stringify(v);
+        const { action, itemId, name, ...rest } = input;
+        const spec = {};
+        for (const [k, v] of Object.entries(rest))
+            if (v !== undefined)
+                spec[k] = v;
+        const refuse = (m) => `if (typeof app.${m} !== 'function') { return { success: false, error: 'this studio has no instances (app.${m}): update PinePaper Studio' }; }`;
+        const why = `(app.lastReceipt && Array.isArray(app.lastReceipt.warnings) && app.lastReceipt.warnings.map(function (w) { return w && (w.message || w.reason); }).filter(Boolean).join(' ')) || ''`;
+        switch (action) {
+            case 'rules':
+                return `
+// Instances: the rules, layouts and shapes this studio has
+(function() {
+  // @engine-methods instanceRules
+  ${refuse('instanceRules')}
+  return Object.assign({ success: true }, app.instanceRules());
+})();`.trim();
+            case 'describe':
+                return `
+// Instances: describe ${oneLine(itemId ?? '')}
+(function() {
+  // @engine-methods describeInstances
+  ${refuse('describeInstances')}
+  const d = app.describeInstances(${S(itemId)});
+  if (!d || d.ok === false) { return { success: false, error: (d && (d.error || d.reason)) || 'no swarm has the id ' + ${S(itemId)} }; }
+  return Object.assign({ success: true, itemId: ${S(itemId)} }, d);
+})();`.trim();
+            case 'modify':
+                return `
+// Instances: modify ${oneLine(itemId ?? '')}
+(function() {
+  // @engine-methods setInstances describeInstances
+  ${refuse('setInstances')}
+  const r = app.setInstances(${S(itemId)}, ${S(spec)});
+  if (!r || r.ok === false) { return { success: false, error: (r && (r.error || r.reason)) || ${why} || 'the swarm was not changed' }; }
+  const d = app.describeInstances(${S(itemId)}) || {};
+  return { success: true, itemId: ${S(itemId)}, spec: r.spec, count: d.count, drawn: d.drawn, subsampled: d.subsampled, path: d.path, determinism: d.determinism };
+})();`.trim();
+            case 'create':
+            default:
+                return `
+// Instances: create a swarm${spec.count ? ` of ${oneLine(String(spec.count))}` : ''}
+(function() {
+  // @engine-methods describeInstances
+  ${refuse('describeInstances')}
+  const item = app.create('instances', ${S(spec)});
+  if (!item) { return { success: false, error: ${why} || 'the studio made no swarm from that spec' }; }
+  const itemId = item.data && (item.data.registryId || item.data.id);${name ? `
+  try { item.name = ${S(name)}; } catch (_) {}` : ''}
+  const d = app.describeInstances(itemId) || {};
+  return { success: true, itemId: itemId, count: d.count, drawn: d.drawn, subsampled: d.subsampled, path: d.path, rule: d.rule, determinism: d.determinism };
+})();`.trim();
+        }
+    }
     generateStick(input) {
         const S = (v) => JSON.stringify(v);
         const { action, ...rest } = input;
@@ -15410,7 +15644,7 @@ String(S(report)) +
   if (typeof app.${fn} !== 'function') { return { success: false, error: 'app.${fn} unavailable — update FxTool (the stick kit is vendored from mcp-cloud)' }; }
   const r = await app.${fn}(${S(opts)});
   if (!r || r.ok === false) { return { success: false, error: (r && (r.reason || r.error)) || 'the stick kit produced nothing' }; }
-  return { success: true, ...r };
+  return { success: true, ...r${action === 'figure' ? ", anchor: app.stickFigureAnchorsFeet === true ? 'feet' : 'hip'" : ''} };
 })();`.trim();
     }
     /**
@@ -15765,7 +15999,8 @@ String(S(opts)) +
 ).trim();
             }
             case 'create': {
-                const v = (input.visual ?? {});
+                // visual: false means no drawing options. The chip is editor-only, and no export draws it.
+                const v = (input.visual || {});
                 const { startTime, duration, ...visualOnly } = v;
                 const placement = (startTime !== undefined || duration !== undefined)
                     ? { ...(startTime !== undefined ? { startTime } : {}), ...(duration !== undefined ? { duration } : {}) }
@@ -16158,9 +16393,15 @@ ${guard('unlockAllItems')}${pass('app.unlockAllItems()')}
   if (!ok) { return { success: false, action: 'load_pose', error: "no such pose, or the skeleton it was saved against is gone. list_poses for what is still loadable" }; }
   return { success: true, action: 'load_pose', poseId: ${S(input.poseId)} };`);
             case 'interpolate_poses':
-                return wrap('Rigging: interpolate poses', `  const ok = R.interpolatePoses(${S(input.poseIdA)}, ${S(input.poseIdB)}, ${input.t ?? 0.5});
-  if (!ok) { return { success: false, action: 'interpolate_poses', error: "one of the two poses does not exist, or they belong to DIFFERENT skeletons — blending across rigs is not defined. Call list_poses to see which skeleton each belongs to" }; }
-  return { success: true, action: 'interpolate_poses', t: ${input.t ?? 0.5} };`);
+                return wrap('Rigging: interpolate poses', ("  // interpolatePoses RETURNS the blended angles and changes nothing; they were discarded and the call said success.\n  const angles = R.interpolatePoses(" +
+String(S(input.poseIdA)) +
+", " +
+String(S(input.poseIdB)) +
+", " +
+String(input.t ?? 0.5) +
+");\n  if (!angles) { return { success: false, action: 'interpolate_poses', error: \"one of the two poses does not exist, or they belong to DIFFERENT skeletons — blending across rigs is not defined. Call list_poses to see which skeleton each belongs to\" }; }\n  const __pose = R.getPose(" +
+String(S(input.poseIdA)) +
+");\n  const skeletonId = __pose && __pose.skeletonId;\n  if (!skeletonId || typeof R.applyBoneAngles !== 'function') { return { success: false, action: 'interpolate_poses', boneAngles: angles, error: 'the blend was computed but could not be applied: this studio does not say which skeleton pose ' + " + String(S(input.poseIdA)) + " + ' belongs to. Apply boneAngles yourself, or key them with add_pose_keyframe.' }; }\n  R.applyBoneAngles(skeletonId, angles);\n  if (app.historyManager) app.historyManager.saveState();\n  return { success: true, action: 'interpolate_poses', t: " + String(input.t ?? 0.5) + ", skeletonId: skeletonId, applied: true, boneAngles: angles };"));
             case 'play_pose_sequence': {
                 const opts = S({
                     ...(input.loop !== undefined ? { loop: input.loop } : {}),
@@ -16222,15 +16463,21 @@ String(S(input.transitionName)) +
                     // saves. It is not a procedural generator, it is a pose player, and
                     // saying "needs a skeleton" when the skeleton is right there sends an
                     // agent looking in the wrong place.
-                    auto_walk: "at least 2 saved walk poses (walk_00…, or walk_contact_L / walk_passing_L / walk_contact_R / walk_passing_R). Run load_pose_library with libraryName 'humanoid' (or 'quadruped') first — it saves exactly those",
+                    auto_walk: "at least 2 saved walk poses (walk_00…, or walk_contact_L / walk_passing_L / walk_contact_R / walk_passing_R). A person or robot rig: run load_pose_library with libraryName 'humanoid' (a cat: 'quadruped') first, which saves exactly those. A rig with no walk cycle (a bird, a fish) moves another way: apply_pose_transition 'bird_flap' or 'fish_swim' (they loop), or move_root to carry it",
                     auto_breath: 'a bone named spine, chest, upper_spine or body',
                     auto_idle: 'a bone named head, hip, upper_hub or spine',
-                    auto_jump: 'a skeleton, and saved jump poses if you want a posed jump rather than a root arc',
+                    auto_jump: "saved jump poses (idle, jump_anticipation, jump_apex, jump_land; load_pose_library 'humanoid' saves them). A bird has none: apply_pose_transition 'bird_flap' instead",
                 };
-                return wrap(`Rigging: ${input.action}`, `  const res = R.${method}(${S(input.skeletonId)}, ${S(input.options ?? {})});
-  if (res && app.historyManager) app.historyManager.saveState();
-  if (!res) { return { success: false, action: ${S(input.action)}, error: ${S(`refused — needs ${needs[input.action]}.`)} }; }
-  return { success: true, action: ${S(input.action)}, result: res };`);
+                return wrap(`Rigging: ${input.action}`, ("  // Through the app's door where it has one: that is where the studio writes the rig-aware receipt (auto-* kinds).\n  const res = app." +
+String(method) +
+" ? app." +
+String(method) +
+"(" +
+String(S(input.skeletonId)) +
+", " +
+String(S(input.options ?? {})) +
+") : R." +
+String(method) + "(" + String(S(input.skeletonId)) + ", " + String(S(input.options ?? {})) + ");\n  // A refusal is null on older studios and { ok: false, reason, kind } on newer ones (rig-aware): both are refusals.\n  const __refused = !res || res.ok === false;\n  if (!__refused && app.historyManager) app.historyManager.saveState();\n  // The studio's own reason first, where it gives one (rig-aware: it knows the rig); this list otherwise.\n  const __why = (app.lastReceipt && Array.isArray(app.lastReceipt.warnings) ? app.lastReceipt.warnings : [])\n    .filter(function (w) { return w && /^auto-/.test(String(w.kind || w.code || '')); }).map(function (w) { return w.message || w.reason; }).filter(Boolean).join(' ');\n  if (__refused) { return { success: false, action: " + String(S(input.action)) + ", error: (res && res.reason) || __why || " + String(S(`refused — needs ${needs[input.action]}.`)) + ", ...(res && res.kind ? { code: res.kind } : {}) }; }\n  return { success: true, action: " + String(S(input.action)) + ", result: res };"));
             }
             case 'move_root':
                 return wrap('Rigging: root locomotion track', `  const ok = R.moveRoot(${S(input.skeletonId)}, ${S(input.keyframes ?? [])}, ${S(input.options ?? {})});
@@ -16512,15 +16759,28 @@ String(op) +
         // pulse — a runtime fire, not a scene edit (no history save)
         const eventIdJson = JSON.stringify(input.eventId);
         const payloadJson = JSON.stringify(input.payload ?? null);
-        return `
-// Pulse event: ${oneLine(input.eventId)}
-(function() {
-  if (typeof app.pulseEvent !== 'function') {
-    return { success: false, error: 'app.pulseEvent unavailable — update FxTool to a build with the event system (S11)' };
-  }
-  app.pulseEvent(${eventIdJson}, ${payloadJson});
-  return { success: true, action: 'pulse', eventId: ${eventIdJson} };
-})();`.trim();
+        return ("\n// Pulse event: " +
+String(oneLine(input.eventId)) +
+"\n(function() {\n  if (typeof app.pulseEvent !== 'function') {\n    return { success: false, error: 'app.pulseEvent unavailable — update FxTool to a build with the event system (S11)' };\n  }\n  // A PULSE NOTHING HEARS IS NOT A SUCCESS (tester, 1.6.36: a pulse of an id no event has returned success:true).\n  // An event's channel is its id; a literal name is a channel only where a rule or relation listens on it.\n  const __id = " +
+String(eventIdJson) +
+";\n  const __all = app.itemRegistry && app.itemRegistry.getAll ? app.itemRegistry.getAll() : [];\n  const __isEvent = __all.some(function(e) { return e && e.item && e.item.data && e.item.data.isEvent && (e.id || e.itemId) === __id; });\n  const __heard = (app.listContraptions && (app.listContraptions() || []).some(function(c) { return c && c.sourceEvent === __id; }))\n    || !!(app.relationRegistry && app.relationRegistry.getAssociations && (app.relationRegistry.getAssociations(__id) || []).length);\n  if (!__isEvent && !__heard) {\n    const __named = __all.filter(function(e) { return e && e.item && e.item.data && e.item.data.isEvent && e.item.data.eventName === __id; }).map(function(e) {" +
+" return e.id || e.itemId; });\n    return { success: false, action: 'pulse', eventId: __id, code: 'event_not_found',\n      error: 'no event has the id ' + JSON.stringify(__id) + ' and no rule or relation listens on it, so the pulse would reach nothing; nothing was fired.'\n        + (__named.length ? ' ' + JSON.stringify(__id) + ' is the name of event ' + __named.join(', ') + ': pulse its id.' : ' Create the event first (action: create), or pulse the id it returned.') };\n  }\n  app.pulseEvent(__id, " +
+String(payloadJson) +
+");\n  return { success: true, action: 'pulse', eventId: __id };\n})();"
+
+
+
+
+
+
+
+
+
+
+
+
+
+).trim();
     }
 }
 /**
@@ -16556,8 +16816,12 @@ String(jsLiteral(targets)) +
 ".filter((id) => !app.getItemById(id));\n  // AN EVENT'S NAME IS NOT ITS CHANNEL (DBLEXP33). A timed event and a pulse by eventId both fire the id create\n  // returned; a rule on the event's name ran only when that literal name was pulsed, so it stayed at fireCount 0\n  // with no word said. Named here, with the id to use.\n  const __src = " +
 String(jsLiteral(input.sourceEvent ?? '')) +
 ";\n  const __named = (app.itemRegistry && app.itemRegistry.getAll ? app.itemRegistry.getAll() : [])\n    .filter((e) => e && e.item && e.item.data && e.item.data.isEvent && e.item.data.eventName === __src && (e.id || e.itemId) !== __src)\n    .map((e) => e.id || e.itemId);\n  // A studio that resolves a name held by one event to its id (FxTool #346) stores the id: read the rule back\n  // rather than trust a flag, so the warning is true on every build.\n  const __stored = typeof app.listContraptions === 'function'\n    ? (app.listContraptions() || []).find((c) => c && c.id === contraptionId) : null;\n  const __resolved = !!(__stored && __named.indexOf(__stored.sourceEvent) >= 0);\n  const " +
-"__warnings = [];\n  if (missing.length) __warnings.push('no item has the id ' + missing.join(', ') + ' yet: the rule does nothing to it until one does');\n  if (__named.length > 1 && !__resolved) __warnings.push(__named.length + ' events are named ' + JSON.stringify(__src) + ' (' + __named.join(', ') + '), so the rule cannot tell which one: it runs only when the literal name is pulsed. Pass one eventId as sourceEvent.');\n  else if (__named.length && !__resolved) __warnings.push('sourceEvent ' + JSON.stringify(__src) + ' is the NAME of event ' + __named[0] + ': its timer and a pulse of its id fire ' + __named[0] + ', not the name, so this rule runs only when the literal name ' + JSON.strin" +
-"gify(__src) + ' is pulsed. Use sourceEvent ' + JSON.stringify(__named[0]) + ' to run it when that event fires.');\n  return { success: true, action: 'add_contraption', contraptionId,\n    ...(__resolved ? { sourceEventResolvedTo: __stored.sourceEvent } : __named.length === 1 ? { eventIdForName: __named[0] } : {}),\n    ...(__warnings.length ? { warning: __warnings.join(' ') } : {}), };"
+"__warnings = [];\n  if (missing.length) __warnings.push('no item has the id ' + missing.join(', ') + ' yet: the rule does nothing to it until one does');\n  // A source no event has, by id or by name (tester, 1.6.36: accepted with no word). A literal channel is allowed:\n  // the rule runs when that exact string is pulsed.\n  const __srcIsEvent = (app.itemRegistry && app.itemRegistry.getAll ? app.itemRegistry.getAll() : []).some((e) => e && e.item && e.item.data && e.item.data.isEvent && (e.id || e.itemId) === __src);\n  if (__src && !__srcIsEvent && !__named.length) __warnings.push('no event has the id or name ' + JSON.stringify(__src) + ' yet, so nothing fires this rule until an event wi" +
+"th that id exists or that exact string is pulsed.');\n  if (__named.length > 1 && !__resolved) __warnings.push(__named.length + ' events are named ' + JSON.stringify(__src) + ' (' + __named.join(', ') + '), so the rule cannot tell which one: it runs only when the literal name is pulsed. Pass one eventId as sourceEvent.');\n  else if (__named.length && !__resolved) __warnings.push('sourceEvent ' + JSON.stringify(__src) + ' is the NAME of event ' + __named[0] + ': its timer and a pulse of its id fire ' + __named[0] + ', not the name, so this rule runs only when the literal name ' + JSON.stringify(__src) + ' is pulsed. Use sourceEvent ' + JSON.stringify(__named[0]) + ' to run it when that eve" +
+"nt fires.');\n  return { success: true, action: 'add_contraption', contraptionId,\n    ...(__resolved ? { sourceEventResolvedTo: __stored.sourceEvent } : __named.length === 1 ? { eventIdForName: __named[0] } : {}),\n    ...(__warnings.length ? { warning: __warnings.join(' ') } : {}), };"
+
+
+
 
 
 
@@ -16765,7 +17029,7 @@ String(JSON.stringify(props)) +
 String(JSON.stringify(easing ?? null)) +
 "); });\n  const keys = Object.keys(byTime).map(function(t) { return byTime[t]; }).sort(function(a, b) { return a.time - b.time; });\n  const beforeTimes = track.map(function(k) { return k.time; });\n  app.addAnimation(" +
 String(JSON.stringify(itemId)) +
-", keys, { mode: 'merge' });\n  const after = (item.data && Array.isArray(item.data.keyframes)) ? item.data.keyframes : [];\n  const kept = beforeTimes.every(function(t) { return after.some(function(k) { return k.time === t; }); });\n  if (!kept) return { success: false, error: 'this studio replaced the track instead of merging into it (no merge mode): the earlier keys are gone. Put every key in one keyframe_animate call.', atTime: AT };\n  if (app.historyManager) app.historyManager.saveState();\n  return { success: true, itemId: " +
+", keys, { mode: 'merge', timeUnits: 'seconds' });\n  const after = (item.data && Array.isArray(item.data.keyframes)) ? item.data.keyframes : [];\n  const kept = beforeTimes.every(function(t) { return after.some(function(k) { return k.time === t; }); });\n  if (!kept) return { success: false, error: 'this studio replaced the track instead of merging into it (no merge mode): the earlier keys are gone. Put every key in one keyframe_animate call.', atTime: AT };\n  if (app.historyManager) app.historyManager.saveState();\n  return { success: true, itemId: " +
 String(JSON.stringify(itemId)) +
 ", atTime: AT, autoKeyed: true, changes: changes, keys: after.length,\n    note: 'written as keyframes (a temporal edit), not a static change; pinepaper_query_mutations shows the series.' };\n})();"