@pinepaper.studio/mcp-server 1.6.32 → 1.6.33

package/dist/types/code-generator.js

@@ -7,7 +7,7 @@
 import { compileChoreography } from '../tools/choreograph.js';
 import { compileBatchTimelines, emitTimelineOpBody } from '../tools/timeline.js';
 import { normalizeSvgSize } from '../utils/svg-size.js';
-import { WORLD3D_COLOR_PATHS, PATTERN_KINDS, EXPRESSION_FUNCTION_ARITY, EXPRESSION_CONSTANTS, EXPRESSION_REJECTED, RELATION_PARAM_KEYS, ANIMATION_OPTION_KEYS } from '../tools/engine-lists.js';
+import { WORLD3D_COLOR_PATHS, PATTERN_KINDS, EXPRESSION_FUNCTION_ARITY, EXPRESSION_CONSTANTS, EXPRESSION_REJECTED, RELATION_PARAM_KEYS, RELATION_LOOP_PARAMS, ANIMATION_OPTION_KEYS, FILTER_TYPES, FILTER_PARAM_RANGES } from '../tools/engine-lists.js';
 import { expressionGrammarText } from '../tools/expression-grammar.js';
 import { REQUIRED_ENGINE_METHODS, OPTIONAL_ENGINE_METHODS } from '../tools/engine-methods.js';
 import { NORMALIZE_PARAM_READS, MODIFY_CHANGE_READS } from '../tools/shape-params.js';
@@ -1483,10 +1483,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 +1508,25 @@ function equationFlipNote(relationType, params) {
         return null;
     return 'params.equation is read with y UP (flipY defaults to true), so on screen the curve is mirrored about cy. If you wrote it in screen coordinates (y down), add flipY: false to the equation.';
 }
-function unreadOptionWarning(relationType, params, injected) {
+/** What a built-in relation reads: its rule's params, and what the relation loop reads on every relation. */
+function relationReads(relationType) {
     const keys = typeof relationType === 'string' ? RELATION_PARAM_KEYS[relationType] : undefined;
+    return keys ? [...keys, ...RELATION_LOOP_PARAMS] : undefined;
+}
+function unreadOptionWarning(relationType, params, injected) {
+    const keys = relationReads(relationType);
     return keys ? unreadKeysWarning(String(relationType), keys, params, injected) : null;
 }
+const unreadKeys = (keys, params, injected = []) => keys && params && typeof params === 'object' ? Object.keys(params).filter((k) => !keys.includes(k) && !injected.includes(k)) : [];
+/**
+ * A relation reply's fields for its options: the unread keys as data (ignoredOptions, which the reply's
+ * ignoredArguments is built from) beside the sentence. Built-ins are known here, a custom relation only in the page.
+ */
+function relationOptionFields(relationType, params, key, injected = []) {
+    const unread = unreadKeys(relationReads(relationType), params, injected);
+    const warning = relationOptionWarning(relationType, params, injected);
+    return `${unread.length ? `, ignoredOptions: ${jsLiteral(unread)}` : ''}${warning ? `, ${key}: ${jsLiteral(warning)}` : ''}${customOptionWarningJs(relationType, params, key, injected)}`;
+}
 /** The keys of `params` outside `keys`, named with a "did you mean" and the list that is read; null when all are read. */
 function unreadKeysWarning(reader, keys, params, injected = []) {
     if (!params || typeof params !== 'object')
@@ -1568,7 +1583,7 @@ String(jsLiteral(targetId)) +
 ", " +
 String(jsLiteral(relationType)) +
 ", " +
-String(JSON.stringify(params, null, 2)) + ");\n  if (!success) {\n    const __why = " + String(relationRefusalReasonJs(jsLiteral(relationType))) + ";\n    return { success: false, relationType: " + String(jsLiteral(relationType)) + ", error: 'the studio refused the ' + " + String(jsLiteral(relationType)) + " + ' relation between ' + " + String(jsLiteral(sourceId)) + " + ' and ' + " + String(jsLiteral(targetId)) + " + (__why ? ': ' + __why : '.') };\n  }\n  app.historyManager.saveState();\n  return { success: true, sourceId: " + String(jsLiteral(sourceId)) + ", targetId: " + String(jsLiteral(targetId)) + ", relationType: " + String(jsLiteral(relationType)) + String((() => { const w = relationOptionWarning(relationType, params); return w ? `, warning: ${jsLiteral(w)}` : ''; })()) + 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 +1659,18 @@ export function normalizeEmitterSpec(spec, assumeDefaultCount = true) {
         for (const k of ['velocities', 'offsets'])
             if (out[k] !== undefined)
                 out[k] = pairs(out[k]);
+        // A trail's single offset is one pair; the studio reads [x, y] and dropped {x, y} with nothing said (TRAILOFF31).
+        const off = out.offset;
+        if (off && typeof off === 'object' && !Array.isArray(off) && typeof off.x === 'number' && typeof off.y === 'number')
+            out.offset = [off.x, off.y];
         return out;
     };
     const out = fix(spec);
+    // rate, start and end drive a trail. Beside bursts they drew nothing and said nothing (EMITCONT31).
+    const trailOnly = ['rate', 'start', 'end'].filter((k) => spec[k] !== undefined);
+    if (trailOnly.length && Array.isArray(spec.bursts) && spec.mode !== 'trail' && spec.target === undefined) {
+        warnings.push(`${trailOnly.join(', ')} ${trailOnly.length > 1 ? 'are' : 'is'} not read by a burst emitter, so ${trailOnly.length > 1 ? 'they had' : 'it had'} no effect: only the bursts' own count is drawn. For particles over time, add bursts, or use mode 'trail' with a target.`);
+    }
     if (Array.isArray(spec.bursts))
         out.bursts = spec.bursts.map((b) => (b && typeof b === 'object' ? fix(b) : b));
     // The studio's default count per burst (ParticleEmitter DEFAULT_LOOK).
@@ -2072,6 +2096,24 @@ function unanimatedTextKeysJs(keys) {
     return ${JSON.stringify(spec)}.filter(function(s) { return !s.names.some(function(n) { return __names.indexOf(n) >= 0; }); }).map(function(s) { return s.key; });
   })()`;
 }
+/**
+ * An image filter's parameter as a key: keyframe_animate stores it, and a filter does not read a track, so the item
+ * never changes with success:true (FILTKEY31). Asked of the same list, so a studio that starts animating one is believed.
+ */
+const FILTER_PARAM_KEYS = new Set([...Object.values(FILTER_PARAM_RANGES).flatMap((p) => Object.keys(p)), ...FILTER_TYPES].filter((k) => !['color', 'opacity', 'scale', 'x', 'y', 'rotation', 'size', 'radius', 'width', 'height', 'value', 'amount'].includes(k)));
+function unanimatedFilterKeysJs(keys) {
+    const filterKeys = [...new Set(keys)].filter((k) => FILTER_PARAM_KEYS.has(k));
+    if (!filterKeys.length)
+        return '[]';
+    return `(function() {
+    let __l = null;
+    try { __l = typeof app.listAnimatableProperties === 'function' ? app.listAnimatableProperties() : null; } catch (_) { __l = null; }
+    if (!__l || !__l.properties) return [];
+    const __names = __l.properties.map(function(p) { return p && p.name; });
+    return ${JSON.stringify(filterKeys)}.filter(function(k) { return __names.indexOf(k) < 0; });
+  })()`;
+}
+const UNANIMATED_FILTER_KEYS_SENTENCE = `' is an image filter setting and not an animatable property, so the key had no effect. Set a fixed value with pinepaper_image_filter or pinepaper_add_filter, and animate opacity or scale for a change over time.'`;
 /** The sentence for the keys unanimatedTextKeysJs found, built in the page. */
 const UNANIMATED_TEXT_KEYS_SENTENCE = `' is not an animatable property in this studio (app.listAnimatableProperties does not list it), so it had no effect: a key animates only where that list names it. Here, set a fixed value with pinepaper_modify_item, or animate fontSize or scaleX. For a skew, key skewX / skewY (degrees) where the studio lists them, else a transform matrix track.'`;
 /**
@@ -2097,12 +2139,6 @@ function keyframeResultNotes(keyframes, { loop = false, append = false, easingAt
         ? `, propertyGaps: ${JSON.stringify(gaps.slice(0, 10))}, gapWarning: ${JSON.stringify(`${gaps.length} keyframe(s) leave out a property other keys animate (${[...new Set(gaps.flatMap((g) => g.missing))].join(', ')}). The engine can break that property's track at such a key; repeat the value on every key — hold it by repeating the previous value.`)}`
         : '';
     const first = [...keyframes].sort((a, b) => a.time - b.time)[0];
-    // loop:true repeats in the editor; an export of the measured build played
-    // the keyframes ONCE and held (round 7, 2.24). Said where it is set, with
-    // the two ways that do export, until the engine's export clock wraps them.
-    const loopNote = loop
-        ? `, loopNote: ${JSON.stringify('loop:true repeats in the editor, but has been measured playing ONCE in an exported video and then holding the last keyframe. For an export longer than one cycle, check a frame in the second cycle — if it holds, write the keyframes out per cycle, or use a loop preset (pinepaper_animate), which does cycle in export.')}`
-        : '';
     // SIZEKEY-PAIR (mcp-cloud #28): on a studio before FxTool #262, x (or
     // position) keyed beside fontSize on one text item drifted in an export: the
     // size was applied after the position, and a text resizes around its anchor.
@@ -2114,7 +2150,7 @@ function keyframeResultNotes(keyframes, { loop = false, append = false, easingAt
     const easingNote = easingAt !== 'departure' && first?.easing && first.easing !== 'linear'
         ? `, note: ${JSON.stringify(`easing '${first.easing}' is on the first keyframe, where it has no effect by default: easing shapes the segment ARRIVING at a keyframe. Put it on the keyframe you are moving to, or pass easingAt: 'departure' to read every easing as the move LEAVING its key (current studio).`)}`
         : '';
-    return `${easingNote}${sizekeyPairNote}${loopNote}${gapNote}`;
+    return `${easingNote}${sizekeyPairNote}${gapNote}`;
 }
 function generateKeyframeAnimateCode(itemId, keyframes, duration, loop = false, timeOffset, clipInPoint, clipOutPoint, timeUnits, append = false, easingAt) {
     const ID = jsLiteral(itemId); // caller text: a quoted literal, never spliced raw
@@ -2172,9 +2208,12 @@ String(JSON.stringify(levelKeys)) +
     const textKeyCheck = textKeysJs ? `
   const __ignored = ${textKeysJs};
   if (__ignored.length) __warn.push(__ignored.join(', ') + ${UNANIMATED_TEXT_KEYS_SENTENCE});` : '';
+    const filterKeyCheck = `
+  const __filterIgnored = ${unanimatedFilterKeysJs(keyframes.flatMap((k) => Object.keys(k.properties ?? {})))};
+  if (__filterIgnored.length) __warn.push(__filterIgnored.join(', ') + ${UNANIMATED_FILTER_KEYS_SENTENCE});`;
     const easingAtCheck = easingAt !== undefined ? `
   if (__opts && Object.prototype.hasOwnProperty.call(__opts, 'easingAt')) __warn.push('easingAt ' + ${JSON.stringify(JSON.stringify(easingAt))} + ' was not applied: this studio predates it, so every easing was read as the move ARRIVING at its key. Put each easing on the key the move goes to instead.');` : '';
-    const runtimeWarning = `${textKeysJs ? ', ...(__ignored.length ? { ignoredProperties: __ignored } : {})' : ''}, ...(__warn.length ? { warning: __warn.join(' ') } : {})`;
+    const runtimeWarning = `, ...(${textKeysJs ? '__ignored.length || ' : ''}__filterIgnored.length ? { ignoredProperties: ${textKeysJs ? '__ignored.concat(__filterIgnored)' : '__filterIgnored'} } : {}), ...(__warn.length ? { warning: __warn.join(' ') } : {})`;
     const addAnimTarget = itemId.startsWith('$') ? '_targetId' : `${ID}`;
     return ("\n// Apply keyframe animation to " +
 String(ID) +
@@ -2190,6 +2229,7 @@ String(keyframesJson) +
 ", __opts);\n  const __warn = [];" +
 String(easingAtCheck) +
 String(textKeyCheck) +
+String(filterKeyCheck) +
 "\n  const __now = (__ki && __ki.data && Array.isArray(__ki.data.keyframes)) ? __ki.data.keyframes.map(function(k) { return k && k.time; }) : [];\n  const __kept = __prev.every(function(t) { return __now.indexOf(t) >= 0; });" +
 String(append ? `
   // Property gaps across the merged track (the same check a single call makes
@@ -2209,8 +2249,7 @@ String(calculatedDuration) +
 ", loop: " +
 String(loop) +
 String(append ? ', append: true' : '') +
-", ...(__track ? { track: __track } : {})" +
-String(append ? `, ...(__gaps.length ? { propertyGaps: __gaps.slice(0, 10), gapWarning: __gaps.length + ' key(s) of the merged track leave out a property other keys animate (' + __gaps.reduce(function(a, g) { g.missing.forEach(function(p) { if (a.indexOf(p) < 0) a.push(p); }); return a; }, []).join(', ') + '). The engine can break that property at such a key; give each key the full set — hold a value by repeating it.' } : {})` : '') + String(timeOffset !== undefined ? `, timeOffset: ${timeOffset}` : '') + String(clipInPoint !== undefined ? `, clipInPoint: ${clipInPoint}` : '') + String(clipOutPoint !== undefined ? `, clipOutPoint: ${clipOutPoint}` : '') + String(__notes) + String(runtimeWarning) + " };\n})();\n").trim();
+", ...(__track ? { track: __track } : {})" + String(append ? `, ...(__gaps.length ? { propertyGaps: __gaps.slice(0, 10), gapWarning: __gaps.length + ' key(s) of the merged track leave out a property other keys animate (' + __gaps.reduce(function(a, g) { g.missing.forEach(function(p) { if (a.indexOf(p) < 0) a.push(p); }); return a; }, []).join(', ') + '). The engine can break that property at such a key; give each key the full set — hold a value by repeating it.' } : {})` : '') + String(timeOffset !== undefined ? `, timeOffset: ${timeOffset}` : '') + String(clipInPoint !== undefined ? `, clipInPoint: ${clipInPoint}` : '') + String(clipOutPoint !== undefined ? `, clipOutPoint: ${clipOutPoint}` : '') + String(__notes) + String(runtimeWarning) + " };\n})();\n").trim();
 }
 /**
  * Template for executing generators
@@ -3554,7 +3593,7 @@ String(JSON.stringify(validated.presetId)) +
         const code = stepNoTarget
             ? `(function() {
   if (!${STEP_ACTIVE_TARGETLESS_JS}) return { success: false, relationType: 'on_event_step_active', error: ${jsLiteral(stepNoTarget)} };
-  return ${built.trim().replace(/;$/, '')};
+  ${asReturningBody(built)}
 })();`
             : built;
         // NO TARGET (event reactions like on_event_play_sound, self-relations): the
@@ -4234,7 +4273,7 @@ if (typeof _gen === 'function') {
 })();`);
         }
         // Establish relations
-        for (const relation of relations) {
+        for (const [relationIndex, relation] of relations.entries()) {
             const { source, target, type, params = {} } = relation;
             const paramsStr = JSON.stringify(params);
             const specProblem = relationSpecProblem(type, params, target, 'no-page');
@@ -4264,7 +4303,10 @@ String(jsLiteral(type)) +
 String(jsLiteral(source)) +
 ", target: " +
 String(jsLiteral(target)) +
-", type: " + String(jsLiteral(type)) + " });\n    } else {\n      const __why = " + String(relationRefusalReasonJs(jsLiteral(type))) + ";\n      (results.relationsRefused = results.relationsRefused || []).push({ source: " + String(jsLiteral(source)) + ", target: " + String(jsLiteral(target)) + ", type: " + String(jsLiteral(type)) + ", reason: __why || 'the studio refused it' });\n      results.success = false;\n      results.error = 'the studio refused ' + results.relationsRefused.length + ' relation(s): ' + results.relationsRefused.map(function(r) { return r.type + ' ' + r.source + ' -> ' + r.target + ' (' + r.reason + ')'; }).join('; ') + '. The items were created.';\n    }\n  }\n})();\n"));
+", type: " +
+String(jsLiteral(type)) +
+" });\n      const __o = { _: 0" +
+String(relationOptionFields(type, params, 'warning')) + " };\n      if (__o.warning) (results.optionWarnings = results.optionWarnings || []).push(__o.warning);\n      if (__o.ignoredOptions) (results.ignoredOptions = results.ignoredOptions || []).push.apply(results.ignoredOptions, __o.ignoredOptions.map(function(k) { return 'relations[" + String(relationIndex) + "].params.' + k; }));\n    } else {\n      const __why = " + String(relationRefusalReasonJs(jsLiteral(type))) + ";\n      (results.relationsRefused = results.relationsRefused || []).push({ source: " + String(jsLiteral(source)) + ", target: " + String(jsLiteral(target)) + ", type: " + String(jsLiteral(type)) + ", reason: __why || 'the studio refused it' });\n      results.success = false;\n      results.error = 'the studio refused ' + results.relationsRefused.length + ' relation(s): ' + results.relationsRefused.map(function(r) { return r.type + ' ' + r.source + ' -> ' + r.target + ' (' + r.reason + ')'; }).join('; ') + '. The items were created.';\n    }\n  }\n})();\n"));
         }
         // Apply animations
         for (const animation of animations) {
@@ -5234,7 +5276,7 @@ const targetId = ${animItemRef};
 const item = app.getItemById(targetId);
 if (!item) throw new Error('Item not found: ' + targetId);
 app.animate(item, { animationType: ${JSON.stringify(String(op.animationType))}, ...${animOpts} });
-return { itemId: targetId, animationType: ${JSON.stringify(String(op.animationType))}${(() => { const w = animationOptionWarning(op.animationOptions); return w ? `, warning: ${jsLiteral(w)}` : ''; })()} };
+return { itemId: targetId, animationType: ${JSON.stringify(String(op.animationType))}${(() => { const w = animationOptionWarning(op.animationOptions); return w ? `, ignoredOptions: ${jsLiteral(unreadKeys(ANIMATION_OPTION_KEYS, op.animationOptions))}, warning: ${jsLiteral(w)}` : ''; })()} };
 `;
             case 'relation':
                 const srcRef = batchRef(op.sourceId);
@@ -5295,7 +5337,7 @@ String(type) +
 ", sourceIds: __failed, error: " +
 String(op.update === true ? '__why' : `'the studio refused the ' + ${type} + ' relation for ' + __failed.join(', ') + ' — nothing was bound' + (__why ? ': ' + __why : '.')`) +
 " };\n}\nreturn { success: true, relationType: " +
-String(type) + ", " + String(op.update === true ? 'updated' : 'bound') + ": __done, targetId" + String(glob ? ', count: __members.length' : '') + String((() => { const w = relationOptionWarning(op.relationType, op.relationOptions, ['index', 'count', 'pattern']); return w ? `, optionWarning: ${jsLiteral(w)}` : ''; })()) + 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 +5356,7 @@ String(relOpts) +
 ");\n// NOT BOUND IS NOT A SUCCESS (owner rule 1, B119). addRelation answers false\n// when it refuses — spring_follow \"not loaded yet\" — and this op returned\n// { relationId: false } with nothing marking it failed, so the batch said\n// success over a relation that does not exist.\nif (!relationId) {\n  const __why = " +
 String(relationRefusalReasonJs(jsLiteral(op.relationType))) +
 ";\n  return { success: false, relationId: false, sourceId, targetId, relationType: " +
-String(JSON.stringify(op.relationType)) + ",\n    error: 'the studio refused the ' + " + String(JSON.stringify(op.relationType)) + " + ' relation between ' + sourceId + ' and ' + targetId + ' — nothing was bound' + (__why ? ': ' + __why : '.') };\n}\nreturn { relationId, sourceId, targetId, relationType: " + String(JSON.stringify(String(op.relationType))) + String((() => { const w = relationOptionWarning(op.relationType, op.relationOptions); return w ? `, warning: ${jsLiteral(w)}` : ''; })()) + 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 +5444,9 @@ return { itemId: ${batchRef(op.itemId)}, merged: true, mergedInto: ${foldTarget}
                     kfExtra.push(`timeUnits: ${jsLiteral(kfUnits)}`);
                 const kfExtraStr = kfExtra.length > 0 ? `, ${kfExtra.join(', ')}` : '';
                 const kfTextKeysJs = unanimatedTextKeysJs((kfSource || []).flatMap((k) => Object.keys(k.properties ?? {})));
-                const kfTextCheck = kfTextKeysJs ? `\nconst _kfIgnored = ${kfTextKeysJs};` : '';
-                const kfIgnored = kfTextKeysJs ? `, ...(_kfIgnored.length ? { ignoredProperties: _kfIgnored, warning: _kfIgnored.join(', ') + ${UNANIMATED_TEXT_KEYS_SENTENCE} } : {})` : '';
+                const kfFilterKeysJs = unanimatedFilterKeysJs((kfSource || []).flatMap((k) => Object.keys(k.properties ?? {})));
+                const kfTextCheck = `\nconst _kfIgnored = ${kfTextKeysJs || '[]'};\nconst _kfFilterIgnored = ${kfFilterKeysJs};`;
+                const kfIgnored = `, ...(_kfIgnored.length || _kfFilterIgnored.length ? { ignoredProperties: _kfIgnored.concat(_kfFilterIgnored), warning: [_kfIgnored.length ? _kfIgnored.join(', ') + ${UNANIMATED_TEXT_KEYS_SENTENCE} : '', _kfFilterIgnored.length ? _kfFilterIgnored.join(', ') + ${UNANIMATED_FILTER_KEYS_SENTENCE} : ''].filter(Boolean).join(' ') } : {})`;
                 return ("\nconst targetId = " +
 String(kfItemRef) +
 ";\nconst _target = (app.getItemById && app.getItemById(targetId))\n  || (app.itemRegistry && app.itemRegistry.get && app.itemRegistry.get(targetId));\nif (!_target) {\n  return { success: false, itemId: targetId, error: 'Item not found: ' + targetId };\n}\nconst _kfItem = _target.item || _target;\nconst _prevKeys = (_kfItem.data && Array.isArray(_kfItem.data.keyframes)) ? _kfItem.data.keyframes.length : 0;\napp.addAnimation(targetId, " +
@@ -6294,9 +6337,14 @@ String((() => {
 String(JSON.stringify(format)) +
 ") !== -1) {\n    try {\n      const __hud = app.screenSpaceItems() || [];\n      if (__hud.length) {\n        result.fidelity = result.fidelity || { warnings: [] };\n        result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'screen_space_ignored', message: __hud.length + ' screen-space (HUD) item(s) are written at their frame coordinates in world space: " +
 String(format) +
-" has no camera frame, so they do not stay fixed under the camera move. Export mp4, webm, gif or png to keep them fixed.' }]);\n      }\n    } catch (_) { /* the export stands */ }\n  }\n  // WHICH STUDIO MADE THIS FILE (D92): a service worker can serve a stale\n  // build right after a deploy, and a retest then judges old code. The\n  // engine's own identity, version + build sha, rides on every export reply.\n  try { if (result && typeof result === 'object' && app.buildId) result.studioBuild = app.buildId; } catch (_) { /* older studio */ }\n  // A STALE STUDIO (D92): the file was made by an old build. Said in the\n  // fidelity warnings the reply shows, not only as a field.\n  try {\n   " +
-" const __bs = app.buildStatus ? app.buildStatus() : null;\n    if (result && typeof result === 'object' && __bs) {\n      result.liveBuild = __bs.liveBuildId;\n      if (__bs.stale) {\n        result.stale = true;\n        result.fidelity = result.fidelity || { warnings: [] };\n        result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'stale_build', message: 'this studio is running an old build (' + __bs.buildId + '; the live build is ' + __bs.liveBuildId + '): this file was made by the old code, so it may differ from what the live build makes. pinepaper_clear_canvas (or pinepaper_agent_start_job) loads the live build; it empties the canvas, so rebuild the scene a" +
-"nd export again if the difference matters.' }]);\n      }\n    }\n  } catch (_) { /* older studio */ }\n  // RELIGHT (FxTool D5): applied to png / pdf / mp4 / webm, not gif / apng\n  // or the vector formats; and it is what makes a video export slow.\n  if (result && result.success && typeof app.getRelight === 'function') {\n    try {\n      const __rl = app.getRelight();\n      if (__rl && __rl.enabled) {\n        result.fidelity = result.fidelity || { warnings: [] };\n        if (['png', 'jpg', 'webp', 'pdf', 'mp4', 'webm'].indexOf(" +
+" has no camera frame, so they do not stay fixed under the camera move. Export mp4, webm, gif or png to keep them fixed.' }]);\n      }\n    } catch (_) { /* the export stands */ }\n  }\n  // A SOUND PAST THE END (SNDTAIL31): placed, accepted, and not in the file. The video's length decides, as it should; it is said.\n  if (result && result.success && ['mp4', 'webm'].indexOf(" +
+String(JSON.stringify(format)) +
+") !== -1 && app.itemRegistry && typeof app.itemRegistry.getAll === 'function') {\n    try {\n      const __end = (result.video && result.video.durationS) || " +
+String(JSON.stringify(duration ?? null)) +
+";\n      const __late = __end ? app.itemRegistry.getAll().filter(function (e) { const d = (e.item || e).data; return d && d.isSoundChip && typeof d.clipStartTime === 'number' && d.clipStartTime >= __end; }) : [];\n      if (__late.length) {\n        result.fidelity = result.fidelity || { warnings: [] };\n        result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'sound_after_end', message: __late.length + ' sound(s) start at or after the end of this ' + __end + ' s export, so they are not in the file: ' + __late.map(function (e) { return (e.item || e).data.registryId + ' at ' + (e.item || e).data.clipStartTime + ' s'; }).slice(0, 10).join(', ') + '.' }]);\n      }" +
+"\n    } catch (_) { /* the export stands */ }\n  }\n  // WHICH STUDIO MADE THIS FILE (D92): a service worker can serve a stale\n  // build right after a deploy, and a retest then judges old code. The\n  // engine's own identity, version + build sha, rides on every export reply.\n  try { if (result && typeof result === 'object' && app.buildId) result.studioBuild = app.buildId; } catch (_) { /* older studio */ }\n  // A STALE STUDIO (D92): the file was made by an old build. Said in the\n  // fidelity warnings the reply shows, not only as a field.\n  try {\n    const __bs = app.buildStatus ? app.buildStatus() : null;\n    if (result && typeof result === 'object' && __bs) {\n      result.liveB" +
+"uild = __bs.liveBuildId;\n      if (__bs.stale) {\n        result.stale = true;\n        result.fidelity = result.fidelity || { warnings: [] };\n        result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'stale_build', message: 'this studio is running an old build (' + __bs.buildId + '; the live build is ' + __bs.liveBuildId + '): this file was made by the old code, so it may differ from what the live build makes. pinepaper_clear_canvas (or pinepaper_agent_start_job) loads the live build; it empties the canvas, so rebuild the scene and export again if the difference matters.' }]);\n      }\n    }\n  } catch (_) { /* older studio */ }\n  // RELIGHT (FxTool D5): appl" +
+"ied to png / pdf / mp4 / webm, not gif / apng\n  // or the vector formats; and it is what makes a video export slow.\n  if (result && result.success && typeof app.getRelight === 'function') {\n    try {\n      const __rl = app.getRelight();\n      if (__rl && __rl.enabled) {\n        result.fidelity = result.fidelity || { warnings: [] };\n        if (['png', 'jpg', 'webp', 'pdf', 'mp4', 'webm'].indexOf(" +
 String(JSON.stringify(format)) +
 ") === -1) {\n          result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'relight_not_applied', message: 'a relight rig is set, but ' + " +
 String(jsLiteral(format)) +
@@ -7343,6 +7391,12 @@ String(jsLiteral(format)) +
 
 
 
+
+
+
+
+
+
 
 
 
@@ -9353,7 +9407,9 @@ String(jsLiteral(templateId)) +
 ).trim();
     }
     generateImportImage(input) {
-        const { url, position, maxWidth, maxHeight, mask, smoothing, maxEdge, nativeSize, shadowColor, shadowBlur, shadowOffset, name } = input;
+        const { url, position, maxWidth, maxHeight, mask, smoothing, maxEdge, nativeSize, shadowColor, shadowBlur, shadowOffset, name, opacity, blendMode, scale, loop } = input;
+        const look = { ...(opacity !== undefined ? { opacity } : {}), ...(blendMode !== undefined ? { blendMode } : {}), ...(scale !== undefined ? { scale } : {}) };
+        const hasLook = Object.keys(look).length > 0;
         // IMPORTSHADOW: the shadow keys, applied through the engine's own modify
         // door once the image is placed (and masked) — the route modify_item takes.
         const shadow = {};
@@ -9375,6 +9431,7 @@ String(jsLiteral(templateId)) +
             maxWidth !== undefined ? `maxWidth: ${maxWidth}` : '',
             maxHeight !== undefined ? `maxHeight: ${maxHeight}` : '',
             nativeSize ? 'nativeSize: true' : '',
+            loop !== undefined ? `loop: ${JSON.stringify(loop)}` : '',
         ].filter(Boolean);
         const optsLiteral = optParts.length ? `{ ${optParts.join(', ')} }` : '{}';
         return ("\n// Import image from URL\n(async function() {\n  if (!app.imageTools) {\n    return { error: 'Image tools not available. Make sure PinePaper Studio is loaded.' };\n  }\n  try {\n    // FETCH IT OURSELVES FIRST, to find out WHY when it fails.\n    //\n    // uploadFromURL sets img.src and rejects with a bare \"Failed to load image\n    // from URL\" — an <img> onerror genuinely carries no reason, so that message\n    // is the browser's limit rather than the engine being unhelpful. fetch()\n    // has the reason: a status code, a CORS rejection, a refused connection, a\n    // DNS failure. A caller cannot debug what the tool will not show them.\n    //\n    // The bytes then go in as a DA" +
@@ -9406,6 +9463,16 @@ String(mask ? `    // A MASK REPLACES THE RASTER (round 8 DD, 4.10). applyMask b
     if (app.itemRegistry && typeof app.itemRegistry.rebind === 'function') app.itemRegistry.rebind(itemId, masked);
     placed = masked;
 ` : '') +
+String(hasLook ? `    // opacity, blendMode, scale: read by modify, on what is drawn. They were not import arguments (OPACIMP31, BLENDIMP31, IMGSCALE31).
+    let __look = null;
+    {
+      let __ok = false;
+      try { __ok = app.modifyItem(itemId, ${JSON.stringify(look)}) !== false; } catch (_) { __ok = false; }
+      __look = __ok
+        ? { applied: true, opacity: placed.opacity, blendMode: placed.blendMode }
+        : { applied: false, warning: 'the image was imported but ' + ${jsLiteral(Object.keys(look).join(', '))} + ' was not applied: set it with pinepaper_modify_item on ' + itemId + '.' };
+    }
+` : '') +
 String(hasShadow ? `    // The shadow goes on what is DRAWN, after a mask has replaced the raster.
     let __shadow = null;
     {
@@ -9428,6 +9495,8 @@ String(name ? `\n      name: ${JSON.stringify(name)},` : '') +
 "\n      bounds: { x: b.x, y: b.y, width: b.width, height: b.height }" +
 String(mask ? `,\n      mask: ${jsLiteral(mask)}` : '') +
 String(hasShadow ? ',\n      shadow: __shadow' : '') +
+String(loop !== undefined ? ",\n      playback: (raster && raster.data && raster.data.animatedImage && raster.data.animatedImage.loop !== undefined) ? { applied: true, plays: raster.data.animatedImage.loop } : { applied: false, warning: 'loop was not applied: this image does not animate in this studio. Animated GIF and WebP do.' }" : '') +
+String(hasLook ? ',\n      look: __look' : '') +
 ",\n      // Stored smaller than its source (the studio's cap): said, with the\n      // way to keep every pixel. The studio reports native size where it can.\n      ...((entry && entry.nativeWidth && entry.width && entry.nativeWidth > entry.width)\n        ? { stored: { width: entry.width, height: entry.height }, native: { width: entry.nativeWidth, height: entry.nativeHeight },\n            note: 'the studio stored this image at ' + entry.width + 'x' + entry.height + ' (its source is ' + entry.nativeWidth + 'x' + entry.nativeHeight + '). Pass maxEdge: \"native\" to keep every pixel.' }\n        : {})\n    };\n  } catch (e) {\n    return { error: 'Failed to import image: ' + e.message };\n " +
 " }\n})();\n"
 
@@ -9519,6 +9588,12 @@ String(hasShadow ? ',\n      shadow: __shadow' : '') +
 
 
 
+
+
+
+
+
+
 
 
 
@@ -16238,10 +16313,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 +16325,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 +16339,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() };`;