@pinepaper.studio/mcp-server 1.6.32 → 1.6.34

package/dist/types/code-generator.js

@@ -7,7 +7,7 @@
 import { compileChoreography } from '../tools/choreograph.js';
 import { compileBatchTimelines, emitTimelineOpBody } from '../tools/timeline.js';
 import { normalizeSvgSize } from '../utils/svg-size.js';
-import { WORLD3D_COLOR_PATHS, PATTERN_KINDS, EXPRESSION_FUNCTION_ARITY, EXPRESSION_CONSTANTS, EXPRESSION_REJECTED, RELATION_PARAM_KEYS, ANIMATION_OPTION_KEYS } from '../tools/engine-lists.js';
+import { WORLD3D_COLOR_PATHS, PATTERN_KINDS, EXPRESSION_FUNCTION_ARITY, EXPRESSION_CONSTANTS, EXPRESSION_REJECTED, RELATION_PARAM_KEYS, RELATION_LOOP_PARAMS, ANIMATION_OPTION_KEYS, FILTER_TYPES, FILTER_PARAM_RANGES } from '../tools/engine-lists.js';
 import { expressionGrammarText } from '../tools/expression-grammar.js';
 import { REQUIRED_ENGINE_METHODS, OPTIONAL_ENGINE_METHODS } from '../tools/engine-methods.js';
 import { NORMALIZE_PARAM_READS, MODIFY_CHANGE_READS } from '../tools/shape-params.js';
@@ -124,18 +124,29 @@ ${itemVarName}.${propertyName} = (function() {
   };
 })();`;
     }
-    // Linear: a diagonal across a 100 px box at the requested position.
-    const defaultOrigin = origin || [position.x - 50, position.y - 50];
-    const defaultDestination = destination || [position.x + 50, position.y + 50];
+    // A LINEAR RAMP FITS THE ITEM, top to bottom, as the engine's own app.create does (FIREFLY31). This was a fixed
+    // 100 px diagonal at the requested position. Leaving the ends out is not enough here: this assigns straight to
+    // Paper, where a gradient with no ends is zero-length. An end the caller gave is kept as given.
+    const fx = position.x, fy = position.y;
+    const o = origin ? `[${origin[0]}, ${origin[1]}]`
+        : destination ? `[${destination[0]}, __gb ? __gb.y : ${fy - 50}]`
+            : `(__gb ? [__gb.x + __gb.width / 2, __gb.y] : [${fx}, ${fy - 50}])`;
+    const d = destination ? `[${destination[0]}, ${destination[1]}]`
+        : origin ? `[${origin[0]}, __gb ? __gb.y + __gb.height : ${fy + 50}]`
+            : `(__gb ? [__gb.x + __gb.width / 2, __gb.y + __gb.height] : [${fx}, ${fy + 50}])`;
     return `
-${itemVarName}.${propertyName} = {
-  gradient: {
-    stops: [${stopsCode}],
-    radial: false
-  },
-  origin: [${defaultOrigin[0]}, ${defaultOrigin[1]}],
-  destination: [${defaultDestination[0]}, ${defaultDestination[1]}]
-};`;
+${itemVarName}.${propertyName} = (function() {
+  const __b = ${itemVarName} && ${itemVarName}.bounds;
+  const __gb = __b && isFinite(__b.x) && isFinite(__b.y) && __b.width > 0 && __b.height > 0 ? __b : null;
+  return {
+    gradient: {
+      stops: [${stopsCode}],
+      radial: false
+    },
+    origin: ${o},
+    destination: ${d}
+  };
+})();`;
 }
 /**
  * Generate shadow code for an item
@@ -1483,10 +1494,10 @@ function customOptionWarningJs(relationType, params, key, injected = []) {
     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 skip = ${JSON.stringify([...injected, ...RELATION_LOOP_PARAMS])};
     var un = ${JSON.stringify(keys)}.filter(function (k) { return cr.reads.indexOf(k) < 0 && skip.indexOf(k) < 0; });
     if (!un.length) return {};
-    return { ${key}: ${jsLiteral(relationType)} + ' does not read ' + un.join(', ') + ', so ' + (un.length > 1 ? 'they were' : 'it was') + ' ignored. ' + ${jsLiteral(relationType)} + ' reads: ' + cr.reads.join(', ') + '.' };
+    return { ignoredOptions: un, ${key}: ${jsLiteral(relationType)} + ' does not read ' + un.join(', ') + ', so ' + (un.length > 1 ? 'they were' : 'it was') + ' ignored. ' + ${jsLiteral(relationType)} + ' reads: ' + cr.reads.join(', ') + '.' };
   } catch (e) { return {}; } })()`;
 }
 export function relationOptionWarning(relationType, params, injected = []) {
@@ -1508,10 +1519,25 @@ function equationFlipNote(relationType, params) {
         return null;
     return 'params.equation is read with y UP (flipY defaults to true), so on screen the curve is mirrored about cy. If you wrote it in screen coordinates (y down), add flipY: false to the equation.';
 }
-function unreadOptionWarning(relationType, params, injected) {
+/** What a built-in relation reads: its rule's params, and what the relation loop reads on every relation. */
+function relationReads(relationType) {
     const keys = typeof relationType === 'string' ? RELATION_PARAM_KEYS[relationType] : undefined;
+    return keys ? [...keys, ...RELATION_LOOP_PARAMS] : undefined;
+}
+function unreadOptionWarning(relationType, params, injected) {
+    const keys = relationReads(relationType);
     return keys ? unreadKeysWarning(String(relationType), keys, params, injected) : null;
 }
+const unreadKeys = (keys, params, injected = []) => keys && params && typeof params === 'object' ? Object.keys(params).filter((k) => !keys.includes(k) && !injected.includes(k)) : [];
+/**
+ * A relation reply's fields for its options: the unread keys as data (ignoredOptions, which the reply's
+ * ignoredArguments is built from) beside the sentence. Built-ins are known here, a custom relation only in the page.
+ */
+function relationOptionFields(relationType, params, key, injected = []) {
+    const unread = unreadKeys(relationReads(relationType), params, injected);
+    const warning = relationOptionWarning(relationType, params, injected);
+    return `${unread.length ? `, ignoredOptions: ${jsLiteral(unread)}` : ''}${warning ? `, ${key}: ${jsLiteral(warning)}` : ''}${customOptionWarningJs(relationType, params, key, injected)}`;
+}
 /** The keys of `params` outside `keys`, named with a "did you mean" and the list that is read; null when all are read. */
 function unreadKeysWarning(reader, keys, params, injected = []) {
     if (!params || typeof params !== 'object')
@@ -1568,7 +1594,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)}` : ''; })()) + String(customOptionWarningJs(relationType, params, 'warning')) + " };\n})();\n").trim();
+String(JSON.stringify(params, null, 2)) + ");\n  if (!success) {\n    const __why = " + String(relationRefusalReasonJs(jsLiteral(relationType))) + ";\n    return { success: false, relationType: " + String(jsLiteral(relationType)) + ", error: 'the studio refused the ' + " + String(jsLiteral(relationType)) + " + ' relation between ' + " + String(jsLiteral(sourceId)) + " + ' and ' + " + String(jsLiteral(targetId)) + " + (__why ? ': ' + __why : '.') };\n  }\n  app.historyManager.saveState();\n  return { success: true, sourceId: " + String(jsLiteral(sourceId)) + ", targetId: " + String(jsLiteral(targetId)) + ", relationType: " + String(jsLiteral(relationType)) + String(relationOptionFields(relationType, params, 'warning')) + " };\n})();\n").trim();
 }
 /**
  * The per-burst particle cap of the CURRENT studio (FxTool ParticleEmitter
@@ -1644,9 +1670,18 @@ export function normalizeEmitterSpec(spec, assumeDefaultCount = true) {
         for (const k of ['velocities', 'offsets'])
             if (out[k] !== undefined)
                 out[k] = pairs(out[k]);
+        // A trail's single offset is one pair; the studio reads [x, y] and dropped {x, y} with nothing said (TRAILOFF31).
+        const off = out.offset;
+        if (off && typeof off === 'object' && !Array.isArray(off) && typeof off.x === 'number' && typeof off.y === 'number')
+            out.offset = [off.x, off.y];
         return out;
     };
     const out = fix(spec);
+    // rate, start and end drive a trail. Beside bursts they drew nothing and said nothing (EMITCONT31).
+    const trailOnly = ['rate', 'start', 'end'].filter((k) => spec[k] !== undefined);
+    if (trailOnly.length && Array.isArray(spec.bursts) && spec.mode !== 'trail' && spec.target === undefined) {
+        warnings.push(`${trailOnly.join(', ')} ${trailOnly.length > 1 ? 'are' : 'is'} not read by a burst emitter, so ${trailOnly.length > 1 ? 'they had' : 'it had'} no effect: only the bursts' own count is drawn. For particles over time, add bursts, or use mode 'trail' with a target.`);
+    }
     if (Array.isArray(spec.bursts))
         out.bursts = spec.bursts.map((b) => (b && typeof b === 'object' ? fix(b) : b));
     // The studio's default count per burst (ParticleEmitter DEFAULT_LOOK).
@@ -2072,6 +2107,24 @@ function unanimatedTextKeysJs(keys) {
     return ${JSON.stringify(spec)}.filter(function(s) { return !s.names.some(function(n) { return __names.indexOf(n) >= 0; }); }).map(function(s) { return s.key; });
   })()`;
 }
+/**
+ * An image filter's parameter as a key: keyframe_animate stores it, and a filter does not read a track, so the item
+ * never changes with success:true (FILTKEY31). Asked of the same list, so a studio that starts animating one is believed.
+ */
+const FILTER_PARAM_KEYS = new Set([...Object.values(FILTER_PARAM_RANGES).flatMap((p) => Object.keys(p)), ...FILTER_TYPES].filter((k) => !['color', 'opacity', 'scale', 'x', 'y', 'rotation', 'size', 'radius', 'width', 'height', 'value', 'amount'].includes(k)));
+function unanimatedFilterKeysJs(keys) {
+    const filterKeys = [...new Set(keys)].filter((k) => FILTER_PARAM_KEYS.has(k));
+    if (!filterKeys.length)
+        return '[]';
+    return `(function() {
+    let __l = null;
+    try { __l = typeof app.listAnimatableProperties === 'function' ? app.listAnimatableProperties() : null; } catch (_) { __l = null; }
+    if (!__l || !__l.properties) return [];
+    const __names = __l.properties.map(function(p) { return p && p.name; });
+    return ${JSON.stringify(filterKeys)}.filter(function(k) { return __names.indexOf(k) < 0; });
+  })()`;
+}
+const UNANIMATED_FILTER_KEYS_SENTENCE = `' is an image filter setting and not an animatable property, so the key had no effect. Set a fixed value with pinepaper_image_filter or pinepaper_add_filter, and animate opacity or scale for a change over time.'`;
 /** The sentence for the keys unanimatedTextKeysJs found, built in the page. */
 const UNANIMATED_TEXT_KEYS_SENTENCE = `' is not an animatable property in this studio (app.listAnimatableProperties does not list it), so it had no effect: a key animates only where that list names it. Here, set a fixed value with pinepaper_modify_item, or animate fontSize or scaleX. For a skew, key skewX / skewY (degrees) where the studio lists them, else a transform matrix track.'`;
 /**
@@ -2097,12 +2150,6 @@ function keyframeResultNotes(keyframes, { loop = false, append = false, easingAt
         ? `, propertyGaps: ${JSON.stringify(gaps.slice(0, 10))}, gapWarning: ${JSON.stringify(`${gaps.length} keyframe(s) leave out a property other keys animate (${[...new Set(gaps.flatMap((g) => g.missing))].join(', ')}). The engine can break that property's track at such a key; repeat the value on every key — hold it by repeating the previous value.`)}`
         : '';
     const first = [...keyframes].sort((a, b) => a.time - b.time)[0];
-    // loop:true repeats in the editor; an export of the measured build played
-    // the keyframes ONCE and held (round 7, 2.24). Said where it is set, with
-    // the two ways that do export, until the engine's export clock wraps them.
-    const loopNote = loop
-        ? `, loopNote: ${JSON.stringify('loop:true repeats in the editor, but has been measured playing ONCE in an exported video and then holding the last keyframe. For an export longer than one cycle, check a frame in the second cycle — if it holds, write the keyframes out per cycle, or use a loop preset (pinepaper_animate), which does cycle in export.')}`
-        : '';
     // SIZEKEY-PAIR (mcp-cloud #28): on a studio before FxTool #262, x (or
     // position) keyed beside fontSize on one text item drifted in an export: the
     // size was applied after the position, and a text resizes around its anchor.
@@ -2114,7 +2161,7 @@ function keyframeResultNotes(keyframes, { loop = false, append = false, easingAt
     const easingNote = easingAt !== 'departure' && first?.easing && first.easing !== 'linear'
         ? `, note: ${JSON.stringify(`easing '${first.easing}' is on the first keyframe, where it has no effect by default: easing shapes the segment ARRIVING at a keyframe. Put it on the keyframe you are moving to, or pass easingAt: 'departure' to read every easing as the move LEAVING its key (current studio).`)}`
         : '';
-    return `${easingNote}${sizekeyPairNote}${loopNote}${gapNote}`;
+    return `${easingNote}${sizekeyPairNote}${gapNote}`;
 }
 function generateKeyframeAnimateCode(itemId, keyframes, duration, loop = false, timeOffset, clipInPoint, clipOutPoint, timeUnits, append = false, easingAt) {
     const ID = jsLiteral(itemId); // caller text: a quoted literal, never spliced raw
@@ -2172,9 +2219,12 @@ String(JSON.stringify(levelKeys)) +
     const textKeyCheck = textKeysJs ? `
   const __ignored = ${textKeysJs};
   if (__ignored.length) __warn.push(__ignored.join(', ') + ${UNANIMATED_TEXT_KEYS_SENTENCE});` : '';
+    const filterKeyCheck = `
+  const __filterIgnored = ${unanimatedFilterKeysJs(keyframes.flatMap((k) => Object.keys(k.properties ?? {})))};
+  if (__filterIgnored.length) __warn.push(__filterIgnored.join(', ') + ${UNANIMATED_FILTER_KEYS_SENTENCE});`;
     const easingAtCheck = easingAt !== undefined ? `
   if (__opts && Object.prototype.hasOwnProperty.call(__opts, 'easingAt')) __warn.push('easingAt ' + ${JSON.stringify(JSON.stringify(easingAt))} + ' was not applied: this studio predates it, so every easing was read as the move ARRIVING at its key. Put each easing on the key the move goes to instead.');` : '';
-    const runtimeWarning = `${textKeysJs ? ', ...(__ignored.length ? { ignoredProperties: __ignored } : {})' : ''}, ...(__warn.length ? { warning: __warn.join(' ') } : {})`;
+    const runtimeWarning = `, ...(${textKeysJs ? '__ignored.length || ' : ''}__filterIgnored.length ? { ignoredProperties: ${textKeysJs ? '__ignored.concat(__filterIgnored)' : '__filterIgnored'} } : {}), ...(__warn.length ? { warning: __warn.join(' ') } : {})`;
     const addAnimTarget = itemId.startsWith('$') ? '_targetId' : `${ID}`;
     return ("\n// Apply keyframe animation to " +
 String(ID) +
@@ -2190,6 +2240,7 @@ String(keyframesJson) +
 ", __opts);\n  const __warn = [];" +
 String(easingAtCheck) +
 String(textKeyCheck) +
+String(filterKeyCheck) +
 "\n  const __now = (__ki && __ki.data && Array.isArray(__ki.data.keyframes)) ? __ki.data.keyframes.map(function(k) { return k && k.time; }) : [];\n  const __kept = __prev.every(function(t) { return __now.indexOf(t) >= 0; });" +
 String(append ? `
   // Property gaps across the merged track (the same check a single call makes
@@ -2209,8 +2260,7 @@ String(calculatedDuration) +
 ", loop: " +
 String(loop) +
 String(append ? ', append: true' : '') +
-", ...(__track ? { track: __track } : {})" +
-String(append ? `, ...(__gaps.length ? { propertyGaps: __gaps.slice(0, 10), gapWarning: __gaps.length + ' key(s) of the merged track leave out a property other keys animate (' + __gaps.reduce(function(a, g) { g.missing.forEach(function(p) { if (a.indexOf(p) < 0) a.push(p); }); return a; }, []).join(', ') + '). The engine can break that property at such a key; give each key the full set — hold a value by repeating it.' } : {})` : '') + String(timeOffset !== undefined ? `, timeOffset: ${timeOffset}` : '') + String(clipInPoint !== undefined ? `, clipInPoint: ${clipInPoint}` : '') + String(clipOutPoint !== undefined ? `, clipOutPoint: ${clipOutPoint}` : '') + String(__notes) + String(runtimeWarning) + " };\n})();\n").trim();
+", ...(__track ? { track: __track } : {})" + String(append ? `, ...(__gaps.length ? { propertyGaps: __gaps.slice(0, 10), gapWarning: __gaps.length + ' key(s) of the merged track leave out a property other keys animate (' + __gaps.reduce(function(a, g) { g.missing.forEach(function(p) { if (a.indexOf(p) < 0) a.push(p); }); return a; }, []).join(', ') + '). The engine can break that property at such a key; give each key the full set — hold a value by repeating it.' } : {})` : '') + String(timeOffset !== undefined ? `, timeOffset: ${timeOffset}` : '') + String(clipInPoint !== undefined ? `, clipInPoint: ${clipInPoint}` : '') + String(clipOutPoint !== undefined ? `, clipOutPoint: ${clipOutPoint}` : '') + String(__notes) + String(runtimeWarning) + " };\n})();\n").trim();
 }
 /**
  * Template for executing generators
@@ -3554,7 +3604,7 @@ String(JSON.stringify(validated.presetId)) +
         const code = stepNoTarget
             ? `(function() {
   if (!${STEP_ACTIVE_TARGETLESS_JS}) return { success: false, relationType: 'on_event_step_active', error: ${jsLiteral(stepNoTarget)} };
-  return ${built.trim().replace(/;$/, '')};
+  ${asReturningBody(built)}
 })();`
             : built;
         // NO TARGET (event reactions like on_event_play_sound, self-relations): the
@@ -4234,7 +4284,7 @@ if (typeof _gen === 'function') {
 })();`);
         }
         // Establish relations
-        for (const relation of relations) {
+        for (const [relationIndex, relation] of relations.entries()) {
             const { source, target, type, params = {} } = relation;
             const paramsStr = JSON.stringify(params);
             const specProblem = relationSpecProblem(type, params, target, 'no-page');
@@ -4264,7 +4314,10 @@ String(jsLiteral(type)) +
 String(jsLiteral(source)) +
 ", target: " +
 String(jsLiteral(target)) +
-", type: " + String(jsLiteral(type)) + " });\n    } else {\n      const __why = " + String(relationRefusalReasonJs(jsLiteral(type))) + ";\n      (results.relationsRefused = results.relationsRefused || []).push({ source: " + String(jsLiteral(source)) + ", target: " + String(jsLiteral(target)) + ", type: " + String(jsLiteral(type)) + ", reason: __why || 'the studio refused it' });\n      results.success = false;\n      results.error = 'the studio refused ' + results.relationsRefused.length + ' relation(s): ' + results.relationsRefused.map(function(r) { return r.type + ' ' + r.source + ' -> ' + r.target + ' (' + r.reason + ')'; }).join('; ') + '. The items were created.';\n    }\n  }\n})();\n"));
+", type: " +
+String(jsLiteral(type)) +
+" });\n      const __o = { _: 0" +
+String(relationOptionFields(type, params, 'warning')) + " };\n      if (__o.warning) (results.optionWarnings = results.optionWarnings || []).push(__o.warning);\n      if (__o.ignoredOptions) (results.ignoredOptions = results.ignoredOptions || []).push.apply(results.ignoredOptions, __o.ignoredOptions.map(function(k) { return 'relations[" + String(relationIndex) + "].params.' + k; }));\n    } else {\n      const __why = " + String(relationRefusalReasonJs(jsLiteral(type))) + ";\n      (results.relationsRefused = results.relationsRefused || []).push({ source: " + String(jsLiteral(source)) + ", target: " + String(jsLiteral(target)) + ", type: " + String(jsLiteral(type)) + ", reason: __why || 'the studio refused it' });\n      results.success = false;\n      results.error = 'the studio refused ' + results.relationsRefused.length + ' relation(s): ' + results.relationsRefused.map(function(r) { return r.type + ' ' + r.source + ' -> ' + r.target + ' (' + r.reason + ')'; }).join('; ') + '. The items were created.';\n    }\n  }\n})();\n"));
         }
         // Apply animations
         for (const animation of animations) {
@@ -5234,7 +5287,7 @@ const targetId = ${animItemRef};
 const item = app.getItemById(targetId);
 if (!item) throw new Error('Item not found: ' + targetId);
 app.animate(item, { animationType: ${JSON.stringify(String(op.animationType))}, ...${animOpts} });
-return { itemId: targetId, animationType: ${JSON.stringify(String(op.animationType))}${(() => { const w = animationOptionWarning(op.animationOptions); return w ? `, warning: ${jsLiteral(w)}` : ''; })()} };
+return { itemId: targetId, animationType: ${JSON.stringify(String(op.animationType))}${(() => { const w = animationOptionWarning(op.animationOptions); return w ? `, ignoredOptions: ${jsLiteral(unreadKeys(ANIMATION_OPTION_KEYS, op.animationOptions))}, warning: ${jsLiteral(w)}` : ''; })()} };
 `;
             case 'relation':
                 const srcRef = batchRef(op.sourceId);
@@ -5295,7 +5348,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)}` : ''; })()) + 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");
+String(type) + ", " + String(op.update === true ? 'updated' : 'bound') + ": __done, targetId" + String(glob ? ', count: __members.length' : '') + String(relationOptionFields(op.relationType, op.relationOptions, 'optionWarning', ['index', 'count', 'pattern'])) + ", ...(__failed.length ? { failed: __failed, warning: __failed.length + ' of ' + __members.length + ' were not " + String(op.update === true ? 'changed' : 'bound') + ": ' + __failed.join(', ') } : {}) };\n");
                 }
                 return ("\n" +
 String(stepGuard) +
@@ -5314,7 +5367,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)}` : ''; })()) + String(customOptionWarningJs(op.relationType, op.relationOptions, 'warning')) + " };\n");
+String(JSON.stringify(op.relationType)) + ",\n    error: 'the studio refused the ' + " + String(JSON.stringify(op.relationType)) + " + ' relation between ' + sourceId + ' and ' + targetId + ' — nothing was bound' + (__why ? ': ' + __why : '.') };\n}\nreturn { relationId, sourceId, targetId, relationType: " + String(JSON.stringify(String(op.relationType))) + String(relationOptionFields(op.relationType, op.relationOptions, 'warning')) + " };\n");
             case 'delete':
                 const delRef = batchRef(op.itemId);
                 return `
@@ -5402,8 +5455,9 @@ return { itemId: ${batchRef(op.itemId)}, merged: true, mergedInto: ${foldTarget}
                     kfExtra.push(`timeUnits: ${jsLiteral(kfUnits)}`);
                 const kfExtraStr = kfExtra.length > 0 ? `, ${kfExtra.join(', ')}` : '';
                 const kfTextKeysJs = unanimatedTextKeysJs((kfSource || []).flatMap((k) => Object.keys(k.properties ?? {})));
-                const kfTextCheck = kfTextKeysJs ? `\nconst _kfIgnored = ${kfTextKeysJs};` : '';
-                const kfIgnored = kfTextKeysJs ? `, ...(_kfIgnored.length ? { ignoredProperties: _kfIgnored, warning: _kfIgnored.join(', ') + ${UNANIMATED_TEXT_KEYS_SENTENCE} } : {})` : '';
+                const kfFilterKeysJs = unanimatedFilterKeysJs((kfSource || []).flatMap((k) => Object.keys(k.properties ?? {})));
+                const kfTextCheck = `\nconst _kfIgnored = ${kfTextKeysJs || '[]'};\nconst _kfFilterIgnored = ${kfFilterKeysJs};`;
+                const kfIgnored = `, ...(_kfIgnored.length || _kfFilterIgnored.length ? { ignoredProperties: _kfIgnored.concat(_kfFilterIgnored), warning: [_kfIgnored.length ? _kfIgnored.join(', ') + ${UNANIMATED_TEXT_KEYS_SENTENCE} : '', _kfFilterIgnored.length ? _kfFilterIgnored.join(', ') + ${UNANIMATED_FILTER_KEYS_SENTENCE} : ''].filter(Boolean).join(' ') } : {})`;
                 return ("\nconst targetId = " +
 String(kfItemRef) +
 ";\nconst _target = (app.getItemById && app.getItemById(targetId))\n  || (app.itemRegistry && app.itemRegistry.get && app.itemRegistry.get(targetId));\nif (!_target) {\n  return { success: false, itemId: targetId, error: 'Item not found: ' + targetId };\n}\nconst _kfItem = _target.item || _target;\nconst _prevKeys = (_kfItem.data && Array.isArray(_kfItem.data.keyframes)) ? _kfItem.data.keyframes.length : 0;\napp.addAnimation(targetId, " +
@@ -5543,7 +5597,9 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
     }
     generateAgentExport(input) {
         const validated = AgentExportInputSchema.parse(input);
-        const { platform, format, quality, framing, duration, estimateOnly, scale, fps, pdf: pdfOpts, region, time: stillTime, maxBytes, loop: gifLoop, broadcast, broadcastHeadroom, bitrate, minBitrate, bitrateMode, audioCodec, transparent, alphaQuantizer, deterministic, motionBlur, ad: adOpts, frames, startTime } = validated;
+        const { platform, format, quality, framing, duration, estimateOnly, scale, fps, pdf: pdfOpts, region, time: stillTime, maxBytes, loop: gifLoop, broadcast, broadcastHeadroom, bitrate, minBitrate, bitrateMode, audioCodec, transparent, alphaQuantizer, deterministic: askedDeterministic, motionBlur, ad: adOpts, frames, startTime } = validated;
+        // Every video is deterministic unless the caller opts out (owner, 2026-11-07), so every receipt says whether its file repeats.
+        const deterministic = askedDeterministic ?? (format === 'mp4' || format === 'webm');
         // Encoder options (FxTool 16719759); the schema keeps them to mp4 / webm.
         const videoEncodeOpts = {};
         // A RANGE of the timeline (FxTool #250): frames for t in [startTime, startTime + duration), each exactly the frame
@@ -6205,10 +6261,10 @@ String(videoDuration) +
 ".264 needs even dimensions, so\n  // 1200x675 came out 1200x676 — and platform specs are exact-pixel. The\n  // result's dimensions become what the file IS, and fidelity says why.\n  const __vd = __vr && __vr.dimensions;\n  if (result && result.success && __vd && Array.isArray(__vd.requested) && Array.isArray(__vd.output)\n      && (__vd.requested[0] !== __vd.output[0] || __vd.requested[1] !== __vd.output[1])) {\n    result.dimensions = { width: __vd.output[0], height: __vd.output[1] };\n    result.fidelity = result.fidelity || { warnings: [] };\n    result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'dimensions_rounded',\n      message: 'the file is ' + __vd.outpu" +
 "t[0] + 'x' + __vd.output[1] + ', not the requested ' + __vd.requested[0] + 'x' + __vd.requested[1] + ': H.264 needs even dimensions, so an odd side was rounded up by 1 px (the extra row / column is background). For an exact-pixel spec, use an even canvas size, or crop the extra line when re-encoding (ffmpeg -vf crop=' + __vd.requested[0] + ':' + __vd.requested[1] + ':0:0).' }]);\n    if (result.fidelity.note) delete result.fidelity.note;\n  }\n" +
 String(deterministic ? ("  // DETERMINISTIC: the container timestamps are pinned either way; the PIXELS\n  // are only identical run to run on the software encoder, because the\n  // browser may pick a different hardware backend each time (FxTool\n  // e34ae03d: 92/255 between backends, 2/255 run to run on hardware). The\n  // engine requests software and reports what it got.\n  // Where the studio says outright whether the file repeats (bitExact, FxTool\n  // PR #31: it test-encodes and keeps whichever encoder does — often the\n  // HARDWARE one on a Mac, since Chrome's software H.264 is not repeatable at\n  // some sizes), that answer decides; the encoder name is only the fallback\n  // for studios that do not r" +
-"eport it.\n  if (result && result.success) {\n    const __hw = __vr && __vr.hardwareAcceleration;\n    const __exact = __vr && typeof __vr.bitExact === 'boolean' ? __vr.bitExact : null;\n    if (__exact === false) {\n      result.fidelity = result.fidelity || { warnings: [] };\n      result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'determinism_not_pinned',\n        ...(__vr && __vr.cause ? { cause: __vr.cause } : {}),\n        message: 'deterministic was asked for, but no encoder on this machine repeats byte for byte at this size (the studio test-encoded and checked' + (__vr && __vr.cause === 'h264-threaded' ? ': the software H.264 encoder is multi-threaded and " +
-"takes no fixed quantizer' : '') + '). What still holds: the frames fed to the encoder are identical (compare frameDigest, not sha256), and the container is identical apart from the encoded samples. Do not cache this file by hash; export WebM for a byte-identical file.' }]);\n      if (result.fidelity.note) delete result.fidelity.note;\n    } else if (__exact === null && __hw !== 'prefer-software') {\n      result.fidelity = result.fidelity || { warnings: [] };\n      result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'determinism_not_pinned',\n        message: __hw\n          ? 'deterministic was asked for, but the encoder ran with hardwareAcceleration ' + JSON.str" +
-"ingify(__hw) + ': the container is pinned, the pixels may still differ slightly between runs (hardware encoders vary). Do not cache this file by hash.'\n          : 'deterministic pinned the container timestamps, but this studio does not report which encoder backend ran, so the pixels may differ slightly between runs if the browser switches between hardware and software encoding. Do not rely on byte-identical files from this studio.' }]);\n      if (result.fidelity.note) delete result.fidelity.note;\n    }\n  }\n"
-
+"eport it.\n  if (result && result.success) {\n    const __hw = __vr && __vr.hardwareAcceleration;\n    const __exact = __vr && typeof __vr.bitExact === 'boolean' ? __vr.bitExact : null;\n    if (__exact === false) {\n      result.fidelity = result.fidelity || { warnings: [] };\n      result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'determinism_not_pinned',\n        ...(__vr && __vr.determinism && __vr.determinism.cause ? { cause: __vr.determinism.cause } : {}),\n        message: 'this file will not repeat byte for byte: no encoder on this machine repeats at this size (the studio test-encoded and checked' + (__vr && __vr.determinism && __vr.determinism.cause === " +
+"'h264-threaded' ? ': the software H.264 encoder varies run to run at this size on this many CPUs' : '') + '). What still holds: the frames fed to the encoder are identical (compare frameDigest, not sha256), and the container is identical apart from the encoded samples. Do not cache this file by hash. For a byte-identical file, export WebM, or export_png_sequence (pinepaper_interchange) and encode the frames with your own FFmpeg, which the server does not provide.' }]);\n      if (result.fidelity.note) delete result.fidelity.note;\n    } else if (__exact === null && __hw !== 'prefer-software') {\n      result.fidelity = result.fidelity || { warnings: [] };\n      result.fidelity.warnings = " +
+"(result.fidelity.warnings || []).concat([{ code: 'determinism_not_pinned',\n        message: __hw\n          ? 'this file may not repeat byte for byte: the encoder ran with hardwareAcceleration ' + JSON.stringify(__hw) + ': the container is pinned, the pixels may still differ slightly between runs (hardware encoders vary). Do not cache this file by hash.'\n          : 'deterministic pinned the container timestamps, but this studio does not report which encoder backend ran, so the pixels may differ slightly between runs if the browser switches between hardware and software encoding. Do not rely on byte-identical files from this studio.' }]);\n      if (result.fidelity.note) delete result.fi" +
+"delity.note;\n    }\n  }\n"
 
 
 
@@ -6294,9 +6350,14 @@ String((() => {
 String(JSON.stringify(format)) +
 ") !== -1) {\n    try {\n      const __hud = app.screenSpaceItems() || [];\n      if (__hud.length) {\n        result.fidelity = result.fidelity || { warnings: [] };\n        result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'screen_space_ignored', message: __hud.length + ' screen-space (HUD) item(s) are written at their frame coordinates in world space: " +
 String(format) +
-" has no camera frame, so they do not stay fixed under the camera move. Export mp4, webm, gif or png to keep them fixed.' }]);\n      }\n    } catch (_) { /* the export stands */ }\n  }\n  // WHICH STUDIO MADE THIS FILE (D92): a service worker can serve a stale\n  // build right after a deploy, and a retest then judges old code. The\n  // engine's own identity, version + build sha, rides on every export reply.\n  try { if (result && typeof result === 'object' && app.buildId) result.studioBuild = app.buildId; } catch (_) { /* older studio */ }\n  // A STALE STUDIO (D92): the file was made by an old build. Said in the\n  // fidelity warnings the reply shows, not only as a field.\n  try {\n   " +
-" const __bs = app.buildStatus ? app.buildStatus() : null;\n    if (result && typeof result === 'object' && __bs) {\n      result.liveBuild = __bs.liveBuildId;\n      if (__bs.stale) {\n        result.stale = true;\n        result.fidelity = result.fidelity || { warnings: [] };\n        result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'stale_build', message: 'this studio is running an old build (' + __bs.buildId + '; the live build is ' + __bs.liveBuildId + '): this file was made by the old code, so it may differ from what the live build makes. pinepaper_clear_canvas (or pinepaper_agent_start_job) loads the live build; it empties the canvas, so rebuild the scene a" +
-"nd export again if the difference matters.' }]);\n      }\n    }\n  } catch (_) { /* older studio */ }\n  // RELIGHT (FxTool D5): applied to png / pdf / mp4 / webm, not gif / apng\n  // or the vector formats; and it is what makes a video export slow.\n  if (result && result.success && typeof app.getRelight === 'function') {\n    try {\n      const __rl = app.getRelight();\n      if (__rl && __rl.enabled) {\n        result.fidelity = result.fidelity || { warnings: [] };\n        if (['png', 'jpg', 'webp', 'pdf', 'mp4', 'webm'].indexOf(" +
+" has no camera frame, so they do not stay fixed under the camera move. Export mp4, webm, gif or png to keep them fixed.' }]);\n      }\n    } catch (_) { /* the export stands */ }\n  }\n  // A SOUND PAST THE END (SNDTAIL31): placed, accepted, and not in the file. The video's length decides, as it should; it is said.\n  if (result && result.success && ['mp4', 'webm'].indexOf(" +
+String(JSON.stringify(format)) +
+") !== -1 && app.itemRegistry && typeof app.itemRegistry.getAll === 'function') {\n    try {\n      const __end = (result.video && result.video.durationS) || " +
+String(JSON.stringify(duration ?? null)) +
+";\n      const __late = __end ? app.itemRegistry.getAll().filter(function (e) { const d = (e.item || e).data; return d && d.isSoundChip && typeof d.clipStartTime === 'number' && d.clipStartTime >= __end; }) : [];\n      if (__late.length) {\n        result.fidelity = result.fidelity || { warnings: [] };\n        result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'sound_after_end', message: __late.length + ' sound(s) start at or after the end of this ' + __end + ' s export, so they are not in the file: ' + __late.map(function (e) { return (e.item || e).data.registryId + ' at ' + (e.item || e).data.clipStartTime + ' s'; }).slice(0, 10).join(', ') + '.' }]);\n      }" +
+"\n    } catch (_) { /* the export stands */ }\n  }\n  // WHICH STUDIO MADE THIS FILE (D92): a service worker can serve a stale\n  // build right after a deploy, and a retest then judges old code. The\n  // engine's own identity, version + build sha, rides on every export reply.\n  try { if (result && typeof result === 'object' && app.buildId) result.studioBuild = app.buildId; } catch (_) { /* older studio */ }\n  // A STALE STUDIO (D92): the file was made by an old build. Said in the\n  // fidelity warnings the reply shows, not only as a field.\n  try {\n    const __bs = app.buildStatus ? app.buildStatus() : null;\n    if (result && typeof result === 'object' && __bs) {\n      result.liveB" +
+"uild = __bs.liveBuildId;\n      if (__bs.stale) {\n        result.stale = true;\n        result.fidelity = result.fidelity || { warnings: [] };\n        result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'stale_build', message: 'this studio is running an old build (' + __bs.buildId + '; the live build is ' + __bs.liveBuildId + '): this file was made by the old code, so it may differ from what the live build makes. pinepaper_clear_canvas (or pinepaper_agent_start_job) loads the live build; it empties the canvas, so rebuild the scene and export again if the difference matters.' }]);\n      }\n    }\n  } catch (_) { /* older studio */ }\n  // RELIGHT (FxTool D5): appl" +
+"ied to png / pdf / mp4 / webm, not gif / apng\n  // or the vector formats; and it is what makes a video export slow.\n  if (result && result.success && typeof app.getRelight === 'function') {\n    try {\n      const __rl = app.getRelight();\n      if (__rl && __rl.enabled) {\n        result.fidelity = result.fidelity || { warnings: [] };\n        if (['png', 'jpg', 'webp', 'pdf', 'mp4', 'webm'].indexOf(" +
 String(JSON.stringify(format)) +
 ") === -1) {\n          result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'relight_not_applied', message: 'a relight rig is set, but ' + " +
 String(jsLiteral(format)) +
@@ -7343,6 +7404,12 @@ String(jsLiteral(format)) +
 
 
 
+
+
+
+
+
+
 
 
 
@@ -9353,7 +9420,9 @@ String(jsLiteral(templateId)) +
 ).trim();
     }
     generateImportImage(input) {
-        const { url, position, maxWidth, maxHeight, mask, smoothing, maxEdge, nativeSize, shadowColor, shadowBlur, shadowOffset, name } = input;
+        const { url, position, maxWidth, maxHeight, mask, smoothing, maxEdge, nativeSize, shadowColor, shadowBlur, shadowOffset, name, opacity, blendMode, scale, loop } = input;
+        const look = { ...(opacity !== undefined ? { opacity } : {}), ...(blendMode !== undefined ? { blendMode } : {}), ...(scale !== undefined ? { scale } : {}) };
+        const hasLook = Object.keys(look).length > 0;
         // IMPORTSHADOW: the shadow keys, applied through the engine's own modify
         // door once the image is placed (and masked) — the route modify_item takes.
         const shadow = {};
@@ -9375,6 +9444,7 @@ String(jsLiteral(templateId)) +
             maxWidth !== undefined ? `maxWidth: ${maxWidth}` : '',
             maxHeight !== undefined ? `maxHeight: ${maxHeight}` : '',
             nativeSize ? 'nativeSize: true' : '',
+            loop !== undefined ? `loop: ${JSON.stringify(loop)}` : '',
         ].filter(Boolean);
         const optsLiteral = optParts.length ? `{ ${optParts.join(', ')} }` : '{}';
         return ("\n// Import image from URL\n(async function() {\n  if (!app.imageTools) {\n    return { error: 'Image tools not available. Make sure PinePaper Studio is loaded.' };\n  }\n  try {\n    // FETCH IT OURSELVES FIRST, to find out WHY when it fails.\n    //\n    // uploadFromURL sets img.src and rejects with a bare \"Failed to load image\n    // from URL\" — an <img> onerror genuinely carries no reason, so that message\n    // is the browser's limit rather than the engine being unhelpful. fetch()\n    // has the reason: a status code, a CORS rejection, a refused connection, a\n    // DNS failure. A caller cannot debug what the tool will not show them.\n    //\n    // The bytes then go in as a DA" +
@@ -9406,6 +9476,16 @@ String(mask ? `    // A MASK REPLACES THE RASTER (round 8 DD, 4.10). applyMask b
     if (app.itemRegistry && typeof app.itemRegistry.rebind === 'function') app.itemRegistry.rebind(itemId, masked);
     placed = masked;
 ` : '') +
+String(hasLook ? `    // opacity, blendMode, scale: read by modify, on what is drawn. They were not import arguments (OPACIMP31, BLENDIMP31, IMGSCALE31).
+    let __look = null;
+    {
+      let __ok = false;
+      try { __ok = app.modifyItem(itemId, ${JSON.stringify(look)}) !== false; } catch (_) { __ok = false; }
+      __look = __ok
+        ? { applied: true, opacity: placed.opacity, blendMode: placed.blendMode }
+        : { applied: false, warning: 'the image was imported but ' + ${jsLiteral(Object.keys(look).join(', '))} + ' was not applied: set it with pinepaper_modify_item on ' + itemId + '.' };
+    }
+` : '') +
 String(hasShadow ? `    // The shadow goes on what is DRAWN, after a mask has replaced the raster.
     let __shadow = null;
     {
@@ -9428,6 +9508,8 @@ String(name ? `\n      name: ${JSON.stringify(name)},` : '') +
 "\n      bounds: { x: b.x, y: b.y, width: b.width, height: b.height }" +
 String(mask ? `,\n      mask: ${jsLiteral(mask)}` : '') +
 String(hasShadow ? ',\n      shadow: __shadow' : '') +
+String(loop !== undefined ? ",\n      playback: (raster && raster.data && raster.data.animatedImage && raster.data.animatedImage.loop !== undefined) ? { applied: true, plays: raster.data.animatedImage.loop } : { applied: false, warning: 'loop was not applied: this image does not animate in this studio. Animated GIF, WebP and APNG do.' }" : '') +
+String(hasLook ? ',\n      look: __look' : '') +
 ",\n      // Stored smaller than its source (the studio's cap): said, with the\n      // way to keep every pixel. The studio reports native size where it can.\n      ...((entry && entry.nativeWidth && entry.width && entry.nativeWidth > entry.width)\n        ? { stored: { width: entry.width, height: entry.height }, native: { width: entry.nativeWidth, height: entry.nativeHeight },\n            note: 'the studio stored this image at ' + entry.width + 'x' + entry.height + ' (its source is ' + entry.nativeWidth + 'x' + entry.nativeHeight + '). Pass maxEdge: \"native\" to keep every pixel.' }\n        : {})\n    };\n  } catch (e) {\n    return { error: 'Failed to import image: ' + e.message };\n " +
 " }\n})();\n"
 
@@ -9519,6 +9601,12 @@ String(hasShadow ? ',\n      shadow: __shadow' : '') +
 
 
 
+
+
+
+
+
+
 
 
 
@@ -16238,10 +16326,8 @@ String(op) +
 }
 /**
  * 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.
+ * studio without it refuses by name instead of a TypeError. The engine's custom action is not offered: it needs a
+ * function, which JSON cannot carry.
  */
 function generateContraptionCode(input) {
     const refuse = (method) => `if (typeof app.${method} !== 'function') {
@@ -16252,7 +16338,7 @@ function generateContraptionCode(input) {
     const body = () => {
         switch (input.action) {
             case 'add_contraption': {
-                const targets = [...new Set((input.actions ?? []).flatMap((a) => (a.type === 'modifyItem' ? [a.targetId] : [])))];
+                const targets = [...new Set((input.actions ?? []).flatMap((a) => ('targetId' in a ? [a.targetId] : [])))];
                 const config = {
                     ...(input.contraptionId ? { id: input.contraptionId } : {}),
                     sourceEvent: input.sourceEvent,
@@ -16266,14 +16352,20 @@ function generateContraptionCode(input) {
   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'" : ''} };`;
+    ...(missing.length ? { warning: 'no item has the id ' + missing.join(', ') + ' yet: the rule does nothing to it until one does' } : {}), };`;
             }
             case 'remove_contraption':
                 return `${refuse('removeContraption')}
   const removed = app.removeContraption(${jsLiteral(input.contraptionId)});
   return removed ? { success: true, action: 'remove_contraption', contraptionId: ${jsLiteral(input.contraptionId)} }
     : { success: false, action: 'remove_contraption', error: 'no rule has the id ' + ${jsLiteral(input.contraptionId)} };`;
+            case 'clear_contraptions':
+                return `${refuse('clearContraptions')}
+  app.clearContraptions();
+  return { success: true, action: 'clear_contraptions' };`;
+            case 'clear_variables':
+                return `${refuse('clearVariables')}
+  return { success: true, action: 'clear_variables', scope: ${scope}, removed: app.clearVariables(${scope}) };`;
             case 'list_contraptions':
                 return `${refuse('listContraptions')}
   return { success: true, action: 'list_contraptions', contraptions: app.listContraptions() };`;