@pinepaper.studio/mcp-server 1.6.31 → 1.6.32

package/dist/types/code-generator.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)};
+    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);
@@ -1470,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
@@ -1802,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 });
@@ -1822,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 });
@@ -2246,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
@@ -2270,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();
@@ -2285,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();
@@ -2542,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"
+
+
+
+
+
 
 
 
@@ -5181,7 +5295,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((() => { 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 ("\n" +
 String(stepGuard) +
@@ -5200,7 +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 `
@@ -5429,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
@@ -5451,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
@@ -6086,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"
+
 
 
 
@@ -7227,6 +7347,7 @@ String(jsLiteral(format)) +
 
 
 
+
 
 
 ).trim();
@@ -8840,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"
@@ -12761,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})();"
@@ -12836,6 +12961,7 @@ String(input.only === 'edit' ? 'true' : 'false') +
 
 
 
+
 
 
 ).trim();
@@ -13385,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 = " +
@@ -16094,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);
@@ -16108,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();
 /**