@pinepaper.studio/mcp-server 1.6.16 → 1.6.18

package/dist/types/code-generator.js

@@ -4,6 +4,8 @@
  * 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 { WORLD3D_COLOR_PATHS } from '../tools/engine-lists.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';
@@ -23,7 +25,7 @@ GlobeEnableInputSchema, GlobeRotateToInputSchema, GlobeSpinInputSchema, WorldTou
 // Custom relation/code types
 RegisterCustomRelationInputSchema, ExecuteCustomCodeInputSchema, 
 // Mask types
-ApplyAnimatedMaskInputSchema, ApplyCustomMaskInputSchema, RemoveMaskInputSchema, SceneGraphInputSchema, SequenceInputSchema, StaggerInputSchema, FlipInputSchema, QueryCapabilitiesInputSchema, } from './schemas.js';
+ApplyAnimatedMaskInputSchema, ApplyCustomMaskInputSchema, RemoveMaskInputSchema, SceneGraphInputSchema, SequenceInputSchema, StaggerInputSchema, FlipInputSchema, QueryCapabilitiesInputSchema, KEYFRAME_EASINGS, EASING_DESCRIPTIONS, } from './schemas.js';
 import { OntologyCompiler } from '../ontology/ontology-compiler.js';
 // =============================================================================
 // HELPER FUNCTIONS
@@ -1697,7 +1699,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();
 }
@@ -2211,6 +2214,39 @@ function world3dColor(value) {
         return value;
     return [0, 2, 4].map((i) => parseInt(full.slice(i, i + 2), 16) / 255);
 }
+/**
+ * The world spec's colour fields: GENERATED from FxTool WORLD_SCHEMA's kind
+ * 'color' entries (scripts/sync-engine-lists.mjs). None of them is named
+ * `color`, so world3dColors never touched them and a hex `env.zenith` reached
+ * the engine as a string, where the validator refused it.
+ */
+export { WORLD3D_COLOR_PATHS };
+/** A hex colour to [r, g, b] 0..1; anything else unchanged (arrays too: light colours may exceed 1). */
+export function world3dHex(value) {
+    return typeof value === 'string' ? world3dColor(value) : value;
+}
+/** Convert hex strings at the world spec's colour paths (configure / create). */
+export function world3dSpecColors(spec) {
+    if (!spec || typeof spec !== 'object' || Array.isArray(spec))
+        return spec;
+    const out = JSON.parse(JSON.stringify(spec));
+    for (const path of WORLD3D_COLOR_PATHS) {
+        const [group, key] = path.split('.');
+        const g = out[group];
+        if (g && typeof g === 'object' && key in g)
+            g[key] = world3dHex(g[key]);
+    }
+    return out;
+}
+/** A light or material spec with hex colours (color, emissive, sheenColor) converted; an array is left exactly as given. */
+function world3dHexColor(spec) {
+    const out = { ...(spec ?? {}) };
+    for (const key of ['color', 'emissive', 'sheenColor']) {
+        if (typeof out[key] === 'string')
+            out[key] = world3dColor(out[key]);
+    }
+    return out;
+}
 /** Recursively convert every `color` field in a world3d payload. */
 function world3dColors(value) {
     if (Array.isArray(value))
@@ -2223,6 +2259,60 @@ function world3dColors(value) {
     }
     return out;
 }
+/** At most this many tiles in one contact sheet: past it, the tiles are too small to judge. */
+export const SHEET_MAX_TILES = 48;
+/**
+ * The times a contact sheet captures, and a label for each. Pure, so the
+ * modes are testable without a browser. Explicit `times` win; otherwise
+ * every / strip / loopSeam. Rounded to the millisecond, clamped at 0.
+ */
+export function sheetTimes(times, sheet) {
+    const r = (t) => Math.max(0, Math.round(t * 1000) / 1000);
+    const fmt = (t) => `${t.toFixed(2)}s`;
+    let out = [];
+    let labels = null;
+    if (times && times.length) {
+        out = times.map(r);
+    }
+    else if (sheet.strip) {
+        const { at, count, step } = sheet.strip;
+        const first = at - Math.floor(count / 2) * step;
+        out = Array.from({ length: count }, (_, i) => r(first + i * step));
+    }
+    else if (sheet.loopSeam && sheet.duration) {
+        // The frame BEFORE the loop wraps, then the first: a jump between them is the stutter.
+        out = [r(sheet.duration - 1 / 30), 0];
+        labels = [`end ${fmt(out[0])}`, 'start 0.00s'];
+    }
+    else if (sheet.every && sheet.duration) {
+        for (let t = 0; t < sheet.duration - 1e-9 && out.length < SHEET_MAX_TILES; t += sheet.every)
+            out.push(r(t));
+    }
+    out = out.slice(0, SHEET_MAX_TILES);
+    return { times: out, labels: labels ?? out.map(fmt) };
+}
+/**
+ * The critique an agent applies to a contact sheet. One scale, the same every
+ * time, so two passes over one film can be compared.
+ */
+export const SHEET_RUBRIC = {
+    scale: 'Score each 1-10. Under 7 on any line is a fix before export.',
+    criteria: [
+        'hook: does something worth watching happen in the first 2 s?',
+        'phone readability: at 360 px wide, can every word be read?',
+        'motion quality: do moves ease in and out, with nothing jumping or sliding at constant speed?',
+        'variety: does something change every 2-4 s, with no stretch that looks the same?',
+        'composition: is there a clear subject, with nothing crammed against an edge?',
+        'brand accuracy: are the colours, fonts and logo the brand\'s own?',
+        'sound sync: do cuts and hits land on the beat (check against pinepaper_beat_cuts)?',
+    ],
+    checklist: [
+        'text overlapping text or a subject',
+        'dead beats: adjacent tiles that are the same picture',
+        'labels or logos cut off in a corner',
+        'a jump between the last and first frame of a loop (loopSeam)',
+    ],
+};
 export class PinePaperCodeGenerator {
     /**
      * Generate code for creating an item
@@ -2250,6 +2340,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 +2559,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 +2592,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 +4085,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, motionBlur, ad: adOpts, frames } = validated;
         // Encoder options (FxTool 16719759); the schema keeps them to mp4 / webm.
         const videoEncodeOpts = {};
         if (broadcast)
@@ -3998,6 +4107,10 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
         // the only bytes that varied, and this pins them.
         if (deterministic)
             videoEncodeOpts.deterministic = true;
+        // Motion blur (FxTool #55): the engine forwards it on every mp4/webm path
+        // (quickExport, the agent paths, the export store, videoExporter.export).
+        if (motionBlur)
+            videoEncodeOpts.motionBlur = motionBlur;
         // A transparent WebM (FxTool 1833b397) rides the store route too.
         const webmAlpha = format === 'webm' && transparent === true;
         if (webmAlpha) {
@@ -4007,13 +4120,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' },
@@ -4278,7 +4400,10 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
       const bg = app.canvasEl && app.canvasEl.style && app.canvasEl.style.backgroundColor;
       const hasColor = !!bg && !/^(transparent|rgba\\([^)]*,\\s*0\\))$/i.test(bg);
       const hasBgItems = !!(app.patternGroup && app.patternGroup.children && app.patternGroup.children.length);
-      if (hasColor || hasBgItems) return [];
+      // A 3D world under the canvas IS the background: since FxTool #50
+      // (747315e3) jpg/webp stills composite it, so nothing turns white/black.
+      const hasWorld = !!app._world3d;
+      if (hasColor || hasBgItems || hasWorld) return [];
       return [{ code: 'alpha_dropped', message: fmt === 'apng'
         ? '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.'
         : fmt === 'jpg'
@@ -4335,7 +4460,9 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
       fps: settings.fps,
       quality,
       width: dimensions.width,
-      height: dimensions.height,
+      height: dimensions.height,${motionBlur ? `
+      // The estimate reports renders (frames x subframes) and renderCost.
+      motionBlur: ${JSON.stringify(motionBlur)},` : ''}
     });
     return {
       success: true,
@@ -4494,6 +4621,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 +4853,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 +5207,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 +5310,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') {
@@ -5139,6 +5327,17 @@ ${Object.keys(videoEncodeOpts).length ? `  if (result && result.success) {
       if (result.fidelity.note) delete result.fidelity.note;
     }
   }
+` : ''}${motionBlur ? `  // What the exporter actually did with motionBlur (FxTool #55 records it as
+  // lastMotionBlur, with renders = frames x subframes). A studio that predates
+  // it ignores the option silently, so that is said by name.
+  if (result && result.success) {
+    const __mb = __vx && __vx.lastMotionBlur;
+    if (__mb) result.motionBlur = __mb;
+    else {
+      result.fidelity = result.fidelity || { warnings: [] };
+      result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'motion_blur_not_applied', message: 'motionBlur was asked for, but this studio did not report applying it: it predates motion blur (FxTool #55), so the video has none.' }]);
+    }
+  }
 ` : ''}  const __ar = __vx && __vx.lastAudioReport;
   if (result && result.success && __ar && typeof __ar === 'object') {
     result.audio = __ar;
@@ -6770,19 +6969,25 @@ ${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) {
 `.trim();
     }
     generateGetAvailableEasings() {
+        // The engine's own list wins: listAnimatableProperties().easings is its
+        // EASING_NAMES, read from the easing table itself. The static list is the
+        // fallback for studios that predate it (fixture-pinned, easing-parity test).
         return `
 // Get available easing functions
 (function() {
+  const fallback = ${JSON.stringify(KEYFRAME_EASINGS)};
+  const descriptions = ${JSON.stringify(EASING_DESCRIPTIONS)};
+  let live = null;
+  try {
+    const r = typeof app !== 'undefined' && app && typeof app.listAnimatableProperties === 'function'
+      ? app.listAnimatableProperties() : null;
+    if (r && Array.isArray(r.easings) && r.easings.length) live = r.easings;
+  } catch (e) { live = null; }
   return {
-    easings: ['linear', 'easeIn', 'easeOut', 'easeInOut', 'bounce', 'elastic'],
-    descriptions: {
-      linear: 'Constant speed',
-      easeIn: 'Slow start, fast end',
-      easeOut: 'Fast start, slow end',
-      easeInOut: 'Slow start and end',
-      bounce: 'Bouncing effect at end',
-      elastic: 'Spring-like overshoot'
-    }
+    easings: live || fallback,
+    source: live ? 'engine' : 'mcp-server fallback list',
+    descriptions,
+    exportNote: 'Every easing renders exactly in video, GIF and APNG. Lottie and CSS get the closest single Bezier: springPlayful loses its wobble, and the in-out quart/quint/expo/circ curves are within 2-4%. SMIL is exact for springs and those four.'
   };
 })();
 `.trim();
@@ -6905,7 +7110,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 +7121,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 +7177,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 +7216,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 +9737,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 +9795,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);
@@ -9573,12 +9818,12 @@ ${checks.includes('contrast') ? `  const all = (app.itemRegistry && typeof app.i
 })();`.trim();
     }
     generateCaptureFrames(input) {
-        const timesJson = JSON.stringify(input.times);
+        const timesJson = JSON.stringify(input.times ?? []);
         const seed = input.seed !== undefined ? input.seed : 0;
         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 +9840,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 +9872,74 @@ ${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();
+    }
+    /**
+     * A contact sheet (G3): capture at the planned times and tile them into one
+     * image in the page. On a studio with sized capture (FxTool #42:
+     * captureFramesAt(times, { width, format })) the engine renders each frame
+     * small; on an older one the full frame is scaled while tiling.
+     */
+    generateCaptureSheet(input) {
+        const sheet = input.sheet;
+        const { times, labels } = sheetTimes(input.times, sheet);
+        const n = times.length;
+        const columns = sheet.columns ?? Math.min(6, Math.max(1, Math.ceil(Math.sqrt(n))));
+        const mime = sheet.format === 'png' ? 'image/png' : 'image/jpeg';
+        const S = (v) => JSON.stringify(v);
+        return `
+// Contact sheet of ${n} frame(s)
+(async function() {
+  if (typeof app.captureFramesAt !== 'function') {
+    return { success: false, error: 'app.captureFramesAt unavailable — update FxTool to a build with the deterministic capture entrypoint' };
+  }
+  const times = ${S(times)};
+  const labels = ${S(labels)};
+  const tileW = ${sheet.tileWidth};
+  const columns = ${columns};
+  const sized = typeof app._frameCapture === 'function';
+  const cap = typeof app.captureFramesAtAsync === 'function' ? app.captureFramesAtAsync.bind(app) : app.captureFramesAt.bind(app);
+  const urls = sized
+    ? await cap(times, { seed: ${input.seed ?? 0}, width: tileW, format: 'png' })
+    : await cap(times, { seed: ${input.seed ?? 0}, capture: function(c) {
+        return typeof app.captureFrameDataURL === 'function' ? app.captureFrameDataURL() : (c && c.toDataURL ? c.toDataURL() : '');
+      } });
+  const imgs = await Promise.all(urls.map(function(u) {
+    return new Promise(function(res) { const im = new Image(); im.onload = function() { res(im); }; im.onerror = function() { res(null); }; im.src = u; });
+  }));
+  const first = imgs.find(function(im) { return im && im.naturalWidth; });
+  if (!first) return { success: false, error: 'no frame could be captured' };
+  const tileH = Math.max(1, Math.round(tileW * first.naturalHeight / first.naturalWidth));
+  const rows = Math.ceil(imgs.length / columns);
+  const gap = 4;
+  const cv = document.createElement('canvas');
+  cv.width = columns * tileW + (columns + 1) * gap;
+  cv.height = rows * tileH + (rows + 1) * gap;
+  const g = cv.getContext('2d');
+  g.fillStyle = '#202020'; g.fillRect(0, 0, cv.width, cv.height);
+  imgs.forEach(function(im, i) {
+    const x = gap + (i % columns) * (tileW + gap);
+    const y = gap + Math.floor(i / columns) * (tileH + gap);
+    if (im) g.drawImage(im, x, y, tileW, tileH);
+    else { g.fillStyle = '#802020'; g.fillRect(x, y, tileW, tileH); }
+    if (${sheet.labels ? 'true' : 'false'}) {
+      const text = labels[i];
+      g.font = '600 13px system-ui, sans-serif';
+      const w = g.measureText(text).width + 10;
+      g.fillStyle = 'rgba(0,0,0,0.65)'; g.fillRect(x + 4, y + 4, w, 20);
+      g.fillStyle = '#fff'; g.fillText(text, x + 9, y + 19);
+    }
+  });
+  const dataUrl = cv.toDataURL(${S(mime)}${sheet.format === 'png' ? '' : ', 0.82'});
+  return { success: true, dataUrl: dataUrl, tiles: imgs.length, columns: columns, rows: rows,
+    width: cv.width, height: cv.height, tileWidth: tileW, times: times,
+    missing: imgs.filter(function(im) { return !im; }).length,
+    sizedCapture: sized };
 })();`.trim();
     }
     /**
@@ -9758,6 +10087,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 } : {}),
@@ -9989,6 +10319,45 @@ ${guard}
     // The facade throws on a missing raster/matte rather than returning {ok:false}.
     return { success: false, error: e && e.message ? e.message : String(e) };
   }
+})();`.trim();
+            }
+            case 'analyze_reference': {
+                const S = (v) => JSON.stringify(v);
+                return `
+// Measure a reference video's FORMAT: cuts, shot lengths, colours, pacing, beat
+(async function() {
+  if (typeof app.analyzeReferenceVideo !== 'function') { return { success: false, error: 'app.analyzeReferenceVideo unavailable — update FxTool' }; }
+  const r = await app.analyzeReferenceVideo(${S(input.id)}, { thumbnails: ${input.thumbnails ? 'true' : 'false'} });
+  if (!r || !r.ok) { return { success: false, error: (r && r.error) || 'the reference could not be analysed' }; }
+  // Kept in the page for remake_from_reference, so the analysis does not have
+  // to travel back through the agent.
+  window.__ppLastReference = { analysis: r, id: ${S(input.id)} };
+  const shots = Array.isArray(r.shots) ? r.shots : [];
+  return { success: true, referenceId: ${S(input.id)}, duration: r.duration, aspect: r.aspect, width: r.width, height: r.height,
+    cuts: r.cuts, shots: shots, pacing: r.pacing, audio: r.audio, card: r.card,
+    ...(r.truncated ? { truncated: true } : {}),
+    next: 'remake_from_reference with texts: your own words, ' + shots.length + ' (one per shot). Nothing of the footage, its words or its sound is copied.' };
+})();`.trim();
+            }
+            case 'remake_from_reference': {
+                const S = (v) => JSON.stringify(v);
+                const opts = {
+                    texts: input.texts ?? [],
+                    ...(input.duration !== undefined ? { duration: input.duration } : {}),
+                    ...(input.clear !== undefined ? { clear: input.clear } : {}),
+                };
+                return `
+// Build a new piece on the analysed reference's structure, in your own words
+(async function() {
+  if (typeof app.remakeFromReference !== 'function') { return { success: false, error: 'app.remakeFromReference unavailable — update FxTool' }; }
+  const last = window.__ppLastReference;
+  if (!last || !last.analysis) { return { success: false, error: 'no analysed reference in this session: call pinepaper_media analyze_reference first' }; }
+  // reference: the analysed clip stays in the project MUTED; without it the
+  // reference's own sound is exported under the new cards.
+  const r = await app.remakeFromReference(last.analysis, Object.assign(${S(opts)}, { reference: last.id }));
+  return r && r.ok
+    ? { success: true, action: 'remake_from_reference', duration: r.duration, shots: r.shots, items: r.items, referenceMuted: last.id }
+    : { success: false, error: (r && r.error) || 'the remake could not be built' };
 })();`.trim();
             }
             case 'stop_live_matte': {
@@ -10160,6 +10529,21 @@ ${guard}
         const S = (v) => JSON.stringify(v);
         const wrap = (comment, body) => `\n// ${comment}\n(function() {\n${body}\n})();`.trim();
         switch (input.action) {
+            case 'apply':
+                // One engine entry point (FxTool #54): app.applyMedium dispatches to the
+                // medium's own method (DesignMedia MEDIA[key].apply) and refuses an absent
+                // or brush-only medium with the reason. The Paper item it returns is not
+                // passed back (it cannot cross the bridge); its id is.
+                return `
+// Medium: apply ${input.medium}
+(async function() {
+  if (typeof app.applyMedium !== 'function') { return { success: false, error: 'app.applyMedium unavailable — update FxTool' }; }
+  const r = await app.applyMedium(${S(input.itemId)}, ${S(input.medium)}, ${S(input.options ?? {})});
+  if (!r || r.ok === false) {
+    return { success: false, error: (r && (r.error || r.reason)) || 'the medium could not be applied', medium: ${S(input.medium)}, ...(r && r.fidelity ? { fidelity: r.fidelity } : {}) };
+  }
+  return { success: true, action: 'apply', medium: r.medium || ${S(input.medium)}, fidelity: r.fidelity, itemId: r.id, ...(r.note ? { note: r.note } : {}) };
+})();`.trim();
             case 'list_media':
                 return wrap('Medium: list', `  if (typeof app.listDesignMedia !== 'function') { return { success: false, error: 'medium axis unavailable — update FxTool' }; }
   const media = app.listDesignMedia();
@@ -10476,12 +10860,15 @@ ${guard}
 // World3D: create — terrain, sky, shadows, walkable character, under the Paper canvas
 (async function() {
   if (typeof app.createWorld3D !== 'function') { return { success: false, error: 'app.createWorld3D unavailable — update FxTool to a world3d-capable build' }; }
-  await app.createWorld3D(${S(world3dColors(input.spec ?? 'forest'))}, ${opts});
+  await app.createWorld3D(${S(world3dSpecColors(world3dColors(input.spec ?? 'forest')))}, ${opts});
   // describe() is the world's own parameter schema — return the preset list +
   // top-level keys so the agent knows what configure can touch, without the
   // full multi-KB schema on every create.
   const d = typeof app.describeWorld3D === 'function' ? await app.describeWorld3D() : null;
-  return { success: true, action: 'create', spec: ${S(input.spec ?? 'forest')}, configurableKeys: d ? Object.keys(d.params || d) : [] };
+  // params is WORLD_SCHEMA: an ARRAY of {path, kind, doc}. Object.keys on it
+  // returned "0", "1", "2"… — the indexes, not a single usable key.
+  const keys = !d ? [] : Array.isArray(d.params) ? d.params.map(function (e) { return e && e.path; }).filter(Boolean) : Object.keys(d.params || d);
+  return { success: true, action: 'create', spec: ${S(input.spec ?? 'forest')}, configurableKeys: keys };
 })();`.trim();
             }
             case 'describe':
@@ -10497,9 +10884,9 @@ ${guard}
 (function() {
   if (typeof app.configureWorld3D !== 'function') { return { success: false, error: 'app.configureWorld3D unavailable — update FxTool' }; }
 ${needWorld}
-  const r = app.configureWorld3D(${S(world3dColors(input.patch))});
+  const r = app.configureWorld3D(${S(world3dSpecColors(world3dColors(input.patch)))});
   // The validator names the right key on a wrong one — forward it verbatim.
-  return r && r.ok ? { success: true, action: 'configure' } : { success: false, error: (r && r.error) || 'configure failed' };
+  return r && r.ok ? { success: true, action: 'configure' } : { success: false, error: (r && (r.error || (Array.isArray(r.errors) && r.errors.length ? r.errors.join('; ') : '') || r.reason)) || 'configure failed' };
 })();`.trim();
             case 'add_actor': {
                 const actor = S({
@@ -10612,7 +10999,7 @@ ${needWorld}
   // @engine-methods extrudeToMesh latheToMesh importOBJToWorld importGLTFToWorld
   if (typeof app.${fn} !== 'function') { return { success: false, error: 'app.${fn} unavailable — update FxTool to a world3d-capable build' }; }
   const r = await app.${fn}(${S(input.pathId)}, ${S(mesh)});
-  if (!r || r.ok === false) { return { success: false, error: (r && r.reason) || 'the world refused the mesh' }; }
+  if (!r || r.ok === false) { return { success: false, error: (r && (r.error || (Array.isArray(r.errors) && r.errors.length ? r.errors.join('; ') : '') || r.reason)) || 'the world refused the mesh' }; }
   return { success: true, meshId: r.id, op: ${S(input.action === 'extrude_path' ? 'extrude' : 'lathe')}, sourceId: ${S(input.pathId)} };
 })();`.trim();
             }
@@ -10639,8 +11026,8 @@ ${needWorld}
 (function() {
   if (typeof app.addWorldLight !== 'function') { return { success: false, error: 'app.addWorldLight unavailable — update FxTool' }; }
 ${needWorld}
-  const r = app.addWorldLight(${S(input.light ?? {})});
-  if (!r || r.ok === false) { return { success: false, error: (r && r.error) || 'the world refused the light' }; }
+  const r = app.addWorldLight(${S(world3dHexColor(input.light))});
+  if (!r || r.ok === false) { return { success: false, error: (r && (r.error || (Array.isArray(r.errors) && r.errors.length ? r.errors.join('; ') : '') || r.reason)) || 'the world refused the light' }; }
   return { success: true, lightId: r.id, light: r.light };
 })();`.trim();
             case 'set_light':
@@ -10648,7 +11035,7 @@ ${needWorld}
 // World3D: edit a light in place
 (function() {
   if (typeof app.setWorldLight !== 'function') { return { success: false, error: 'app.setWorldLight unavailable — update FxTool' }; }
-  return { success: !!app.setWorldLight(${S(input.lightId)}, ${S(input.light ?? {})}) };
+  return { success: !!app.setWorldLight(${S(input.lightId)}, ${S(world3dHexColor(input.light))}) };
 })();`.trim();
             case 'remove_light':
                 return `
@@ -10671,8 +11058,8 @@ ${needWorld}
 (function() {
   if (typeof app.addWorldMaterial !== 'function') { return { success: false, error: 'app.addWorldMaterial unavailable — update FxTool' }; }
 ${needWorld}
-  const r = app.addWorldMaterial(${S(input.material ?? {})});
-  if (!r || r.ok === false) { return { success: false, error: (r && r.error) || 'the world refused the material' }; }
+  const r = app.addWorldMaterial(${S(world3dHexColor(input.material))});
+  if (!r || r.ok === false) { return { success: false, error: (r && (r.error || (Array.isArray(r.errors) && r.errors.length ? r.errors.join('; ') : '') || r.reason)) || 'the world refused the material' }; }
   return { success: true, materialId: r.id, material: r.material };
 })();`.trim();
             case 'set_material':
@@ -10680,7 +11067,7 @@ ${needWorld}
 // World3D: patch a material — every object referencing it changes next frame
 (function() {
   if (typeof app.setWorldMaterial !== 'function') { return { success: false, error: 'app.setWorldMaterial unavailable — update FxTool' }; }
-  return { success: !!app.setWorldMaterial(${S(input.materialId)}, ${S(input.material ?? {})}) };
+  return { success: !!app.setWorldMaterial(${S(input.materialId)}, ${S(world3dHexColor(input.material))}) };
 })();`.trim();
             case 'remove_material':
                 return `
@@ -10739,7 +11126,7 @@ ${needWorld}
 (function() {
   if (typeof app.setWorldNavTarget !== 'function') { return { success: false, error: 'app.setWorldNavTarget unavailable — update FxTool' }; }
   const r = app.setWorldNavTarget(${S(input.navTarget)});
-  if (!r || r.ok === false) { return { success: false, error: (r && r.error) || 'the nav target was refused' }; }
+  if (!r || r.ok === false) { return { success: false, error: (r && (r.error || (Array.isArray(r.errors) && r.errors.length ? r.errors.join('; ') : '') || r.reason)) || 'the nav target was refused' }; }
   return { success: true, navTarget: ${S(input.navTarget)} };
 })();`.trim();
             case 'get_nav_target':
@@ -11239,7 +11626,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 +12524,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