@pinepaper.studio/mcp-server 1.6.33 → 1.6.35

package/dist/types/code-generator.js

@@ -124,18 +124,29 @@ ${itemVarName}.${propertyName} = (function() {
   };
 })();`;
     }
-    // Linear: a diagonal across a 100 px box at the requested position.
-    const defaultOrigin = origin || [position.x - 50, position.y - 50];
-    const defaultDestination = destination || [position.x + 50, position.y + 50];
+    // A LINEAR RAMP FITS THE ITEM, top to bottom, as the engine's own app.create does (FIREFLY31). This was a fixed
+    // 100 px diagonal at the requested position. Leaving the ends out is not enough here: this assigns straight to
+    // Paper, where a gradient with no ends is zero-length. An end the caller gave is kept as given.
+    const fx = position.x, fy = position.y;
+    const o = origin ? `[${origin[0]}, ${origin[1]}]`
+        : destination ? `[${destination[0]}, __gb ? __gb.y : ${fy - 50}]`
+            : `(__gb ? [__gb.x + __gb.width / 2, __gb.y] : [${fx}, ${fy - 50}])`;
+    const d = destination ? `[${destination[0]}, ${destination[1]}]`
+        : origin ? `[${origin[0]}, __gb ? __gb.y + __gb.height : ${fy + 50}]`
+            : `(__gb ? [__gb.x + __gb.width / 2, __gb.y + __gb.height] : [${fx}, ${fy + 50}])`;
     return `
-${itemVarName}.${propertyName} = {
-  gradient: {
-    stops: [${stopsCode}],
-    radial: false
-  },
-  origin: [${defaultOrigin[0]}, ${defaultOrigin[1]}],
-  destination: [${defaultDestination[0]}, ${defaultDestination[1]}]
-};`;
+${itemVarName}.${propertyName} = (function() {
+  const __b = ${itemVarName} && ${itemVarName}.bounds;
+  const __gb = __b && isFinite(__b.x) && isFinite(__b.y) && __b.width > 0 && __b.height > 0 ? __b : null;
+  return {
+    gradient: {
+      stops: [${stopsCode}],
+      radial: false
+    },
+    origin: ${o},
+    destination: ${d}
+  };
+})();`;
 }
 /**
  * Generate shadow code for an item
@@ -363,7 +374,10 @@ if (item && item.data) { item.data.renderAs = ${JSON.stringify(itemType)}; item.
         createScale.scaleY = num(properties.scaleY);
     const hasCreateScale = Object.keys(createScale).length > 0;
     const SCALE_KEYS = ['scale', 'scaleX', 'scaleY'];
-    const ignored = Object.keys(properties).filter((k) => !(hasCreateScale && SCALE_KEYS.includes(k) && num(properties[k]) !== undefined)).filter((k) => itemType === 'text'
+    // VISIBLE AT CREATE. create() does not read visible, so a shape made hidden (a morph target, a reveal) was
+    // drawn; it was reported ignored. A boolean is applied to the item right after create.
+    const createVisible = typeof properties.visible === 'boolean' ? properties.visible : undefined;
+    const ignored = Object.keys(properties).filter((k) => !(k === 'visible' && createVisible !== undefined)).filter((k) => !(hasCreateScale && SCALE_KEYS.includes(k) && num(properties[k]) !== undefined)).filter((k) => itemType === 'text'
         ? (!CREATE_KNOWN_KEYS.has(k) && !textOnly(k) && !DIRECTION_KEYS.includes(k))
             || (k === 'letterSpacing' && letterSpacingCss(properties[k]) === undefined)
         : !CREATE_KNOWN_KEYS.has(k) || textOnly(k));
@@ -411,6 +425,10 @@ const item = app.create(${jsLiteral(itemType)}, ${JSON.stringify(params, null, 2
     if (opacity !== undefined) {
         code += `\nitem.opacity = ${opacity};`;
     }
+    if (createVisible !== undefined) {
+        code += `
+if (item) item.visible = ${createVisible};`;
+    }
     if (hasCreateScale) {
         code += `
 const __scale = (function(it) {
@@ -1547,6 +1565,31 @@ export function animationOptionWarning(options) {
     return unreadKeysWarning('animationOptions', ANIMATION_OPTION_KEYS, options);
 }
 const VISIBILITY_REACTION = /^on_(event|enter|exit)_set_visibility$/;
+/** The relations that PULSE params.event (FxTool js/relations/triggers.js dispatchTrigger). */
+const EVENT_PULSING_RELATIONS = new Set(['on_complete', 'at_beat']);
+/**
+ * ONCOMP34: AN EVENT'S NAME IS NOT ITS CHANNEL, here as in DBLEXP33. on_complete / at_beat pulse params.event
+ * verbatim, and a reaction listens on its source's id, so {event: 'done'} (the name of event item_4) pulsed a
+ * channel nothing listens on: bound, stored, no warning, never seen. A name exactly one event holds, and that no
+ * item has as its id, is put back as that event's id before the bind; a name two events share is named instead.
+ * Statements, run in the page; `paramsVar` is mutated in place and `__ev` holds the reply fields.
+ */
+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});`;
+}
+/** 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]; });
+  if (__ev.warning) ${replyVar}.${key} = ${replyVar}.${key} ? ${replyVar}.${key} + ' ' + __ev.warning : __ev.warning;`;
 /**
  * A visibility reaction reads params.visible and nothing else: absent means show. `value`, which the other set_*
  * reactions take, was ignored, so {value: false} SHOWED the item and a hide did nothing (issue #29 O4).
@@ -1576,14 +1619,18 @@ String(JSON.stringify(sourceId)) +
 String(JSON.stringify(targetId)) +
 "].filter(function(id) { return !app._isKnownRelationEndpoint(norm(id)); });\n    if (bad.length) {\n      return { success: false, relationType: " +
 String(jsLiteral(relationType)) +
-", error: bad.map(function(id) { return JSON.stringify(id); }).join(' and ')\n        + ' ' + (bad.length > 1 ? 'are not items' : 'is not an item') + ' on the canvas, so the relation would be stored and skipped every frame. Check the id (pinepaper_get_items lists them).' };\n    }\n  }\n  const success = app.addRelation(" +
+", error: bad.map(function(id) { return JSON.stringify(id); }).join(' and ')\n        + ' ' + (bad.length > 1 ? 'are not items' : 'is not an item') + ' on the canvas, so the relation would be stored and skipped every frame. Check the id (pinepaper_get_items lists them).' };\n    }\n  }\n  const __params = " +
+String(JSON.stringify(params, null, 2)) +
+";\n  " +
+String(eventNameResolveJs(relationType, '__params')) +
+"\n  const success = app.addRelation(" +
 String(jsLiteral(sourceId)) +
 ", " +
 String(jsLiteral(targetId)) +
 ", " +
 String(jsLiteral(relationType)) +
-", " +
-String(JSON.stringify(params, null, 2)) + ");\n  if (!success) {\n    const __why = " + String(relationRefusalReasonJs(jsLiteral(relationType))) + ";\n    return { success: false, relationType: " + String(jsLiteral(relationType)) + ", error: 'the studio refused the ' + " + String(jsLiteral(relationType)) + " + ' relation between ' + " + String(jsLiteral(sourceId)) + " + ' and ' + " + String(jsLiteral(targetId)) + " + (__why ? ': ' + __why : '.') };\n  }\n  app.historyManager.saveState();\n  return { success: true, sourceId: " + String(jsLiteral(sourceId)) + ", targetId: " + String(jsLiteral(targetId)) + ", relationType: " + String(jsLiteral(relationType)) + String(relationOptionFields(relationType, params, 'warning')) + " };\n})();\n").trim();
+", __params);\n  if (!success) {\n    const __why = " +
+String(relationRefusalReasonJs(jsLiteral(relationType))) + ";\n    return { success: false, relationType: " + String(jsLiteral(relationType)) + ", error: 'the studio refused the ' + " + String(jsLiteral(relationType)) + " + ' relation between ' + " + String(jsLiteral(sourceId)) + " + ' and ' + " + String(jsLiteral(targetId)) + " + (__why ? ': ' + __why : '.') };\n  }\n  app.historyManager.saveState();\n  const __reply = { success: true, sourceId: " + String(jsLiteral(sourceId)) + ", targetId: " + String(jsLiteral(targetId)) + ", relationType: " + String(jsLiteral(relationType)) + String(relationOptionFields(relationType, params, 'warning')) + " };\n  " + String(EV_MERGE_JS('__reply')) + "\n  return __reply;\n})();\n").trim();
 }
 /**
  * The per-burst particle cap of the CURRENT studio (FxTool ParticleEmitter
@@ -1721,6 +1768,11 @@ export function normalizeEmitterSpec(spec, assumeDefaultCount = true) {
         const f = o.fade;
         if (f && typeof f === 'object' && !Array.isArray(f))
             scalarRanges(`${where}.fade`, f, ['in', 'out']);
+        // fade takes 'none', 'linear' (or true / false) or { in, out }. Any other word is not read, so the
+        // particles keep the default linear fade over their life: fade 'out' looked like an option (EMITFADE34).
+        if (typeof f === 'string' && f !== 'none' && f !== 'linear') {
+            warnings.push(`${where}.fade ${JSON.stringify(f)} is not a fade the studio reads, so the particles keep the default linear fade over their whole life. Use 'none', 'linear', or { in, out } in seconds (or fadeIn / fadeOut).`);
+        }
     };
     scalarRanges('spec', out, [...SCALAR_ONLY, ...SPEC_ONLY]);
     bursts.forEach((b, i) => { if (b && typeof b === 'object')
@@ -2305,6 +2357,29 @@ function generateExecuteGeneratorCode(generatorName, params, region) {
  * at all and draws full-canvas). So the item is checked first and refused by
  * name, and the result says whether this studio clips to shapes.
  */
+/** Relations the studio declares ONCE over a set (multiInstance: false in js/relations/collection.js). */
+export const COLLECTION_RELATIONS = new Set(['phase_wave', 'ring_forming', 'flock']);
+/**
+ * The part of an export region that is rendered: the region itself, or, when
+ * outputWidth / outputHeight have another aspect, the largest box of that aspect
+ * centred in it (a cover crop). Never larger than the region.
+ */
+export function regionCoverCrop(r) {
+    const outW = r.outputWidth ?? Math.round(r.width);
+    const outH = r.outputHeight ?? Math.round(r.height);
+    const want = outW / outH, have = r.width / r.height;
+    // Under half a source pixel of difference on either side is the same box.
+    if (!(outW > 0 && outH > 0) || Math.abs(r.width - r.height * want) < 0.5 && Math.abs(r.height - r.width / want) < 0.5) {
+        return { x: r.x, y: r.y, width: r.width, height: r.height, cropped: false };
+    }
+    const round = (v) => Math.round(v * 1000) / 1000;
+    if (want > have) {
+        const h = r.width / want;
+        return { x: r.x, y: round(r.y + (r.height - h) / 2), width: r.width, height: round(h), cropped: true };
+    }
+    const w = r.height * want;
+    return { x: round(r.x + (r.width - w) / 2), y: r.y, width: round(w), height: r.height, cropped: true };
+}
 function emitGeneratorRun(generatorName, paramsJson, region) {
     const options = JSON.stringify(region ? { region } : {});
     const itemId = region && typeof region.shape === 'object' ? region.shape.itemId : null;
@@ -3602,7 +3677,7 @@ String(JSON.stringify(validated.presetId)) +
         if (validated.targetId)
             return code;
         return code
-            .replace(`return { success: true, sourceId: ${jsLiteral(validated.sourceId)}, targetId: ${jsLiteral(validated.sourceId)},`, `return { success: true, sourceId: ${jsLiteral(validated.sourceId)}, targetId: null,`)
+            .replace(`const __reply = { success: true, sourceId: ${jsLiteral(validated.sourceId)}, targetId: ${jsLiteral(validated.sourceId)},`, `const __reply = { success: true, sourceId: ${jsLiteral(validated.sourceId)}, targetId: null,`)
             .replace(`relation between ${validated.sourceId} and ${validated.sourceId}.`, `relation on ${validated.sourceId} (no target).`);
     }
     /**
@@ -4297,15 +4372,17 @@ String(jsLiteral(source)) +
 String(jsLiteral(target)) +
 "];\n  if (sourceId && targetId) {\n    const params = " +
 String(paramsStr) +
-";\n    // A refused relation is not listed as made (owner rule 1).\n    if (app.addRelation(sourceId, targetId, " +
+";\n    " +
+String(eventNameResolveJs(type, 'params')) +
+"\n    // A refused relation is not listed as made (owner rule 1).\n    if (app.addRelation(sourceId, targetId, " +
 String(jsLiteral(type)) +
-", params)) {\n      results.relations.push({ source: " +
+", params)) {\n      results.relations.push(Object.assign({ source: " +
 String(jsLiteral(source)) +
 ", target: " +
 String(jsLiteral(target)) +
 ", type: " +
 String(jsLiteral(type)) +
-" });\n      const __o = { _: 0" +
+" }, __ev.eventResolvedTo ? { eventResolvedFrom: __ev.eventResolvedFrom, eventResolvedTo: __ev.eventResolvedTo } : {}));\n      if (__ev.warning) (results.optionWarnings = results.optionWarnings || []).push(__ev.warning);\n      const __o = { _: 0" +
 String(relationOptionFields(type, params, 'warning')) + " };\n      if (__o.warning) (results.optionWarnings = results.optionWarnings || []).push(__o.warning);\n      if (__o.ignoredOptions) (results.ignoredOptions = results.ignoredOptions || []).push.apply(results.ignoredOptions, __o.ignoredOptions.map(function(k) { return 'relations[" + String(relationIndex) + "].params.' + k; }));\n    } else {\n      const __why = " + String(relationRefusalReasonJs(jsLiteral(type))) + ";\n      (results.relationsRefused = results.relationsRefused || []).push({ source: " + String(jsLiteral(source)) + ", target: " + String(jsLiteral(target)) + ", type: " + String(jsLiteral(type)) + ", reason: __why || 'the studio refused it' });\n      results.success = false;\n      results.error = 'the studio refused ' + results.relationsRefused.length + ' relation(s): ' + results.relationsRefused.map(function(r) { return r.type + ' ' + r.source + ' -> ' + r.target + ' (' + r.reason + ')'; }).join('; ') + '. The items were created.';\n    }\n  }\n})();\n"));
         }
         // Apply animations
@@ -5308,6 +5385,45 @@ const __members = app.itemRegistry.getAll()
 if (!__members.length) throw new Error('no item is named like ' + ${jsLiteral(op.sourceId)} + ': name items with properties.name');`
                         : `const __members = [{ id: ${srcRef} }];
 if (!app.getItemById(__members[0].id)) throw new Error('Source not found: ' + __members[0].id);`;
+                    // A COLLECTION RULE IS DECLARED ONCE OVER THE SET (PHASEWAVE32, RINGFORM33). phase_wave, ring_forming
+                    // and flock take their members from params.members (or a group's children) and space them by rank in
+                    // that list; one relation per item gave each a set of one, so every disc took slot 0 (all at phase 0,
+                    // all on the angle-0 point of the ring). Bound once, on the first match, with the matches as members.
+                    const rel = String(op.relationType);
+                    const relParams = (op.relationOptions ?? {});
+                    if (glob && op.update !== true && COLLECTION_RELATIONS.has(rel)) {
+                        // ring_forming centres on the source's own bounds by default, and the source is a member that
+                        // moves: the centre is fixed at the members' centre as bound, unless a target or center was given.
+                        const ringCentre = rel === 'ring_forming' && noTarget && relParams.center === undefined;
+                        return ("\n" +
+String(members) +
+"\nconst targetId = " +
+String(noTarget ? 'null' : tgtRef) +
+";\nconst target = " +
+String(noTarget ? 'null' : 'app.getItemById(targetId)') +
+";\n" +
+String(noTarget ? '' : "if (!target) throw new Error('Target not found: ' + targetId);\n") +
+"const __ids = __members.map((m) => m.id);\nconst __p = Object.assign({}, " +
+String(relOpts) +
+String(relParams.members === undefined ? ', { members: { ids: __ids } }' : '') +
+");\n" +
+String(ringCentre ? `{
+  let __b = null;
+  __ids.forEach((id) => { const it = app.getItemById(id); if (it && it.bounds) __b = __b ? __b.unite(it.bounds) : it.bounds.clone(); });
+  if (__b) __p.center = { x: __b.center.x, y: __b.center.y };
+}
+` : '') +
+"const __src = app.getItemById(__ids[0]);\nconst __existing = app.relationRegistry && app.relationRegistry.getAssociations\n  && app.relationRegistry.getAssociations(__ids[0], " +
+String(type) +
+").some((a) => a.target === targetId || (targetId === null && a.target == null));\nconst ok = (__existing && typeof app.modifyRelationParams === 'function')\n  ? (app.modifyRelationParams(__ids[0], targetId, " +
+String(type) +
+", __p) || (targetId === null && app.modifyRelationParams(__ids[0], undefined, " +
+String(type) +
+", __p)))\n  : app.addRelation(__src, target, " +
+String(type) +
+", __p);\nif (!ok) {\n  const __why = " +
+String(relationRefusalReasonJs(type)) + ";\n  return { success: false, relationType: " + String(type) + ", sourceIds: [__ids[0]], error: 'the studio refused the ' + " + String(type) + " + ' relation over ' + __ids.length + ' members — nothing was bound' + (__why ? ': ' + __why : '.') };\n}\nreturn { success: true, relationType: " + String(type) + ", bound: [__ids[0]], members: __ids, count: __ids.length, targetId" + String(ringCentre ? ', center: __p.center' : '') + String(relationOptionFields(op.relationType, op.relationOptions, 'optionWarning', ['members'])) + " };\n");
+                    }
                     return ("\n" +
 String(stepGuard) +
 String(members) +
@@ -5349,14 +5465,18 @@ String(noTarget ? 'null' : tgtRef) +
 String(noTarget ? 'null' : 'app.getItemById(targetId)') +
 ";\nif (!source) throw new Error('Source not found: ' + sourceId);\n" +
 String(noTarget ? '' : "if (!target) throw new Error('Target not found: ' + targetId);\n") +
-"const relationId = app.addRelation(source, target, " +
-String(JSON.stringify(String(op.relationType))) +
-", " +
+"const __relOpts = " +
 String(relOpts) +
-");\n// NOT BOUND IS NOT A SUCCESS (owner rule 1, B119). addRelation answers false\n// when it refuses — spring_follow \"not loaded yet\" — and this op returned\n// { relationId: false } with nothing marking it failed, so the batch said\n// success over a relation that does not exist.\nif (!relationId) {\n  const __why = " +
+";\n" +
+String(eventNameResolveJs(op.relationType, '__relOpts')) +
+"\nconst relationId = app.addRelation(source, target, " +
+String(JSON.stringify(String(op.relationType))) +
+", __relOpts);\n// NOT BOUND IS NOT A SUCCESS (owner rule 1, B119). addRelation answers false\n// when it refuses — spring_follow \"not loaded yet\" — and this op returned\n// { relationId: false } with nothing marking it failed, so the batch said\n// success over a relation that does not exist.\nif (!relationId) {\n  const __why = " +
 String(relationRefusalReasonJs(jsLiteral(op.relationType))) +
 ";\n  return { success: false, relationId: false, sourceId, targetId, relationType: " +
-String(JSON.stringify(op.relationType)) + ",\n    error: 'the studio refused the ' + " + String(JSON.stringify(op.relationType)) + " + ' relation between ' + sourceId + ' and ' + targetId + ' — nothing was bound' + (__why ? ': ' + __why : '.') };\n}\nreturn { relationId, sourceId, targetId, relationType: " + String(JSON.stringify(String(op.relationType))) + String(relationOptionFields(op.relationType, op.relationOptions, 'warning')) + " };\n");
+String(JSON.stringify(op.relationType)) +
+",\n    error: 'the studio refused the ' + " +
+String(JSON.stringify(op.relationType)) + " + ' relation between ' + sourceId + ' and ' + targetId + ' — nothing was bound' + (__why ? ': ' + __why : '.') };\n}\nconst __reply = { relationId, sourceId, targetId, relationType: " + String(JSON.stringify(String(op.relationType))) + String(relationOptionFields(op.relationType, op.relationOptions, 'warning')) + " };\n" + String(EV_MERGE_JS('__reply')) + "\nreturn __reply;\n");
             case 'delete':
                 const delRef = batchRef(op.itemId);
                 return `
@@ -5586,7 +5706,10 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
     }
     generateAgentExport(input) {
         const validated = AgentExportInputSchema.parse(input);
-        const { platform, format, quality, framing, duration, estimateOnly, scale, fps, pdf: pdfOpts, region, time: stillTime, maxBytes, loop: gifLoop, broadcast, broadcastHeadroom, bitrate, minBitrate, bitrateMode, audioCodec, transparent, alphaQuantizer, deterministic, motionBlur, ad: adOpts, frames, startTime } = validated;
+        const { platform, format, quality, framing, duration, estimateOnly, scale, fps, pdf: pdfOpts, region, time: stillTime, maxBytes, loop: gifLoop, broadcast, broadcastHeadroom, bitrate, minBitrate, bitrateMode, audioCodec, transparent, alphaQuantizer, deterministic: askedDeterministic, motionBlur, ad: adOpts, frames, startTime } = validated;
+        const regionSrc = region ? regionCoverCrop(region) : undefined;
+        // Every video is deterministic unless the caller opts out (owner, 2026-11-07), so every receipt says whether its file repeats.
+        const deterministic = askedDeterministic ?? (format === 'mp4' || format === 'webm');
         // Encoder options (FxTool 16719759); the schema keeps them to mp4 / webm.
         const videoEncodeOpts = {};
         // A RANGE of the timeline (FxTool #250): frames for t in [startTime, startTime + duration), each exactly the frame
@@ -5911,34 +6034,42 @@ String(stillTime === undefined ? `  if (['png', 'jpg', 'webp', 'svg', 'pdf'].ind
 ` : '') +
 "  // A STILL SHOWS WHAT IS ALIVE AT ITS MOMENT. Lifetimes that fall back to the\n  // MCP's frame callback are applied by the frame loop, and a seek does not run\n  // it — so a png at time 0.8 s drew nothing staged at 0.8 s, and an item past\n  // its ttl still showed (retest). The visibility pass runs here for stills.\n  if (['png', 'jpg', 'webp', 'svg', 'pdf'].indexOf(format) !== -1) {\n    const __L = globalThis.__ppMcp;\n    if (__L && __L.lifetimeApp === app && typeof __L.applyLifetimes === 'function') {\n      try { __L.applyLifetimes(__stillT !== null ? __stillT : (typeof app.playbackTime === 'number' ? app.playbackTime : 0)); } catch (_) { /* the still renders either way */ }\n   " +
 " }\n  }\n  // The engine's report on the audio track of THIS export (FxTool b41860aa:\n  // encoder delay compensated, padding past the picture dropped). Cleared\n  // first so a report left by an earlier export is never read as this one's.\n  const __vx = app.exportEngine && app.exportEngine.videoExporter;\n  if (__vx && 'lastAudioReport' in __vx) __vx.lastAudioReport = null;\n  if (__vx && 'lastVideoReport' in __vx) __vx.lastVideoReport = null;\n  // A STILL AT A CHOSEN MOMENT (round 7 X, 1.57). Without this a png is\n  // whatever frame the playhead is on — two identical builds gave PNGs that\n  // differed in the animated streak while their MP4s were byte-identical.\n  // Seek, render," +
-" and put the playhead back afterwards.\n  const __prevT = typeof app.playbackTime === 'number' ? app.playbackTime : 0;\n  if (__stillT !== null) {\n    if (typeof app.setPlaybackTime !== 'function') {\n      return { success: false, platform, format, error: 'app.setPlaybackTime unavailable — this studio cannot render a still at a chosen time.' };\n    }\n    app.setPlaybackTime(__stillT);\n    if (typeof paper !== 'undefined' && paper.view && typeof paper.view.update === 'function') paper.view.update();\n  }\n\n  try {\n    // jpg / webp render as png, then re-encode below.\n    switch ((format === 'jpg' || format === 'webp') ? 'png' : format) {\n      case 'svg':\n        const svgString " +
-"= app.exportAnimatedSVG ? app.exportAnimatedSVG() : app.exportSVGWithCSS();\n        result = {\n          success: true,\n          platform,\n          format: 'svg',\n          data: svgString,\n          mimeType: 'image/svg+xml',\n          size: new Blob([svgString]).size,\n          hasAnimations: svgString.includes('<animate') || svgString.includes('@keyframes')\n        };\n        break;\n\n      case 'png':\n        " +
-String(region ? ("// A REGION, not the whole board — carousel slices, crops. renderRegionToDataURL\n        // re-renders that world rect offscreen without touching the live view;\n        // it was reachable only from custom code. A differing output aspect is\n        // covered by the engine, not stretched.\n        if (typeof app.renderRegionToDataURL !== 'function') {\n          result = { success: false, platform, format: 'png', error: 'app.renderRegionToDataURL unavailable — update PinePaper Studio to export a region.' };\n          break;\n        }\n        {\n          const rw = " +
+" and put the playhead back afterwards.\n  const __prevT = typeof app.playbackTime === 'number' ? app.playbackTime : 0;\n  // A PDF STILL HOLDS ITS MOMENT (PDFEXP34 a). exportPDF awaits its PDF library\n  // and then captures the live view, so a playing timeline ran on past the seek\n  // and the page showed about t=1.3 s whatever time asked for. The timeline is\n  // paused for the PDF and resumed after it.\n  let __pausedForStill = false;\n  let __pdfEvaluated = false;\n  if (__stillT !== null) {\n    if (typeof app.setPlaybackTime !== 'function') {\n      return { success: false, platform, format, error: 'app.setPlaybackTime unavailable — this studio cannot render a still at a chosen tim" +
+"e.' };\n    }\n    if (format === 'pdf' && app.isPlayingKeyframes && !app.isAnimationPaused) {\n      try { app.pauseKeyframeTimeline(); __pausedForStill = true; } catch (_) { /* the seek below still applies */ }\n    }\n    app.setPlaybackTime(__stillT);\n    if (typeof paper !== 'undefined' && paper.view && typeof paper.view.update === 'function') paper.view.update();\n  }\n\n  try {\n    // jpg / webp render as png, then re-encode below.\n    switch ((format === 'jpg' || format === 'webp') ? 'png' : format) {\n      case 'svg':\n        const svgString = app.exportAnimatedSVG ? app.exportAnimatedSVG() : app.exportSVGWithCSS();\n        result = {\n          success: true,\n          pla" +
+"tform,\n          format: 'svg',\n          data: svgString,\n          mimeType: 'image/svg+xml',\n          size: new Blob([svgString]).size,\n          hasAnimations: svgString.includes('<animate') || svgString.includes('@keyframes')\n        };\n        break;\n\n      case 'png':\n        " +
+String(region ? ("// A REGION, not the whole board — carousel slices, crops. renderRegionToDataURL\n        // re-renders that world rect offscreen without touching the live view;\n        // it was reachable only from custom code. A differing output aspect is\n        // cropped here first (regionCoverCrop), so the engine only scales.\n        if (typeof app.renderRegionToDataURL !== 'function') {\n          result = { success: false, platform, format: 'png', error: 'app.renderRegionToDataURL unavailable — update PinePaper Studio to export a region.' };\n          break;\n        }\n        {\n          const rw = " +
 String(region.outputWidth ?? Math.round(region.width)) +
 ", rh = " +
 String(region.outputHeight ?? Math.round(region.height)) +
 ";\n          // OWNERSHIP BY CENTRE (1.78, FxTool 78ec5916): excludeForeign hides, for\n          // this render, a top-level item that reaches in but is centred outside —\n          // a neighbouring card's overflowing headline. Older studios ignore the\n          // fourth argument, and leave lastRegionExcluded unset.\n          if ('lastRegionExcluded' in app) app.lastRegionExcluded = null;\n          // A video in the region is waited for at this time (round 12, 12.5):\n          // the render drew before the clip's seek landed.\n          if (typeof app.awaitMediaAt === 'function') await app.awaitMediaAt(__stillT !== null ? __stillT : (typeof app.playbackTime === 'number' ? app.playba" +
 "ckTime : 0));\n          const regionUrl = app.renderRegionToDataURL(new paper.Rectangle(" +
-String(region.x) +
+String(regionSrc.x) +
 ", " +
-String(region.y) +
+String(regionSrc.y) +
 ", " +
-String(region.width) +
+String(regionSrc.width) +
 ", " +
-String(region.height) +
+String(regionSrc.height) +
 "), rw, rh" +
 String(region.excludeForeign === false ? '' : ', { excludeForeign: true }') +
 ");\n          const __excluded = Array.isArray(app.lastRegionExcluded) ? app.lastRegionExcluded.filter(function(id) { return id; }) : null;\n          // ITEMS THAT CROSS THE REGION'S EDGE (round 9 II, 1.78). In the sheet\n          // recipe — one big canvas, one region per card — text that overflows\n          // its cell spills into the next card's export (up to 5,826 foreign px),\n          // silently. A region cannot know which card an item belongs to, so it\n          // cannot clip per card; it can name every item that is only partly\n          // inside it, which is exactly the overflow in either direction.\n          const __rx = " +
-String(region.x) +
+String(regionSrc.x) +
 ", __ry = " +
-String(region.y) +
+String(regionSrc.y) +
 ", __rr = " +
-String(region.x + region.width) +
+String(regionSrc.x + regionSrc.width) +
 ", __rb = " +
-String(region.y + region.height) +
+String(regionSrc.y + regionSrc.height) +
 ";\n          const crossing = [], coveringExcluded = [];\n          if (app.itemRegistry && typeof app.itemRegistry.getAll === 'function') {\n            app.itemRegistry.getAll().forEach(function(e) {\n              const b = e && e.item && e.item.visible !== false && e.item.bounds;\n              if (!b || !(b.width > 0)) return;\n              const r = b.x + b.width, bt = b.y + b.height;\n              const intersects = b.x < __rr && r > __rx && b.y < __rb && bt > __ry;\n              const inside = b.x >= __rx - 0.5 && r <= __rr + 0.5 && b.y >= __ry - 0.5 && bt <= __rb + 0.5;\n              const covers = b.x <= __rx && r >= __rr && b.y <= __ry && bt >= __rb; // a full-bleed backdrop" +
 " is not overflow\n              if (intersects && !inside && !covers && crossing.length < 20) crossing.push(e.itemId);\n              if (covers && __excluded && (__excluded.indexOf(e.itemId) >= 0 || (e.item.data && __excluded.indexOf(e.item.data.id) >= 0))) coveringExcluded.push(e.itemId);\n            });\n          }\n          result = { success: true, platform, format: 'png', data: regionUrl, mimeType: 'image/png',\n            size: Math.round(String(regionUrl).length * 0.75), dimensions: { width: rw, height: rh },\n            region: " +
 String(JSON.stringify({ x: region.x, y: region.y, width: region.width, height: region.height })) +
+String(regionSrc.cropped ? `,
+            // A DIFFERENT OUTPUT ASPECT IS A CROP (REGION34). The studio grew the box to
+            // the output's aspect instead, drawing content from outside the region and
+            // black past the canvas edge. The server now trims the region about its
+            // centre to the output's aspect, so the studio is only asked to scale.
+            croppedTo: ${JSON.stringify({ x: regionSrc.x, y: regionSrc.y, width: regionSrc.width, height: regionSrc.height })},
+            cropNote: ${JSON.stringify('the output aspect differs from the region\'s, so the region was cropped about its centre to fit (croppedTo); nothing outside the region is drawn.')}` : '') +
 " };\n          if (__excluded && __excluded.length) {\n            result.excludedItems = __excluded;\n            result.excludedNote = 'centred outside this region, so treated as belonging to a neighbouring region and left out of this image.';\n          }\n          if (coveringExcluded.length) {\n            result.warning = 'backdrop item(s) ' + coveringExcluded.join(', ') + ' cover this whole region but are centred outside it, so they were left out as foreign — this image has no background from them. Re-export with region.excludeForeign: false, or give each card its own backdrop.';\n          }\n          if (crossing.length) {\n            result.crossingItems = crossing;\n         " +
 "   result.warning = (result.warning ? result.warning + ' ' : '') + crossing.length + ' item(s) are only partly inside this region, so part of them is cut off here or spills into a neighbouring region: ' + crossing.join(', ') + '. In a sheet of cards this is text overflowing its card — shorten it, shrink it, or wrap it.';\n          }\n        }\n        break;"
 
@@ -5962,6 +6093,11 @@ String(JSON.stringify({ x: region.x, y: region.y, width: region.width, height: r
 
 
 
+
+
+
+
+
 
 
 
@@ -6000,9 +6136,9 @@ String(encodeOptsJs ? `
             // Broadcast / bitrate. A store that rebuilds its options without
             // them is caught by the video report below, not assumed.
             ${encodeOptsJs.slice(2)},` : '') +
-"\n          });\n          if (!stored || stored.ok === false) {\n            result = { success: false, platform, format, error: (stored && stored.reason) || 'the export store refused the export without saying why' };\n          } else {\n            let chunkBytes = 4 * 1024 * 1024;\n            try {\n              const declared = app.exportEngine.constructor && app.exportEngine.constructor.EXPORT_CHUNK_BYTES;\n              if (typeof declared === 'number' && declared > 0) chunkBytes = declared;\n            } catch (_) { /* keep the default */ }\n            result = {\n              success: true, platform, framing,\n              // Trust the container the store reports over the on" +
-"e asked for:\n              // mp4 falls back to WebM without WebCodecs, and WebM bytes named\n              // .mp4 fail in container-validating players.\n              format: stored.format || format,\n              retained: true,\n              exportId: stored.exportId,\n              mimeType: stored.mimeType || videoMimeType,\n              size: stored.size,\n              chunkBytes: chunkBytes,\n              dimensions: cameraDims || dimensions,\n            };\n          }\n          break;\n        }\n\n        // NO EXPORT STORE ON THIS STUDIO, or gif. Both remaining failures are\n        // named rather than left to blow up: a streamed export hands back a\n        // marker " +
-"instead of a Blob and FileReader throws on it, and an export\n        // past the inline ceiling used to die somewhere in the base64 rather\n        // than say so. The ceiling sits above what this path could already do\n        // (60 s at 8 Mbps is roughly 60 MB) so nothing that works today starts\n        // refusing.\n        const INLINE_MAX_BYTES = " +
+"\n          });\n          if (!stored || stored.ok === false) {\n            result = { success: false, platform, format, error: (stored && stored.reason) || 'the export store refused the export without saying why',\n              // The studio's code for a refusal (audio_codec_unavailable, B45), for a caller to branch on.\n              ...(stored && typeof stored.code === 'string' ? { code: stored.code } : {}) };\n          } else {\n            let chunkBytes = 4 * 1024 * 1024;\n            try {\n              const declared = app.exportEngine.constructor && app.exportEngine.constructor.EXPORT_CHUNK_BYTES;\n              if (typeof declared === 'number' && declared > 0) chunkBytes = d" +
+"eclared;\n            } catch (_) { /* keep the default */ }\n            result = {\n              success: true, platform, framing,\n              // Trust the container the store reports over the one asked for:\n              // mp4 falls back to WebM without WebCodecs, and WebM bytes named\n              // .mp4 fail in container-validating players.\n              format: stored.format || format,\n              retained: true,\n              exportId: stored.exportId,\n              mimeType: stored.mimeType || videoMimeType,\n              size: stored.size,\n              chunkBytes: chunkBytes,\n              dimensions: cameraDims || dimensions,\n            };\n          }\n      " +
+"    break;\n        }\n\n        // NO EXPORT STORE ON THIS STUDIO, or gif. Both remaining failures are\n        // named rather than left to blow up: a streamed export hands back a\n        // marker instead of a Blob and FileReader throws on it, and an export\n        // past the inline ceiling used to die somewhere in the base64 rather\n        // than say so. The ceiling sits above what this path could already do\n        // (60 s at 8 Mbps is roughly 60 MB) so nothing that works today starts\n        // refusing.\n        const INLINE_MAX_BYTES = " +
 String(INLINE_MAX_BYTES) +
 ";\n        const mb = (n) => (n / (1024 * 1024)).toFixed(1);\n        const deliver = async (raw) => {\n          // Normalise first: a {blob, …} record would otherwise be reported as\n          // \"streamed to a file instead of returning bytes\", which is a true\n          // sentence about the wrong problem.\n          const blob = asBlob(raw) || raw;\n          if (!blob || typeof blob.size !== 'number' || typeof blob.slice !== 'function') {\n            return {\n              success: false, platform, format,\n              error: 'this export streamed to a file instead of returning bytes, and this studio has no app.exportEngine.exportToStore to page it back from — update FxTool for " +
 "long-form export',\n            };\n          }\n          if (blob.size > INLINE_MAX_BYTES) {\n            return {\n              success: false, platform, format, size: blob.size,\n              error: 'export is ' + mb(blob.size) + ' MB, over the ' + mb(INLINE_MAX_BYTES)\n                + ' MB inline ceiling, and this studio has no app.exportEngine.exportToStore to page it out of — update FxTool, or lower duration/quality',\n            };\n          }\n          // The container the file IS: an encoder that cannot do H.264 at this\n          // size writes VP9 WebM (round 12: mp4 at 12000 px came back WebM),\n          // and naming it .mp4 breaks players. Said below in fidelity.\n  " +
@@ -6021,21 +6157,42 @@ String(gifLoop !== undefined ? `// A LOOP COUNT (8.30): _quickExportVideo rebuil
 "\n          if (videoResult && videoResult.blob) {\n            result = await deliver(videoResult.blob);\n          } else {\n            result = { success: false, error: format.toUpperCase() + ' export returned no data' };\n          }\n          " +
 String(maxBytes !== undefined ? ("// A BYTE BUDGET (round 9 GG, 8.31 — email wants <= 1 MB). gif.js has no\n          // colour-count knob, so size is the lever: GIF bytes scale roughly with\n          // pixel count, so the frame is shrunk by sqrt(budget / size) with a\n          // margin and re-encoded, at most twice. Every attempt is reported.\n          if (format === 'gif' && result && result.success && result.size > " +
 String(maxBytes) +
-") {\n            const attempts = [{ width: dimensions.width, height: dimensions.height, bytes: result.size }];\n            let w = dimensions.width, h = dimensions.height;\n            for (let k = 0; k < 2 && result.success && result.size > " +
+") {\n            // THE FILE'S OWN SIZE, from its header (GIFMAX34). The first GIF comes from _quickExportVideo, which\n            // may not render at the canvas size, so shrinking \"the canvas\" could ask for a LARGER frame: a\n            // 20 kB budget turned a 74 kB GIF into a 170 kB one. Each attempt is measured, a retry never asks for\n            // more pixels than the file it replaces, and the smallest file wins.\n            const __gifDims = async (b) => {\n              try {\n                const a = new Uint8Array(await (asBlob(b) || b).slice(0, 10).arrayBuffer());\n                if (a[0] === 0x47 && a[1] === 0x49 && a[2] === 0x46) return { width: a[6] | (a[7] << 8), he" +
+"ight: a[8] | (a[9] << 8) };\n              } catch (_) { /* the canvas size stands in */ }\n              return null;\n            };\n            const __d0 = (videoResult && videoResult.blob && await __gifDims(videoResult.blob)) || { width: dimensions.width, height: dimensions.height };\n            const attempts = [{ width: __d0.width, height: __d0.height, bytes: result.size }];\n            let best = result, bestDims = __d0;\n            let w = __d0.width, h = __d0.height;\n            for (let k = 0; k < 2 && best.size > " +
 String(maxBytes) +
 "; k++) {\n              const f = Math.sqrt(" +
 String(maxBytes) +
-" / result.size) * 0.9;\n              w = Math.max(16, Math.round(w * f / 2) * 2); h = Math.max(16, Math.round(h * f / 2) * 2);\n              // videoExporter.export, not _quickExportVideo: the latter rebuilds\n              // its settings without width / height, so a \"smaller\" retry\n              // through it came out the same size.\n              if (!app.exportEngine.videoExporter || typeof app.exportEngine.videoExporter.export !== 'function') break;\n              const again = await app.exportEngine.videoExporter.export(Object.assign({}, baseVideoSettings, { format: 'gif', width: w, height: h }" +
+" / best.size) * 0.9;\n              w = Math.max(16, Math.min(bestDims.width - 2, Math.round(bestDims.width * f / 2) * 2));\n              h = Math.max(16, Math.min(bestDims.height - 2, Math.round(bestDims.height * f / 2) * 2));\n              // videoExporter.export, not _quickExportVideo: the latter rebuilds\n              // its settings without width / height, so a \"smaller\" retry\n              // through it came out the same size.\n              if (!app.exportEngine.videoExporter || typeof app.exportEngine.videoExporter.export !== 'function') break;\n              const again = await app.exportEngine.videoExporter.export(Object.assign({}, baseVideoSettings, { format: 'gif', width:" +
+" w, height: h }" +
 String(gifLoop !== undefined ? `, { loop: ${JSON.stringify(gifLoop)} }` : '') +
-"));\n              if (!again) break;\n              result = await deliver(again);\n              attempts.push({ width: w, height: h, bytes: result.size });\n            }\n            result.budget = { maxBytes: " +
+"));\n              if (!again) break;\n              const r2 = await deliver(again);\n              const d2 = (await __gifDims(again)) || { width: w, height: h };\n              attempts.push({ width: d2.width, height: d2.height, bytes: r2.size });\n              if (r2.success && r2.size < best.size) { best = r2; bestDims = d2; }\n            }\n            result = best;\n            result.budget = { maxBytes: " +
 String(maxBytes) +
 ", met: !!(result.success && result.size <= " +
 String(maxBytes) +
-"), attempts: attempts };\n            if (result.success && result.size > " +
+"), attempts: attempts };\n            // The file delivered is said by its own size, met or not (GIFMAX34: a missed budget kept the\n            // requested dimensions in the reply).\n            if (result.success) result.dimensions = { width: bestDims.width, height: bestDims.height };\n            if (result.success && (bestDims.width !== dimensions.width || bestDims.height !== dimensions.height)) {\n              result.downscaled = { from: { width: dimensions.width, height: dimensions.height }, to: { width: bestDims.width, height: bestDims.height }, reason: bestDims === __d0 ? 'studio' : 'maxBytes' };\n            }\n            if (result.success && result.size > " +
 String(maxBytes) +
-") {\n              result.warning = 'still ' + result.size + ' bytes after shrinking to ' + w + 'x' + h + ' — over the ' + " +
+") {\n              result.warning = 'still ' + result.size + ' bytes at ' + bestDims.width + 'x' + bestDims.height + ', the smallest of ' + attempts.length + ' tries — over the ' + " +
 String(maxBytes) +
-" + '-byte budget. Lower fps, shorten duration, or use quality \"draft\".';\n            } else if (result.success) {\n              result.dimensions = { width: w, height: h };\n            }\n          }"
+" + '-byte budget. Lower fps, shorten duration, or use quality \"draft\".';\n            }\n          }"
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 
 
 
@@ -6162,7 +6319,8 @@ String(pdfOpts.searchableText !== false) +
 
 
 ) : '') +
-"\n        if (app.exportEngine && app.exportEngine.exportPDF) {\n          // Print options reach the engine (they were engine-only before), and\n          // download:false, because the tool delivers the bytes itself.\n          // lastPdfReport is a report PROPERTY (9917cfa5), read through the\n          // engine object like the exporter's audio / video reports, and only\n          // when present.\n          const __pee = app.exportEngine;\n          if ('lastPdfReport' in __pee) __pee.lastPdfReport = null;\n          const pdfOut = await app.exportEngine.exportPDF({\n            dpi: " +
+"\n        if (app.exportEngine && app.exportEngine.exportPDF) {\n          // Print options reach the engine (they were engine-only before), and\n          // download:false, because the tool delivers the bytes itself.\n          // lastPdfReport is a report PROPERTY (9917cfa5), read through the\n          // engine object like the exporter's audio / video reports, and only\n          // when present.\n          const __pee = app.exportEngine;\n          if ('lastPdfReport' in __pee) __pee.lastPdfReport = null;\n          // exportPDF does not evaluate the scene at the playhead as exportPNG\n          // does (relations, timed events), so the same engine step runs here,\n          // and w" +
+"hat its timed events changed is put back after the page.\n          if (__stillT !== null && typeof __pee._evaluateStillAt === 'function') {\n            try { __pee._evaluateStillAt(__stillT); __pdfEvaluated = true; } catch (_) { /* the page renders either way */ }\n            if (typeof paper !== 'undefined' && paper.view && typeof paper.view.update === 'function') paper.view.update();\n          }\n          const pdfOut = await app.exportEngine.exportPDF({\n            dpi: " +
 String(pdfOpts?.dpi ?? 'settings.dpi') +
 ",\n            download: false," +
 String(pdfOpts?.searchableText === false ? '\n            searchableText: false,' : '') +
@@ -6171,18 +6329,20 @@ String(pdfOpts?.orientation ? `\n            orientation: ${JSON.stringify(pdfOp
 String(pdfOpts?.bleed !== undefined ? `\n            includeBleed: ${pdfOpts.bleed > 0}, bleed: ${pdfOpts.bleed},` : '') +
 String(pdfOpts?.trimMarks !== undefined ? `\n            trimMarks: ${pdfOpts.trimMarks},` : '') +
 "\n          });\n          const blob = asBlob(pdfOut);\n          if (!blob) {\n            const got = pdfOut === null ? 'null'\n              : typeof pdfOut === 'object' ? 'an object with keys [' + Object.keys(pdfOut).join(', ') + ']'\n                : typeof pdfOut;\n            result = { success: false, platform, format: 'pdf',\n              error: 'the PDF export did not produce a file: expected a Blob, got ' + got + '.' };\n            break;\n          }\n          const dataUrl = await blobToDataUrl(blob);\n          result = {\n            success: true, platform, format: 'pdf', data: dataUrl,\n            mimeType: 'application/pdf', size: blob.size, dpi: settings.dpi,\n    " +
-"        // The record carries the page geometry the engine chose; it is the\n            // only place a caller can learn it.\n            ...(pdfOut && pdfOut.width ? { dimensions: { width: pdfOut.width, height: pdfOut.height } } : {}),\n            ...(pdfOut && pdfOut.format ? { paperFormat: pdfOut.format } : {})," +
-String(pdfOpts?.paperFormat && pdfOpts.paperFormat !== 'custom' && ((pdfOpts.bleed ?? 0) > 0 || pdfOpts.trimMarks) ? `
-            // Bleed and trim marks on a NAMED paper size: the studio keeps the
-            // page at that size and centres the art, so neither appears (prod
-            // retest: MediaBox = TrimBox = A4, no marks). Said, not silent.
-            warnings: [${JSON.stringify(`bleed / trimMarks were passed with paperFormat '${pdfOpts.paperFormat}', and this studio applies them only to paperFormat 'custom' (page = canvas + bleed): the page stayed ${pdfOpts.paperFormat} with no bleed and no marks. For print with bleed, size the canvas with a PRINT preset (agent_start_job canvasPreset 'print-a4' / 'print-letter' / 'print-a4-landscape' / 'print-letter-landscape', which carry 300 dpi — a plain 2480x3508 canvas is read at 96 dpi and comes out ~656 mm wide) and pass paperFormat 'custom'.`)}],` : '') +
-"\n          };\n        } else {\n          result = { success: false, error: 'PDF export failed' };\n        }\n        break;\n\n      default:\n        result = { success: false, error: 'Unknown format: ' + format };\n    }\n  } catch (e) {\n    result = { success: false, error: (e && typeof e.message === 'string' && e.message) || (typeof e === 'string' && e) || ('the ' + format + ' export threw with no message'), platform, format };\n  }\n\n  // One site, after every branch has set its result: a successful export says\n  // what this scene lost to this format, rather than the caller finding out by\n  // opening the file. Only when there is something to say — see fidelity().\n  // RE-EN" +
-"CODE A STILL FOR A BYTE BUDGET. The png path rendered it (whole board\n  // or region); the browser's own encoder makes jpg / webp at the tier's\n  // compression. jpg has no alpha, so it is flattened onto the scene background\n  // (white when there is none) rather than left to the encoder's black.\n  if (result && result.success && (format === 'jpg' || format === 'webp') && typeof result.data === 'string') {\n    const mime = format === 'jpg' ? 'image/jpeg' : 'image/webp';\n    try {\n      const encoded = await new Promise(function(resolve, reject) {\n        const img = new Image();\n        img.onload = function() {\n          const c = document.createElement('canvas');\n          c.w" +
-"idth = img.naturalWidth; c.height = img.naturalHeight;\n          const x = c.getContext('2d');\n          // The scene's own background when one is set — white text on a\n          // transparent board vanished into a white flatten. White otherwise.\n          if (mime === 'image/jpeg') {\n            const bg = app.canvasEl && app.canvasEl.style && app.canvasEl.style.backgroundColor;\n            x.fillStyle = (bg && !/^(transparent|rgba\\([^)]*,\\s*0\\))$/i.test(bg)) ? bg : '#ffffff';\n            x.fillRect(0, 0, c.width, c.height);\n          }\n          x.drawImage(img, 0, 0);\n          resolve(c.toDataURL(mime, settings.compression));\n        };\n        img.onerror = function() " +
-"{ reject(new Error('the rendered frame could not be decoded for re-encoding')); };\n        img.src = result.data;\n      });\n      if (String(encoded).indexOf('data:' + mime) !== 0) {\n        result = { success: false, platform, format, error: 'this browser cannot encode ' + format + ' (it returned ' + String(encoded).slice(5, 20) + '…).' };\n      } else {\n        result = Object.assign({}, result, { format, data: encoded, mimeType: mime, size: Math.round(String(encoded).length * 0.75), encodeQuality: settings.compression });\n      }\n    } catch (e) {\n      result = { success: false, platform, format, error: (e && typeof e.message === 'string' && e.message) || (typeof e === 'string" +
-"' && e) || ('re-encoding the still as ' + format + ' failed with no message') };\n    }\n  }\n\n  if (result && result.success) Object.assign(result, fidelity(format));\n  // MOTION FROM RELATIONS IS MOTION. The studio's check counts keyframe tracks\n  // and simple animations only, so an orbit (or attached_to a moving item, a\n  // generator, the camera) exported with animated:false while the frames moved,\n  // and callers rebuilt the scene with keyframes. When it says false, the\n  // frames decide: four captures across the export. The times are uneven so a\n  // loop cannot land on whole periods and look still. After the export, so it\n  // cannot touch the file. A capture leaves the p" +
-"ose of the last time it drew,\n  // so the samples end on 0 again: the canvas is left at rest, as found.\n  if (result && result.success && ['mp4', 'webm', 'gif', 'apng'].indexOf(format) !== -1\n      && result.fidelity && result.fidelity.checked && result.fidelity.checked.animated === false\n      && typeof app.captureFramesAt === 'function') {\n    try {\n      const __mt = [0, 0.17, 0.43, 0.71].map((k) => Math.round(k * " +
+"        // The record carries the page geometry the engine chose; it is the\n            // only place a caller can learn it.\n            ...(pdfOut && pdfOut.width ? { dimensions: { width: pdfOut.width, height: pdfOut.height } } : {}),\n            ...(pdfOut && pdfOut.format ? { paperFormat: pdfOut.format } : {}),\n            // What the page carries for print (FxTool #347): marks drawn, bleed applied, page and trim boxes.\n            ...(pdfOut && pdfOut.print && typeof pdfOut.print === 'object' ? { print: pdfOut.print } : {})," +
+String(pdfOpts?.paperFormat && pdfOpts.paperFormat !== 'custom' && pdfOpts.trimMarks ? `
+            // TRIM MARKS ON A NAMED SHEET. Bleed is applied there (page = sheet + 2 x bleed, TrimBox = sheet), but
+            // a studio before FxTool #347 draws no marks on a named sheet. Said unless the file's own record
+            // says it drew them.
+            ...((pdfOut && pdfOut.print && pdfOut.print.trimMarksDrawn) || (__pee.lastPdfReport && __pee.lastPdfReport.trimMarksDrawn) ? {} : {
+              warnings: [${JSON.stringify(`trimMarks were passed with paperFormat '${pdfOpts.paperFormat}', and this studio draws trim marks only with paperFormat 'custom' (the page is the canvas plus bleed), so this page has none. Any bleed was applied. For marks, pass paperFormat 'custom' on a canvas sized by a print preset (canvasPreset 'print-a4' etc., 300 dpi).`)}],
+            }),` : '') +
+"\n          };\n        } else {\n          result = { success: false, error: 'PDF export failed' };\n        }\n        break;\n\n      default:\n        result = { success: false, error: 'Unknown format: ' + format };\n    }\n  } catch (e) {\n    result = { success: false, error: (e && typeof e.message === 'string' && e.message) || (typeof e === 'string' && e) || ('the ' + format + ' export threw with no message'), platform, format,\n      ...(e && typeof e.code === 'string' ? { code: e.code } : {}) };\n  }\n\n  // One site, after every branch has set its result: a successful export says\n  // what this scene lost to this format, rather than the caller finding out by\n  // opening the fi" +
+"le. Only when there is something to say — see fidelity().\n  // RE-ENCODE A STILL FOR A BYTE BUDGET. The png path rendered it (whole board\n  // or region); the browser's own encoder makes jpg / webp at the tier's\n  // compression. jpg has no alpha, so it is flattened onto the scene background\n  // (white when there is none) rather than left to the encoder's black.\n  if (result && result.success && (format === 'jpg' || format === 'webp') && typeof result.data === 'string') {\n    const mime = format === 'jpg' ? 'image/jpeg' : 'image/webp';\n    try {\n      const encoded = await new Promise(function(resolve, reject) {\n        const img = new Image();\n        img.onload = function() {" +
+"\n          const c = document.createElement('canvas');\n          c.width = img.naturalWidth; c.height = img.naturalHeight;\n          const x = c.getContext('2d');\n          // The scene's own background when one is set — white text on a\n          // transparent board vanished into a white flatten. White otherwise.\n          if (mime === 'image/jpeg') {\n            const bg = app.canvasEl && app.canvasEl.style && app.canvasEl.style.backgroundColor;\n            x.fillStyle = (bg && !/^(transparent|rgba\\([^)]*,\\s*0\\))$/i.test(bg)) ? bg : '#ffffff';\n            x.fillRect(0, 0, c.width, c.height);\n          }\n          x.drawImage(img, 0, 0);\n          resolve(c.toDataURL(mime, " +
+"settings.compression));\n        };\n        img.onerror = function() { reject(new Error('the rendered frame could not be decoded for re-encoding')); };\n        img.src = result.data;\n      });\n      if (String(encoded).indexOf('data:' + mime) !== 0) {\n        result = { success: false, platform, format, error: 'this browser cannot encode ' + format + ' (it returned ' + String(encoded).slice(5, 20) + '…).' };\n      } else {\n        result = Object.assign({}, result, { format, data: encoded, mimeType: mime, size: Math.round(String(encoded).length * 0.75), encodeQuality: settings.compression });\n      }\n    } catch (e) {\n      result = { success: false, platform, format, error: (e &" +
+"& typeof e.message === 'string' && e.message) || (typeof e === 'string' && e) || ('re-encoding the still as ' + format + ' failed with no message') };\n    }\n  }\n\n  if (result && result.success) Object.assign(result, fidelity(format));\n  // MOTION FROM RELATIONS IS MOTION. The studio's check counts keyframe tracks\n  // and simple animations only, so an orbit (or attached_to a moving item, a\n  // generator, the camera) exported with animated:false while the frames moved,\n  // and callers rebuilt the scene with keyframes. When it says false, the\n  // frames decide: four captures across the export. The times are uneven so a\n  // loop cannot land on whole periods and look still. After" +
+" the export, so it\n  // cannot touch the file. A capture leaves the pose of the last time it drew,\n  // so the samples end on 0 again: the canvas is left at rest, as found.\n  if (result && result.success && ['mp4', 'webm', 'gif', 'apng'].indexOf(format) !== -1\n      && result.fidelity && result.fidelity.checked && result.fidelity.checked.animated === false\n      && typeof app.captureFramesAt === 'function') {\n    try {\n      const __mt = [0, 0.17, 0.43, 0.71].map((k) => Math.round(k * " +
 String(videoDuration) +
 " * 1000) / 1000);\n      const __mcap = typeof app.captureFramesAtAsync === 'function' ? app.captureFramesAtAsync.bind(app) : app.captureFramesAt.bind(app);\n      const __mf = await __mcap(__mt.concat([0]), { seed: 0, capture: (c) => (typeof app.captureFrameDataURL === 'function' ? app.captureFrameDataURL() : (c && c.toDataURL ? c.toDataURL() : '')) });\n      const __mu = new Set((__mf || []).filter((u) => typeof u === 'string' && u.length > 0));\n      if (__mu.size > 1) {\n        result.fidelity.checked.animated = true;\n        result.fidelity.checked.motion = 'frames differ across the export (sampled at ' + __mt.join(', ') + ' s): the motion comes from relations, generators or the c" +
 "amera, not keyframe tracks';\n      }\n    } catch (e) { /* the studio's answer stands */ }\n  }\n  if (result && result.success && __lint && __lint.length && !result.lintWarnings) {\n    result.lintWarnings = __lint;\n    result.fidelity = result.fidelity || { warnings: [] };\n    result.fidelity.warnings = (result.fidelity.warnings || []).concat(__lint.map(function (w) {\n      return { code: String(w.code || 'lint'), message: String(w.message || w.code || 'scene lint warning'), ...(w.itemId ? { items: [w.itemId] } : {}) };\n    }));\n    if (result.fidelity.note) delete result.fidelity.note;\n  }\n  if (result && result.success && __fit) result.platformFit = __fit;\n" +
@@ -6248,10 +6408,10 @@ String(videoDuration) +
 ".264 needs even dimensions, so\n  // 1200x675 came out 1200x676 — and platform specs are exact-pixel. The\n  // result's dimensions become what the file IS, and fidelity says why.\n  const __vd = __vr && __vr.dimensions;\n  if (result && result.success && __vd && Array.isArray(__vd.requested) && Array.isArray(__vd.output)\n      && (__vd.requested[0] !== __vd.output[0] || __vd.requested[1] !== __vd.output[1])) {\n    result.dimensions = { width: __vd.output[0], height: __vd.output[1] };\n    result.fidelity = result.fidelity || { warnings: [] };\n    result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'dimensions_rounded',\n      message: 'the file is ' + __vd.outpu" +
 "t[0] + 'x' + __vd.output[1] + ', not the requested ' + __vd.requested[0] + 'x' + __vd.requested[1] + ': H.264 needs even dimensions, so an odd side was rounded up by 1 px (the extra row / column is background). For an exact-pixel spec, use an even canvas size, or crop the extra line when re-encoding (ffmpeg -vf crop=' + __vd.requested[0] + ':' + __vd.requested[1] + ':0:0).' }]);\n    if (result.fidelity.note) delete result.fidelity.note;\n  }\n" +
 String(deterministic ? ("  // DETERMINISTIC: the container timestamps are pinned either way; the PIXELS\n  // are only identical run to run on the software encoder, because the\n  // browser may pick a different hardware backend each time (FxTool\n  // e34ae03d: 92/255 between backends, 2/255 run to run on hardware). The\n  // engine requests software and reports what it got.\n  // Where the studio says outright whether the file repeats (bitExact, FxTool\n  // PR #31: it test-encodes and keeps whichever encoder does — often the\n  // HARDWARE one on a Mac, since Chrome's software H.264 is not repeatable at\n  // some sizes), that answer decides; the encoder name is only the fallback\n  // for studios that do not r" +
-"eport it.\n  if (result && result.success) {\n    const __hw = __vr && __vr.hardwareAcceleration;\n    const __exact = __vr && typeof __vr.bitExact === 'boolean' ? __vr.bitExact : null;\n    if (__exact === false) {\n      result.fidelity = result.fidelity || { warnings: [] };\n      result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'determinism_not_pinned',\n        ...(__vr && __vr.cause ? { cause: __vr.cause } : {}),\n        message: 'deterministic was asked for, but no encoder on this machine repeats byte for byte at this size (the studio test-encoded and checked' + (__vr && __vr.cause === 'h264-threaded' ? ': the software H.264 encoder is multi-threaded and " +
-"takes no fixed quantizer' : '') + '). What still holds: the frames fed to the encoder are identical (compare frameDigest, not sha256), and the container is identical apart from the encoded samples. Do not cache this file by hash; export WebM for a byte-identical file.' }]);\n      if (result.fidelity.note) delete result.fidelity.note;\n    } else if (__exact === null && __hw !== 'prefer-software') {\n      result.fidelity = result.fidelity || { warnings: [] };\n      result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'determinism_not_pinned',\n        message: __hw\n          ? 'deterministic was asked for, but the encoder ran with hardwareAcceleration ' + JSON.str" +
-"ingify(__hw) + ': the container is pinned, the pixels may still differ slightly between runs (hardware encoders vary). Do not cache this file by hash.'\n          : 'deterministic pinned the container timestamps, but this studio does not report which encoder backend ran, so the pixels may differ slightly between runs if the browser switches between hardware and software encoding. Do not rely on byte-identical files from this studio.' }]);\n      if (result.fidelity.note) delete result.fidelity.note;\n    }\n  }\n"
-
+"eport it.\n  if (result && result.success) {\n    const __hw = __vr && __vr.hardwareAcceleration;\n    const __exact = __vr && typeof __vr.bitExact === 'boolean' ? __vr.bitExact : null;\n    if (__exact === false) {\n      result.fidelity = result.fidelity || { warnings: [] };\n      result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'determinism_not_pinned',\n        ...(__vr && __vr.determinism && __vr.determinism.cause ? { cause: __vr.determinism.cause } : {}),\n        message: 'this file will not repeat byte for byte: no encoder on this machine repeats at this size (the studio test-encoded and checked' + (__vr && __vr.determinism && __vr.determinism.cause === " +
+"'h264-threaded' ? ': the software H.264 encoder varies run to run at this size on this many CPUs' : '') + '). What still holds: the frames fed to the encoder are identical (compare frameDigest, not sha256), and the container is identical apart from the encoded samples. Do not cache this file by hash. For a byte-identical file, export WebM, or export_png_sequence (pinepaper_interchange) and encode the frames with your own FFmpeg, which the server does not provide.' }]);\n      if (result.fidelity.note) delete result.fidelity.note;\n    } else if (__exact === null && __hw !== 'prefer-software') {\n      result.fidelity = result.fidelity || { warnings: [] };\n      result.fidelity.warnings = " +
+"(result.fidelity.warnings || []).concat([{ code: 'determinism_not_pinned',\n        message: __hw\n          ? 'this file may not repeat byte for byte: the encoder ran with hardwareAcceleration ' + JSON.stringify(__hw) + ': the container is pinned, the pixels may still differ slightly between runs (hardware encoders vary). Do not cache this file by hash.'\n          : 'deterministic pinned the container timestamps, but this studio does not report which encoder backend ran, so the pixels may differ slightly between runs if the browser switches between hardware and software encoding. Do not rely on byte-identical files from this studio.' }]);\n      if (result.fidelity.note) delete result.fi" +
+"delity.note;\n    }\n  }\n"
 
 
 
@@ -6333,7 +6493,8 @@ String((() => {
                 warning: `${frames} frames at ${Math.round(fps * 1000) / 1000} fps is ${actual.toFixed(3)} s — ${((actual - videoDuration) * 1000).toFixed(1)} ms over the ${videoDuration} s asked for. For a hard cap (e.g. a 6 s bumper) use duration ${fit.toFixed(4)} (${Math.floor(videoDuration * fps)} frames).`,
             })};\n`;
         })()) +
-"\n  if (__stillT !== null) {\n    try { app.setPlaybackTime(__prevT); } catch (_) { /* the still is already rendered */ }\n    if (result && result.success) { result.time = __stillT; if (__stillTimeNote) result.stillTimeNote = __stillTimeNote; }\n  }\n  // SCREEN-SPACE ITEMS (FxTool D20): SVG and Lottie write geometry, not the\n  // camera's frame map, so a HUD item is placed as if the camera had not moved.\n  if (result && result.success && typeof app.screenSpaceItems === 'function' && ['svg', 'lottie', 'dotlottie'].indexOf(" +
+"\n  if (__pdfEvaluated && typeof app._restoreReactionJournal === 'function') {\n    try { app._restoreReactionJournal(); } catch (_) { /* the page is already rendered */ }\n  }\n  if (__stillT !== null) {\n    try { app.setPlaybackTime(__prevT); } catch (_) { /* the still is already rendered */ }\n    if (__pausedForStill) { try { app.resumeKeyframeTimeline(); } catch (_) { /* the still is already rendered */ } }\n    if (result && result.success) { result.time = __stillT; if (__stillTimeNote) result.stillTimeNote = __stillTimeNote; }\n  }\n  // SCREEN-SPACE ITEMS (FxTool D20): SVG and Lottie write geometry, not the\n  // camera's frame map, so a HUD item is placed as if the camera had not" +
+" moved.\n  if (result && result.success && typeof app.screenSpaceItems === 'function' && ['svg', 'lottie', 'dotlottie'].indexOf(" +
 String(JSON.stringify(format)) +
 ") !== -1) {\n    try {\n      const __hud = app.screenSpaceItems() || [];\n      if (__hud.length) {\n        result.fidelity = result.fidelity || { warnings: [] };\n        result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'screen_space_ignored', message: __hud.length + ' screen-space (HUD) item(s) are written at their frame coordinates in world space: " +
 String(format) +
@@ -7383,6 +7544,57 @@ String(jsLiteral(format)) +
 
 
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 
 
 
@@ -9495,7 +9707,7 @@ String(name ? `\n      name: ${JSON.stringify(name)},` : '') +
 "\n      bounds: { x: b.x, y: b.y, width: b.width, height: b.height }" +
 String(mask ? `,\n      mask: ${jsLiteral(mask)}` : '') +
 String(hasShadow ? ',\n      shadow: __shadow' : '') +
-String(loop !== undefined ? ",\n      playback: (raster && raster.data && raster.data.animatedImage && raster.data.animatedImage.loop !== undefined) ? { applied: true, plays: raster.data.animatedImage.loop } : { applied: false, warning: 'loop was not applied: this image does not animate in this studio. Animated GIF and WebP do.' }" : '') +
+String(loop !== undefined ? ",\n      playback: (raster && raster.data && raster.data.animatedImage && raster.data.animatedImage.loop !== undefined) ? { applied: true, plays: raster.data.animatedImage.loop } : { applied: false, warning: 'loop was not applied: this image does not animate in this studio. Animated GIF, WebP and APNG do.' }" : '') +
 String(hasLook ? ',\n      look: __look' : '') +
 ",\n      // Stored smaller than its source (the studio's cap): said, with the\n      // way to keep every pixel. The studio reports native size where it can.\n      ...((entry && entry.nativeWidth && entry.width && entry.nativeWidth > entry.width)\n        ? { stored: { width: entry.width, height: entry.height }, native: { width: entry.nativeWidth, height: entry.nativeHeight },\n            note: 'the studio stored this image at ' + entry.width + 'x' + entry.height + ' (its source is ' + entry.nativeWidth + 'x' + entry.nativeHeight + '). Pass maxEdge: \"native\" to keep every pixel.' }\n        : {})\n    };\n  } catch (e) {\n    return { error: 'Failed to import image: ' + e.message };\n " +
 " }\n})();\n"
@@ -16335,11 +16547,28 @@ function generateContraptionCode(input) {
                     ...(input.elseTrigger ? { elseTrigger: input.elseTrigger } : {}),
                     ...(input.enabled !== undefined ? { enabled: input.enabled } : {}),
                 };
-                return `${refuse('addContraption')}
-  const contraptionId = app.addContraption(${jsLiteral(config)});
-  const missing = ${jsLiteral(targets)}.filter((id) => !app.getItemById(id));
-  return { success: true, action: 'add_contraption', contraptionId,
-    ...(missing.length ? { warning: 'no item has the id ' + missing.join(', ') + ' yet: the rule does nothing to it until one does' } : {}), };`;
+                return ("" +
+String(refuse('addContraption')) +
+"\n  const contraptionId = app.addContraption(" +
+String(jsLiteral(config)) +
+");\n  const missing = " +
+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(' ') } : {}), };"
+
+
+
+
+
+
+
+
+
+
+);
             }
             case 'remove_contraption':
                 return `${refuse('removeContraption')}