@pinepaper.studio/mcp-server 1.6.16 → 1.6.17

package/dist/types/code-generator.js

@@ -4,6 +4,7 @@
  * Converts MCP tool inputs to executable PinePaper JavaScript code.
  * This code is designed to run in the browser context where window.PinePaper is available.
  */
+import { normalizeSvgSize } from '../utils/svg-size.js';
 import { REQUIRED_ENGINE_METHODS, OPTIONAL_ENGINE_METHODS } from '../tools/engine-methods.js';
 import { ACCEPTED_CREATE_PARAMS, NORMALIZE_PARAM_READS, MODIFY_CHANGE_READS } from '../tools/shape-params.js';
 import { generateP5DrawCode } from '../tools/p5-compat/p5-helpers.js';
@@ -1697,7 +1698,8 @@ function generateSetCanvasSizeCode(width, height, preset) {
   // echoing the request back.
   return { success: true, width: (r && r.width) || ${width}, height: (r && r.height) || ${height},
     ...(r && r.preset ? { preset: r.preset } : {}),
-    ...(r && r.unbounded !== undefined ? { unbounded: r.unbounded } : {}) };
+    ...(r && r.unbounded !== undefined ? { unbounded: r.unbounded } : {})${!preset && (width > 8192 || height > 8192) ? `,
+    note: 'above 8192 px per side: Chrome and Firefox render it (the studio allows up to 16384 safely), but Safari and iOS may produce a blank or corrupt canvas — export from Chrome.'` : ''} };
 })();
 `.trim();
 }
@@ -2250,6 +2252,9 @@ export class PinePaperCodeGenerator {
      */
     generateModifyItem(input) {
         const validated = ModifyItemInputSchema.parse(input);
+        if (validated.atTime !== undefined) {
+            return generateAutoKeyCode(validated.itemId, validated.properties, validated.atTime, validated.easing);
+        }
         return generateModifyItemCode(validated.itemId, validated.properties, validated.data);
     }
     /**
@@ -2466,12 +2471,21 @@ ${INLINE_REMOTE_IMAGES}
   imported.scale(${scale});
   const itemId = app.registerItem(imported, 'svg-import', { source: 'mcp' });
   app.historyManager.saveState();
+  const _b = imported.bounds;
+  const _tiny = _b && _b.width < 16 && _b.height < 16;
   return { success: true, itemId, changes: _r.changes, position: { x: ${position.x}, y: ${position.y} },
+    size: _b ? { width: Math.round(_b.width * 10) / 10, height: Math.round(_b.height * 10) / 10 } : null,
+    ...(_tiny ? { warning: 'the SVG came in at ' + _b.width.toFixed(1) + 'x' + _b.height.toFixed(1) + ' px — too small to see (a root sized in em or % reads as 1 px). Pass scale, or give the SVG a width / height in px.' } : {}),
     ...(_inl.notes.length ? { imageWarnings: _inl.notes } : {}) };
 })();
 `.trim();
         }
         if (svgString) {
+            // A root sized in em / % (icon sets) renders ~5 px: sized from the
+            // viewBox instead, and the result says so (see utils/svg-size.ts).
+            const sized = normalizeSvgSize(svgString);
+            svgString = sized.svg;
+            const sizeFix = sized.fix;
             // Escape the SVG string for embedding in code
             const escapedSvg = svgString.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$/g, '\\$');
             return `
@@ -2490,7 +2504,14 @@ imported.position = new paper.Point(${position.x}, ${position.y});
 imported.scale(${scale});
 const itemId = app.registerItem(imported, 'svg-import', { source: 'mcp' });
 app.historyManager.saveState();
+// A SPECK IS NOT A SUCCESS WORTH REPORTING QUIETLY: under 16 px both ways,
+// the import is said to be tiny, with the fix.
+const _b = imported.bounds;
+const _tiny = _b && _b.width < 16 && _b.height < 16;
 return { success: true, itemId, changes: _r.changes, position: { x: ${position.x}, y: ${position.y} },
+  size: _b ? { width: Math.round(_b.width * 10) / 10, height: Math.round(_b.height * 10) / 10 } : null,
+  ${sizeFix ? `sizeFix: ${JSON.stringify(sizeFix)},` : ''}
+  ...(_tiny ? { warning: 'the SVG came in at ' + _b.width.toFixed(1) + 'x' + _b.height.toFixed(1) + ' px — too small to see. Pass scale, or give the SVG a width / height in px.' } : {}),
   ...(_inl.notes.length ? { imageWarnings: _inl.notes } : {}) };
 })();
 `.trim();
@@ -3976,7 +3997,7 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
     }
     generateAgentExport(input) {
         const validated = AgentExportInputSchema.parse(input);
-        const { platform, format, quality, framing, duration, estimateOnly, scale, fps, pdf: pdfOpts, region, time: stillTime, maxBytes, loop: gifLoop, broadcast, broadcastHeadroom, bitrate, minBitrate, bitrateMode, transparent, alphaQuantizer, deterministic, 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, frames } = validated;
         // Encoder options (FxTool 16719759); the schema keeps them to mp4 / webm.
         const videoEncodeOpts = {};
         if (broadcast)
@@ -4007,13 +4028,22 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
         }
         const encodeOptsJs = Object.keys(videoEncodeOpts).length ? `, ...${JSON.stringify(videoEncodeOpts)}` : '';
         const qualityLevel = quality || 'standard';
-        const videoDuration = duration ?? 5;
+        let videoDuration = duration ?? 5;
         // Quality settings (bitrate in bps for VideoEncoder)
         const qualitySettings = {
             draft: { compression: 0.6, fps: 15, dpi: 72, bitrate: 2_000_000 },
             standard: { compression: 0.85, fps: 30, dpi: 150, bitrate: 5_000_000 },
             high: { compression: 0.95, fps: 60, dpi: 300, bitrate: 8_000_000 },
         }[qualityLevel];
+        // FRAMES, EXACTLY (showcase film, 11.1). The engine makes ceil(duration x
+        // fps) frames for mp4 / webm / gif and floor(...) for apng, so 7.91667 s
+        // at 24 fps was 191 frames, not 190 — and N / fps itself can land a hair
+        // above N in floating point (190 / 24 * 24 > 190). The duration is nudged
+        // a microsecond toward the side that rounds to N.
+        if (frames !== undefined) {
+            const fpsEff = fps ?? qualitySettings.fps;
+            videoDuration = frames / fpsEff + (format === 'apng' ? 1e-6 : -1e-6);
+        }
         // Platform presets
         const platformPresets = {
             'instagram': { width: 1080, height: 1080, staticFormat: 'png', animatedFormat: 'mp4' },
@@ -4494,6 +4524,9 @@ ${stillTime !== undefined ? `
           // a neighbouring card's overflowing headline. Older studios ignore the
           // fourth argument, and leave lastRegionExcluded unset.
           if ('lastRegionExcluded' in app) app.lastRegionExcluded = null;
+          // A video in the region is waited for at this time (round 12, 12.5):
+          // the render drew before the clip's seek landed.
+          if (typeof app.awaitMediaAt === 'function') await app.awaitMediaAt(${stillTime !== undefined ? stillTime : "typeof app.playbackTime === 'number' ? app.playbackTime : 0"});
           const regionUrl = app.renderRegionToDataURL(new paper.Rectangle(${region.x}, ${region.y}, ${region.width}, ${region.height}), rw, rh${region.excludeForeign === false ? '' : ', { excludeForeign: true }'});
           const __excluded = Array.isArray(app.lastRegionExcluded) ? app.lastRegionExcluded.filter(function(id) { return id; }) : null;
           // ITEMS THAT CROSS THE REGION'S EDGE (round 9 II, 1.78). In the sheet
@@ -4723,7 +4756,12 @@ ${stillTime !== undefined ? `
                 + ' MB inline ceiling, and this studio has no app.exportEngine.exportToStore to page it out of — update FxTool, or lower duration/quality',
             };
           }
-          return { success: true, platform, format, framing, data: await blobToDataUrl(blob), mimeType: videoMimeType, size: blob.size };
+          // The container the file IS: an encoder that cannot do H.264 at this
+          // size writes VP9 WebM (round 12: mp4 at 12000 px came back WebM),
+          // and naming it .mp4 breaks players. Said below in fidelity.
+          const __mime = (blob.type && String(blob.type).split(';')[0]) || videoMimeType;
+          const __fmt = __mime === 'video/webm' ? 'webm' : __mime === 'video/mp4' ? 'mp4' : format;
+          return { success: true, platform, format: __fmt, framing, data: await blobToDataUrl(blob), mimeType: __mime, size: blob.size };
         };
 
         // Camera framing requires going direct to videoExporter so width/height
@@ -5072,6 +5110,56 @@ ${stillTime !== undefined ? `
   // The applied value is the engine's own report where it gives one
   // (5adfcf1c: lastVideoReport.headroom), so the result and the report agree.
   if (result && result.success) result.broadcastHeadroom = { value: (__vr && typeof __vr.headroom === 'number') ? __vr.headroom : 12, defaulted: true, note: 'broadcast defaults to 12 luma codes of headroom, which keeps encoder ringing legal; pass broadcastHeadroom: 0 for the full range.' };` : ''}
+  // FROZEN OUTPUT (round 12, 12.3): constant bitrate at 3552x1080 answered
+  // success with 600 identical frames. The file cannot be decoded here on the
+  // store route, so this is a size check: an animated scene whose video
+  // carries under 0.002 bits per pixel per frame is almost certainly one
+  // frame repeated. Labelled as a suspicion, with how to confirm it.
+  if (result && result.success && (result.format === 'mp4' || result.format === 'webm') && result.fidelity && result.fidelity.checked && result.fidelity.checked.animated && typeof result.size === 'number') {
+    const __d = result.dimensions || dimensions;
+    const __frames = Math.max(1, Math.round(${videoDuration} * (settings.fps || 30)));
+    const __bpp = (result.size * 8) / Math.max(1, __d.width * __d.height * __frames);
+    // The studio's own count of distinct frames it fed the encoder, where it
+    // reports one, decides; the size is only the fallback (a small dot moving on
+    // a flat field is also a tiny file).
+    const __vf = __vr && __vr.frames;
+    const __distinct = __vf && typeof __vf.distinct === 'number' ? __vf.distinct : null;
+    // The studio's decoded-output test (output_frozen) is the real answer for
+    // an encoder freeze; the size guess stays out when it has spoken.
+    const __engineFrozen = !!(__vr && Array.isArray(__vr.warnings) && __vr.warnings.some(function(w) { return w && w.code === 'output_frozen'; }));
+    if (!__engineFrozen && (__distinct !== null ? __distinct <= 1 : __bpp < 0.002)) {
+      result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'possibly_frozen',
+        message: __distinct !== null
+          ? 'the scene animates, but the studio rendered ' + __distinct + ' distinct frame(s) for the encoder — the animation did not play during the export (not an encoder fault). Check that the animation runs on the timeline over the exported range.'
+          : 'the video carries ' + __bpp.toFixed(5) + ' bits per pixel per frame (' + result.size + ' bytes for ' + __frames + ' frames at ' + __d.width + 'x' + __d.height + ') — the encoder has most likely repeated one frame. Check two frames (ffprobe, or pinepaper_capture_frames against the scene); a smaller size, bitrateMode variable, or format webm usually avoids it.' }]);
+      if (result.fidelity.note) delete result.fidelity.note;
+    }
+  }
+  // THE STUDIO'S OWN CODED VIDEO WARNINGS (e.g. an output-side freeze the
+  // input-frame count cannot see): passed through when they carry a code this
+  // tool does not already raise from the numbers. Plain-string warnings are
+  // the bitrate / luma texts, raised above from their numbers instead.
+  if (result && result.success && __vr && Array.isArray(__vr.warnings)) {
+    // format_substituted is NOT here: the studio's own (agreed with FxTool)
+    // is the better-informed one, so it passes and this tool's is skipped.
+    const __mine = ['bitrate_below_floor', 'luma_out_of_range', 'determinism_not_pinned', 'dimensions_rounded', 'possibly_frozen', 'alpha_not_applied', 'alpha_keyframe_mismatch'];
+    const __extra = __vr.warnings.filter(function(w) { return w && typeof w === 'object' && typeof w.code === 'string' && __mine.indexOf(w.code) < 0; })
+      .map(function(w) { return { code: w.code, message: String(w.message || w.code) }; });
+    if (__extra.length) {
+      result.fidelity = result.fidelity || { warnings: [] };
+      result.fidelity.warnings = (result.fidelity.warnings || []).concat(__extra);
+      if (result.fidelity.note) delete result.fidelity.note;
+    }
+  }
+  // A DIFFERENT CONTAINER THAN ASKED (round 12, 12.7): the file is named by
+  // what it is, and the substitution is said, not left to a player to find.
+  const __studioSaidFormat = !!(__vr && Array.isArray(__vr.warnings) && __vr.warnings.some(function(w) { return w && w.code === 'format_substituted'; }));
+  if (!__studioSaidFormat && result && result.success && (result.format === 'mp4' || result.format === 'webm') && result.format !== format && (format === 'mp4' || format === 'webm')) {
+    result.fidelity = result.fidelity || { warnings: [] };
+    result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'format_substituted',
+      message: format + ' was asked for, but the browser encoder could not make ' + format + ' at ' + ((result.dimensions && result.dimensions.width) || '') + 'x' + ((result.dimensions && result.dimensions.height) || '') + ((__vr && __vr.codecFallback && __vr.codecFallback.reason) ? ' (' + __vr.codecFallback.reason + ')' : '') + ', so the file is ' + result.format + ' (saved with that extension). For ' + format + ' at this size, export smaller (scale) and upscale, or re-encode the ' + result.format + '.' }]);
+    if (result.fidelity.note) delete result.fidelity.note;
+  }
   // AN ODD SIDE ROUNDED UP (FxTool e64a5260). H.264 needs even dimensions, so
   // 1200x675 came out 1200x676 — and platform specs are exact-pixel. The
   // result's dimensions become what the file IS, and fidelity says why.
@@ -5125,7 +5213,10 @@ ${Object.keys(videoEncodeOpts).length ? `  if (result && result.success) {
     const __vw = [];
     // The engine joins its warnings into one string (bitrate floor, then
     // luma), so each is raised from its own numbers, not from that text.
-    if (__vr && typeof __vr.achievedBitrate === 'number' && typeof __vr.bitrateFloor === 'number' && __vr.achievedBitrate < __vr.bitrateFloor * 0.95) {
+    // The studio's own measured bitrate_not_honoured, where it sends one,
+    // replaces this estimate.
+    const __engineBitrate = !!(__vr && Array.isArray(__vr.warnings) && __vr.warnings.some(function(w) { return w && w.code === 'bitrate_not_honoured'; }));
+    if (!__engineBitrate && __vr && typeof __vr.achievedBitrate === 'number' && typeof __vr.bitrateFloor === 'number' && __vr.achievedBitrate < __vr.bitrateFloor * 0.95) {
       __vw.push({ code: 'bitrate_below_floor', message: 'achieved ' + (__vr.achievedBitrate / 1e6).toFixed(2) + ' Mbps against a ' + (__vr.bitrateFloor / 1e6).toFixed(1) + ' Mbps floor: the browser encoder treats the bitrate as a ceiling and does not pad simple content. Re-encode for delivery (e.g. ffmpeg -b:v with -minrate / -bufsize) if the spec requires the floor.' });
     }
     if (!__vr || typeof __vr !== 'object') {
@@ -6905,7 +6996,7 @@ ${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) {
 `.trim();
     }
     generateImportImage(input) {
-        const { url, position, maxWidth, maxHeight, mask, smoothing } = input;
+        const { url, position, maxWidth, maxHeight, mask, smoothing, maxEdge, nativeSize } = input;
         // Each fragment used to be written with a LEADING comma, as if it followed
         // an entry that no longer exists — so the first one opened the object with
         // `{, position: …}` and the emitted code was a syntax error. Passing any
@@ -6916,6 +7007,7 @@ ${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) {
             position ? `position: { x: ${position.x}, y: ${position.y} }` : '',
             maxWidth !== undefined ? `maxWidth: ${maxWidth}` : '',
             maxHeight !== undefined ? `maxHeight: ${maxHeight}` : '',
+            nativeSize ? 'nativeSize: true' : '',
         ].filter(Boolean);
         const optsLiteral = optParts.length ? `{ ${optParts.join(', ')} }` : '{}';
         return `
@@ -6971,7 +7063,7 @@ ${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) {
         fr.readAsDataURL(blob);
       });
     }
-    const entry = await app.imageTools.uploadFromURL(src);
+    const entry = await app.imageTools.uploadFromURL(src${maxEdge !== undefined ? `, { maxEdge: ${maxEdge === 'native' ? 'Infinity' : maxEdge} }` : ''});
     const opts = ${optsLiteral};
     const raster = await app.imageTools.placeImage(entry.id, Object.keys(opts).length > 0 ? opts : undefined);
 ${smoothing ? `    // Pixel art wants 'off': Paper's Raster draws with smoothing 'low' by
@@ -7010,7 +7102,13 @@ ${mask ? `    // A MASK REPLACES THE RASTER (round 8 DD, 4.10). applyMask builds
       success: true,
       itemId: itemId,
       message: 'Image imported and placed on canvas.',
-      bounds: { x: b.x, y: b.y, width: b.width, height: b.height }${mask ? `,\n      mask: '${mask}'` : ''}
+      bounds: { x: b.x, y: b.y, width: b.width, height: b.height }${mask ? `,\n      mask: '${mask}'` : ''},
+      // Stored smaller than its source (the studio's cap): said, with the
+      // way to keep every pixel. The studio reports native size where it can.
+      ...((entry && entry.nativeWidth && entry.width && entry.nativeWidth > entry.width)
+        ? { stored: { width: entry.width, height: entry.height }, native: { width: entry.nativeWidth, height: entry.nativeHeight },
+            note: 'the studio stored this image at ' + entry.width + 'x' + entry.height + ' (its source is ' + entry.nativeWidth + 'x' + entry.nativeHeight + '). Pass maxEdge: "native" to keep every pixel.' }
+        : {})
     };
   } catch (e) {
     return { error: 'Failed to import image: ' + e.message };
@@ -9525,24 +9623,55 @@ if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
         const n = Math.min(1200, Math.max(3, Math.round(duration * fps)));
         return `
 // Accessibility measurements (${checks.join(', ')})
-(function() {
+(async function() {
   const out = { success: true, fps: ${fps}, duration: ${duration} };
   const rgba = function(c) {
     if (!c || c.gradient || typeof c.red !== 'number') return null;
     return { r: Math.round(c.red * 255), g: Math.round(c.green * 255), b: Math.round(c.blue * 255), a: typeof c.alpha === 'number' ? c.alpha : 1 };
   };
   out.page = (app.canvasEl && app.canvasEl.style && app.canvasEl.style.backgroundColor) || null;
-${checks.includes('contrast') ? `  const all = (app.itemRegistry && typeof app.itemRegistry.getAll === 'function') ? app.itemRegistry.getAll() : [];
-  const texts = all.filter(function(e) { return e && e.item && e.item.className === 'PointText' && e.item.visible !== false && String(e.item.content || '').trim() !== ''; });
-  const solids = all.filter(function(e) { return e && e.item && e.item.className !== 'PointText' && e.item.visible !== false && rgba(e.item.fillColor) && e.item.bounds; });
-  out.texts = texts.map(function(e) {
-    const it = e.item, c = it.bounds.center;
-    const under = solids.filter(function(s) { return s.item.bounds.contains(c) && typeof s.item.isBelow === 'function' && s.item.isBelow(it); });
-    const top = under.reduce(function(best, s) { return (!best || (typeof s.item.isAbove === 'function' && s.item.isAbove(best.item))) ? s : best; }, null);
-    const w = String(it.fontWeight || '');
-    return { id: e.itemId, content: String(it.content), fill: rgba(it.fillColor), fontSize: it.fontSize || 0,
-      bold: w === 'bold' || Number(w) >= 700, behind: top ? rgba(top.item.fillColor) : null, behindId: top ? top.itemId : undefined };
+${checks.includes('contrast') ? `  // SAMPLED OVER TIME (round 12, 12.9): text is judged where it is on screen.
+  // Reading only the current playhead found no visible text in a scene of
+  // timed captions and passed with nothing checked. The times: 0, inside each
+  // text's lifetime, every keyframe time, and every second of the duration —
+  // the playhead is moved, lifetimes applied, and put back.
+  const all = (app.itemRegistry && typeof app.itemRegistry.getAll === 'function') ? app.itemRegistry.getAll() : [];
+  const snap = function(t) {
+    const texts = all.filter(function(e) { return e && e.item && e.item.className === 'PointText' && e.item.visible !== false && e.item.opacity !== 0 && String(e.item.content || '').trim() !== ''; });
+    const solids = all.filter(function(e) { return e && e.item && e.item.className !== 'PointText' && e.item.visible !== false && rgba(e.item.fillColor) && e.item.bounds; });
+    return texts.map(function(e) {
+      const it = e.item, c = it.bounds.center;
+      const under = solids.filter(function(s) { return s.item.bounds.contains(c) && typeof s.item.isBelow === 'function' && s.item.isBelow(it); });
+      const top = under.reduce(function(best, s) { return (!best || (typeof s.item.isAbove === 'function' && s.item.isAbove(best.item))) ? s : best; }, null);
+      const w = String(it.fontWeight || '');
+      return { id: e.itemId, t: t, content: String(it.content), fill: rgba(it.fillColor), fontSize: it.fontSize || 0,
+        bold: w === 'bold' || Number(w) >= 700, behind: top ? rgba(top.item.fillColor) : null, behindId: top ? top.itemId : undefined };
+    });
+  };
+  const times = [0];
+  all.forEach(function(e) {
+    const d = (e && e.item && e.item.data) || {};
+    if (typeof d.bornAt === 'number') times.push(d.bornAt + Math.min(0.1, (typeof d.ttl === 'number' ? d.ttl : 1) / 2));
+    if (Array.isArray(d.keyframes)) d.keyframes.forEach(function(k) { if (k && typeof k.time === 'number') times.push(k.time); });
   });
+  Array.from({ length: Math.floor(${duration}) + 1 }, function(_, i) { times.push(i); });
+  const uniq = times.filter(function(t, i) { return t >= 0 && t <= ${duration} + 1e-6 && times.indexOf(t) === i; }).sort(function(a, b) { return a - b; }).slice(0, 60);
+  const L = globalThis.__ppMcp;
+  const at = function(t) {
+    if (typeof app.setPlaybackTime === 'function') app.setPlaybackTime(t);
+    if (L && L.lifetimeApp === app && typeof L.applyLifetimes === 'function') { try { L.applyLifetimes(t); } catch (_) { /* sampled as is */ } }
+    if (typeof paper !== 'undefined' && paper.view && typeof paper.view.update === 'function') paper.view.update();
+  };
+  const prevT = typeof app.playbackTime === 'number' ? app.playbackTime : 0;
+  out.texts = [];
+  if (typeof app.setPlaybackTime === 'function') {
+    uniq.forEach(function(t) { at(t); out.texts = out.texts.concat(snap(t)); });
+    at(prevT);
+    out.sampledTimes = uniq.length;
+  } else {
+    out.texts = snap(prevT);
+    out.sampledTimes = 1;
+  }
 ` : ''}${checks.includes('flash') ? `  if (typeof app.captureFramesAt !== 'function') {
     out.flashUnavailable = 'this studio has no deterministic frame capture (app.captureFramesAt), so flashing was not checked.';
   } else {
@@ -9552,7 +9681,9 @@ ${checks.includes('contrast') ? `  const all = (app.itemRegistry && typeof app.i
     const ctx = small.getContext('2d', { willReadFrequently: true });
     const lut = Array.from({ length: 256 }, function(_, v) { const x = v / 255; return x <= 0.04045 ? x / 12.92 : Math.pow((x + 0.055) / 1.055, 2.4); });
     const times = Array.from({ length: ${n} }, function(_, i) { return i / ${fps}; });
-    out.series = app.captureFramesAt(times, { capture: function(c) {
+    // Waits for video per frame where the studio can (12.6).
+    const __cap = typeof app.captureFramesAtAsync === 'function' ? app.captureFramesAtAsync.bind(app) : app.captureFramesAt.bind(app);
+    out.series = await __cap(times, { capture: function(c) {
       // Transparent canvas shows the page's CSS background, so composite on it.
       ctx.fillStyle = out.page || '#ffffff';
       ctx.fillRect(0, 0, W, H);
@@ -9578,7 +9709,7 @@ ${checks.includes('contrast') ? `  const all = (app.itemRegistry && typeof app.i
         const includeDataUrls = !!input.includeDataUrls;
         return `
 // Deterministic frame capture
-(function() {
+(async function() {
   if (typeof app.captureFramesAt !== 'function') {
     return { success: false, error: 'app.captureFramesAt unavailable — update FxTool to a build with the deterministic capture entrypoint' };
   }
@@ -9595,7 +9726,24 @@ ${checks.includes('contrast') ? `  const all = (app.itemRegistry && typeof app.i
     // plain 9-text scene (round 7 X, #7) on studios without hashFrame. A native
     // reduce is not a generated loop and is not counted; same djb2-xor.
     : function(s) { return Array.prototype.reduce.call(s, function(h, c) { return (((h << 5) + h) ^ c.charCodeAt(0)) >>> 0; }, 5381).toString(16); };
-  const frames = app.captureFramesAt(${timesJson}, {
+  // A VIDEO ON SCREEN IS WAITED FOR (round 12, 12.6): the sync capture drew
+  // before a clip's seek landed, so a frame showed the previous time's
+  // picture. captureFramesAtAsync waits per frame; older studios keep the
+  // sync one (and say video-not-synced themselves).
+  //
+  // What is REPORTED is what happened, not what exists (retest of 009f00e: a
+  // "videoSynced: true" capture right after an upload showed the video black).
+  // videoWait says whether the studio waited per frame; firstSeek is the
+  // studio's own answer for the first time (seeked / timedOut / skipped).
+  // A seek that times out later is an engine warning (video-seek-timeout),
+  // forwarded in governor.engineWarnings.
+  const __waits = typeof app.captureFramesAtAsync === 'function';
+  let __firstSeek = null;
+  if (typeof app.awaitMediaAt === 'function' && ${timesJson}.length) {
+    try { __firstSeek = await app.awaitMediaAt(${timesJson}[0]); } catch (e) { __firstSeek = { error: String(e && e.message || e) }; }
+  }
+  const __cap = __waits ? app.captureFramesAtAsync.bind(app) : app.captureFramesAt.bind(app);
+  const frames = await __cap(${timesJson}, {
     seed: ${seed},
     capture: function(c, t, i) {
       // Prefer app.captureFrameDataURL(): it renders only the used region, so an
@@ -9610,7 +9758,11 @@ ${checks.includes('contrast') ? `  const all = (app.itemRegistry && typeof app.i
     }
   });
   const uniqueHashes = new Set(frames.map(function(f) { return f.hash; })).size;
-  return { success: true, seed: ${seed}, frameCount: frames.length, uniqueHashes: uniqueHashes, allIdentical: uniqueHashes <= 1, frames: frames };
+  return { success: true, seed: ${seed}, frameCount: frames.length, uniqueHashes: uniqueHashes, allIdentical: uniqueHashes <= 1,
+    videoWait: __waits ? 'awaited per frame' : 'not supported by this studio (frames may show a video before its seek lands)',
+    ...(__firstSeek ? { firstSeek: __firstSeek } : {}),
+    ...(__firstSeek && __firstSeek.timedOut > 0 ? { videoWarning: 'the video seek for the first frame timed out: its video may show an earlier picture. Retry after the clip has loaded.' } : {}),
+    frames: frames };
 })();`.trim();
     }
     /**
@@ -9758,6 +9910,7 @@ ${checks.includes('contrast') ? `  const all = (app.itemRegistry && typeof app.i
                 const opts = JSON.stringify({
                     ...(input.position ? { position: input.position } : {}),
                     ...(input.scale !== undefined ? { scale: input.scale } : {}),
+                    ...(input.fit !== undefined ? { fit: input.fit } : {}),
                     ...(input.timeOffset !== undefined ? { timeOffset: input.timeOffset } : {}),
                     ...(input.clipInPoint !== undefined ? { clipInPoint: input.clipInPoint } : {}),
                     ...(input.clipOutPoint !== undefined ? { clipOutPoint: input.clipOutPoint } : {}),
@@ -11239,7 +11392,10 @@ ${guard(fn)}
             }
             case 'render_soundtrack': {
                 const opts = {
-                    ...(typeof input.options?.duration === 'number' ? { duration: input.options.duration } : {}),
+                    // A top-level duration was stripped by the schema and the render
+                    // used its default length, silently; both spellings are read now.
+                    ...(typeof input.duration === 'number' ? { duration: input.duration }
+                        : typeof input.options?.duration === 'number' ? { duration: input.options.duration } : {}),
                     ...(input.sampleRate !== undefined ? { sampleRate: input.sampleRate } : {}),
                     ...(input.bitDepth !== undefined ? { bitDepth: input.bitDepth } : {}),
                 };
@@ -12134,4 +12290,98 @@ return {
   fonts: fonts,
 };`;
 }
+/**
+ * AUTO-KEY FROM AN AGENT (plan C5a): "at t, make it orange" writes a key at t,
+ * the way a user's drag does with auto-key on — not a static edit.
+ *
+ * The key is MERGED into the item's track (addAnimation mode 'merge'): other
+ * keys stay. So the track stays whole:
+ * - the new key also carries every OTHER animated property's value at t
+ *   (getInterpolatedState), because a key missing a property the others
+ *   animate can break that property's curve;
+ * - a property the track did not animate yet is added to every existing key
+ *   (its old value before t, the new one from t), and a first key at 0 holds
+ *   the old value, so the change eases in from what it was instead of
+ *   jumping.
+ * No duration is passed: addAnimation starts timeline playback when given one.
+ * The result names each property's previous value and what was written.
+ */
+export function generateAutoKeyCode(itemId, props, atTime, easing) {
+    return `
+// Auto-key ${itemId} at ${atTime}s
+(function() {
+  const item = app.getItemById(${JSON.stringify(itemId)});
+  if (!item) return { success: false, error: ${JSON.stringify(`no item "${itemId}" on the canvas — check the id with pinepaper_get_items.`)} };
+  if (typeof app.addAnimation !== 'function') return { success: false, error: 'this studio cannot write keyframes (no addAnimation).' };
+  const AT = ${atTime};
+  const NEW = ${JSON.stringify(props)};
+  const track = (item.data && Array.isArray(item.data.keyframes)) ? item.data.keyframes : [];
+  const animated = track.reduce(function(a, k) { Object.keys((k && k.properties) || {}).forEach(function(p) { if (a.indexOf(p) < 0) a.push(p); }); return a; }, []);
+  // The static value of a property the track does not animate yet.
+  const read = function(p) {
+    const c = function(v) { return v && typeof v.toCSS === 'function' ? v.toCSS(true) : v; };
+    if (p === 'x') return item.position && item.position.x;
+    if (p === 'y') return item.position && item.position.y;
+    if (p === 'scale') return item.scaling ? item.scaling.x : 1;
+    if (p === 'scaleX') return item.scaling ? item.scaling.x : 1;
+    if (p === 'scaleY') return item.scaling ? item.scaling.y : 1;
+    if (p === 'color' || p === 'fillColor') return c(item.fillColor);
+    if (p === 'strokeColor') return c(item.strokeColor);
+    if (p === 'width') return item.bounds && item.bounds.width;
+    if (p === 'height') return item.bounds && item.bounds.height;
+    const v = item[p];
+    return (v === undefined || typeof v === 'function') ? undefined : c(v);
+  };
+  const state = (track.length && typeof app.getInterpolatedState === 'function') ? (app.getInterpolatedState(item, AT) || {}) : {};
+  const byTime = {};
+  const put = function(t, p, v, e) { const k = byTime[t] || (byTime[t] = { time: t, properties: {} }); k.properties[p] = v; if (e) k.easing = e; };
+  const changes = [];
+  Object.keys(NEW).forEach(function(p) {
+    const wasAnimated = animated.indexOf(p) >= 0;
+    const before = wasAnimated ? state[p] : read(p);
+    if (!wasAnimated && before !== undefined) {
+      track.forEach(function(k) { put(k.time, p, k.time < AT ? before : NEW[p]); });
+      if (!track.length && AT > 0) put(0, p, before);
+    }
+    changes.push({ property: p, before: before === undefined ? null : before, after: NEW[p], easedFrom: before === undefined ? 'unknown — keyed at t only' : (wasAnimated ? 'the track' : 'its value before t') });
+  });
+  // The key at t: the new values, plus every other animated property as it is at t.
+  animated.forEach(function(p) { if (!(p in NEW) && state[p] !== undefined) put(AT, p, state[p]); });
+  Object.keys(NEW).forEach(function(p) { put(AT, p, NEW[p], ${JSON.stringify(easing ?? null)}); });
+  const keys = Object.keys(byTime).map(function(t) { return byTime[t]; }).sort(function(a, b) { return a.time - b.time; });
+  const beforeTimes = track.map(function(k) { return k.time; });
+  app.addAnimation(${JSON.stringify(itemId)}, keys, { mode: 'merge' });
+  const after = (item.data && Array.isArray(item.data.keyframes)) ? item.data.keyframes : [];
+  const kept = beforeTimes.every(function(t) { return after.some(function(k) { return k.time === t; }); });
+  if (!kept) return { success: false, error: 'this studio replaced the track instead of merging into it (no merge mode): the earlier keys are gone. Put every key in one keyframe_animate call.', atTime: AT };
+  if (app.historyManager) app.historyManager.saveState();
+  return { success: true, itemId: ${JSON.stringify(itemId)}, atTime: AT, autoKeyed: true, changes: changes, keys: after.length,
+    note: 'written as keyframes (a temporal edit), not a static change; pinepaper_query_mutations shows the series.' };
+})();`.trim();
+}
+/**
+ * A property's time series (plan C5a): the item's own keyframe track, read
+ * back. Until the engine keeps a mutation log (C3) this is the keys, not the
+ * history of who changed what — the result says so.
+ */
+export function generateQueryMutationsCode(itemId, property, range, fps = 30) {
+    return `
+// Keyframe series for ${itemId}${property ? '.' + property : ''}
+(function() {
+  const item = app.getItemById(${JSON.stringify(itemId)});
+  if (!item) return { success: false, error: ${JSON.stringify(`no item "${itemId}" on the canvas.`)} };
+  const P = ${JSON.stringify(property ?? null)}, R = ${JSON.stringify(range ?? null)}, FPS = ${fps};
+  const track = (item.data && Array.isArray(item.data.keyframes)) ? item.data.keyframes : [];
+  const series = {};
+  track.forEach(function(k) {
+    if (R && (k.time < R[0] || k.time > R[1])) return;
+    Object.keys((k && k.properties) || {}).forEach(function(p) {
+      if (P && p !== P) return;
+      (series[p] = series[p] || []).push({ t: k.time, frame: Math.round(k.time * FPS), value: k.properties[p], easing: k.easing || null });
+    });
+  });
+  return { success: true, itemId: ${JSON.stringify(itemId)}, source: 'keyframes', series: series, keys: track.length,
+    note: 'the item\\'s keyframe track, read back. Who changed what and the before value per edit need the studio\\'s mutation log, which this studio does not expose yet.' };
+})();`.trim();
+}
 //# sourceMappingURL=code-generator.js.map