@pinepaper.studio/mcp-server 1.6.30 → 1.6.32

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 } from '../tools/engine-lists.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 { 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.
@@ -1258,14 +1317,33 @@ export function fireIfProblem(params) {
     }
     return null;
 }
+/**
+ * A TARGET-LESS on_event_step_active runs only on a studio that says so. An older studio runs an event reaction only
+ * when its target exists (a sound alone was exempt), and step_active acts on its GROUP, not its target, so one bound
+ * with no target reported success and never stepped (beta STEPACT30). FxTool #281 runs it target-less and lists it in
+ * PinePaper.TARGETLESS_EVENT_RELATIONS, the set _bindOnEventRelation itself reads, so the marker cannot say yes while
+ * the engine says no. The refusal is decided in the page (STEP_ACTIVE_TARGETLESS_JS); here, only whether to ask.
+ */
+export function targetlessStepProblem(relationType, target) {
+    if (relationType !== 'on_event_step_active' || (target != null && target !== ''))
+        return null;
+    return 'on_event_step_active needs a targetId on this studio. It steps the group named in params.groupName, not its target, but this studio runs an event reaction only when its target exists: without one it binds, reports success and never runs. Point it at any item, for example one member of the group (a current studio runs it without one).';
+}
+/** True in the page when the studio runs on_event_step_active with no target. */
+export const STEP_ACTIVE_TARGETLESS_JS = "(typeof app !== 'undefined' && !!app && app.TARGETLESS_EVENT_RELATIONS?.has?.('on_event_step_active') === true)";
 /**
  * fireIfProblem for any relation a tool is about to add: an on_event_fire_if
  * itself, or one an on_event_add_relation will add when its event fires
  * (params.type / params.params). Every path that adds relations asks this, so
  * the check does not depend on which tool built the relation.
  */
-export function relationSpecProblem(relationType, params) {
+export function relationSpecProblem(relationType, params, ...target) {
     const p = (params && typeof params === 'object' ? params : {});
+    // A target-less on_event_step_active is decided in the page, not here (targetlessStepProblem): it runs on a studio
+    // that lists it in TARGETLESS_EVENT_RELATIONS and does nothing on an older one. Only a caller with no page to ask
+    // (create_scene, which binds no relation without a target) refuses it outright.
+    if (target.length > 1 && target[1] === 'no-page' && targetlessStepProblem(relationType, target[0]))
+        return targetlessStepProblem(relationType, target[0]);
     if (relationType === 'on_event_fire_if')
         return fireIfProblem(p);
     if (relationType === 'time_expression' && typeof p.expression === 'string')
@@ -1372,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)};
+    var un = ${JSON.stringify(keys)}.filter(function (k) { return cr.reads.indexOf(k) < 0 && skip.indexOf(k) < 0; });
+    if (!un.length) return {};
+    return { ${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);
@@ -1393,14 +1510,26 @@ function equationFlipNote(relationType, params) {
 }
 function unreadOptionWarning(relationType, params, injected) {
     const keys = typeof relationType === 'string' ? RELATION_PARAM_KEYS[relationType] : undefined;
-    if (!keys || !params || typeof params !== 'object')
+    return keys ? unreadKeysWarning(String(relationType), keys, params, injected) : null;
+}
+/** 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')
         return null;
     const unknown = Object.keys(params).filter((k) => !keys.includes(k) && !injected.includes(k));
     if (!unknown.length)
         return null;
     const norm = (x) => x.replace(/_/g, '').toLowerCase();
     const hint = unknown.map((k) => keys.find((x) => norm(x) === norm(k)) ?? keys.find((x) => editDistance(norm(x), norm(k)) <= (k.length > 5 ? 2 : 1))).map((x, i) => (x ? `${unknown[i]} → ${x}?` : '')).filter(Boolean);
-    return `${relationType} does not read ${unknown.join(', ')}, so ${unknown.length > 1 ? 'they were' : 'it was'} ignored${hint.length ? ` (${hint.join('; ')})` : ''}. ${relationType} reads: ${keys.join(', ')}.`;
+    return `${reader} does not read ${unknown.join(', ')}, so ${unknown.length > 1 ? 'they were' : 'it was'} ignored${hint.length ? ` (${hint.join('; ')})` : ''}. ${reader} reads: ${keys.join(', ')}.`;
+}
+/**
+ * An animationOptions key app.animate never reads (ANIMATION_OPTION_KEYS, generated from the engine). The batch hands
+ * the options over as they are, so an unknown key was dropped with the op reported done. pinepaper_animate's own
+ * names (intensity, speed …) are translated before this (batch-op-names.ts), so they never reach it.
+ */
+export function animationOptionWarning(options) {
+    return unreadKeysWarning('animationOptions', ANIMATION_OPTION_KEYS, options);
 }
 const VISIBILITY_REACTION = /^on_(event|enter|exit)_set_visibility$/;
 /**
@@ -1439,7 +1568,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((() => { const w = relationOptionWarning(relationType, params); return w ? `, warning: ${jsLiteral(w)}` : ''; })()) + String(customOptionWarningJs(relationType, params, 'warning')) + " };\n})();\n").trim();
 }
 /**
  * The per-burst particle cap of the CURRENT studio (FxTool ParticleEmitter
@@ -1546,13 +1675,14 @@ export function normalizeEmitterSpec(spec, assumeDefaultCount = true) {
             mismatch(`bursts[${i}]`, own.count ?? out.count, own.velocities ?? out.velocities);
     });
     // A RANGE WHERE THE STUDIO READS ONE NUMBER is not drawn as a range (1.6.24
-    // probe: gravity [100, 300] fell to 0, opacity [0.2, 1] to 1, no word). What
-    // it draws instead depends on the studio build: older ones take num()'s
-    // fallback (count [a, b] → 0, so nothing is drawn); FxTool #228 draws the
-    // middle and says so (emitter-range-not-read). Only size, speed, angle,
-    // spawn, lifetime and spin go through range(). The text says what holds on
-    // both, so it is true whichever studio the server is pointed at.
-    const SCALAR_ONLY = ['gravity', 'drag', 'friction', 'opacity', 'fadeIn', 'fadeOut', 'strokeWidth', 'jitter', 'jitterHz', 'aspect', 'sizeEnd', 'count'];
+    // probe: count [a, b] → 0 on older studios, the middle on FxTool #228). Only
+    // the keys that take one number on EVERY build are named here. gravity, drag,
+    // friction, opacity, sizeEnd and jitter were too, until the studio began to
+    // sample them per particle: the tester measured drag 101–206 against this text
+    // saying one value. What a given studio does with a range on those is its own
+    // to say (emitter-range-not-read, in engineWarnings), so it is true for
+    // whichever studio the server is pointed at.
+    const SCALAR_ONLY = ['fadeIn', 'fadeOut', 'strokeWidth', 'jitterHz', 'aspect', 'count'];
     const SPEC_ONLY = ['rate', 'start', 'end', 'seed'];
     const OUTCOME = {
         count: 'an older studio reads a range here as 0 and draws no particles',
@@ -1561,7 +1691,7 @@ export function normalizeEmitterSpec(spec, assumeDefaultCount = true) {
         for (const k of keys) {
             const v = o[k];
             if (Array.isArray(v) && v.length >= 2) {
-                warnings.push(`${where}.${k} ${JSON.stringify(v)} is not drawn as a range: ${k} takes one number, so the studio draws one value for every particle (its default, or the middle of the range, depending on the build${OUTCOME[k] ? `; ${OUTCOME[k]}` : ''}). Pass the single value you want. Only size, speed, angle, spawn, lifetime and spin take a [min, max] range.`);
+                warnings.push(`${where}.${k} ${JSON.stringify(v)} is not drawn as a range: ${k} takes one number, so the studio draws one value for every particle (its default, or the middle of the range, depending on the build${OUTCOME[k] ? `; ${OUTCOME[k]}` : ''}). Pass the single value you want.`);
             }
         }
         const f = o.fade;
@@ -1770,7 +1900,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 });
@@ -1790,7 +1920,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 });
@@ -1944,6 +2074,48 @@ function unanimatedTextKeysJs(keys) {
 }
 /** The sentence for the keys unanimatedTextKeysJs found, built in the page. */
 const UNANIMATED_TEXT_KEYS_SENTENCE = `' is not an animatable property in this studio (app.listAnimatableProperties does not list it), so it had no effect: 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.'`;
+/**
+ * The warnings a keyframe track's result carries, as object-literal fields (", key: value" …): keys that leave out a
+ * property, loop in an export, x beside fontSize on an older studio, easing on the first key. One function for
+ * pinepaper_keyframe_animate and the batch keyframe_animate op: the batch had its own copy of the emitter and none
+ * of these (SIZEKEY-PAIR: the same keys warned through the tool and not through the batch).
+ */
+function keyframeResultNotes(keyframes, { loop = false, append = false, easingAt } = {}) {
+    // A KEY THAT LEAVES A PROPERTY OUT (round 9 HH, engine 2.30): the engine
+    // treats the gap as a break in that property's track rather than holding or
+    // interpolating across it, silently. Named here — which keys lack which
+    // properties — with the fix a caller can make now: give every key the full set.
+    const propSets = keyframes.map((k) => Object.keys(k.properties ?? {}));
+    const allProps = [...new Set(propSets.flat())];
+    const gaps = keyframes
+        .map((k, i) => ({ time: k.time, missing: allProps.filter((p) => !propSets[i].includes(p)) }))
+        .filter((g) => g.missing.length);
+    // With append the gaps that matter are the MERGED track's (an earlier key
+    // with no scale beside a new key with one), so that check runs in the page
+    // on the result instead (below).
+    const gapNote = !append && gaps.length && keyframes.length > 1
+        ? `, 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.
+    // Said there, with the two ways that hold; a current studio is quiet.
+    const sizekeyPairNote = (allProps.includes('x') || allProps.includes('position')) && allProps.includes('fontSize')
+        // A studio that writes text size before position (FxTool #262, which also brought _applyScaleParams) holds x.
+        ? `, ...(typeof app._applyScaleParams !== 'function' ? { sizekeyPairWarning: ${JSON.stringify('x (or position) and fontSize keyed on the same text item drift off the keyed position in an export on this studio (SIZEKEY-PAIR). Animate scaleX / scaleY instead of fontSize, or move a group that holds the text; or update the studio.')} } : {})`
+        : '';
+    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}`;
+}
 function generateKeyframeAnimateCode(itemId, keyframes, duration, loop = false, timeOffset, clipInPoint, clipOutPoint, timeUnits, append = false, easingAt) {
     const ID = jsLiteral(itemId); // caller text: a quoted literal, never spliced raw
     const keyframesJson = JSON.stringify(normalizeKeyframePositions(keyframes), null, 2);
@@ -1995,39 +2167,7 @@ String(JSON.stringify(levelKeys)) +
     // never applies — a Ken Burns eased only there rendered linear. Said in the
     // result rather than silently moved: moving it would change what the other
     // keys the caller wrote mean.
-    // A KEY THAT LEAVES A PROPERTY OUT (round 9 HH, engine 2.30): the engine
-    // treats the gap as a break in that property's track rather than holding or
-    // interpolating across it, silently. Named here — which keys lack which
-    // properties — with the fix a caller can make now: give every key the full set.
-    const propSets = keyframes.map((k) => Object.keys(k.properties ?? {}));
-    const allProps = [...new Set(propSets.flat())];
-    const gaps = keyframes
-        .map((k, i) => ({ time: k.time, missing: allProps.filter((p) => !propSets[i].includes(p)) }))
-        .filter((g) => g.missing.length);
-    // With append the gaps that matter are the MERGED track's (an earlier key
-    // with no scale beside a new key with one), so that check runs in the page
-    // on the result instead (below).
-    const gapNote = !append && gaps.length && keyframes.length > 1
-        ? `, 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.
-    // Said there, with the two ways that hold; a current studio is quiet.
-    const sizekeyPairNote = (allProps.includes('x') || allProps.includes('position')) && allProps.includes('fontSize')
-        // A studio that writes text size before position (FxTool #262, which also brought _applyScaleParams) holds x.
-        ? `, ...(typeof app._applyScaleParams !== 'function' ? { sizekeyPairWarning: ${JSON.stringify('x (or position) and fontSize keyed on the same text item drift off the keyed position in an export on this studio (SIZEKEY-PAIR). Animate scaleX / scaleY instead of fontSize, or move a group that holds the text; or update the studio.')} } : {})`
-        : '';
-    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).`)}`
-        : '';
+    const __notes = keyframeResultNotes(keyframes, { loop, append, easingAt });
     const textKeysJs = unanimatedTextKeysJs(keyframes.flatMap((k) => Object.keys(k.properties ?? {})));
     const textKeyCheck = textKeysJs ? `
   const __ignored = ${textKeysJs};
@@ -2070,7 +2210,7 @@ String(calculatedDuration) +
 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(easingNote) + String(sizekeyPairNote) + String(loopNote) + String(gapNote) + String(runtimeWarning) + " };\n})();\n").trim();
+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
@@ -2204,6 +2344,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
@@ -2228,13 +2391,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();
@@ -2243,13 +2400,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();
@@ -2500,7 +2651,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"
+
+
+
+
+
 
 
 
@@ -3385,14 +3541,22 @@ String(JSON.stringify(validated.presetId)) +
 ).trim();
         }
         {
-            const problem = relationSpecProblem(validated.relationType, validated.params);
+            const problem = relationSpecProblem(validated.relationType, validated.params, validated.targetId);
             if (problem)
                 return `(function() { return { success: false, relationType: ${jsLiteral(validated.relationType)}, error: ${jsLiteral(problem)} }; })();`;
         }
         if (validated.relationType === 'moves_along_path') {
             return generateMovesAlongPathCode(validated.sourceId, validated.targetId ?? undefined, (validated.params ?? {}));
         }
-        const code = generateAddRelationCode(validated.sourceId, validated.targetId || validated.sourceId, validated.relationType, validated.params);
+        const built = generateAddRelationCode(validated.sourceId, validated.targetId || validated.sourceId, validated.relationType, validated.params);
+        // Target-less step_active: refused in the page, only on a studio that would drop it (targetlessStepProblem).
+        const stepNoTarget = targetlessStepProblem(validated.relationType, validated.targetId);
+        const code = stepNoTarget
+            ? `(function() {
+  if (!${STEP_ACTIVE_TARGETLESS_JS}) return { success: false, relationType: 'on_event_step_active', error: ${jsLiteral(stepNoTarget)} };
+  return ${built.trim().replace(/;$/, '')};
+})();`
+            : built;
         // NO TARGET (event reactions like on_event_play_sound, self-relations): the
         // engine is handed the source as the target, but the reply must not say
         // "item_2 → item_2" — a model reads that as the event wired to itself.
@@ -4073,7 +4237,7 @@ if (typeof _gen === 'function') {
         for (const relation of relations) {
             const { source, target, type, params = {} } = relation;
             const paramsStr = JSON.stringify(params);
-            const specProblem = relationSpecProblem(type, params);
+            const specProblem = relationSpecProblem(type, params, target, 'no-page');
             if (specProblem) {
                 codeParts.push(`
 // Refused relation: ${oneLine(source)} ${oneLine(type)} ${oneLine(target)}
@@ -5070,13 +5234,16 @@ 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))} };
+return { itemId: targetId, animationType: ${JSON.stringify(String(op.animationType))}${(() => { const w = animationOptionWarning(op.animationOptions); return w ? `, warning: ${jsLiteral(w)}` : ''; })()} };
 `;
             case 'relation':
                 const srcRef = batchRef(op.sourceId);
                 const tgtRef = batchRef(op.targetId);
                 const relOpts = JSON.stringify(op.relationOptions || {});
-                const fireIf = relationSpecProblem(op.relationType, op.relationOptions);
+                const fireIf = relationSpecProblem(op.relationType, op.relationOptions, op.targetId);
+                // Target-less step_active: refused in the page, only on a studio that would drop it (targetlessStepProblem).
+                const stepNoTarget = targetlessStepProblem(op.relationType, op.targetId);
+                const stepGuard = stepNoTarget ? `if (!${STEP_ACTIVE_TARGETLESS_JS}) throw new Error(${jsLiteral('on_event_step_active: ' + stepNoTarget)});\n` : '';
                 if (fireIf)
                     return `
 throw new Error(${JSON.stringify(String(op.relationType) + ': ' + fireIf)});
@@ -5100,6 +5267,7 @@ if (!__members.length) throw new Error('no item is named like ' + ${jsLiteral(op
                         : `const __members = [{ id: ${srcRef} }];
 if (!app.getItemById(__members[0].id)) throw new Error('Source not found: ' + __members[0].id);`;
                     return ("\n" +
+String(stepGuard) +
 String(members) +
 "\nconst targetId = " +
 String(noTarget ? 'null' : tgtRef) +
@@ -5127,10 +5295,11 @@ 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((() => { const w = relationOptionWarning(op.relationType, op.relationOptions, ['index', 'count', 'pattern']); return w ? `, optionWarning: ${jsLiteral(w)}` : ''; })()) + String(customOptionWarningJs(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 ("\nconst sourceId = " +
+                return ("\n" +
+String(stepGuard) +
+"const sourceId = " +
 String(srcRef) +
 ";\nconst targetId = " +
 String(noTarget ? 'null' : tgtRef) +
@@ -5145,9 +5314,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((() => { const w = relationOptionWarning(op.relationType, op.relationOptions); return w ? `, warning: ${jsLiteral(w)}` : ''; })()) + String(customOptionWarningJs(op.relationType, op.relationOptions, 'warning')) + " };\n");
             case 'delete':
                 const delRef = batchRef(op.itemId);
                 return `
@@ -5248,7 +5415,7 @@ String(kfLoop) +
 String(kfAppend ? ", mode: 'merge'" : '') +
 String(kfExtraStr) +
 " });" +
-String(kfTextCheck) + "\nreturn { success: true, itemId: targetId, duration: " + String(kfDuration) + ", loop: " + String(kfLoop) + String(kfAppend ? ', append: true' : '') + String(kfAppend ? '' : `, ...(_prevKeys ? { track: { replaced: true, previousKeys: _prevKeys, note: 'the item already had a keyframe track; this op replaced it. To add keys to it instead, pass append: true.' } } : {})`) + String(kfIgnored) + " };\n");
+String(kfTextCheck) + "\nreturn { success: true, itemId: targetId, duration: " + String(kfDuration) + ", loop: " + String(kfLoop) + String(kfAppend ? ', append: true' : '') + String(keyframeResultNotes(kfSource, { loop: kfLoop === true, append: kfAppend })) + String(kfAppend ? '' : `, ...(_prevKeys ? { track: { replaced: true, previousKeys: _prevKeys, note: 'the item already had a keyframe track; this op replaced it. To add keys to it instead, pass append: true.' } } : {})`) + String(kfIgnored) + " };\n");
             }
             case 'apply_mask': {
                 const maskItemRef = batchRef(op.itemId);
@@ -5376,7 +5543,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
@@ -5398,8 +5565,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
@@ -6033,9 +6205,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"
+
 
 
 
@@ -7174,6 +7347,7 @@ String(jsLiteral(format)) +
 
 
 
+
 
 
 ).trim();
@@ -8787,7 +8961,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"
@@ -12605,11 +12779,19 @@ String(sheet.format === 'png' ? '' : ', 0.82') +
         // A fire_if the doc declares is checked before anything is built: refused, the whole document is, with every reason.
         const specProblems = ops
             .filter((o) => o.op === 'addRelation')
-            .map((o) => { const r = o; const why = relationSpecProblem(r.relation, r.params); return why ? `${r.from} -> ${r.to} (${r.relation}): ${why}` : null; })
+            .map((o) => { const r = o; const why = relationSpecProblem(r.relation, r.params, r.to); return why ? `${r.from} -> ${r.to} (${r.relation}): ${why}` : null; })
             .filter((x) => !!x);
         if (specProblems.length) {
             return `(function() { return { success: false, error: ${jsLiteral('nothing was built: ' + specProblems.join(' | '))} }; })();`;
         }
+        // Target-less step_active relations refuse the whole document in the page, only on a studio that would drop them.
+        const stepNoTarget = ops
+            .filter((o) => o.op === 'addRelation')
+            .map((o) => { const r = o; const why = targetlessStepProblem(r.relation, r.to); return why ? `${r.from} -> (no target) (${r.relation}): ${why}` : null; })
+            .filter((x) => !!x);
+        const stepDocGuard = stepNoTarget.length
+            ? `if (!${STEP_ACTIVE_TARGETLESS_JS}) return { success: false, error: ${jsLiteral('nothing was built: ' + stepNoTarget.join(' | '))} };\n`
+            : '';
         const opsJson = JSON.stringify(ops, null, 2);
         const diagJson = JSON.stringify(diagnostics);
         const docJson = JSON.stringify(input.doc);
@@ -12621,7 +12803,9 @@ String(sheet.format === 'png' ? '' : ', 0.82') +
 String(oneLine(ops.filter((o) => o.op === 'create').length)) +
 " items, " +
 String(oneLine(ops.filter((o) => o.op === 'addRelation').length)) +
-" relations)\n(async function() {\n  // Engine door first: the studio's own OntologyCompiler reads every node facet\n  // (geometry, paint, text, the keyframe track, masks) and builds through the\n  // template loader's paths — the round trip the studio's pixel tests verify\n  // (e2e/graph-instantiate-parity.spec.js). The server-side compile above is\n  // kept for the diagnostics preview and for studios that predate the facade,\n  // which get the box loop below and a note saying so.\n  const doc = " +
+" relations)\n(async function() {\n  " +
+String(stepDocGuard) +
+"  // Engine door first: the studio's own OntologyCompiler reads every node facet\n  // (geometry, paint, text, the keyframe track, masks) and builds through the\n  // template loader's paths — the round trip the studio's pixel tests verify\n  // (e2e/graph-instantiate-parity.spec.js). The server-side compile above is\n  // kept for the diagnostics preview and for studios that predate the facade,\n  // which get the box loop below and a note saying so.\n  const doc = " +
 String(docJson) +
 ";\n  if (typeof app.instantiateOntology === 'function') {\n    // THE LIVE CANVAS, unless one was given: the engine lays out for 1080x1080\n    // otherwise, which put items at (540,540) on a 640x360 canvas (gate run 3).\n    const __opts = " +
 String(engineOptsJson) +
@@ -12679,8 +12863,6 @@ String(diagJson) +
 
 
 
-
-
 
 
 
@@ -12700,16 +12882,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})();"
@@ -12775,6 +12961,7 @@ String(input.only === 'edit' ? 'true' : 'false') +
 
 
 
+
 
 
 ).trim();
@@ -13324,7 +13511,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 = " +
@@ -16033,6 +16220,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);
@@ -16047,6 +16236,74 @@ 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 animateItem, playSound and custom actions are
+ * not offered: animateItem goes through app.modify, which acts on the selection and not on its target; playSound does
+ * not call app.playSound the way that method is written; custom needs a function, which JSON cannot carry. All three
+ * answer ok regardless, so a rule using them would report success for nothing.
+ */
+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) => (a.type === 'modifyItem' ? [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' } : {}),
+    ${targets.length ? "note: 'changes a rule makes to an item stay: nothing rewinds them, so another export starts from the changed scene'" : ''} };`;
+            }
+            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 '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();
 /**