@pinepaper.studio/mcp-server 1.6.15 → 1.6.16

package/dist/types/code-generator.js

@@ -917,8 +917,15 @@ if (_flagged && _flagged.item && _flagged.item.data) Object.assign(_flagged.item
         + modIgnored.filter((k) => MODIFY_DID_YOU_MEAN[k]).map((k) => ` Did you mean ${MODIFY_DID_YOU_MEAN[k]} (not ${k})?`).join(''))}`;
     code += `
 app.historyManager.saveState();
+${properties.content !== undefined ? `
+// CONTENT UNDER A CONTENT TRACK (round 10, 10.13): the keyframes set the text
+// on every frame, so a direct edit is overwritten at once — it answered
+// success and changed nothing visible.
+const __ctItem = app.getItemById('${itemId}');
+const __ctKeys = (__ctItem && __ctItem.data && Array.isArray(__ctItem.data.keyframes))
+  ? __ctItem.data.keyframes.filter(function(k) { return k && k.properties && Object.prototype.hasOwnProperty.call(k.properties, 'content'); }).length : 0;` : ''}
 ${modDirection ? emitDirectionCheck(`app.getItemById('${itemId}')`, modDirection) : ''}${modTabular ? emitTabularCheck(`app.getItemById('${itemId}')`) : ''}${modStrokePos ? emitStrokePositionCheck(`app.getItemById('${itemId}')`, modStrokePos) : ''}
-return { success: true, itemId: '${itemId}'${modFit ? ', textFit: __textFit' : ''}${modDirection ? ', direction: __direction' : ''}${modTabular ? ', tabularFigures: __tabular' : ''}${modStrokePos ? ', strokePosition: __strokePos' : ''}${affine ? `, affine: ${JSON.stringify({ skewX, skewY, matrix, note: 'applied to the current shape: calling again compounds it. To undo, apply the inverse (negative skew, or the inverse matrix).' })}` : ''}${modLifetime ? ', lifetime: __lifetime' : ''}${modFont ? ', ...(__font ? { font: __font } : {})' : ''}${modWarning} };`;
+return { success: true, itemId: '${itemId}'${properties.content !== undefined ? `, ...(__ctKeys ? { contentTrackWarning: 'this text\\'s content is keyframed (' + __ctKeys + ' key(s)), so the track sets it on every frame and this edit does not show. Change the content keys with pinepaper_keyframe_animate (append: true replaces same-time keys), or animate another property.' } : {})` : ''}${modFit ? ', textFit: __textFit' : ''}${modDirection ? ', direction: __direction' : ''}${modTabular ? ', tabularFigures: __tabular' : ''}${modStrokePos ? ', strokePosition: __strokePos' : ''}${affine ? `, affine: ${JSON.stringify({ skewX, skewY, matrix, note: 'applied to the current shape: calling again compounds it. To undo, apply the inverse (negative skew, or the inverse matrix).' })}` : ''}${modLifetime ? ', lifetime: __lifetime' : ''}${modFont ? ', ...(__font ? { font: __font } : {})' : ''}${modWarning} };`;
     // Wrapped, because the body now RETURNS early on a miss rather than falling
     // through to an unconditional success. Async only when a font must load
     // before modifyItem re-measures the text.
@@ -1235,7 +1242,7 @@ if (!_target) {
   return { success: false, error: ${JSON.stringify(itemId)} + ' is not on the canvas, so ' + ${JSON.stringify(what)} + ' would have done nothing. Check the id with pinepaper_get_items — create returns the registry id, not the Paper id.' };
 }`.trim();
 }
-function generateKeyframeAnimateCode(itemId, keyframes, duration, loop = false, timeOffset, clipInPoint, clipOutPoint, timeUnits) {
+function generateKeyframeAnimateCode(itemId, keyframes, duration, loop = false, timeOffset, clipInPoint, clipOutPoint, timeUnits, append = false) {
     const keyframesJson = JSON.stringify(normalizeKeyframePositions(keyframes), null, 2);
     const calculatedDuration = duration || Math.max(...keyframes.map(k => k.time));
     const opts = { duration: calculatedDuration, loop };
@@ -1247,6 +1254,10 @@ function generateKeyframeAnimateCode(itemId, keyframes, duration, loop = false,
         opts.clipOutPoint = clipOutPoint;
     if (timeUnits !== undefined)
         opts.timeUnits = timeUnits;
+    // addAnimation SETS the item's track; mode 'merge' adds to it (FxTool
+    // 2475333b). An engine without merge ignores the option and replaces.
+    if (append)
+        opts.mode = 'merge';
     // A FADE ON AN AUDIO ITEM WAS ACCEPTED AND NEVER HEARD. addAnimation keyframes
     // the audio item's sentinel, and the mix reads one static audioGain per clip,
     // so {audioGain: 0→1} answered success, duration 15, and exported at a flat
@@ -1285,7 +1296,10 @@ function generateKeyframeAnimateCode(itemId, keyframes, duration, loop = false,
     const gaps = keyframes
         .map((k, i) => ({ time: k.time, missing: allProps.filter((p) => !propSets[i].includes(p)) }))
         .filter((g) => g.missing.length);
-    const gapNote = gaps.length && keyframes.length > 1
+    // 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];
@@ -1302,8 +1316,25 @@ function generateKeyframeAnimateCode(itemId, keyframes, duration, loop = false,
 // Apply keyframe animation to ${itemId}
 (function() {
   ${requireItem(itemId, 'the animation')}${audioLevelGuard}
+  // The track as it was, so the result can say what happened to it: merged
+  // (every earlier key still there) or replaced. That is the evidence of
+  // merge support — an older engine takes the option and replaces anyway.
+  const __ki = _target && (_target.item || _target);
+  const __prev = (__ki && __ki.data && Array.isArray(__ki.data.keyframes)) ? __ki.data.keyframes.map(function(k) { return k && k.time; }) : [];
   app.addAnimation('${itemId}', ${keyframesJson}, ${JSON.stringify(opts)});
-  return { success: true, itemId: '${itemId}', duration: ${calculatedDuration}, loop: ${loop}${timeOffset !== undefined ? `, timeOffset: ${timeOffset}` : ''}${clipInPoint !== undefined ? `, clipInPoint: ${clipInPoint}` : ''}${clipOutPoint !== undefined ? `, clipOutPoint: ${clipOutPoint}` : ''}${easingNote}${loopNote}${gapNote} };
+  const __now = (__ki && __ki.data && Array.isArray(__ki.data.keyframes)) ? __ki.data.keyframes.map(function(k) { return k && k.time; }) : [];
+  const __kept = __prev.every(function(t) { return __now.indexOf(t) >= 0; });${append ? `
+  // Property gaps across the merged track (the same check a single call makes
+  // on its own keys at generation time).
+  const __all = (__ki && __ki.data && Array.isArray(__ki.data.keyframes)) ? __ki.data.keyframes : [];
+  const __props = __all.reduce(function(acc, k) { Object.keys((k && k.properties) || {}).forEach(function(p) { if (acc.indexOf(p) < 0) acc.push(p); }); return acc; }, []);
+  const __gaps = __all.length > 1 ? __all.map(function(k) { const have = Object.keys((k && k.properties) || {}); return { time: k && k.time, missing: __props.filter(function(p) { return have.indexOf(p) < 0; }) }; }).filter(function(g) { return g.missing.length; }) : [];` : ''}
+  const __track = !__prev.length ? null
+    : ${append ? `(__kept
+      ? { appended: true, previousKeys: __prev.length, keys: __now.length }
+      : { appended: false, replaced: true, previousKeys: __prev.length, warning: 'append was asked for, but this studio replaced the existing track (' + __prev.length + ' key(s)) instead of adding to it: it has no merge mode. Put every key in one keyframe_animate call.' })`
+        : `{ replaced: true, previousKeys: __prev.length, note: 'the item already had a keyframe track (' + __prev.length + ' key(s)); this call replaced it. To add keys to it instead, pass append: true.' }`};
+  return { success: true, itemId: '${itemId}', duration: ${calculatedDuration}, loop: ${loop}${append ? ', append: true' : ''}, ...(__track ? { track: __track } : {})${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.' } : {})` : ''}${timeOffset !== undefined ? `, timeOffset: ${timeOffset}` : ''}${clipInPoint !== undefined ? `, clipInPoint: ${clipInPoint}` : ''}${clipOutPoint !== undefined ? `, clipOutPoint: ${clipOutPoint}` : ''}${easingNote}${loopNote}${gapNote} };
 })();
 `.trim();
 }
@@ -2283,7 +2314,7 @@ export class PinePaperCodeGenerator {
      */
     generateKeyframeAnimate(input) {
         const validated = KeyframeAnimateInputSchema.parse(input);
-        return generateKeyframeAnimateCode(validated.itemId, validated.keyframes, validated.duration, validated.loop, validated.timeOffset, validated.clipInPoint, validated.clipOutPoint, validated.timeUnits);
+        return generateKeyframeAnimateCode(validated.itemId, validated.keyframes, validated.duration, validated.loop, validated.timeOffset, validated.clipInPoint, validated.clipOutPoint, validated.timeUnits, validated.append);
     }
     /**
      * Generate code for importing / retargeting a motion-capture clip
@@ -3945,7 +3976,7 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
     }
     generateAgentExport(input) {
         const validated = AgentExportInputSchema.parse(input);
-        const { platform, format, quality, framing, duration, estimateOnly, scale, fps, pdf: pdfOpts, region, time: stillTime, maxBytes, loop: gifLoop, broadcast, broadcastHeadroom, bitrate, minBitrate, bitrateMode, transparent, alphaQuantizer, ad: adOpts } = validated;
+        const { platform, format, quality, framing, duration, estimateOnly, scale, fps, pdf: pdfOpts, region, time: stillTime, maxBytes, loop: gifLoop, broadcast, broadcastHeadroom, bitrate, minBitrate, bitrateMode, transparent, alphaQuantizer, deterministic, ad: adOpts } = validated;
         // Encoder options (FxTool 16719759); the schema keeps them to mp4 / webm.
         const videoEncodeOpts = {};
         if (broadcast)
@@ -3963,6 +3994,10 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
             videoEncodeOpts.minBitrate = minBitrate;
         if (bitrateMode !== undefined)
             videoEncodeOpts.bitrateMode = bitrateMode;
+        // Byte-identical repeats (FxTool 3b335567): the container timestamps are
+        // the only bytes that varied, and this pins them.
+        if (deterministic)
+            videoEncodeOpts.deterministic = true;
         // A transparent WebM (FxTool 1833b397) rides the store route too.
         const webmAlpha = format === 'webm' && transparent === true;
         if (webmAlpha) {
@@ -4968,6 +5003,18 @@ ${stillTime !== undefined ? `
 
   if (result && result.success) Object.assign(result, fidelity(format));
   if (result && result.success && __fit) result.platformFit = __fit;
+  // A LANDSCAPE CANVAS FOR A PORTRAIT PLATFORM (or the reverse) is not an
+  // aspect nuance but the wrong deliverable: tiktok on a 16:9 canvas came out
+  // 1920x1080 with only a note (round 10, 10.7). Said where a caller looks.
+  if (result && result.success && __fit) {
+    const __pw = __fit.preset.split('x').map(Number), __uw = __fit.used.split('x').map(Number);
+    if ((__pw[0] > __pw[1]) !== (__uw[0] > __uw[1]) && __pw[0] !== __pw[1]) {
+      result.fidelity = result.fidelity || { warnings: [] };
+      result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'platform_orientation_mismatch',
+        message: platform + ' is ' + (__pw[0] > __pw[1] ? 'landscape' : 'portrait') + ' (' + __fit.preset + '), but the canvas is ' + (__uw[0] > __uw[1] ? 'landscape' : 'portrait') + ', so the file is ' + __fit.used + '. For a ' + platform + ' deliverable, resize the canvas to ' + __fit.preset + ' (pinepaper_set_canvas_size) and re-lay the scene for it; the export does not reframe a scene.' }]);
+      if (result.fidelity.note) delete result.fidelity.note;
+    }
+  }
   // AUDIO TIMING, WHERE THE STUDIO REPORTS IT (6.27). An MP4's AAC track used
   // to start ~44 ms late and run past the picture — a 6.000 s bumper with sound
   // then failed its cap. The engine now reports the track; it is surfaced as
@@ -5037,7 +5084,34 @@ ${stillTime !== undefined ? `
       message: 'the file is ' + __vd.output[0] + 'x' + __vd.output[1] + ', not the requested ' + __vd.requested[0] + 'x' + __vd.requested[1] + ': H.264 needs even dimensions, so an odd side was rounded up by 1 px (the extra row / column is background). For an exact-pixel spec, use an even canvas size, or crop the extra line when re-encoding (ffmpeg -vf crop=' + __vd.requested[0] + ':' + __vd.requested[1] + ':0:0).' }]);
     if (result.fidelity.note) delete result.fidelity.note;
   }
-  // LUMA OUTSIDE 16-235 (8.35, FxTool 4f1ec3ae). The broadcast encode is
+${deterministic ? `  // DETERMINISTIC: the container timestamps are pinned either way; the PIXELS
+  // are only identical run to run on the software encoder, because the
+  // browser may pick a different hardware backend each time (FxTool
+  // e34ae03d: 92/255 between backends, 2/255 run to run on hardware). The
+  // engine requests software and reports what it got.
+  // Where the studio says outright whether the file repeats (bitExact, FxTool
+  // PR #31: it test-encodes and keeps whichever encoder does — often the
+  // HARDWARE one on a Mac, since Chrome's software H.264 is not repeatable at
+  // some sizes), that answer decides; the encoder name is only the fallback
+  // for studios that do not report it.
+  if (result && result.success) {
+    const __hw = __vr && __vr.hardwareAcceleration;
+    const __exact = __vr && typeof __vr.bitExact === 'boolean' ? __vr.bitExact : null;
+    if (__exact === false) {
+      result.fidelity = result.fidelity || { warnings: [] };
+      result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'determinism_not_pinned',
+        message: 'deterministic was asked for, but no encoder on this machine repeats byte for byte at this size (the studio test-encoded and checked): the pixels may differ slightly between runs. Do not cache this file by hash; a different frame size may repeat.' }]);
+      if (result.fidelity.note) delete result.fidelity.note;
+    } else if (__exact === null && __hw !== 'prefer-software') {
+      result.fidelity = result.fidelity || { warnings: [] };
+      result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'determinism_not_pinned',
+        message: __hw
+          ? 'deterministic was asked for, but the encoder ran with hardwareAcceleration ' + JSON.stringify(__hw) + ': the container is pinned, the pixels may still differ slightly between runs (hardware encoders vary). Do not cache this file by hash.'
+          : 'deterministic pinned the container timestamps, but this studio does not report which encoder backend ran, so the pixels may differ slightly between runs if the browser switches between hardware and software encoding. Do not rely on byte-identical files from this studio.' }]);
+      if (result.fidelity.note) delete result.fidelity.note;
+    }
+  }
+` : ''}  // LUMA OUTSIDE 16-235 (8.35, FxTool 4f1ec3ae). The broadcast encode is
   // decoded back and measured: H.264 ringing at hard edges puts a fraction of
   // a percent of samples out of range, which QC rejects. broadcastHeadroom
   // cuts it but never to zero, so a legaliser pass is the requirement.
@@ -7701,6 +7775,12 @@ ${loads}
         // Anything else (asset id, data:, URL) passes through untouched.
         // @engine-methods analyzeAudio animateToBeat
         const resolveSource = `  let __src = ${JSON.stringify(input.source || '')};
+  // A large source was staged beside the code (see the handler); read it back.
+  if (__src.indexOf('__ppStage:') === 0) {
+    const __staged = window.__ppStage && window.__ppStage[__src.slice('__ppStage:'.length)];
+    if (!__staged) return { success: false, error: 'the staged audio did not reach the page — try again, or upload it with pinepaper_media upload_audio and pass the returned id.' };
+    __src = __staged;
+  }
   const __A = (typeof window !== 'undefined') && window.PinePaperAgent;
   const __m = (__src && __A && typeof __A.listMedia === 'function')
     ? __A.listMedia().find(function(x) { return x.id === __src || x.registryId === __src; })
@@ -7724,6 +7804,11 @@ ${resolveSource}
   if (r && typeof r === 'object' && 'ok' in r) {
     return { success: r.ok !== false, ...r };
   }
+  // Nothing back is not a result: it was reported as success with an empty
+  // body (gap 5.5), which reads as "analysed, no beats".
+  if (r === undefined || r === null) {
+    return { success: false, error: '${method} returned nothing, so there is no result to report. If the source is large, upload it with pinepaper_media upload_audio and pass the returned id.' };
+  }
   return { success: true, result: r };
 })();`.trim();
         if (input.action === 'analyze') {
@@ -8247,7 +8332,12 @@ ${resolve}
   // engine mints a NUMBER. Returning the number meant the id could not be
   // round-tripped: pass it back to add/remove and zod rejects it before the
   // call is made.
-  const _pid = precomp && precomp.id !== undefined ? precomp.id : precomp;
+  // THE REGISTRY ID, not Paper's. createPrecomp returns the group, whose
+  // .id is Paper's numeric id ("49"), which no tool accepts back ("precomp:
+  // no such item(s): 49", round 10, 10.11). The registry id — what
+  // listPrecomps and every other tool use — is on the group's data.
+  const _d = (precomp && precomp.data) || {};
+  const _pid = _d.registryId || _d.id || (precomp && precomp.id !== undefined ? precomp.id : precomp);
   return { success: true, action: 'create', precompId: String(_pid), itemCount: items.length, name: ${JSON.stringify(input.name || '')} };
 })();`.trim();
             }
@@ -8258,7 +8348,11 @@ ${resolve}
   // addToPrecomp answers falsy when the precomp or the item is not found, and
   // this reported success regardless — the same silent-success shape as an
   // unknown itemId elsewhere.
-  const _ok = app.addToPrecomp(${JSON.stringify(input.precompId || '')}, ${JSON.stringify(input.itemId || '')});
+  // The engine takes the ITEM, not its id (it clones it); an id string made
+  // add throw and could never have worked. Resolved here, and a miss named.
+  const _item = app.getItemById(${JSON.stringify(input.itemId || '')});
+  if (!_item) return { success: false, action: 'add', error: 'no item ' + ${JSON.stringify(JSON.stringify(input.itemId || ''))} + ' on the canvas — check the id with pinepaper_get_items.' };
+  const _ok = app.addToPrecomp(${JSON.stringify(input.precompId || '')}, _item);
   if (_ok === false || _ok === null || _ok === undefined) {
     return { success: false, action: 'add', error: 'nothing was added — check the precompId (create returns it as a string) and the itemId with pinepaper_get_items.' };
   }
@@ -8268,7 +8362,14 @@ ${resolve}
                 return `
 // Remove item from precomp
 (function() {
-  app.removeFromPrecomp(${JSON.stringify(input.precompId || '')}, ${JSON.stringify(input.itemId || '')});
+  // The item, not its id (the engine checks item.parent); and its answer is
+  // read — null meant nothing was removed, and this said success regardless.
+  const _item = app.getItemById(${JSON.stringify(input.itemId || '')});
+  if (!_item) return { success: false, action: 'remove', error: 'no item ' + ${JSON.stringify(JSON.stringify(input.itemId || ''))} + ' on the canvas — check the id with pinepaper_get_items.' };
+  const _r = app.removeFromPrecomp(${JSON.stringify(input.precompId || '')}, _item);
+  if (_r === null || _r === undefined || _r === false) {
+    return { success: false, action: 'remove', error: 'nothing was removed — the item is not in that precomp, or the precompId is not a precomp (create returns it; list shows them).' };
+  }
   return { success: true, action: 'remove', precompId: ${JSON.stringify(input.precompId || '')}, itemId: ${JSON.stringify(input.itemId || '')} };
 })();`.trim();
             default:
@@ -9665,7 +9766,7 @@ ${checks.includes('contrast') ? `  const all = (app.itemRegistry && typeof app.i
 // Upload video from URL
 (async function() {
 ${guard}
-  const info = await A.uploadVideo(${srcExpr(input.url, 'video')}, ${opts});
+  const info = await A.uploadVideo(${srcExpr(input.url, 'video')}, ${input.atPlayhead ? `Object.assign(${opts}, { timeOffset: Number(app.playbackTime) || 0 })` : opts});
   return { success: true, action: 'upload_video', media: info };
 })();`.trim();
             }
@@ -9680,7 +9781,7 @@ ${guard}
 // Upload audio from URL
 (async function() {
 ${guard}
-  const info = await A.uploadAudio(${srcExpr(input.url, 'audio')}, ${opts});${input.volume !== undefined ? `
+  const info = await A.uploadAudio(${srcExpr(input.url, 'audio')}, ${input.atPlayhead ? `Object.assign(${opts}, { timeOffset: Number(app.playbackTime) || 0 })` : opts});${input.volume !== undefined ? `
   // THE LEVEL IS STORED UNDER ONE KEY AND EXPORTED FROM ANOTHER. The upload
   // records volume as \`gain\` on the registry entry; the video exporter's mix
   // reads \`audioGain\`. So a bed uploaded at 0.25 exported at unity (measured:
@@ -9729,10 +9830,37 @@ ${guard}
   if (typeof A.setMediaClip !== 'function') { return { success: false, error: 'setMediaClip unavailable — update FxTool' }; }
 ${resolveMedia}
   if (!__m) return __miss;
-  const ok = A.setMediaClip(__mid, ${input.inPoint}, ${input.outPoint});
+${input.timeOffset !== undefined ? `  // Moving the clip is the 4th argument, which older studios' setMediaClip
+  // does not take (it dropped it silently): its declared arity is the tell.
+  if (A.setMediaClip.length < 4) {
+    return { success: false, action: 'set_clip', id: __mid, error: 'this studio can re-trim a clip but not move it (setMediaClip takes no start time here) — nothing was changed. Update the studio, or remove and re-upload the clip with timeOffset.' };
+  }
+` : ''}  const ok = A.setMediaClip(__mid, ${input.inPoint}, ${input.outPoint}${input.timeOffset !== undefined ? `, ${input.timeOffset}` : ''});
   return ok
-    ? { success: true, action: 'set_clip', id: __mid, registryId: __m.registryId, inPoint: ${input.inPoint}, outPoint: ${input.outPoint} }
+    ? { success: true, action: 'set_clip', id: __mid, registryId: __m.registryId, inPoint: ${input.inPoint}, outPoint: ${input.outPoint}${input.timeOffset !== undefined ? `, timeOffset: ${input.timeOffset}` : ''} }
     : { success: false, action: 'set_clip', id: __mid, error: 'the studio refused the clip window ${input.inPoint}–${input.outPoint} for ' + __mid + '.' };
+})();`.trim();
+            // Split and transitions (FxTool, verified on main): the engine's own
+            // refusals come back as {ok:false, reason} and are errors here.
+            case 'split':
+                return `
+// Split a media clip at canvas time ${input.at}
+(async function() {
+${guard}
+  if (typeof A.splitMedia !== 'function') { return { success: false, action: 'split', error: 'this studio is too old to split a clip (no splitMedia) — nothing was changed.' }; }
+  const r = await A.splitMedia(${JSON.stringify(input.id)}, ${input.at});
+  if (!r || r.ok === false) return { success: false, action: 'split', error: (r && r.reason) || 'the studio refused the split' };
+  return Object.assign({ success: true, action: 'split' }, r);
+})();`.trim();
+            case 'add_transition':
+                return `
+// ${input.transition?.type ?? 'crossfade'} between ${input.fromItemId} and ${input.toItemId}
+(function() {
+${guard}
+  if (typeof A.addTransition !== 'function') { return { success: false, action: 'add_transition', error: 'this studio is too old for clip transitions (no addTransition) — nothing was changed.' }; }
+  const r = A.addTransition(${JSON.stringify(input.fromItemId)}, ${JSON.stringify(input.toItemId)}, ${JSON.stringify(input.transition ?? {})});
+  if (!r || r.ok === false) return { success: false, action: 'add_transition', error: (r && r.reason) || 'the studio refused the transition' };
+  return Object.assign({ success: true, action: 'add_transition' }, r);
 })();`.trim();
             // ── Video-editing actions (v1.6.4) — these live on `app` (PinePaper
             // facades), not the agent media API, so they carry their own guards.
@@ -9742,15 +9870,18 @@ ${resolveMedia}
                 return `
 // Remap a clip's time — speed ramps, freeze frames, reverse (null clears)
 (function() {
+  // A media id (vraster_ / araster_, what upload returns) is resolved to the
+  // registry id these app facades take (round 10, 10.12).
+  const __reg = function(r) { const __A = window.PinePaperAgent; const __m = (__A && typeof __A.listMedia === 'function') ? __A.listMedia().find(function(x) { return x.id === r; }) : null; return (__m && __m.registryId) || r; };
   if (typeof app.setTimeRemap !== 'function') { return { success: false, error: 'app.setTimeRemap unavailable — update FxTool to a time-remap-capable build' }; }
-  const r = app.setTimeRemap(${S(input.id)}, ${S(input.remapTrack ?? null)});
+  const r = app.setTimeRemap(__reg(${S(input.id)}), ${S(input.remapTrack ?? null)});
   if (!(r && r.ok)) return { success: false, error: (r && r.error) || 'remap failed' };
   // WHAT THE REMAP CANNOT DO, READ BACK FROM WHAT WAS STORED. The clip is on
   // the timeline only for its trimmed window, and past that it is HIDDEN
   // whatever the curve says — a remap to 6.5 s on a 5 s clip cut to black at
   // 5.0 s. Source values outside [inPoint, outPoint] are clamped, so that part
   // of the curve is a hold. Both answered success before.
-  const __rid = typeof app._resolveId === 'function' ? app._resolveId(${S(input.id)}) : ${S(input.id)};
+  const __rid = typeof app._resolveId === 'function' ? app._resolveId(__reg(${S(input.id)})) : ${S(input.id)};
   const __e = __rid && app.itemRegistry && app.itemRegistry.get(__rid);
   const __p = (__e && __e.properties) || {};
   const __tr = Array.isArray(__p.timeRemap) ? __p.timeRemap : [];
@@ -9778,15 +9909,18 @@ ${resolveMedia}
                 return `
 // Speed ramp: consecutive {duration, speed} segments compiled to a remap curve
 (function() {
+  // A media id (vraster_ / araster_, what upload returns) is resolved to the
+  // registry id these app facades take (round 10, 10.12).
+  const __reg = function(r) { const __A = window.PinePaperAgent; const __m = (__A && typeof __A.listMedia === 'function') ? __A.listMedia().find(function(x) { return x.id === r; }) : null; return (__m && __m.registryId) || r; };
   if (typeof app.speedRamp !== 'function') { return { success: false, error: 'app.speedRamp unavailable — update FxTool to a time-remap-capable build' }; }
-  const r = app.speedRamp(${S(input.id)}, ${S(input.segments)});
+  const r = app.speedRamp(__reg(${S(input.id)}), ${S(input.segments)});
   if (!(r && r.ok)) return { success: false, error: (r && r.error) || 'speed ramp failed' };
   // WHAT THE REMAP CANNOT DO, READ BACK FROM WHAT WAS STORED. The clip is on
   // the timeline only for its trimmed window, and past that it is HIDDEN
   // whatever the curve says — a remap to 6.5 s on a 5 s clip cut to black at
   // 5.0 s. Source values outside [inPoint, outPoint] are clamped, so that part
   // of the curve is a hold. Both answered success before.
-  const __rid = typeof app._resolveId === 'function' ? app._resolveId(${S(input.id)}) : ${S(input.id)};
+  const __rid = typeof app._resolveId === 'function' ? app._resolveId(__reg(${S(input.id)})) : ${S(input.id)};
   const __e = __rid && app.itemRegistry && app.itemRegistry.get(__rid);
   const __p = (__e && __e.properties) || {};
   const __tr = Array.isArray(__p.timeRemap) ? __p.timeRemap : [];
@@ -9822,8 +9956,11 @@ ${resolveMedia}
                 return `
 // Match cut: align the SUBJECT across the cut (on-device detection)
 (async function() {
+  // A media id (vraster_ / araster_, what upload returns) is resolved to the
+  // registry id these app facades take (round 10, 10.12).
+  const __reg = function(r) { const __A = window.PinePaperAgent; const __m = (__A && typeof __A.listMedia === 'function') ? __A.listMedia().find(function(x) { return x.id === r; }) : null; return (__m && __m.registryId) || r; };
   if (typeof app.matchCut !== 'function') { return { success: false, error: 'app.matchCut unavailable — update FxTool to a match-cut-capable build' }; }
-  const r = await app.matchCut(${S(input.fromItemId)}, ${S(input.toItemId)}, ${opts});
+  const r = await app.matchCut(__reg(${S(input.fromItemId)}), __reg(${S(input.toItemId)}), ${opts});
   if (r && r.needsConsent) { return { success: false, needsConsent: true, cost: r.cost, error: 'Detection model download needs consent — re-call with consent: true' }; }
   if (!r || !r.ok) { return { success: false, error: (r && r.error) || 'match cut failed' }; }
   return { success: true, action: 'match_cut', aspectMismatch: r.aspectMismatch || false };
@@ -9841,9 +9978,12 @@ ${resolveMedia}
                 return `
 // Track matte: the matte item's ${input.channel || 'luma'} drives the target's alpha${input.live ? ' (LIVE — re-cuts as the matte animates)' : ''}
 (async function() {
+  // A media id (vraster_ / araster_, what upload returns) is resolved to the
+  // registry id these app facades take (round 10, 10.12).
+  const __reg = function(r) { const __A = window.PinePaperAgent; const __m = (__A && typeof __A.listMedia === 'function') ? __A.listMedia().find(function(x) { return x.id === r; }) : null; return (__m && __m.registryId) || r; };
   if (typeof app.applyTrackMatte !== 'function') { return { success: false, error: 'app.applyTrackMatte unavailable — update FxTool to a track-matte-capable build' }; }
   try {
-    await app.applyTrackMatte(${S(input.id)}, ${S(input.matteItemId)}, ${opts});
+    await app.applyTrackMatte(__reg(${S(input.id)}), __reg(${S(input.matteItemId)}), ${opts});
     return { success: true, action: 'apply_track_matte', id: ${S(input.id)}, matte: ${S(input.matteItemId)}, live: ${S(!!input.live)} };
   } catch (e) {
     // The facade throws on a missing raster/matte rather than returning {ok:false}.
@@ -9856,8 +9996,11 @@ ${resolveMedia}
                 return `
 // Stop a live matte, leaving the last cut in place
 (function() {
+  // A media id (vraster_ / araster_, what upload returns) is resolved to the
+  // registry id these app facades take (round 10, 10.12).
+  const __reg = function(r) { const __A = window.PinePaperAgent; const __m = (__A && typeof __A.listMedia === 'function') ? __A.listMedia().find(function(x) { return x.id === r; }) : null; return (__m && __m.registryId) || r; };
   if (typeof app.stopLiveMatte !== 'function') { return { success: false, error: 'app.stopLiveMatte unavailable — update FxTool' }; }
-  const r = app.stopLiveMatte(${S(input.id)});
+  const r = app.stopLiveMatte(__reg(${S(input.id)}));
   return r && r.ok ? { success: true, action: 'stop_live_matte' } : { success: false, error: (r && r.error) || 'no live matte on that item' };
 })();`.trim();
             }
@@ -11876,4 +12019,119 @@ ${guard('unlockAllItems')}${pass('app.unlockAllItems()')}
 }
 // Export singleton instance
 export const codeGenerator = new PinePaperCodeGenerator();
+/**
+ * WORDS ARE VECTOR (cloud: every generated plate is text-free; the words come
+ * back as textLayers). Lays them out as real PinePaper text over a placed
+ * plate, by role, inside title-safe (5%), sized from the canvas height:
+ * headline top-left (Anton by default, fitted to the safe width), subhead
+ * under it, caption / cta stacked up from the bottom-left, label top-right.
+ * Each text is checked against the plate's average colour under it (WCAG:
+ * 4.5:1, 3:1 for large text) and gets the lightest dark scrim that passes
+ * when it falls short. A body for pinepaper_execute_custom_code (async).
+ */
+export function emitTextLayersPlacement(layers, plateRef) {
+    const ROLE_FONT = { headline: 'Anton' };
+    const families = [...new Set(layers.map((l) => l.font || ROLE_FONT[l.role ?? ''] || 'Inter'))];
+    const fontBlocks = families.map((f) => `{${emitEnsureFont(f)}
+  if (__font) fonts.push(__font);
+}`).join('\n');
+    return `
+const fonts = [];
+${fontBlocks}
+const plate = (function(r) {
+  let it = app.getItemById(r);
+  if (!it && window.PinePaperAgent && typeof window.PinePaperAgent.listMedia === 'function') {
+    const m = window.PinePaperAgent.listMedia().find(function(x) { return x.id === r || x.registryId === r; });
+    if (m) it = app.getItemById(m.registryId);
+  }
+  return it;
+})(${JSON.stringify(plateRef)});
+const cs = app.getCanvasSize();
+const W = cs.width, H = cs.height, mx = Math.round(W * 0.05), my = Math.round(H * 0.05);
+const LAYERS = ${JSON.stringify(layers)};
+const SPEC = {
+  headline: { size: 0.075, font: 'Anton', where: 'top' },
+  subhead: { size: 0.036, font: 'Inter', where: 'top' },
+  caption: { size: 0.028, font: 'Inter', where: 'bottom' },
+  cta: { size: 0.032, font: 'Inter', where: 'bottom', bold: true },
+  label: { size: 0.022, font: 'Inter', where: 'topright' },
+};
+const lin = function(v) { return v <= 0.04045 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4); };
+const make = function(l, spec, x, y, anchor) {
+  const size = Math.max(8, Math.round(H * spec.size));
+  const it = app.create('text', { content: l.content, x: x, y: y, fontSize: size, fontFamily: l.font || spec.font, color: '#ffffff', anchor: anchor });
+  if (!it) return null;
+  if (spec.bold) it.fontWeight = 'bold';
+  if (typeof app.fitText === 'function') {
+    try { app.fitText(it, { maxWidth: W - 2 * mx, maxFontSize: size, minFontSize: Math.max(8, Math.round(size * 0.4)), hold: anchor.indexOf('bottom') === 0 ? 'bottom' : 'top' }); } catch (_) { /* keeps its size */ }
+  }
+  return it;
+};
+const contrast = function(it, spec) {
+  if (!plate || typeof plate.getAverageColor !== 'function') return { checked: false, note: 'the plate is not an image the studio can sample (a video plate): contrast was not checked.' };
+  // The BRIGHT end of what is under the text, not its mean: a caption across
+  // bright reflections on a dark road averaged to 15:1 and was unreadable in
+  // the bright part. An 8 x 3 grid of cells, each averaged, judged at the
+  // 90th percentile of luminance.
+  const b0 = it.bounds, lums = [];
+  for (let gy = 0; gy < 3; gy++) {
+    for (let gx = 0; gx < 8; gx++) {
+      const cw = b0.width / 8, ch = b0.height / 3;
+      const cc = plate.getAverageColor(new paper.Rectangle(b0.left + gx * cw, b0.top + gy * ch, cw, ch));
+      if (cc) lums.push(0.2126 * lin(cc.red) + 0.7152 * lin(cc.green) + 0.0722 * lin(cc.blue));
+    }
+  }
+  if (!lums.length) return { checked: false };
+  lums.sort(function(x, y) { return x - y; });
+  const L = lums[Math.floor(0.9 * (lums.length - 1))];
+  const ratio = 1.05 / (L + 0.05);
+  const large = it.fontSize >= 24 || (spec.bold && it.fontSize >= 18.66);
+  const required = large ? 3 : 4.5;
+  const out = { checked: true, ratio: Math.round(ratio * 100) / 100, required: required, approximate: 'against the bright end (90th percentile of 24 sampled cells) of the plate behind the text' };
+  if (ratio >= required) return out;
+  // The lightest black scrim that reaches the requirement: under it the
+  // background luminance is L * (1 - a).
+  const a = Math.min(0.85, Math.max(0.2, 1 - (1.05 / required - 0.05) / L));
+  const pad = Math.round(it.fontSize * 0.35);
+  const b = it.bounds;
+  const s = app.create('rectangle', { x: b.left - pad, y: b.top - pad, width: b.width + 2 * pad, height: b.height + 2 * pad, color: '#000000', anchor: 'top-left' });
+  if (s) { s.opacity = a; if (typeof s.insertBelow === 'function') s.insertBelow(it); }
+  out.scrim = { itemId: s && s.data && s.data.registryId, opacity: Math.round(a * 100) / 100 };
+  out.ratioAfter = Math.round(1.05 / (L * (1 - a) + 0.05) * 100) / 100;
+  return out;
+};
+const role = function(l) { return SPEC[l.role] ? l.role : 'caption'; };
+const placed = [];
+let top = my;
+LAYERS.filter(function(l) { return SPEC[role(l)].where === 'top'; }).forEach(function(l) {
+  const spec = SPEC[role(l)];
+  const it = make(l, spec, mx, top, 'top-left');
+  if (!it) return;
+  top = it.bounds.bottom + Math.round(H * 0.015);
+  placed.push({ it: it, l: l, spec: spec });
+});
+let bottom = H - my;
+LAYERS.filter(function(l) { return SPEC[role(l)].where === 'bottom'; }).slice().reverse().forEach(function(l) {
+  const spec = SPEC[role(l)];
+  const it = make(l, spec, mx, bottom, 'bottom-left');
+  if (!it) return;
+  bottom = it.bounds.top - Math.round(H * 0.012);
+  placed.unshift({ it: it, l: l, spec: spec });
+});
+let rtop = my;
+LAYERS.filter(function(l) { return SPEC[role(l)].where === 'topright'; }).forEach(function(l) {
+  const spec = SPEC[role(l)];
+  const it = make(l, spec, W - mx, rtop, 'top-right');
+  if (!it) return;
+  rtop = it.bounds.bottom + Math.round(H * 0.01);
+  placed.push({ it: it, l: l, spec: spec });
+});
+if (app.historyManager) app.historyManager.saveState();
+return {
+  textItems: placed.map(function(p) {
+    return { itemId: p.it.data && p.it.data.registryId, role: role(p.l), content: p.l.content, fontFamily: p.it.fontFamily, fontSize: Math.round(p.it.fontSize), contrast: contrast(p.it, p.spec) };
+  }),
+  fonts: fonts,
+};`;
+}
 //# sourceMappingURL=code-generator.js.map