@pinepaper.studio/mcp-server 1.6.29 → 1.6.31

package/dist/types/code-generator.js

@@ -7,7 +7,7 @@
 import { compileChoreography } from '../tools/choreograph.js';
 import { compileBatchTimelines, emitTimelineOpBody } from '../tools/timeline.js';
 import { normalizeSvgSize } from '../utils/svg-size.js';
-import { WORLD3D_COLOR_PATHS, PATTERN_KINDS, EXPRESSION_FUNCTION_ARITY, EXPRESSION_CONSTANTS, EXPRESSION_REJECTED, RELATION_PARAM_KEYS } from '../tools/engine-lists.js';
+import { WORLD3D_COLOR_PATHS, PATTERN_KINDS, EXPRESSION_FUNCTION_ARITY, EXPRESSION_CONSTANTS, EXPRESSION_REJECTED, RELATION_PARAM_KEYS, ANIMATION_OPTION_KEYS } from '../tools/engine-lists.js';
 import { expressionGrammarText } from '../tools/expression-grammar.js';
 import { REQUIRED_ENGINE_METHODS, OPTIONAL_ENGINE_METHODS } from '../tools/engine-methods.js';
 import { NORMALIZE_PARAM_READS, MODIFY_CHANGE_READS } from '../tools/shape-params.js';
@@ -402,8 +402,13 @@ const item = app.create(${jsLiteral(itemType)}, ${JSON.stringify(params, null, 2
     if (hasCreateScale) {
         code += `
 const __scale = (function(it) {
+  // A studio whose create() applies scale (FxTool #262) already has it: nothing to redo.
+  const __want = ${JSON.stringify(createScale)};
+  const __s0 = (it && it.scaling) || { x: 1, y: 1 };
+  const __near = function(a, b) { return b === undefined || Math.abs(a - b) < 1e-6; };
+  if (__near(__s0.x, __want.scaleX) && __near(__s0.y, __want.scaleY)) return { applied: true, x: __s0.x, y: __s0.y };
   if (!it || !it.data || typeof app.modifyItem !== 'function') return { applied: false, note: 'this studio has no app.modifyItem, so the scale was not applied at create; set it with pinepaper_modify_item.' };
-  app.modifyItem(it.data.registryId, ${JSON.stringify(createScale)});
+  app.modifyItem(it.data.registryId, __want);
   const s = it.scaling || { x: 1, y: 1 };
   return { applied: true, x: s.x, y: s.y };
 })(item);`;
@@ -1253,14 +1258,33 @@ export function fireIfProblem(params) {
     }
     return null;
 }
+/**
+ * A TARGET-LESS on_event_step_active runs only on a studio that says so. An older studio runs an event reaction only
+ * when its target exists (a sound alone was exempt), and step_active acts on its GROUP, not its target, so one bound
+ * with no target reported success and never stepped (beta STEPACT30). FxTool #281 runs it target-less and lists it in
+ * PinePaper.TARGETLESS_EVENT_RELATIONS, the set _bindOnEventRelation itself reads, so the marker cannot say yes while
+ * the engine says no. The refusal is decided in the page (STEP_ACTIVE_TARGETLESS_JS); here, only whether to ask.
+ */
+export function targetlessStepProblem(relationType, target) {
+    if (relationType !== 'on_event_step_active' || (target != null && target !== ''))
+        return null;
+    return 'on_event_step_active needs a targetId on this studio. It steps the group named in params.groupName, not its target, but this studio runs an event reaction only when its target exists: without one it binds, reports success and never runs. Point it at any item, for example one member of the group (a current studio runs it without one).';
+}
+/** True in the page when the studio runs on_event_step_active with no target. */
+export const STEP_ACTIVE_TARGETLESS_JS = "(typeof app !== 'undefined' && !!app && app.TARGETLESS_EVENT_RELATIONS?.has?.('on_event_step_active') === true)";
 /**
  * fireIfProblem for any relation a tool is about to add: an on_event_fire_if
  * itself, or one an on_event_add_relation will add when its event fires
  * (params.type / params.params). Every path that adds relations asks this, so
  * the check does not depend on which tool built the relation.
  */
-export function relationSpecProblem(relationType, params) {
+export function relationSpecProblem(relationType, params, ...target) {
     const p = (params && typeof params === 'object' ? params : {});
+    // A target-less on_event_step_active is decided in the page, not here (targetlessStepProblem): it runs on a studio
+    // that lists it in TARGETLESS_EVENT_RELATIONS and does nothing on an older one. Only a caller with no page to ask
+    // (create_scene, which binds no relation without a target) refuses it outright.
+    if (target.length > 1 && target[1] === 'no-page' && targetlessStepProblem(relationType, target[0]))
+        return targetlessStepProblem(relationType, target[0]);
     if (relationType === 'on_event_fire_if')
         return fireIfProblem(p);
     if (relationType === 'time_expression' && typeof p.expression === 'string')
@@ -1388,14 +1412,26 @@ function equationFlipNote(relationType, params) {
 }
 function unreadOptionWarning(relationType, params, injected) {
     const keys = typeof relationType === 'string' ? RELATION_PARAM_KEYS[relationType] : undefined;
-    if (!keys || !params || typeof params !== 'object')
+    return keys ? unreadKeysWarning(String(relationType), keys, params, injected) : null;
+}
+/** The keys of `params` outside `keys`, named with a "did you mean" and the list that is read; null when all are read. */
+function unreadKeysWarning(reader, keys, params, injected = []) {
+    if (!params || typeof params !== 'object')
         return null;
     const unknown = Object.keys(params).filter((k) => !keys.includes(k) && !injected.includes(k));
     if (!unknown.length)
         return null;
     const norm = (x) => x.replace(/_/g, '').toLowerCase();
     const hint = unknown.map((k) => keys.find((x) => norm(x) === norm(k)) ?? keys.find((x) => editDistance(norm(x), norm(k)) <= (k.length > 5 ? 2 : 1))).map((x, i) => (x ? `${unknown[i]} → ${x}?` : '')).filter(Boolean);
-    return `${relationType} does not read ${unknown.join(', ')}, so ${unknown.length > 1 ? 'they were' : 'it was'} ignored${hint.length ? ` (${hint.join('; ')})` : ''}. ${relationType} reads: ${keys.join(', ')}.`;
+    return `${reader} does not read ${unknown.join(', ')}, so ${unknown.length > 1 ? 'they were' : 'it was'} ignored${hint.length ? ` (${hint.join('; ')})` : ''}. ${reader} reads: ${keys.join(', ')}.`;
+}
+/**
+ * An animationOptions key app.animate never reads (ANIMATION_OPTION_KEYS, generated from the engine). The batch hands
+ * the options over as they are, so an unknown key was dropped with the op reported done. pinepaper_animate's own
+ * names (intensity, speed …) are translated before this (batch-op-names.ts), so they never reach it.
+ */
+export function animationOptionWarning(options) {
+    return unreadKeysWarning('animationOptions', ANIMATION_OPTION_KEYS, options);
 }
 const VISIBILITY_REACTION = /^on_(event|enter|exit)_set_visibility$/;
 /**
@@ -1541,13 +1577,14 @@ export function normalizeEmitterSpec(spec, assumeDefaultCount = true) {
             mismatch(`bursts[${i}]`, own.count ?? out.count, own.velocities ?? out.velocities);
     });
     // A RANGE WHERE THE STUDIO READS ONE NUMBER is not drawn as a range (1.6.24
-    // probe: gravity [100, 300] fell to 0, opacity [0.2, 1] to 1, no word). What
-    // it draws instead depends on the studio build: older ones take num()'s
-    // fallback (count [a, b] → 0, so nothing is drawn); FxTool #228 draws the
-    // middle and says so (emitter-range-not-read). Only size, speed, angle,
-    // spawn, lifetime and spin go through range(). The text says what holds on
-    // both, so it is true whichever studio the server is pointed at.
-    const SCALAR_ONLY = ['gravity', 'drag', 'friction', 'opacity', 'fadeIn', 'fadeOut', 'strokeWidth', 'jitter', 'jitterHz', 'aspect', 'sizeEnd', 'count'];
+    // probe: count [a, b] → 0 on older studios, the middle on FxTool #228). Only
+    // the keys that take one number on EVERY build are named here. gravity, drag,
+    // friction, opacity, sizeEnd and jitter were too, until the studio began to
+    // sample them per particle: the tester measured drag 101–206 against this text
+    // saying one value. What a given studio does with a range on those is its own
+    // to say (emitter-range-not-read, in engineWarnings), so it is true for
+    // whichever studio the server is pointed at.
+    const SCALAR_ONLY = ['fadeIn', 'fadeOut', 'strokeWidth', 'jitterHz', 'aspect', 'count'];
     const SPEC_ONLY = ['rate', 'start', 'end', 'seed'];
     const OUTCOME = {
         count: 'an older studio reads a range here as 0 and draws no particles',
@@ -1556,7 +1593,7 @@ export function normalizeEmitterSpec(spec, assumeDefaultCount = true) {
         for (const k of keys) {
             const v = o[k];
             if (Array.isArray(v) && v.length >= 2) {
-                warnings.push(`${where}.${k} ${JSON.stringify(v)} is not drawn as a range: ${k} takes one number, so the studio draws one value for every particle (its default, or the middle of the range, depending on the build${OUTCOME[k] ? `; ${OUTCOME[k]}` : ''}). Pass the single value you want. Only size, speed, angle, spawn, lifetime and spin take a [min, max] range.`);
+                warnings.push(`${where}.${k} ${JSON.stringify(v)} is not drawn as a range: ${k} takes one number, so the studio draws one value for every particle (its default, or the middle of the range, depending on the build${OUTCOME[k] ? `; ${OUTCOME[k]}` : ''}). Pass the single value you want.`);
             }
         }
         const f = o.fade;
@@ -1916,12 +1953,14 @@ const TEXT_KEY_ENGINE_NAMES = {
     wordSpacing: ['wordSpacing'],
     textDecoration: ['textDecoration'],
     textTransform: ['textTransform'],
-    // Not text, same failure (SHEARKEY, mcp-cloud #29): no studio has a skew
-    // channel yet, so skew keys were stored and drew nothing. A sheared motion
-    // today is a `transform` matrix track.
+    // Not text, same failure (SHEARKEY, mcp-cloud #29): a studio before FxTool
+    // #263 has no skew channel, so skew keys were stored and drew nothing. The
+    // current one animates skewX / skewY. `shear` is no channel on any studio:
+    // keyed, it drew nothing with no word (measured on 56c79202), so it is named
+    // unless a studio ever lists `shear` itself.
     skewX: ['skewX'],
     skewY: ['skewY'],
-    shear: ['shear', 'skewX'],
+    shear: ['shear'],
 };
 /** A JS expression (run in the page) → the keys of `keys` this studio does not animate. '' when none are text keys. */
 function unanimatedTextKeysJs(keys) {
@@ -1936,7 +1975,49 @@ function unanimatedTextKeysJs(keys) {
   })()`;
 }
 /** The sentence for the keys unanimatedTextKeysJs found, built in the page. */
-const UNANIMATED_TEXT_KEYS_SENTENCE = `' is not an animatable property in this studio (app.listAnimatableProperties does not list it), so it had no effect: a key animates only where that list names it. Here, set a fixed value with pinepaper_modify_item, or animate fontSize or scaleX (a skew: a transform matrix track).'`;
+const UNANIMATED_TEXT_KEYS_SENTENCE = `' is not an animatable property in this studio (app.listAnimatableProperties does not list it), so it had no effect: a key animates only where that list names it. Here, set a fixed value with pinepaper_modify_item, or animate fontSize or scaleX. For a skew, key skewX / skewY (degrees) where the studio lists them, else a transform matrix track.'`;
+/**
+ * The warnings a keyframe track's result carries, as object-literal fields (", key: value" …): keys that leave out a
+ * property, loop in an export, x beside fontSize on an older studio, easing on the first key. One function for
+ * pinepaper_keyframe_animate and the batch keyframe_animate op: the batch had its own copy of the emitter and none
+ * of these (SIZEKEY-PAIR: the same keys warned through the tool and not through the batch).
+ */
+function keyframeResultNotes(keyframes, { loop = false, append = false, easingAt } = {}) {
+    // A KEY THAT LEAVES A PROPERTY OUT (round 9 HH, engine 2.30): the engine
+    // treats the gap as a break in that property's track rather than holding or
+    // interpolating across it, silently. Named here — which keys lack which
+    // properties — with the fix a caller can make now: give every key the full set.
+    const propSets = keyframes.map((k) => Object.keys(k.properties ?? {}));
+    const allProps = [...new Set(propSets.flat())];
+    const gaps = keyframes
+        .map((k, i) => ({ time: k.time, missing: allProps.filter((p) => !propSets[i].includes(p)) }))
+        .filter((g) => g.missing.length);
+    // With append the gaps that matter are the MERGED track's (an earlier key
+    // with no scale beside a new key with one), so that check runs in the page
+    // on the result instead (below).
+    const gapNote = !append && gaps.length && keyframes.length > 1
+        ? `, propertyGaps: ${JSON.stringify(gaps.slice(0, 10))}, gapWarning: ${JSON.stringify(`${gaps.length} keyframe(s) leave out a property other keys animate (${[...new Set(gaps.flatMap((g) => g.missing))].join(', ')}). The engine can break that property's track at such a key; repeat the value on every key — hold it by repeating the previous value.`)}`
+        : '';
+    const first = [...keyframes].sort((a, b) => a.time - b.time)[0];
+    // loop:true repeats in the editor; an export of the measured build played
+    // the keyframes ONCE and held (round 7, 2.24). Said where it is set, with
+    // the two ways that do export, until the engine's export clock wraps them.
+    const loopNote = loop
+        ? `, loopNote: ${JSON.stringify('loop:true repeats in the editor, but has been measured playing ONCE in an exported video and then holding the last keyframe. For an export longer than one cycle, check a frame in the second cycle — if it holds, write the keyframes out per cycle, or use a loop preset (pinepaper_animate), which does cycle in export.')}`
+        : '';
+    // SIZEKEY-PAIR (mcp-cloud #28): on a studio before FxTool #262, x (or
+    // position) keyed beside fontSize on one text item drifted in an export: the
+    // size was applied after the position, and a text resizes around its anchor.
+    // Said there, with the two ways that hold; a current studio is quiet.
+    const sizekeyPairNote = (allProps.includes('x') || allProps.includes('position')) && allProps.includes('fontSize')
+        // A studio that writes text size before position (FxTool #262, which also brought _applyScaleParams) holds x.
+        ? `, ...(typeof app._applyScaleParams !== 'function' ? { sizekeyPairWarning: ${JSON.stringify('x (or position) and fontSize keyed on the same text item drift off the keyed position in an export on this studio (SIZEKEY-PAIR). Animate scaleX / scaleY instead of fontSize, or move a group that holds the text; or update the studio.')} } : {})`
+        : '';
+    const easingNote = easingAt !== 'departure' && first?.easing && first.easing !== 'linear'
+        ? `, note: ${JSON.stringify(`easing '${first.easing}' is on the first keyframe, where it has no effect by default: easing shapes the segment ARRIVING at a keyframe. Put it on the keyframe you are moving to, or pass easingAt: 'departure' to read every easing as the move LEAVING its key (current studio).`)}`
+        : '';
+    return `${easingNote}${sizekeyPairNote}${loopNote}${gapNote}`;
+}
 function generateKeyframeAnimateCode(itemId, keyframes, duration, loop = false, timeOffset, clipInPoint, clipOutPoint, timeUnits, append = false, easingAt) {
     const ID = jsLiteral(itemId); // caller text: a quoted literal, never spliced raw
     const keyframesJson = JSON.stringify(normalizeKeyframePositions(keyframes), null, 2);
@@ -1988,38 +2069,7 @@ String(JSON.stringify(levelKeys)) +
     // never applies — a Ken Burns eased only there rendered linear. Said in the
     // result rather than silently moved: moving it would change what the other
     // keys the caller wrote mean.
-    // A KEY THAT LEAVES A PROPERTY OUT (round 9 HH, engine 2.30): the engine
-    // treats the gap as a break in that property's track rather than holding or
-    // interpolating across it, silently. Named here — which keys lack which
-    // properties — with the fix a caller can make now: give every key the full set.
-    const propSets = keyframes.map((k) => Object.keys(k.properties ?? {}));
-    const allProps = [...new Set(propSets.flat())];
-    const gaps = keyframes
-        .map((k, i) => ({ time: k.time, missing: allProps.filter((p) => !propSets[i].includes(p)) }))
-        .filter((g) => g.missing.length);
-    // With append the gaps that matter are the MERGED track's (an earlier key
-    // with no scale beside a new key with one), so that check runs in the page
-    // on the result instead (below).
-    const gapNote = !append && gaps.length && keyframes.length > 1
-        ? `, propertyGaps: ${JSON.stringify(gaps.slice(0, 10))}, gapWarning: ${JSON.stringify(`${gaps.length} keyframe(s) leave out a property other keys animate (${[...new Set(gaps.flatMap((g) => g.missing))].join(', ')}). The engine can break that property's track at such a key; repeat the value on every key — hold it by repeating the previous value.`)}`
-        : '';
-    const first = [...keyframes].sort((a, b) => a.time - b.time)[0];
-    // loop:true repeats in the editor; an export of the measured build played
-    // the keyframes ONCE and held (round 7, 2.24). Said where it is set, with
-    // the two ways that do export, until the engine's export clock wraps them.
-    const loopNote = loop
-        ? `, loopNote: ${JSON.stringify('loop:true repeats in the editor, but has been measured playing ONCE in an exported video and then holding the last keyframe. For an export longer than one cycle, check a frame in the second cycle — if it holds, write the keyframes out per cycle, or use a loop preset (pinepaper_animate), which does cycle in export.')}`
-        : '';
-    // SIZEKEY-PAIR (mcp-cloud #28): x (or position) keyed beside fontSize on one
-    // text item has been measured drifting in an export: the size is applied
-    // after the position, and a text resizes around its anchor, so the box leaves
-    // the keyed x. Said, with the two ways that hold.
-    const sizekeyPairNote = (allProps.includes('x') || allProps.includes('position')) && allProps.includes('fontSize')
-        ? `, sizekeyPairWarning: ${JSON.stringify('x (or position) and fontSize keyed on the same text item have been measured drifting off the keyed position in an export (SIZEKEY-PAIR). Animate scaleX / scaleY instead of fontSize, or move a group that holds the text.')}`
-        : '';
-    const easingNote = easingAt !== 'departure' && first?.easing && first.easing !== 'linear'
-        ? `, note: ${JSON.stringify(`easing '${first.easing}' is on the first keyframe, where it has no effect by default: easing shapes the segment ARRIVING at a keyframe. Put it on the keyframe you are moving to, or pass easingAt: 'departure' to read every easing as the move LEAVING its key (current studio).`)}`
-        : '';
+    const __notes = keyframeResultNotes(keyframes, { loop, append, easingAt });
     const textKeysJs = unanimatedTextKeysJs(keyframes.flatMap((k) => Object.keys(k.properties ?? {})));
     const textKeyCheck = textKeysJs ? `
   const __ignored = ${textKeysJs};
@@ -2062,7 +2112,7 @@ String(calculatedDuration) +
 String(loop) +
 String(append ? ', append: true' : '') +
 ", ...(__track ? { track: __track } : {})" +
-String(append ? `, ...(__gaps.length ? { propertyGaps: __gaps.slice(0, 10), gapWarning: __gaps.length + ' key(s) of the merged track leave out a property other keys animate (' + __gaps.reduce(function(a, g) { g.missing.forEach(function(p) { if (a.indexOf(p) < 0) a.push(p); }); return a; }, []).join(', ') + '). The engine can break that property at such a key; give each key the full set — hold a value by repeating it.' } : {})` : '') + String(timeOffset !== undefined ? `, timeOffset: ${timeOffset}` : '') + String(clipInPoint !== undefined ? `, clipInPoint: ${clipInPoint}` : '') + String(clipOutPoint !== undefined ? `, clipOutPoint: ${clipOutPoint}` : '') + String(easingNote) + String(sizekeyPairNote) + String(loopNote) + String(gapNote) + String(runtimeWarning) + " };\n})();\n").trim();
+String(append ? `, ...(__gaps.length ? { propertyGaps: __gaps.slice(0, 10), gapWarning: __gaps.length + ' key(s) of the merged track leave out a property other keys animate (' + __gaps.reduce(function(a, g) { g.missing.forEach(function(p) { if (a.indexOf(p) < 0) a.push(p); }); return a; }, []).join(', ') + '). The engine can break that property at such a key; give each key the full set — hold a value by repeating it.' } : {})` : '') + String(timeOffset !== undefined ? `, timeOffset: ${timeOffset}` : '') + String(clipInPoint !== undefined ? `, clipInPoint: ${clipInPoint}` : '') + String(clipOutPoint !== undefined ? `, clipOutPoint: ${clipOutPoint}` : '') + String(__notes) + String(runtimeWarning) + " };\n})();\n").trim();
 }
 /**
  * Template for executing generators
@@ -3377,14 +3427,22 @@ String(JSON.stringify(validated.presetId)) +
 ).trim();
         }
         {
-            const problem = relationSpecProblem(validated.relationType, validated.params);
+            const problem = relationSpecProblem(validated.relationType, validated.params, validated.targetId);
             if (problem)
                 return `(function() { return { success: false, relationType: ${jsLiteral(validated.relationType)}, error: ${jsLiteral(problem)} }; })();`;
         }
         if (validated.relationType === 'moves_along_path') {
             return generateMovesAlongPathCode(validated.sourceId, validated.targetId ?? undefined, (validated.params ?? {}));
         }
-        const code = generateAddRelationCode(validated.sourceId, validated.targetId || validated.sourceId, validated.relationType, validated.params);
+        const built = generateAddRelationCode(validated.sourceId, validated.targetId || validated.sourceId, validated.relationType, validated.params);
+        // Target-less step_active: refused in the page, only on a studio that would drop it (targetlessStepProblem).
+        const stepNoTarget = targetlessStepProblem(validated.relationType, validated.targetId);
+        const code = stepNoTarget
+            ? `(function() {
+  if (!${STEP_ACTIVE_TARGETLESS_JS}) return { success: false, relationType: 'on_event_step_active', error: ${jsLiteral(stepNoTarget)} };
+  return ${built.trim().replace(/;$/, '')};
+})();`
+            : built;
         // NO TARGET (event reactions like on_event_play_sound, self-relations): the
         // engine is handed the source as the target, but the reply must not say
         // "item_2 → item_2" — a model reads that as the event wired to itself.
@@ -4065,7 +4123,7 @@ if (typeof _gen === 'function') {
         for (const relation of relations) {
             const { source, target, type, params = {} } = relation;
             const paramsStr = JSON.stringify(params);
-            const specProblem = relationSpecProblem(type, params);
+            const specProblem = relationSpecProblem(type, params, target, 'no-page');
             if (specProblem) {
                 codeParts.push(`
 // Refused relation: ${oneLine(source)} ${oneLine(type)} ${oneLine(target)}
@@ -5062,13 +5120,16 @@ const targetId = ${animItemRef};
 const item = app.getItemById(targetId);
 if (!item) throw new Error('Item not found: ' + targetId);
 app.animate(item, { animationType: ${JSON.stringify(String(op.animationType))}, ...${animOpts} });
-return { itemId: targetId, animationType: ${JSON.stringify(String(op.animationType))} };
+return { itemId: targetId, animationType: ${JSON.stringify(String(op.animationType))}${(() => { const w = animationOptionWarning(op.animationOptions); return w ? `, warning: ${jsLiteral(w)}` : ''; })()} };
 `;
             case 'relation':
                 const srcRef = batchRef(op.sourceId);
                 const tgtRef = batchRef(op.targetId);
                 const relOpts = JSON.stringify(op.relationOptions || {});
-                const fireIf = relationSpecProblem(op.relationType, op.relationOptions);
+                const fireIf = relationSpecProblem(op.relationType, op.relationOptions, op.targetId);
+                // Target-less step_active: refused in the page, only on a studio that would drop it (targetlessStepProblem).
+                const stepNoTarget = targetlessStepProblem(op.relationType, op.targetId);
+                const stepGuard = stepNoTarget ? `if (!${STEP_ACTIVE_TARGETLESS_JS}) throw new Error(${jsLiteral('on_event_step_active: ' + stepNoTarget)});\n` : '';
                 if (fireIf)
                     return `
 throw new Error(${JSON.stringify(String(op.relationType) + ': ' + fireIf)});
@@ -5092,6 +5153,7 @@ if (!__members.length) throw new Error('no item is named like ' + ${jsLiteral(op
                         : `const __members = [{ id: ${srcRef} }];
 if (!app.getItemById(__members[0].id)) throw new Error('Source not found: ' + __members[0].id);`;
                     return ("\n" +
+String(stepGuard) +
 String(members) +
 "\nconst targetId = " +
 String(noTarget ? 'null' : tgtRef) +
@@ -5119,10 +5181,11 @@ String(type) +
 ", sourceIds: __failed, error: " +
 String(op.update === true ? '__why' : `'the studio refused the ' + ${type} + ' relation for ' + __failed.join(', ') + ' — nothing was bound' + (__why ? ': ' + __why : '.')`) +
 " };\n}\nreturn { success: true, relationType: " +
-String(type) +
-", " + String(op.update === true ? 'updated' : 'bound') + ": __done, targetId" + String(glob ? ', count: __members.length' : '') + String((() => { const w = relationOptionWarning(op.relationType, op.relationOptions, ['index', 'count', 'pattern']); return w ? `, optionWarning: ${jsLiteral(w)}` : ''; })()) + ", ...(__failed.length ? { failed: __failed, warning: __failed.length + ' of ' + __members.length + ' were not " + String(op.update === true ? 'changed' : 'bound') + ": ' + __failed.join(', ') } : {}) };\n");
+String(type) + ", " + String(op.update === true ? 'updated' : 'bound') + ": __done, targetId" + String(glob ? ', count: __members.length' : '') + String((() => { const w = relationOptionWarning(op.relationType, op.relationOptions, ['index', 'count', 'pattern']); return w ? `, optionWarning: ${jsLiteral(w)}` : ''; })()) + ", ...(__failed.length ? { failed: __failed, warning: __failed.length + ' of ' + __members.length + ' were not " + String(op.update === true ? 'changed' : 'bound') + ": ' + __failed.join(', ') } : {}) };\n");
                 }
-                return ("\nconst sourceId = " +
+                return ("\n" +
+String(stepGuard) +
+"const sourceId = " +
 String(srcRef) +
 ";\nconst targetId = " +
 String(noTarget ? 'null' : tgtRef) +
@@ -5137,9 +5200,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)}` : ''; })()) + " };\n");
             case 'delete':
                 const delRef = batchRef(op.itemId);
                 return `
@@ -5240,7 +5301,7 @@ String(kfLoop) +
 String(kfAppend ? ", mode: 'merge'" : '') +
 String(kfExtraStr) +
 " });" +
-String(kfTextCheck) + "\nreturn { success: true, itemId: targetId, duration: " + String(kfDuration) + ", loop: " + String(kfLoop) + String(kfAppend ? ', append: true' : '') + String(kfAppend ? '' : `, ...(_prevKeys ? { track: { replaced: true, previousKeys: _prevKeys, note: 'the item already had a keyframe track; this op replaced it. To add keys to it instead, pass append: true.' } } : {})`) + String(kfIgnored) + " };\n");
+String(kfTextCheck) + "\nreturn { success: true, itemId: targetId, duration: " + String(kfDuration) + ", loop: " + String(kfLoop) + String(kfAppend ? ', append: true' : '') + String(keyframeResultNotes(kfSource, { loop: kfLoop === true, append: kfAppend })) + String(kfAppend ? '' : `, ...(_prevKeys ? { track: { replaced: true, previousKeys: _prevKeys, note: 'the item already had a keyframe track; this op replaced it. To add keys to it instead, pass append: true.' } } : {})`) + String(kfIgnored) + " };\n");
             }
             case 'apply_mask': {
                 const maskItemRef = batchRef(op.itemId);
@@ -5643,11 +5704,12 @@ String(JSON.stringify(scaled)) +
 String(format === 'webm' && transparent === true ? '' : ", 'webm'") +
 String(format === 'apng' && transparent === false ? ", 'apng'" : '') +
 "].indexOf(fmt) === -1) return [];\n      const bg = app.canvasEl && app.canvasEl.style && app.canvasEl.style.backgroundColor;\n      const hasColor = !!bg && !/^(transparent|rgba\\([^)]*,\\s*0\\))$/i.test(bg);\n      const hasBgItems = !!(app.patternGroup && app.patternGroup.children && app.patternGroup.children.length);\n      // A 3D world under the canvas IS the background: since FxTool #50\n      // (747315e3) jpg/webp stills composite it, so nothing turns white/black.\n      const hasWorld = !!app._world3d;\n      // So does a styled scene: one raster sized to COVER the frame (gate run 3:\n      // every export after styled_scene warned of black areas it does not have).\n      const h" +
-"asStyledScene = !!(app.textItemGroup && app.textItemGroup.children\n        && app.textItemGroup.children.some(function (it) { return it && it.data && it.data.styledScene && it.visible !== false; }));\n      if (hasColor || hasBgItems || hasWorld || hasStyledScene) return [];\n      return [{ code: 'alpha_dropped', message: fmt === 'apng'\n        ? 'apng with transparent: false and no background colour: the frames are filled BLACK. Set a background colour, or drop transparent: false to keep the alpha.'\n        : fmt === 'jpg'\n        ? 'jpg has no transparency and this scene has no background, so transparent areas are filled white. Use png or webp to keep them.'\n        : fmt + ' is ex" +
-"ported without transparency and this scene has no background, so transparent areas come out BLACK. Set a background colour, or export apng (animated, full alpha) or png to keep it.' }];\n    } catch (e) { return []; }\n  }\n  // TEXT THAT DOES NOT FIT (FxTool 661224ef: textOverflowReport) — text past\n  // its fit box at the minimum size, or off the frame. The pre-batch check for\n  // certificates, speaker cards and localised variants, on every export.\n  function textOverflow() {\n    try {\n      const rep = (typeof app.textOverflowReport === 'function' && app.textOverflowReport()) || [];\n      return rep.slice(0, 10).map(function(o) {\n        return { code: 'text_overflow', message: " +
-"(o.id || 'a text item') + ' (' + JSON.stringify(String(o.content || '').slice(0, 40)) + '): ' + (o.reason || 'overflows'), items: [o.id] };\n      });\n    } catch (e) { return []; }\n  }\n  function fidelity(fmt) {\n    const own = alphaLoss(fmt).concat(textOverflow());\n    try {\n      if (!app.exportEngine || typeof app.exportEngine.exportFidelity !== 'function') {\n        return { fidelity: { available: false, reason: 'this studio cannot check export fidelity — update PinePaper Studio.', ...(own.length ? { warnings: own } : {}) } };\n      }\n      const r = app.exportEngine.exportFidelity(fmt);\n      if (!r) { return { fidelity: { available: false, reason: 'the fidelity check retur" +
-"ned nothing.', ...(own.length ? { warnings: own } : {}) } }; }\n      const warnings = (r.warnings || []).concat(own);\n      return {\n        fidelity: {\n          available: true,\n          warnings: warnings,\n          checked: r.checked,\n          ...(warnings.length === 0\n            ? { note: 'this scene loses nothing to ' + fmt + '. That is a statement about THIS SCENE, not a claim that the format is lossless.' }\n            : {}),\n        },\n      };\n    } catch (e) {\n      return { fidelity: { available: false, reason: (e && e.message) || 'the fidelity check threw.', ...(own.length ? { warnings: own } : {}) } };\n    }\n  }\n\n  // Preflight: same resolved settings as t" +
-"he real export, but render nothing.\n  // Branching HERE rather than in a separate tool is deliberate — the estimate\n  // has to see the same platform dimensions, fps and quality the export would\n  // use, and a parallel tool would re-derive them and drift.\n  if (" +
+"asStyledScene = !!(app.textItemGroup && app.textItemGroup.children\n        && app.textItemGroup.children.some(function (it) { return it && it.data && it.data.styledScene && it.visible !== false; }));\n      if (hasColor || hasBgItems || hasWorld || hasStyledScene) return [];\n      // The fill is the studio's page colour, not black: every opaque export\n      // path asks the engine's _pageColor, which is white when no page colour\n      // is set (an older engine fell back to black for video). An apng was\n      // measured white (bitrate sweep, 11.02), so name the page colour, not a hue.\n      return [{ code: 'alpha_dropped', message: fmt === 'apng'\n        ? 'apng with transparent: f" +
+"alse and no background colour: the frames are filled with the studio page colour (white in current studios), not a colour this scene chose. Set a background colour, or drop transparent: false to keep the alpha.'\n        : fmt === 'jpg'\n        ? 'jpg has no transparency and this scene has no background, so transparent areas are filled white. Use png or webp to keep them.'\n        : fmt + ' is exported without transparency and this scene has no background, so transparent areas are filled with the studio page colour (white in current studios), not a colour this scene chose. Set a background colour, or export apng (animated, full alpha) or png to keep it.' }];\n    } catch (e) { return [];" +
+" }\n  }\n  // TEXT THAT DOES NOT FIT (FxTool 661224ef: textOverflowReport) — text past\n  // its fit box at the minimum size, or off the frame. The pre-batch check for\n  // certificates, speaker cards and localised variants, on every export.\n  function textOverflow() {\n    try {\n      const rep = (typeof app.textOverflowReport === 'function' && app.textOverflowReport()) || [];\n      return rep.slice(0, 10).map(function(o) {\n        return { code: 'text_overflow', message: (o.id || 'a text item') + ' (' + JSON.stringify(String(o.content || '').slice(0, 40)) + '): ' + (o.reason || 'overflows'), items: [o.id] };\n      });\n    } catch (e) { return []; }\n  }\n  function fidelity(fmt) {" +
+"\n    const own = alphaLoss(fmt).concat(textOverflow());\n    try {\n      if (!app.exportEngine || typeof app.exportEngine.exportFidelity !== 'function') {\n        return { fidelity: { available: false, reason: 'this studio cannot check export fidelity — update PinePaper Studio.', ...(own.length ? { warnings: own } : {}) } };\n      }\n      const r = app.exportEngine.exportFidelity(fmt);\n      if (!r) { return { fidelity: { available: false, reason: 'the fidelity check returned nothing.', ...(own.length ? { warnings: own } : {}) } }; }\n      const warnings = (r.warnings || []).concat(own);\n      return {\n        fidelity: {\n          available: true,\n          warnings: warnings," +
+"\n          checked: r.checked,\n          ...(warnings.length === 0\n            ? { note: 'this scene loses nothing to ' + fmt + '. That is a statement about THIS SCENE, not a claim that the format is lossless.' }\n            : {}),\n        },\n      };\n    } catch (e) {\n      return { fidelity: { available: false, reason: (e && e.message) || 'the fidelity check threw.', ...(own.length ? { warnings: own } : {}) } };\n    }\n  }\n\n  // Preflight: same resolved settings as the real export, but render nothing.\n  // Branching HERE rather than in a separate tool is deliberate — the estimate\n  // has to see the same platform dimensions, fps and quality the export would\n  // use, and a " +
+"parallel tool would re-derive them and drift.\n  if (" +
 String(estimateOnly ? 'true' : 'false') +
 ") {\n    if (typeof app.estimateExportSize !== 'function') {\n      return { success: false, estimateOnly: true, error: 'This PinePaper build has no estimateExportSize() — update the editor to preflight export size.' };\n    }\n    const est = await app.estimateExportSize({\n      format,\n      duration: " +
 String(videoDuration) +
@@ -7160,6 +7222,9 @@ String(jsLiteral(format)) +
 
 
 
+
+
+
 
 
 
@@ -10569,7 +10634,7 @@ String(jsLiteral(input.filterName || '')) +
 String(JSON.stringify(input.itemId)) +
 ", filter: " +
 String(JSON.stringify(input.filterName || '')) +
-String(input.filterName === 'bloom' ? `, warning: 'bloom is drawn inside the image\\'s own pixels, so its halo stops at the image edge and does not spill onto the canvas (BLOOMCLIP). For a halo past the edge, use pinepaper_apply_effect glow or a shadow.'` : '') +
+String(input.filterName === 'bloom' ? `, ...(typeof app._writeRasterPixels !== 'function' ? { warning: 'on this studio bloom is drawn inside the image\\'s own pixels, so its halo stops at the image edge (BLOOMCLIP). For a halo past the edge, use pinepaper_apply_effect glow or a shadow, or update the studio.' } : {})` : '') +
 " };\n  } catch (e) {\n    return { success: false, action: 'apply', error: 'Failed to apply filter: ' + e.message };\n  }\n})();"
 ).trim();
             case 'chain':
@@ -12593,11 +12658,19 @@ String(sheet.format === 'png' ? '' : ', 0.82') +
         // A fire_if the doc declares is checked before anything is built: refused, the whole document is, with every reason.
         const specProblems = ops
             .filter((o) => o.op === 'addRelation')
-            .map((o) => { const r = o; const why = relationSpecProblem(r.relation, r.params); return why ? `${r.from} -> ${r.to} (${r.relation}): ${why}` : null; })
+            .map((o) => { const r = o; const why = relationSpecProblem(r.relation, r.params, r.to); return why ? `${r.from} -> ${r.to} (${r.relation}): ${why}` : null; })
             .filter((x) => !!x);
         if (specProblems.length) {
             return `(function() { return { success: false, error: ${jsLiteral('nothing was built: ' + specProblems.join(' | '))} }; })();`;
         }
+        // Target-less step_active relations refuse the whole document in the page, only on a studio that would drop them.
+        const stepNoTarget = ops
+            .filter((o) => o.op === 'addRelation')
+            .map((o) => { const r = o; const why = targetlessStepProblem(r.relation, r.to); return why ? `${r.from} -> (no target) (${r.relation}): ${why}` : null; })
+            .filter((x) => !!x);
+        const stepDocGuard = stepNoTarget.length
+            ? `if (!${STEP_ACTIVE_TARGETLESS_JS}) return { success: false, error: ${jsLiteral('nothing was built: ' + stepNoTarget.join(' | '))} };\n`
+            : '';
         const opsJson = JSON.stringify(ops, null, 2);
         const diagJson = JSON.stringify(diagnostics);
         const docJson = JSON.stringify(input.doc);
@@ -12609,7 +12682,9 @@ String(sheet.format === 'png' ? '' : ', 0.82') +
 String(oneLine(ops.filter((o) => o.op === 'create').length)) +
 " items, " +
 String(oneLine(ops.filter((o) => o.op === 'addRelation').length)) +
-" relations)\n(async function() {\n  // Engine door first: the studio's own OntologyCompiler reads every node facet\n  // (geometry, paint, text, the keyframe track, masks) and builds through the\n  // template loader's paths — the round trip the studio's pixel tests verify\n  // (e2e/graph-instantiate-parity.spec.js). The server-side compile above is\n  // kept for the diagnostics preview and for studios that predate the facade,\n  // which get the box loop below and a note saying so.\n  const doc = " +
+" relations)\n(async function() {\n  " +
+String(stepDocGuard) +
+"  // Engine door first: the studio's own OntologyCompiler reads every node facet\n  // (geometry, paint, text, the keyframe track, masks) and builds through the\n  // template loader's paths — the round trip the studio's pixel tests verify\n  // (e2e/graph-instantiate-parity.spec.js). The server-side compile above is\n  // kept for the diagnostics preview and for studios that predate the facade,\n  // which get the box loop below and a note saying so.\n  const doc = " +
 String(docJson) +
 ";\n  if (typeof app.instantiateOntology === 'function') {\n    // THE LIVE CANVAS, unless one was given: the engine lays out for 1080x1080\n    // otherwise, which put items at (540,540) on a 640x360 canvas (gate run 3).\n    const __opts = " +
 String(engineOptsJson) +
@@ -12667,8 +12742,6 @@ String(diagJson) +
 
 
 
-
-
 
 
 
@@ -12688,12 +12761,32 @@ 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  const __custom = (typeof window !== 'undefined' && window.__ppCustomRelations) ? Object.values(window.__ppCustomRelations) : [];\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.spl" +
-"it('*')[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 ? { removeMember: [{ 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  // 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 { s" +
-"uccess: true, density: result.density, suggestions: result.suggestions,\n    ...(Array.isArray(result.warnings) && result.warnings.length ? { warnings: result.warnings } : {}),\n    relations: __rels, ...(__relCount > __rels.length ? { relationsShown: __rels.length, relationCount: __relCount } : {}),\n    ...(__custom.length ? { customRelations: __custom } : {}),\n    ...(__edit.groups.length || __edit.relations.length || __edit.customRelations.length ? { edit: __edit } : {}) };\n})();"
+") 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 (" +
+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 (!" +
+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 (" +
+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})();"
+
+
+
+
+
+
+
+
+
+
+
+
+
 
 
 
@@ -13699,7 +13792,7 @@ String(interval === null ? 'null' : interval) +
   ${guard}
   const r = await app.removeLook(${target});
   if (!r || r.ok === false) return { success: false, action: 'remove', error: (r && r.error) || 'nothing to remove' };
-  return { success: true, action: 'remove', target: ${target}, removed: r.removed, scene: r.scene, note: 'removing a look restores colours, strokes, shadows, fonts and pixels, not geometry; it has been measured leaving a multi-part character rig about 1 px off its pose (LOOKRESTORE). Check the pose if pixel-exact alignment matters.' };
+  return { success: true, action: 'remove', target: ${target}, removed: r.removed, scene: r.scene, ...(typeof app._applySkewKeyframePose !== 'function' ? { note: 'this studio restores colours, strokes, shadows, fonts and pixels when a look is removed, not geometry; it has been measured leaving a multi-part character rig about 1 px off its pose (LOOKRESTORE). Check the pose if pixel-exact alignment matters, or update the studio.' } : {}) };
 })();`.trim();
             case 'grid':
                 return `
@@ -13933,16 +14026,18 @@ ${body}
                 return ("\n// Medium: apply " +
 String(oneLine(input.medium)) +
 "\n(async function() {\n  if (typeof app.applyMedium !== 'function') { return { success: false, error: 'app.applyMedium unavailable — update FxTool' }; }\n" +
-String(input.medium === 'ink' && input.options && input.options.keepColor && !input.options.color ? `  // INKCOLOR (mcp-cloud #30): keepColor keeps the item's colour, but with no
-  // color the ink MARKS take the brush default (#16141c). They take the item's
-  // own colour instead.
-  const __mopts = ${S(input.options)};
-  const __e0 = app.itemRegistry && app.itemRegistry.get(${S(input.itemId)});
-  const __it0 = (__e0 && __e0.item) || (app.getItemById ? app.getItemById(${S(input.itemId)}) : null);
-  const __css = function(c) { try { return c && typeof c.toCSS === 'function' ? c.toCSS(true) : null; } catch (_) { return null; } };
-  const __c0 = __it0 && (__css(__it0.strokeColor) || __css(__it0.fillColor));
-  if (__c0) __mopts.color = __c0;
-  const r = await app.applyMedium(${S(input.itemId)}, ${S(input.medium)}, __mopts);` : `  const r = await app.applyMedium(${S(input.itemId)}, ${S(input.medium)}, ${S(input.options ?? {})});`) +
+String(input.medium === 'ink' && input.options && input.options.keepColor && !input.options.color ? ("  // INKCOLOR (mcp-cloud #30): keepColor keeps the item's colour, but with no\n  // color the ink MARKS take the brush default (#16141c). They take the item's\n  // own colour instead.\n  const __mopts = " +
+String(S(input.options)) +
+";\n  // A studio from FxTool #261 on (which also brought _writeRasterPixels) picks the item's colour itself, gradients\n  // and text included, and says so in colorNote: leave it to the studio there.\n  const __e0 = typeof app._writeRasterPixels === 'function' ? null : app.itemRegistry && app.itemRegistry.get(" +
+String(S(input.itemId)) +
+");\n  const __it0 = typeof app._writeRasterPixels === 'function' ? null : ((__e0 && __e0.item) || (app.getItemById ? app.getItemById(" +
+String(S(input.itemId)) +
+") : null));\n  const __css = function(c) { try { return c && typeof c.toCSS === 'function' ? c.toCSS(true) : null; } catch (_) { return null; } };\n  const __c0 = __it0 && (__css(__it0.strokeColor) || __css(__it0.fillColor));\n  if (__c0) __mopts.color = __c0;\n  const r = await app.applyMedium(" +
+String(S(input.itemId)) +
+", " +
+String(S(input.medium)) +
+", __mopts);"
+) : `  const r = await app.applyMedium(${S(input.itemId)}, ${S(input.medium)}, ${S(input.options ?? {})});`) +
 "\n  if (!r || r.ok === false) {\n    return { success: false, error: (r && (r.error || r.reason)) || 'the medium could not be applied', medium: " +
 String(S(input.medium)) +
 ", ...(r && r.fidelity ? { fidelity: r.fidelity } : {}) };\n  }\n  // ink / charcoal restyle IN PLACE (FxTool D32): the same item, marked with\n  // data.brushStyle on its paths and texts. Read the mark back, so an item\n  // the engine passed over is a failure rather than a success (gate D32).\n  if (" +
@@ -13975,6 +14070,8 @@ String(S(input.medium)) +
 
 
 
+
+
 ).trim();
             case 'sdf_stroke': {
                 // FxTool D5: an SDF capsule stroke rendered to a bitmap and created as a