@pinepaper.studio/mcp-server 1.6.31 → 1.6.33

package/dist/types/code-generator.js

@@ -7,7 +7,7 @@
 import { compileChoreography } from '../tools/choreograph.js';
 import { compileBatchTimelines, emitTimelineOpBody } from '../tools/timeline.js';
 import { normalizeSvgSize } from '../utils/svg-size.js';
-import { WORLD3D_COLOR_PATHS, PATTERN_KINDS, EXPRESSION_FUNCTION_ARITY, EXPRESSION_CONSTANTS, EXPRESSION_REJECTED, RELATION_PARAM_KEYS, ANIMATION_OPTION_KEYS } from '../tools/engine-lists.js';
+import { WORLD3D_COLOR_PATHS, PATTERN_KINDS, EXPRESSION_FUNCTION_ARITY, EXPRESSION_CONSTANTS, EXPRESSION_REJECTED, RELATION_PARAM_KEYS, RELATION_LOOP_PARAMS, ANIMATION_OPTION_KEYS, FILTER_TYPES, FILTER_PARAM_RANGES } from '../tools/engine-lists.js';
 import { expressionGrammarText } from '../tools/expression-grammar.js';
 import { REQUIRED_ENGINE_METHODS, OPTIONAL_ENGINE_METHODS } from '../tools/engine-methods.js';
 import { NORMALIZE_PARAM_READS, MODIFY_CHANGE_READS } from '../tools/shape-params.js';
@@ -16,6 +16,16 @@ import { jsLiteral } from '../utils/js-literal.js';
 /** A value spliced into a generated `//` comment, on one line: a line break in caller text would end the comment and run the rest as code. */
 /** How many relations pinepaper_lint_scene lists back; past it the result says how many there are. */
 const RELATIONS_READBACK_CAP = 200;
+/**
+ * A relation's parameters as a caller may read them: the engine's own rule for what leaves a relation
+ * (RelationRegistry.stripTransientParams, its save boundary), applied in the page because that is where the value is.
+ *
+ * The engine keeps its working state in the stored params: _itemRegistry (written on the first frame), _initialized,
+ * _startTime, _affectedItems, listeners as functions. Read back raw, a reply carried the registry, so it failed the page
+ * bridge's structured clone and took the walker's path, where the whole reply was truncated to fit. Sent back in an update
+ * op, the same keys overwrite live state: the engine fills those slots only when empty, so a stale copy stays for good.
+ */
+const RELATION_PUBLIC_PARAMS_JS = "((p) => Object.fromEntries(Object.entries(p || {}).filter(([k, v]) => k.charAt(0) !== '_' && typeof v !== 'function')))";
 function oneLine(v) {
     return String(v).replace(/[\r\n\u2028\u2029]+/g, ' ');
 }
@@ -182,12 +192,13 @@ function generateCreateItemCode(itemType, position, properties, dataFlags, posit
     if (properties.content === undefined && properties.text !== undefined) {
         properties = { ...properties, content: properties.text };
     }
+    // The alias replaces the key: left beside justification, the engine's receipt
+    // reported textAlign 'justify' as refused while it had been applied.
     if (properties.justification === undefined) {
-        if (properties.textAlign !== undefined) {
-            properties = { ...properties, justification: properties.textAlign };
-        }
-        else if (properties.align !== undefined) {
-            properties = { ...properties, justification: properties.align };
+        const alignKey = properties.textAlign !== undefined ? 'textAlign' : properties.align !== undefined ? 'align' : null;
+        if (alignKey) {
+            const { [alignKey]: alignValue, ...rest } = properties;
+            properties = { ...rest, justification: cssAlignToJustification(alignValue) };
         }
     }
     // Extract special properties that need separate handling
@@ -218,6 +229,7 @@ function generateCreateItemCode(itemType, position, properties, dataFlags, posit
         textDirection.resolved = baseDirection(createProps.content);
     }
     const textTabular = itemType === 'text' && wantsTabular(createProps) === true;
+    const textTypography = itemType === 'text' ? typographyRequest(createProps) : [];
     const createFillOpacity = createProps.fillOpacity !== undefined;
     const textStrokePos = itemType === 'text' ? takeStrokePosition(createProps, false) : null;
     const params = {
@@ -422,6 +434,8 @@ const __scale = (function(it) {
         code += emitDirectionCheck('item', textDirection);
     if (textTabular)
         code += emitTabularCheck('item');
+    if (textTypography.length)
+        code += emitTypographyCheck('item', textTypography);
     if (createFillOpacity)
         code += emitFillOpacityCheck('item');
     if (textStrokePos)
@@ -476,7 +490,7 @@ String(outlineOnly ? `, fill: ${JSON.stringify(OUTLINE_NOTE)}` : '') +
 String(textFit ? ', textFit: __textFit' : '') +
 String(textDirection ? ', direction: __direction' : '') +
 String(textTabular ? ', tabularFigures: __tabular' : '') +
-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
@@ -743,6 +757,50 @@ function anchorHold(anchor) {
     const a = String(anchor ?? '').toLowerCase();
     return /^top/.test(a) ? 'top' : /^bottom/.test(a) ? 'bottom' : undefined;
 }
+/**
+ * wordSpacing, textTransform, textDecoration and justify (FxTool #289, WORDSPC).
+ * The engine stores them on item.data and its text layer draws them; a studio
+ * before #289 has no such layer and the keys are lost. These keys are on the
+ * current engine's read list (shape-params.ts), so the unread-key report no
+ * longer names them; the reply instead reads item.data, so an older studio is
+ * still named rather than reported as done.
+ */
+/**
+ * textAlign / align, the CSS names, as Paper's justification: start / end read
+ * left / right and centre reads center, as the engine's own textAlign door does.
+ * Anything else passes through for the engine to judge (and report).
+ */
+function cssAlignToJustification(v) {
+    if (typeof v !== 'string')
+        return v;
+    const k = v.trim().toLowerCase();
+    return { start: 'left', end: 'right', centre: 'center', left: 'left', center: 'center', right: 'right', justify: 'justify' }[k] ?? v;
+}
+const TYPOGRAPHY_KEYS = ['wordSpacing', 'textTransform', 'textDecoration'];
+function typographyRequest(props) {
+    const keys = TYPOGRAPHY_KEYS.filter((k) => props[k] !== undefined);
+    const align = props.justification ?? props.textAlign ?? props.align;
+    if (typeof align === 'string' && align.trim().toLowerCase() === 'justify')
+        keys.push('justify');
+    return keys;
+}
+function emitTypographyCheck(itemExpr, keys) {
+    return ("\nconst __typography = (function(it, keys) {\n  if (!it || it.className !== 'PointText') return { applied: false, note: keys.join(', ') + ' apply to text items only.' };\n  const d = it.data || {};\n  if (typeof app._applyTextTypography !== 'function') return { applied: false, ignored: keys, note: 'this studio does not draw ' + keys.join(', ') + ' (it needs an engine with text typography): the text is drawn without ' + (keys.length > 1 ? 'them' : 'it') + '. Set the case in the content itself; for an underline, a line item under the text.' };\n  const out = { applied: true };\n  const unset = [];\n  for (const k of keys) {\n    const v = k === 'justify' ? (d.justify === true ? true : undefi" +
+"ned) : d[k];\n    out[k] = v === undefined ? null : v;\n    if (v === undefined) unset.push(k);\n  }\n  if (unset.length) out.note = unset.join(', ') + (unset.length > 1 ? ' are' : ' is') + ' not set on the item now: a clearing value (none / normal / 0) removes it, and a value the studio cannot draw is refused by name in the engine receipt.';\n  return out;\n})(" +
+String(itemExpr) +
+", " +
+String(JSON.stringify(keys)) +
+");"
+
+
+
+
+
+
+
+
+);
+}
 function emitTextFit(itemExpr, box, holdFallback = 'undefined') {
     return `
 if (typeof app.fitText === 'function') {
@@ -978,12 +1036,12 @@ function generateModifyItemCode(itemId, properties, dataFlags) {
     const aliased = new Set();
     if (restProperties.justification === undefined) {
         if (restProperties.textAlign !== undefined) {
-            restProperties.justification = restProperties.textAlign;
+            restProperties.justification = cssAlignToJustification(restProperties.textAlign);
             delete restProperties.textAlign;
             aliased.add('textAlign');
         }
         else if (restProperties.align !== undefined) {
-            restProperties.justification = restProperties.align;
+            restProperties.justification = cssAlignToJustification(restProperties.align);
             delete restProperties.align;
             aliased.add('align');
         }
@@ -1001,6 +1059,7 @@ function generateModifyItemCode(itemId, properties, dataFlags) {
         delete restProperties.fit;
     const modDirection = takeDirection(restProperties);
     const modTabular = wantsTabular(restProperties) === true;
+    const modTypography = typographyRequest(restProperties);
     const modFillOpacity = restProperties.fillOpacity !== undefined;
     const modStrokePos = takeStrokePosition(restProperties, true);
     // modifyItem(id, changes), NOT select() + modify().
@@ -1145,12 +1204,12 @@ const __ctKeys = (__ctItem && __ctItem.data && Array.isArray(__ctItem.data.keyfr
 "\n" +
 String(modDirection ? emitDirectionCheck(`app.getItemById(${ID})`, modDirection) : '') +
 String(modTabular ? emitTabularCheck(`app.getItemById(${ID})`) : '') +
+String(modTypography.length ? emitTypographyCheck(`app.getItemById(${ID})`, modTypography) : '') +
 String(modFillOpacity ? emitFillOpacityCheck(`app.getItemById(${ID})`) : '') +
 String(modStrokePos ? emitStrokePositionCheck(`app.getItemById(${ID})`, modStrokePos) : '') +
 "\nreturn { success: true, itemId: " +
 String(ID) +
-String(properties.content !== undefined ? `, ...(__ctKeys ? { contentTrackWarning: 'this text\\'s content is keyframed (' + __ctKeys + ' key(s)), so the track sets it on every frame and this edit does not show. Change the content keys with pinepaper_keyframe_animate (append: true replaces same-time keys), or animate another property.' } : {})` : '') +
-String(modFit ? ', textFit: __textFit' : '') + String(modDirection ? ', direction: __direction' : '') + String(modTabular ? ', tabularFigures: __tabular' : '') + String(modFillOpacity ? ', fillOpacity: __fillOpacity' : '') + String(modStrokePos ? ', strokePosition: __strokePos' : '') + String(affine ? `, affine: ${jsLiteral({ skewX, skewY, matrix, note: 'applied to the current shape: calling again compounds it. To undo, apply the inverse (negative skew, or the inverse matrix).' })}` : '') + String(modLifetime ? ', lifetime: __lifetime' : '') + String(modFont ? ', ...(__font ? { font: __font } : {})' : '') + String(modWarning) + " };");
+String(properties.content !== undefined ? `, ...(__ctKeys ? { contentTrackWarning: 'this text\\'s content is keyframed (' + __ctKeys + ' key(s)), so the track sets it on every frame and this edit does not show. Change the content keys with pinepaper_keyframe_animate (append: true replaces same-time keys), or animate another property.' } : {})` : '') + String(modFit ? ', textFit: __textFit' : '') + String(modDirection ? ', direction: __direction' : '') + String(modTabular ? ', tabularFigures: __tabular' : '') + String(modTypography.length ? ', typography: __typography' : '') + String(modFillOpacity ? ', fillOpacity: __fillOpacity' : '') + String(modStrokePos ? ', strokePosition: __strokePos' : '') + String(affine ? `, affine: ${jsLiteral({ skewX, skewY, matrix, note: 'applied to the current shape: calling again compounds it. To undo, apply the inverse (negative skew, or the inverse matrix).' })}` : '') + String(modLifetime ? ', lifetime: __lifetime' : '') + String(modFont ? ', ...(__font ? { font: __font } : {})' : '') + String(modWarning) + " };");
     // Wrapped, because the body now RETURNS early on a miss rather than falling
     // through to an unconditional success. Async only when a font must load
     // before modifyItem re-measures the text.
@@ -1391,6 +1450,45 @@ function editDistance(a, b) {
     }
     return row[b.length];
 }
+/**
+ * The params keys a custom relation reads, worked out when it is registered: what it declares, every `params.X` its
+ * compute / apply source reads, and the index / count a name pattern adds. null when the source uses params any other
+ * way (params[k], destructuring, handing params on), because then the list could not be trusted and a warning could
+ * name a key that works; null means no check, never a wrong one (RELWARN27: a bogus option on a built-in relation was
+ * named, the same option on a custom one was stored in silence).
+ */
+export function customRelationReads(params, computeFunction, applyFunction) {
+    const src = `${String(computeFunction ?? '')}\n${String(applyFunction ?? '')}`.replace(/\/\*[\s\S]*?\*\/|\/\/[^\n]*/g, '');
+    const bare = [...src.matchAll(/\bparams\b(?!\s*\??\.\s*[A-Za-z_$])/g)];
+    if (bare.length)
+        return null;
+    const keys = new Set(['index', 'count']);
+    if (params && typeof params === 'object')
+        Object.keys(params).forEach((k) => keys.add(k));
+    for (const m of src.matchAll(/\bparams\s*\??\.\s*([A-Za-z_$][\w$]*)/g))
+        keys.add(m[1]);
+    return [...keys].sort();
+}
+/**
+ * A relation's options checked against a CUSTOM relation's read list, in the page (the rule was registered there, maybe
+ * in an earlier call). A fragment for a result object: `, ...{ key: warning }` or nothing. Built-ins are checked here
+ * already (relationOptionWarning), so only a type without a built-in list is asked about.
+ */
+function customOptionWarningJs(relationType, params, key, injected = []) {
+    if (typeof relationType !== 'string' || RELATION_PARAM_KEYS[relationType] || !params || typeof params !== 'object')
+        return '';
+    const keys = Object.keys(params);
+    if (!keys.length)
+        return '';
+    return `, ...(function () { try {
+    var cr = typeof window !== 'undefined' && window.__ppCustomRelations && window.__ppCustomRelations[${jsLiteral(relationType)}];
+    if (!cr || !Array.isArray(cr.reads)) return {};
+    var skip = ${JSON.stringify([...injected, ...RELATION_LOOP_PARAMS])};
+    var un = ${JSON.stringify(keys)}.filter(function (k) { return cr.reads.indexOf(k) < 0 && skip.indexOf(k) < 0; });
+    if (!un.length) return {};
+    return { ignoredOptions: un, ${key}: ${jsLiteral(relationType)} + ' does not read ' + un.join(', ') + ', so ' + (un.length > 1 ? 'they were' : 'it was') + ' ignored. ' + ${jsLiteral(relationType)} + ' reads: ' + cr.reads.join(', ') + '.' };
+  } catch (e) { return {}; } })()`;
+}
 export function relationOptionWarning(relationType, params, injected = []) {
     const flip = equationFlipNote(relationType, params);
     const unread = unreadOptionWarning(relationType, params, injected);
@@ -1410,10 +1508,25 @@ function equationFlipNote(relationType, params) {
         return null;
     return 'params.equation is read with y UP (flipY defaults to true), so on screen the curve is mirrored about cy. If you wrote it in screen coordinates (y down), add flipY: false to the equation.';
 }
-function unreadOptionWarning(relationType, params, injected) {
+/** What a built-in relation reads: its rule's params, and what the relation loop reads on every relation. */
+function relationReads(relationType) {
     const keys = typeof relationType === 'string' ? RELATION_PARAM_KEYS[relationType] : undefined;
+    return keys ? [...keys, ...RELATION_LOOP_PARAMS] : undefined;
+}
+function unreadOptionWarning(relationType, params, injected) {
+    const keys = relationReads(relationType);
     return keys ? unreadKeysWarning(String(relationType), keys, params, injected) : null;
 }
+const unreadKeys = (keys, params, injected = []) => keys && params && typeof params === 'object' ? Object.keys(params).filter((k) => !keys.includes(k) && !injected.includes(k)) : [];
+/**
+ * A relation reply's fields for its options: the unread keys as data (ignoredOptions, which the reply's
+ * ignoredArguments is built from) beside the sentence. Built-ins are known here, a custom relation only in the page.
+ */
+function relationOptionFields(relationType, params, key, injected = []) {
+    const unread = unreadKeys(relationReads(relationType), params, injected);
+    const warning = relationOptionWarning(relationType, params, injected);
+    return `${unread.length ? `, ignoredOptions: ${jsLiteral(unread)}` : ''}${warning ? `, ${key}: ${jsLiteral(warning)}` : ''}${customOptionWarningJs(relationType, params, key, injected)}`;
+}
 /** The keys of `params` outside `keys`, named with a "did you mean" and the list that is read; null when all are read. */
 function unreadKeysWarning(reader, keys, params, injected = []) {
     if (!params || typeof params !== 'object')
@@ -1470,7 +1583,7 @@ 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((() => { const w = relationOptionWarning(relationType, params); return w ? `, warning: ${jsLiteral(w)}` : ''; })()) + " };\n})();\n").trim();
+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();
 }
 /**
  * The per-burst particle cap of the CURRENT studio (FxTool ParticleEmitter
@@ -1546,9 +1659,18 @@ export function normalizeEmitterSpec(spec, assumeDefaultCount = true) {
         for (const k of ['velocities', 'offsets'])
             if (out[k] !== undefined)
                 out[k] = pairs(out[k]);
+        // A trail's single offset is one pair; the studio reads [x, y] and dropped {x, y} with nothing said (TRAILOFF31).
+        const off = out.offset;
+        if (off && typeof off === 'object' && !Array.isArray(off) && typeof off.x === 'number' && typeof off.y === 'number')
+            out.offset = [off.x, off.y];
         return out;
     };
     const out = fix(spec);
+    // rate, start and end drive a trail. Beside bursts they drew nothing and said nothing (EMITCONT31).
+    const trailOnly = ['rate', 'start', 'end'].filter((k) => spec[k] !== undefined);
+    if (trailOnly.length && Array.isArray(spec.bursts) && spec.mode !== 'trail' && spec.target === undefined) {
+        warnings.push(`${trailOnly.join(', ')} ${trailOnly.length > 1 ? 'are' : 'is'} not read by a burst emitter, so ${trailOnly.length > 1 ? 'they had' : 'it had'} no effect: only the bursts' own count is drawn. For particles over time, add bursts, or use mode 'trail' with a target.`);
+    }
     if (Array.isArray(spec.bursts))
         out.bursts = spec.bursts.map((b) => (b && typeof b === 'object' ? fix(b) : b));
     // The studio's default count per burst (ParticleEmitter DEFAULT_LOOK).
@@ -1802,7 +1924,7 @@ const formatted = relations.map(r => ({
   // this tool even though it was wired correctly on the canvas.
   targetId: r.target ?? r.targetId ?? null,
   relationType: r.relation || r.type,
-  params: r.params || {}
+  params: ${RELATION_PUBLIC_PARAMS_JS}(r.params)
 }));
 
 ({ relations: formatted });
@@ -1822,7 +1944,7 @@ const relations = results.map(r => ({
   // the filter string labelled every edge 'unknown' on an unfiltered query —
   // which is exactly the query you make when exploring an unfamiliar graph.
   relationType: r.relation || ${relationType ? jsLiteral(relationType) : "'unknown'"},
-  params: r.params || {}
+  params: ${RELATION_PUBLIC_PARAMS_JS}(r.params)
 }));
 
 ({ relations });
@@ -1974,6 +2096,24 @@ function unanimatedTextKeysJs(keys) {
     return ${JSON.stringify(spec)}.filter(function(s) { return !s.names.some(function(n) { return __names.indexOf(n) >= 0; }); }).map(function(s) { return s.key; });
   })()`;
 }
+/**
+ * An image filter's parameter as a key: keyframe_animate stores it, and a filter does not read a track, so the item
+ * never changes with success:true (FILTKEY31). Asked of the same list, so a studio that starts animating one is believed.
+ */
+const FILTER_PARAM_KEYS = new Set([...Object.values(FILTER_PARAM_RANGES).flatMap((p) => Object.keys(p)), ...FILTER_TYPES].filter((k) => !['color', 'opacity', 'scale', 'x', 'y', 'rotation', 'size', 'radius', 'width', 'height', 'value', 'amount'].includes(k)));
+function unanimatedFilterKeysJs(keys) {
+    const filterKeys = [...new Set(keys)].filter((k) => FILTER_PARAM_KEYS.has(k));
+    if (!filterKeys.length)
+        return '[]';
+    return `(function() {
+    let __l = null;
+    try { __l = typeof app.listAnimatableProperties === 'function' ? app.listAnimatableProperties() : null; } catch (_) { __l = null; }
+    if (!__l || !__l.properties) return [];
+    const __names = __l.properties.map(function(p) { return p && p.name; });
+    return ${JSON.stringify(filterKeys)}.filter(function(k) { return __names.indexOf(k) < 0; });
+  })()`;
+}
+const UNANIMATED_FILTER_KEYS_SENTENCE = `' is an image filter setting and not an animatable property, so the key had no effect. Set a fixed value with pinepaper_image_filter or pinepaper_add_filter, and animate opacity or scale for a change over time.'`;
 /** The sentence for the keys unanimatedTextKeysJs found, built in the page. */
 const UNANIMATED_TEXT_KEYS_SENTENCE = `' is not an animatable property in this studio (app.listAnimatableProperties does not list it), so it had no effect: a key animates only where that list names it. Here, set a fixed value with pinepaper_modify_item, or animate fontSize or scaleX. For a skew, key skewX / skewY (degrees) where the studio lists them, else a transform matrix track.'`;
 /**
@@ -1999,12 +2139,6 @@ function keyframeResultNotes(keyframes, { loop = false, append = false, easingAt
         ? `, propertyGaps: ${JSON.stringify(gaps.slice(0, 10))}, gapWarning: ${JSON.stringify(`${gaps.length} keyframe(s) leave out a property other keys animate (${[...new Set(gaps.flatMap((g) => g.missing))].join(', ')}). The engine can break that property's track at such a key; repeat the value on every key — hold it by repeating the previous value.`)}`
         : '';
     const first = [...keyframes].sort((a, b) => a.time - b.time)[0];
-    // loop:true repeats in the editor; an export of the measured build played
-    // the keyframes ONCE and held (round 7, 2.24). Said where it is set, with
-    // the two ways that do export, until the engine's export clock wraps them.
-    const loopNote = loop
-        ? `, loopNote: ${JSON.stringify('loop:true repeats in the editor, but has been measured playing ONCE in an exported video and then holding the last keyframe. For an export longer than one cycle, check a frame in the second cycle — if it holds, write the keyframes out per cycle, or use a loop preset (pinepaper_animate), which does cycle in export.')}`
-        : '';
     // SIZEKEY-PAIR (mcp-cloud #28): on a studio before FxTool #262, x (or
     // position) keyed beside fontSize on one text item drifted in an export: the
     // size was applied after the position, and a text resizes around its anchor.
@@ -2016,7 +2150,7 @@ function keyframeResultNotes(keyframes, { loop = false, append = false, easingAt
     const easingNote = easingAt !== 'departure' && first?.easing && first.easing !== 'linear'
         ? `, note: ${JSON.stringify(`easing '${first.easing}' is on the first keyframe, where it has no effect by default: easing shapes the segment ARRIVING at a keyframe. Put it on the keyframe you are moving to, or pass easingAt: 'departure' to read every easing as the move LEAVING its key (current studio).`)}`
         : '';
-    return `${easingNote}${sizekeyPairNote}${loopNote}${gapNote}`;
+    return `${easingNote}${sizekeyPairNote}${gapNote}`;
 }
 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
@@ -2074,9 +2208,12 @@ String(JSON.stringify(levelKeys)) +
     const textKeyCheck = textKeysJs ? `
   const __ignored = ${textKeysJs};
   if (__ignored.length) __warn.push(__ignored.join(', ') + ${UNANIMATED_TEXT_KEYS_SENTENCE});` : '';
+    const filterKeyCheck = `
+  const __filterIgnored = ${unanimatedFilterKeysJs(keyframes.flatMap((k) => Object.keys(k.properties ?? {})))};
+  if (__filterIgnored.length) __warn.push(__filterIgnored.join(', ') + ${UNANIMATED_FILTER_KEYS_SENTENCE});`;
     const easingAtCheck = easingAt !== undefined ? `
   if (__opts && Object.prototype.hasOwnProperty.call(__opts, 'easingAt')) __warn.push('easingAt ' + ${JSON.stringify(JSON.stringify(easingAt))} + ' was not applied: this studio predates it, so every easing was read as the move ARRIVING at its key. Put each easing on the key the move goes to instead.');` : '';
-    const runtimeWarning = `${textKeysJs ? ', ...(__ignored.length ? { ignoredProperties: __ignored } : {})' : ''}, ...(__warn.length ? { warning: __warn.join(' ') } : {})`;
+    const runtimeWarning = `, ...(${textKeysJs ? '__ignored.length || ' : ''}__filterIgnored.length ? { ignoredProperties: ${textKeysJs ? '__ignored.concat(__filterIgnored)' : '__filterIgnored'} } : {}), ...(__warn.length ? { warning: __warn.join(' ') } : {})`;
     const addAnimTarget = itemId.startsWith('$') ? '_targetId' : `${ID}`;
     return ("\n// Apply keyframe animation to " +
 String(ID) +
@@ -2092,6 +2229,7 @@ String(keyframesJson) +
 ", __opts);\n  const __warn = [];" +
 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
@@ -2111,8 +2249,7 @@ 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();
+", ...(__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
@@ -2246,6 +2383,29 @@ function withRadiusAxes(props) {
         out.height = radiusY * 2;
     return out;
 }
+/**
+ * One get_items entry. What create applied is read back here, so an agent can check it: the name a patch addresses
+ * the item by, and scale, rotation and opacity when they are not the default (CROWSCALE30: a create-time scale
+ * rendered exactly and get_items did not show it; PATCHIMG29: an import's name was not shown either). Defaults are
+ * left out, so a plain item's entry stays as small as before.
+ */
+const GET_ITEMS_ENTRY_JS = ("entry => {\n  const it = entry.item || {};\n  const out = {\n    id: entry.id || entry.itemId,\n    type: entry.type,\n    position: it.position ? { x: it.position.x, y: it.position.y } : null,\n    hasAnimation: !!((it.data?.animationType && it.data.animationType !== 'none') || (Array.isArray(it.data?.keyframes) && it.data.keyframes.length > 0)),\n    relations: app.getRelations(entry.id || entry.itemId).map(r => r.relation || r.type)\n  };\n  const name = it.name || entry.name || (it.data && it.data.name);\n  if (name) out.name = name;\n  const r2 = (v) => Math.round(v * 1000) / 1000;\n  if (it.scaling && (Math.abs(it.scaling.x - 1) > 1e-6 || Math.abs(it.scaling.y - 1) > 1e-6)) out.scale" +
+" = { x: r2(it.scaling.x), y: r2(it.scaling.y) };\n  if (typeof it.rotation === 'number' && Math.abs(it.rotation) > 1e-6) out.rotation = r2(it.rotation);\n  if (typeof it.opacity === 'number' && it.opacity !== 1) out.opacity = r2(it.opacity);\n  return out;\n}"
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+);
 function generateGetItemsCode(filter) {
     // A filter OBJECT is not the same as a filter. `{}` is already handled, but
     // so is `{ type: undefined }` and anything whose keys this function does not
@@ -2270,13 +2430,7 @@ function generateGetItemsCode(filter) {
         return `
 // Get all items
 const entries = app.itemRegistry.getAll();
-const items = entries.map(entry => ({
-  id: entry.id || entry.itemId,
-  type: entry.type,
-  position: entry.item.position ? { x: entry.item.position.x, y: entry.item.position.y } : null,
-  hasAnimation: !!((entry.item.data?.animationType && entry.item.data.animationType !== 'none') || (Array.isArray(entry.item.data?.keyframes) && entry.item.data.keyframes.length > 0)),
-  relations: app.getRelations(entry.id || entry.itemId).map(r => r.relation || r.type)
-}));
+const items = entries.map(${GET_ITEMS_ENTRY_JS});
 
 ({ items, count: items.length });
 `.trim();
@@ -2285,13 +2439,7 @@ const items = entries.map(entry => ({
 // Get items with filter
 const entries = app.itemRegistry.getAll();
 const filtered = entries.filter(entry => ${conditions.join(' && ')});
-const items = filtered.map(entry => ({
-  id: entry.id || entry.itemId,
-  type: entry.type,
-  position: entry.item.position ? { x: entry.item.position.x, y: entry.item.position.y } : null,
-  hasAnimation: !!((entry.item.data?.animationType && entry.item.data.animationType !== 'none') || (Array.isArray(entry.item.data?.keyframes) && entry.item.data.keyframes.length > 0)),
-  relations: app.getRelations(entry.id || entry.itemId).map(r => r.relation || r.type)
-}));
+const items = filtered.map(${GET_ITEMS_ENTRY_JS});
 
 ({ items, count: items.length });
 `.trim();
@@ -2542,7 +2690,12 @@ function generateClearCanvasCode() {
 String(MEDIA_PURGE) +
 "\n\nif (typeof app.clearCanvas === 'function') {\n  app.clearCanvas();\n} else {\n  // Fallback for older builds without clearCanvas().\n  if (app.textItemGroup) app.textItemGroup.removeChildren();\n  if (app.patternGroup) app.patternGroup.removeChildren();\n  if (app.itemRegistry) app.itemRegistry.clear();\n  if (app.relationRegistry) app.relationRegistry.clear();\n}\n" +
 String(ID_COUNTER_RESET) +
-"\n\nif (app.historyManager) app.historyManager.saveState();\n\nconst remaining = app.itemRegistry ? app.itemRegistry.getAll().length : 0;\n\n({ success: true, removedCount: Math.max(0, before - remaining), remainingItems: remaining, mediaRemoved: __mediaRemoved });\n"
+"\n// A rule outlives app.clearCanvas, and would go on running in the next scene against its item ids.\nlet __rulesRemoved = 0;\nif (typeof app.listContraptions === 'function' && typeof app.removeContraption === 'function') {\n  app.listContraptions().map((c) => c.id).forEach((id) => { if (app.removeContraption(id)) __rulesRemoved++; });\n}\n\nif (app.historyManager) app.historyManager.saveState();\n\nconst remaining = app.itemRegistry ? app.itemRegistry.getAll().length : 0;\n\n({ success: true, ...(__rulesRemoved ? { contraptionsRemoved: __rulesRemoved } : {}), removedCount: Math.max(0, before - remaining), remainingItems: remaining, mediaRemoved: __mediaRemoved });\n"
+
+
+
+
+
 
 
 
@@ -3440,7 +3593,7 @@ String(JSON.stringify(validated.presetId)) +
         const code = stepNoTarget
             ? `(function() {
   if (!${STEP_ACTIVE_TARGETLESS_JS}) return { success: false, relationType: 'on_event_step_active', error: ${jsLiteral(stepNoTarget)} };
-  return ${built.trim().replace(/;$/, '')};
+  ${asReturningBody(built)}
 })();`
             : built;
         // NO TARGET (event reactions like on_event_play_sound, self-relations): the
@@ -4120,7 +4273,7 @@ if (typeof _gen === 'function') {
 })();`);
         }
         // Establish relations
-        for (const relation of relations) {
+        for (const [relationIndex, relation] of relations.entries()) {
             const { source, target, type, params = {} } = relation;
             const paramsStr = JSON.stringify(params);
             const specProblem = relationSpecProblem(type, params, target, 'no-page');
@@ -4150,7 +4303,10 @@ String(jsLiteral(type)) +
 String(jsLiteral(source)) +
 ", target: " +
 String(jsLiteral(target)) +
-", type: " + String(jsLiteral(type)) + " });\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"));
+", type: " +
+String(jsLiteral(type)) +
+" });\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
         for (const animation of animations) {
@@ -5120,7 +5276,7 @@ const targetId = ${animItemRef};
 const item = app.getItemById(targetId);
 if (!item) throw new Error('Item not found: ' + targetId);
 app.animate(item, { animationType: ${JSON.stringify(String(op.animationType))}, ...${animOpts} });
-return { itemId: targetId, animationType: ${JSON.stringify(String(op.animationType))}${(() => { const w = animationOptionWarning(op.animationOptions); return w ? `, warning: ${jsLiteral(w)}` : ''; })()} };
+return { itemId: targetId, animationType: ${JSON.stringify(String(op.animationType))}${(() => { const w = animationOptionWarning(op.animationOptions); return w ? `, ignoredOptions: ${jsLiteral(unreadKeys(ANIMATION_OPTION_KEYS, op.animationOptions))}, warning: ${jsLiteral(w)}` : ''; })()} };
 `;
             case 'relation':
                 const srcRef = batchRef(op.sourceId);
@@ -5181,7 +5337,7 @@ String(type) +
 ", sourceIds: __failed, error: " +
 String(op.update === true ? '__why' : `'the studio refused the ' + ${type} + ' relation for ' + __failed.join(', ') + ' — nothing was bound' + (__why ? ': ' + __why : '.')`) +
 " };\n}\nreturn { success: true, relationType: " +
-String(type) + ", " + String(op.update === true ? 'updated' : 'bound') + ": __done, targetId" + String(glob ? ', count: __members.length' : '') + String((() => { const w = relationOptionWarning(op.relationType, op.relationOptions, ['index', 'count', 'pattern']); return w ? `, optionWarning: ${jsLiteral(w)}` : ''; })()) + ", ...(__failed.length ? { failed: __failed, warning: __failed.length + ' of ' + __members.length + ' were not " + String(op.update === true ? 'changed' : 'bound') + ": ' + __failed.join(', ') } : {}) };\n");
+String(type) + ", " + String(op.update === true ? 'updated' : 'bound') + ": __done, targetId" + String(glob ? ', count: __members.length' : '') + String(relationOptionFields(op.relationType, op.relationOptions, 'optionWarning', ['index', 'count', 'pattern'])) + ", ...(__failed.length ? { failed: __failed, warning: __failed.length + ' of ' + __members.length + ' were not " + String(op.update === true ? 'changed' : 'bound') + ": ' + __failed.join(', ') } : {}) };\n");
                 }
                 return ("\n" +
 String(stepGuard) +
@@ -5200,7 +5356,7 @@ 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 = " +
 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((() => { const w = relationOptionWarning(op.relationType, op.relationOptions); return w ? `, warning: ${jsLiteral(w)}` : ''; })()) + " };\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}\nreturn { relationId, sourceId, targetId, relationType: " + String(JSON.stringify(String(op.relationType))) + String(relationOptionFields(op.relationType, op.relationOptions, 'warning')) + " };\n");
             case 'delete':
                 const delRef = batchRef(op.itemId);
                 return `
@@ -5288,8 +5444,9 @@ return { itemId: ${batchRef(op.itemId)}, merged: true, mergedInto: ${foldTarget}
                     kfExtra.push(`timeUnits: ${jsLiteral(kfUnits)}`);
                 const kfExtraStr = kfExtra.length > 0 ? `, ${kfExtra.join(', ')}` : '';
                 const kfTextKeysJs = unanimatedTextKeysJs((kfSource || []).flatMap((k) => Object.keys(k.properties ?? {})));
-                const kfTextCheck = kfTextKeysJs ? `\nconst _kfIgnored = ${kfTextKeysJs};` : '';
-                const kfIgnored = kfTextKeysJs ? `, ...(_kfIgnored.length ? { ignoredProperties: _kfIgnored, warning: _kfIgnored.join(', ') + ${UNANIMATED_TEXT_KEYS_SENTENCE} } : {})` : '';
+                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, " +
@@ -5429,7 +5586,7 @@ 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, 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, motionBlur, ad: adOpts, frames, startTime } = validated;
         // 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
@@ -5451,8 +5608,13 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
             videoEncodeOpts.minBitrate = minBitrate;
         if (bitrateMode !== undefined)
             videoEncodeOpts.bitrateMode = bitrateMode;
-        // Byte-identical repeats (FxTool 3b335567): the container timestamps are
-        // the only bytes that varied, and this pins them.
+        // B45 (FxTool #288): 'aac' makes the studio refuse an MP4 whose soundtrack would be Opus (code
+        // audio_codec_unavailable) rather than write a file WhatsApp rejects. 'any' is the engine's default, so not sent.
+        if (audioCodec === 'aac')
+            videoEncodeOpts.audioCodec = 'aac';
+        // Determinism (B31, the contract signed off in FxTool #290): identical encoder
+        // input and a container identical apart from the encoded samples; the file
+        // itself repeats only where the studio reports bitExact: true.
         if (deterministic)
             videoEncodeOpts.deterministic = true;
         // Motion blur (FxTool #55): the engine forwards it on every mp4/webm path
@@ -6086,9 +6248,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        message: 'deterministic was asked for, but no encoder on this machine repeats byte for byte at this size (the studio test-encoded and checked): the pixels may differ slightly between runs. Do not cache this file by hash; a different frame size may repeat.' }]);\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.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 r" +
-"uns 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.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"
+
 
 
 
@@ -6174,9 +6337,14 @@ String((() => {
 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) +
-" has no camera frame, so they do not stay fixed under the camera move. Export mp4, webm, gif or png to keep them fixed.' }]);\n      }\n    } catch (_) { /* the export stands */ }\n  }\n  // WHICH STUDIO MADE THIS FILE (D92): a service worker can serve a stale\n  // build right after a deploy, and a retest then judges old code. The\n  // engine's own identity, version + build sha, rides on every export reply.\n  try { if (result && typeof result === 'object' && app.buildId) result.studioBuild = app.buildId; } catch (_) { /* older studio */ }\n  // A STALE STUDIO (D92): the file was made by an old build. Said in the\n  // fidelity warnings the reply shows, not only as a field.\n  try {\n   " +
-" const __bs = app.buildStatus ? app.buildStatus() : null;\n    if (result && typeof result === 'object' && __bs) {\n      result.liveBuild = __bs.liveBuildId;\n      if (__bs.stale) {\n        result.stale = true;\n        result.fidelity = result.fidelity || { warnings: [] };\n        result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'stale_build', message: 'this studio is running an old build (' + __bs.buildId + '; the live build is ' + __bs.liveBuildId + '): this file was made by the old code, so it may differ from what the live build makes. pinepaper_clear_canvas (or pinepaper_agent_start_job) loads the live build; it empties the canvas, so rebuild the scene a" +
-"nd export again if the difference matters.' }]);\n      }\n    }\n  } catch (_) { /* older studio */ }\n  // RELIGHT (FxTool D5): applied to png / pdf / mp4 / webm, not gif / apng\n  // or the vector formats; and it is what makes a video export slow.\n  if (result && result.success && typeof app.getRelight === 'function') {\n    try {\n      const __rl = app.getRelight();\n      if (__rl && __rl.enabled) {\n        result.fidelity = result.fidelity || { warnings: [] };\n        if (['png', 'jpg', 'webp', 'pdf', 'mp4', 'webm'].indexOf(" +
+" has no camera frame, so they do not stay fixed under the camera move. Export mp4, webm, gif or png to keep them fixed.' }]);\n      }\n    } catch (_) { /* the export stands */ }\n  }\n  // A SOUND PAST THE END (SNDTAIL31): placed, accepted, and not in the file. The video's length decides, as it should; it is said.\n  if (result && result.success && ['mp4', 'webm'].indexOf(" +
+String(JSON.stringify(format)) +
+") !== -1 && app.itemRegistry && typeof app.itemRegistry.getAll === 'function') {\n    try {\n      const __end = (result.video && result.video.durationS) || " +
+String(JSON.stringify(duration ?? null)) +
+";\n      const __late = __end ? app.itemRegistry.getAll().filter(function (e) { const d = (e.item || e).data; return d && d.isSoundChip && typeof d.clipStartTime === 'number' && d.clipStartTime >= __end; }) : [];\n      if (__late.length) {\n        result.fidelity = result.fidelity || { warnings: [] };\n        result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'sound_after_end', message: __late.length + ' sound(s) start at or after the end of this ' + __end + ' s export, so they are not in the file: ' + __late.map(function (e) { return (e.item || e).data.registryId + ' at ' + (e.item || e).data.clipStartTime + ' s'; }).slice(0, 10).join(', ') + '.' }]);\n      }" +
+"\n    } catch (_) { /* the export stands */ }\n  }\n  // WHICH STUDIO MADE THIS FILE (D92): a service worker can serve a stale\n  // build right after a deploy, and a retest then judges old code. The\n  // engine's own identity, version + build sha, rides on every export reply.\n  try { if (result && typeof result === 'object' && app.buildId) result.studioBuild = app.buildId; } catch (_) { /* older studio */ }\n  // A STALE STUDIO (D92): the file was made by an old build. Said in the\n  // fidelity warnings the reply shows, not only as a field.\n  try {\n    const __bs = app.buildStatus ? app.buildStatus() : null;\n    if (result && typeof result === 'object' && __bs) {\n      result.liveB" +
+"uild = __bs.liveBuildId;\n      if (__bs.stale) {\n        result.stale = true;\n        result.fidelity = result.fidelity || { warnings: [] };\n        result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'stale_build', message: 'this studio is running an old build (' + __bs.buildId + '; the live build is ' + __bs.liveBuildId + '): this file was made by the old code, so it may differ from what the live build makes. pinepaper_clear_canvas (or pinepaper_agent_start_job) loads the live build; it empties the canvas, so rebuild the scene and export again if the difference matters.' }]);\n      }\n    }\n  } catch (_) { /* older studio */ }\n  // RELIGHT (FxTool D5): appl" +
+"ied to png / pdf / mp4 / webm, not gif / apng\n  // or the vector formats; and it is what makes a video export slow.\n  if (result && result.success && typeof app.getRelight === 'function') {\n    try {\n      const __rl = app.getRelight();\n      if (__rl && __rl.enabled) {\n        result.fidelity = result.fidelity || { warnings: [] };\n        if (['png', 'jpg', 'webp', 'pdf', 'mp4', 'webm'].indexOf(" +
 String(JSON.stringify(format)) +
 ") === -1) {\n          result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'relight_not_applied', message: 'a relight rig is set, but ' + " +
 String(jsLiteral(format)) +
@@ -7221,6 +7389,13 @@ String(jsLiteral(format)) +
 
 
 
+
+
+
+
+
+
+
 
 
 
@@ -8840,7 +9015,7 @@ String(validated.priority || 0) +
 "\n    });\n    // The definition as given, kept on the page so a later call can read it back (pinepaper_lint_scene\n    // customRelations): the engine keeps the compiled rule, not the text an agent would edit.\n    window.__ppCustomRelations = window.__ppCustomRelations || {};\n    window.__ppCustomRelations[" +
 String(jsLiteral(validated.name)) +
 "] = " +
-String(jsLiteral({ name: validated.name, ...(validated.description ? { description: validated.description } : {}), params: validated.params ?? {}, computeFunction: validated.computeFunction, applyFunction: validated.applyFunction })) +
+String(jsLiteral({ name: validated.name, ...(validated.description ? { description: validated.description } : {}), params: validated.params ?? {}, computeFunction: validated.computeFunction, applyFunction: validated.applyFunction, reads: customRelationReads(validated.params, validated.computeFunction, validated.applyFunction) })) +
 ";\n    return { success: true, relationName: " +
 String(jsLiteral(validated.name)) +
 ", message: 'Custom relation registered successfully' };\n  } catch (error) {\n    return { success: false, error: error.message };\n  }\n})();\n"
@@ -9232,7 +9407,9 @@ String(jsLiteral(templateId)) +
 ).trim();
     }
     generateImportImage(input) {
-        const { url, position, maxWidth, maxHeight, mask, smoothing, maxEdge, nativeSize, shadowColor, shadowBlur, shadowOffset, name } = input;
+        const { url, position, maxWidth, maxHeight, mask, smoothing, maxEdge, nativeSize, shadowColor, shadowBlur, shadowOffset, name, opacity, blendMode, scale, loop } = input;
+        const look = { ...(opacity !== undefined ? { opacity } : {}), ...(blendMode !== undefined ? { blendMode } : {}), ...(scale !== undefined ? { scale } : {}) };
+        const hasLook = Object.keys(look).length > 0;
         // IMPORTSHADOW: the shadow keys, applied through the engine's own modify
         // door once the image is placed (and masked) — the route modify_item takes.
         const shadow = {};
@@ -9254,6 +9431,7 @@ String(jsLiteral(templateId)) +
             maxWidth !== undefined ? `maxWidth: ${maxWidth}` : '',
             maxHeight !== undefined ? `maxHeight: ${maxHeight}` : '',
             nativeSize ? 'nativeSize: true' : '',
+            loop !== undefined ? `loop: ${JSON.stringify(loop)}` : '',
         ].filter(Boolean);
         const optsLiteral = optParts.length ? `{ ${optParts.join(', ')} }` : '{}';
         return ("\n// Import image from URL\n(async function() {\n  if (!app.imageTools) {\n    return { error: 'Image tools not available. Make sure PinePaper Studio is loaded.' };\n  }\n  try {\n    // FETCH IT OURSELVES FIRST, to find out WHY when it fails.\n    //\n    // uploadFromURL sets img.src and rejects with a bare \"Failed to load image\n    // from URL\" — an <img> onerror genuinely carries no reason, so that message\n    // is the browser's limit rather than the engine being unhelpful. fetch()\n    // has the reason: a status code, a CORS rejection, a refused connection, a\n    // DNS failure. A caller cannot debug what the tool will not show them.\n    //\n    // The bytes then go in as a DA" +
@@ -9285,6 +9463,16 @@ String(mask ? `    // A MASK REPLACES THE RASTER (round 8 DD, 4.10). applyMask b
     if (app.itemRegistry && typeof app.itemRegistry.rebind === 'function') app.itemRegistry.rebind(itemId, masked);
     placed = masked;
 ` : '') +
+String(hasLook ? `    // opacity, blendMode, scale: read by modify, on what is drawn. They were not import arguments (OPACIMP31, BLENDIMP31, IMGSCALE31).
+    let __look = null;
+    {
+      let __ok = false;
+      try { __ok = app.modifyItem(itemId, ${JSON.stringify(look)}) !== false; } catch (_) { __ok = false; }
+      __look = __ok
+        ? { applied: true, opacity: placed.opacity, blendMode: placed.blendMode }
+        : { applied: false, warning: 'the image was imported but ' + ${jsLiteral(Object.keys(look).join(', '))} + ' was not applied: set it with pinepaper_modify_item on ' + itemId + '.' };
+    }
+` : '') +
 String(hasShadow ? `    // The shadow goes on what is DRAWN, after a mask has replaced the raster.
     let __shadow = null;
     {
@@ -9307,6 +9495,8 @@ 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(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"
 
@@ -9398,6 +9588,12 @@ String(hasShadow ? ',\n      shadow: __shadow' : '') +
 
 
 
+
+
+
+
+
+
 
 
 
@@ -12761,16 +12957,20 @@ String(diagJson) +
 String(optsJson) +
 ");\n  // THE RELATIONS AS BOUND, so a later agent can find the one to edit without exporting the scene to read it:\n  // from, to, type and params, capped. And the custom relation definitions registered on this page, as given.\n  const __rels = [];\n  let __relCount = 0;\n  try {\n    const __rr = app.relationRegistry;\n    const __active = __rr && typeof __rr.queryActive === 'function' ? __rr.queryActive() : [];\n    __active.forEach((e) => (e.associations || []).forEach((a) => {\n      __relCount++;\n      if (__rels.length >= " +
 String(RELATIONS_READBACK_CAP) +
-") return;\n      const __name = e.item && e.item.data && e.item.data.name;\n      __rels.push({ from: e.itemId, ...(__name ? { fromName: __name } : {}), to: a.target === undefined ? null : a.target, type: a.relation, params: a.params || {} });\n    }));\n  } catch (e) { /* the relations are an addition; the lint stands without them */ }\n  // CUSTOM RELATIONS THIS SCENE USES (#43): one registered before a clear_canvas stayed in the read-back of the scene\n  // after it. Those in use are listed; the rest are named in registeredUnused. Their source (computeFunction /\n  // applyFunction) only with withSource: true, since an edit of params never needs it.\n  const __usedTypes = new Set();\n  " +
-"try { const __rr2 = app.relationRegistry; (__rr2 && typeof __rr2.queryActive === 'function' ? __rr2.queryActive() : []).forEach((e) => (e.associations || []).forEach((a) => __usedTypes.add(a.relation))); } catch (e) { /* none known */ }\n  const __allCustom = (typeof window !== 'undefined' && window.__ppCustomRelations) ? Object.values(window.__ppCustomRelations) : [];\n  const __strip = (d) => { if (" +
+") return;\n      const __name = e.item && e.item.data && e.item.data.name;\n      __rels.push({ from: e.itemId, ...(__name ? { fromName: __name } : {}), to: a.target === undefined ? null : a.target, type: a.relation, params: " +
+String(RELATION_PUBLIC_PARAMS_JS) +
+"(a.params) });\n    }));\n  } catch (e) { /* the relations are an addition; the lint stands without them */ }\n  // CUSTOM RELATIONS THIS SCENE USES (#43): one registered before a clear_canvas stayed in the read-back of the scene\n  // after it. Those in use are listed; the rest are named in registeredUnused. Their source (computeFunction /\n  // applyFunction) only with withSource: true, since an edit of params never needs it.\n  const __usedTypes = new Set();\n  try { const __rr2 = app.relationRegistry; (__rr2 && typeof __rr2.queryActive === 'function' ? __rr2.queryActive() : []).forEach((e) => (e.associations || []).forEach((a) => __usedTypes.add(a.relation))); } catch (e) { /* none kno" +
+"wn */ }\n  const __allCustom = (typeof window !== 'undefined' && window.__ppCustomRelations) ? Object.values(window.__ppCustomRelations) : [];\n  const __strip = (d) => { if (" +
 String(input.withSource === true ? 'true' : 'false') +
 ") return d; const o = Object.assign({}, d); delete o.computeFunction; delete o.applyFunction; return o; };\n  const __custom = __allCustom.filter((d) => __usedTypes.has(d.name)).map(__strip);\n  const __unusedCustom = __allCustom.filter((d) => !__usedTypes.has(d.name)).map((d) => d.name);\n  // HOW TO CHANGE IT (#43): an editing agent needs the op, not the schemas. Each relation comes with the batch op that\n  // changes it; a group bound by a name pattern (\"dot-*\", recorded in each member's params) comes once, with the ops\n  // that add and remove a member; a custom motion with the call that redefines it.\n  const __edit = { hint: 'To change this scene, send the ops below (your values " +
-"in relationOptions) in ONE pinepaper_agent_batch_execute call; a custom motion changes by sending its pinepaper_register_custom_relation call again.', groups: [], relations: [], customRelations: [] };\n  try {\n    const __byPat = new Map();\n    __rels.forEach((r) => {\n      const pat = r.params && r.params.pattern;\n      if (typeof pat === 'string') {\n        const k = pat + '|' + r.type + '|' + r.to;\n        if (!__byPat.has(k)) __byPat.set(k, { pattern: pat, type: r.type, to: r.to, members: [] });\n        __byPat.get(k).members.push(r);\n        return;\n      }\n      __edit.relations.push({ from: r.from, ...(r.fromName ? { fromName: r.fromName } : {}), to: r.to, relationType: r." +
-"type,\n        change: { type: 'relation', sourceId: r.fromName || r.from, ...(r.to != null ? { targetId: r.to } : {}), relationType: r.type, update: true, relationOptions: r.params } });\n    });\n    __byPat.forEach((g) => {\n      const base = Object.assign({}, g.members[0].params); delete base.index; delete base.count; delete base.pattern;\n      const names = g.members.map((m) => m.fromName).filter(Boolean).sort((a, b) => a.localeCompare(b, undefined, { numeric: true }));\n      const prefix = g.pattern.split('*')[0];\n      const nums = names.map((n) => Number(n.slice(prefix.length))).filter((n) => Number.isFinite(n));\n      const next = prefix + (nums.length ? Math.max.apply(null, " +
-"nums) + 1 : g.members.length + 1);\n      const firstEntry = app.itemRegistry.get(g.members[0].from);\n      const bind = { type: 'relation', sourceId: g.pattern, ...(g.to != null ? { targetId: g.to } : {}), relationType: g.type, relationOptions: base };\n      __edit.groups.push({ pattern: g.pattern, relationType: g.type, members: g.members.length, ...(names.length ? { first: names[0], last: names[names.length - 1] } : {}), relationOptions: base,\n        change: Object.assign({}, bind, { update: true }),\n        addMember: [{ type: 'create', itemType: (firstEntry && firstEntry.type) || 'circle', position: [0, 0], properties: { name: next } }, bind],\n        ...(names.length ? { removeM" +
-"ember: [{ type: 'delete', itemId: names[names.length - 1] }, bind] } : {}) });\n    });\n    __custom.forEach((d) => __edit.customRelations.push({ name: d.name, change: { tool: 'pinepaper_register_custom_relation', args: d } }));\n  } catch (e) { /* the read-back stands without the edit ops */ }\n  if (!" +
+"in relationOptions) in ONE pinepaper_agent_batch_execute call; a custom motion changes by sending its pinepaper_register_custom_relation call again (withSource: true gives the complete call).', groups: [], relations: [], customRelations: [] };\n  try {\n    const __byPat = new Map();\n    __rels.forEach((r) => {\n      const pat = r.params && r.params.pattern;\n      if (typeof pat === 'string') {\n        const k = pat + '|' + r.type + '|' + r.to;\n        if (!__byPat.has(k)) __byPat.set(k, { pattern: pat, type: r.type, to: r.to, members: [] });\n        __byPat.get(k).members.push(r);\n        return;\n      }\n      __edit.relations.push({ from: r.from, ...(r.fromName ? { fromName: r.f" +
+"romName } : {}), to: r.to, relationType: r.type,\n        change: { type: 'relation', sourceId: r.fromName || r.from, ...(r.to != null ? { targetId: r.to } : {}), relationType: r.type, update: true, relationOptions: r.params } });\n    });\n    __byPat.forEach((g) => {\n      const base = Object.assign({}, g.members[0].params); delete base.index; delete base.count; delete base.pattern;\n      const names = g.members.map((m) => m.fromName).filter(Boolean).sort((a, b) => a.localeCompare(b, undefined, { numeric: true }));\n      const prefix = g.pattern.split('*')[0];\n      const nums = names.map((n) => Number(n.slice(prefix.length))).filter((n) => Number.isFinite(n));\n      const next = pr" +
+"efix + (nums.length ? Math.max.apply(null, nums) + 1 : g.members.length + 1);\n      const firstEntry = app.itemRegistry.get(g.members[0].from);\n      const bind = { type: 'relation', sourceId: g.pattern, ...(g.to != null ? { targetId: g.to } : {}), relationType: g.type, relationOptions: base };\n      __edit.groups.push({ pattern: g.pattern, relationType: g.type, members: g.members.length, ...(names.length ? { first: names[0], last: names[names.length - 1] } : {}), relationOptions: base,\n        change: Object.assign({}, bind, { update: true }),\n        addMember: [{ type: 'create', itemType: (firstEntry && firstEntry.type) || 'circle', position: [0, 0], properties: { name: next } }, b" +
+"ind],\n        ...(names.length ? { removeMember: [{ type: 'delete', itemId: names[names.length - 1] }, bind] } : {}) });\n    });\n    // The register call requires its source, so without withSource there is no call to offer: an op that can only be\n    // refused is not one to send. reads is the server's own working-out from that source, not an argument of the call.\n    __custom.forEach((d) => {\n      const args = Object.assign({}, d); delete args.reads;\n      __edit.customRelations.push(" +
+String(input.withSource === true ? "{ name: d.name, change: { tool: 'pinepaper_register_custom_relation', args } }" : "args") +
+");\n    });\n  } catch (e) { /* the read-back stands without the edit ops */ }\n  if (!" +
 String(input.withSource === true ? 'true' : 'false') +
-" && __custom.length) __edit.customHint = 'custom relation source is left out; pass withSource: true to read the current computeFunction / applyFunction before rewriting one.';\n  // A GROUP IS LISTED ONCE (#43): members bound by a name pattern repeated the same relation once per item in\n  // `relations`; they are in edit.groups, and counted here.\n  const __loose = __rels.filter((r) => !(r.params && typeof r.params.pattern === 'string'));\n  const __grouped = __rels.length - __loose.length;\n  const __editOut = __edit.groups.length || __edit.relations.length || __edit.customRelations.length ? { edit: __edit } : {};\n  if (" +
+" && __custom.length) __edit.customHint = 'custom relations are listed without their source, and the call that redefines one needs it: pass withSource: true to get each complete pinepaper_register_custom_relation call.';\n  // A GROUP IS LISTED ONCE (#43): members bound by a name pattern repeated the same relation once per item in\n  // `relations`; they are in edit.groups, and counted here.\n  const __loose = __rels.filter((r) => !(r.params && typeof r.params.pattern === 'string'));\n  const __grouped = __rels.length - __loose.length;\n  const __editOut = __edit.groups.length || __edit.relations.length || __edit.customRelations.length ? { edit: __edit } : {};\n  if (" +
 String(input.only === 'edit' ? 'true' : 'false') +
 ") {\n    return Object.assign({ success: true }, __editOut.edit ? __editOut : { edit: { hint: 'nothing to change: this scene binds no relations.' } },\n      __unusedCustom.length ? { registeredUnused: __unusedCustom } : {});\n  }\n  // warnings: what the engine's own rules found (TEXT_CLIPS_FRAME: a centre-anchored text running past the\n  // frame edge). Passed through when the studio reports them; an older studio has none to pass.\n  return { success: true, density: result.density, suggestions: result.suggestions,\n    ...(Array.isArray(result.warnings) && result.warnings.length ? { warnings: result.warnings } : {}),\n    relations: __loose, ...(__grouped ? { groupedRelations: __grouped" +
 ", groupedNote: 'relations bound by a name pattern are listed once per group in edit.groups' } : {}),\n    ...(__relCount > __rels.length ? { relationsShown: __rels.length, relationCount: __relCount } : {}),\n    ...(__custom.length ? { customRelations: __custom } : {}),\n    ...(__unusedCustom.length ? { registeredUnused: __unusedCustom } : {}),\n    ...__editOut };\n})();"
@@ -12836,6 +13036,7 @@ String(input.only === 'edit' ? 'true' : 'false') +
 
 
 
+
 
 
 ).trim();
@@ -13385,7 +13586,7 @@ String(id) +
 String(id) +
 ", beats: " +
 String(input.beats.length) +
-", keyframes: __r.keyframes.length, duration: __r.end, final: __r.final };\n" +
+", keyframes: __r.keyframes.length, duration: __r.end, final: __r.final, ...(__r.defaultsUsed ? { defaultsUsed: __r.defaultsUsed } : {}) };\n" +
 String(input.sound ? ("  // SOUND ON THE ACTION (D68): one placed sound per moment the motion makes —\n  // pop, launch, contact, shake — loud as the moment is strong. A sound that\n  // does not place is reported; it never undoes the motion.\n  const __map = Object.assign({ pop: 'pop', whoosh: 'whoosh', contact: 'tom', shake: 'hat' }, " +
 String(S(typeof input.sound === 'object' ? Object.fromEntries(Object.entries(input.sound).filter(([k]) => k !== 'gain')) : {})) +
 ");\n  const __gain = " +
@@ -16094,6 +16295,8 @@ String(op) +
   return { success: true, action: 'create', eventId${input.at !== undefined ? `, at: ${JSON.stringify(input.at)}` : ''} };
 })();`.trim();
         }
+        if (input.action !== 'pulse')
+            return generateContraptionCode(input);
         // pulse — a runtime fire, not a scene edit (no history save)
         const eventIdJson = JSON.stringify(input.eventId);
         const payloadJson = JSON.stringify(input.payload ?? null);
@@ -16108,6 +16311,78 @@ String(op) +
 })();`.trim();
     }
 }
+/**
+ * Rules, variables and bound text (the studio's contraption engine). Each action asks for the method it calls, so a
+ * studio without it refuses by name instead of a TypeError. The engine's custom action is not offered: it needs a
+ * function, which JSON cannot carry.
+ */
+function generateContraptionCode(input) {
+    const refuse = (method) => `if (typeof app.${method} !== 'function') {
+    return { success: false, action: ${jsLiteral(input.action)}, error: 'this studio has no contraption engine (app.${method}): update PinePaper Studio' };
+  }`;
+    const scope = jsLiteral(input.scope ?? 'default');
+    const key = jsLiteral(input.key ?? '');
+    const body = () => {
+        switch (input.action) {
+            case 'add_contraption': {
+                const targets = [...new Set((input.actions ?? []).flatMap((a) => ('targetId' in a ? [a.targetId] : [])))];
+                const config = {
+                    ...(input.contraptionId ? { id: input.contraptionId } : {}),
+                    sourceEvent: input.sourceEvent,
+                    actions: input.actions,
+                    ...(input.condition ? { condition: input.condition } : {}),
+                    ...(input.thenTrigger ? { thenTrigger: input.thenTrigger } : {}),
+                    ...(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' } : {}), };`;
+            }
+            case 'remove_contraption':
+                return `${refuse('removeContraption')}
+  const removed = app.removeContraption(${jsLiteral(input.contraptionId)});
+  return removed ? { success: true, action: 'remove_contraption', contraptionId: ${jsLiteral(input.contraptionId)} }
+    : { success: false, action: 'remove_contraption', error: 'no rule has the id ' + ${jsLiteral(input.contraptionId)} };`;
+            case 'clear_contraptions':
+                return `${refuse('clearContraptions')}
+  app.clearContraptions();
+  return { success: true, action: 'clear_contraptions' };`;
+            case 'clear_variables':
+                return `${refuse('clearVariables')}
+  return { success: true, action: 'clear_variables', scope: ${scope}, removed: app.clearVariables(${scope}) };`;
+            case 'list_contraptions':
+                return `${refuse('listContraptions')}
+  return { success: true, action: 'list_contraptions', contraptions: app.listContraptions() };`;
+            case 'set_variable':
+                return `${refuse('setVariable')}
+  app.setVariable(${key}, ${jsLiteral(input.value)}, ${scope});
+  return { success: true, action: 'set_variable', key: ${key}, value: app.getVariable(${key}, null, ${scope}) };`;
+            case 'get_variable':
+                return `${refuse('getVariable')}
+  return { success: true, action: 'get_variable', key: ${key}, value: app.getVariable(${key}, ${jsLiteral(input.fallback ?? null)}, ${scope}) };`;
+            case 'increment_variable':
+                return `${refuse('incrementVariable')}
+  return { success: true, action: 'increment_variable', key: ${key}, value: app.incrementVariable(${key}, ${input.by ?? 1}, ${scope}) };`;
+            default: {
+                const itemId = jsLiteral(input.itemId);
+                return `${refuse('bindTextToState')}
+  const item = app.getItemById(${itemId});
+  if (!item) return { success: false, action: 'bind_text', error: 'Item not found: ' + ${itemId} };
+  if (item.content === undefined) return { success: false, action: 'bind_text', error: ${itemId} + ' is not a text item, so it has no text to bind' };
+  app.bindTextToState(${itemId}, ${jsLiteral(input.template)}, ${scope});
+  return { success: true, action: 'bind_text', itemId: ${itemId}, text: item.content };`;
+            }
+        }
+    };
+    return `
+// Contraption engine: ${input.action}
+(function() {
+  ${body()}
+})();`.trim();
+}
 // Export singleton instance
 export const codeGenerator = new PinePaperCodeGenerator();
 /**