@pinepaper.studio/mcp-server 1.6.13 → 1.6.15

package/dist/types/code-generator.js

@@ -5,6 +5,7 @@
  * This code is designed to run in the browser context where window.PinePaper is available.
  */
 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';
 import { CreateItemInputSchema, ImportMotionCaptureInputSchema, ModifyItemInputSchema, AddRelationInputSchema, AnimateItemInputSchema, KeyframeAnimateInputSchema, ExecuteGeneratorInputSchema, ApplyEffectInputSchema, SetBackgroundColorInputSchema, SetCanvasSizeInputSchema, CreateGlossySphereInputSchema, CreateDiagonalStripesInputSchema, BatchCreateInputSchema, BatchModifyInputSchema, CreateGridInputSchema, CreateSceneInputSchema, 
 // Diagram types
@@ -33,6 +34,38 @@ import { OntologyCompiler } from '../ontology/ontology-compiler.js';
 function isGradient(color) {
     return typeof color === 'object' && color !== null && 'type' in color && 'stops' in color;
 }
+/**
+ * A colour OBJECT is a gradient spec, checked before it reaches the engine.
+ *
+ * {gradient: true, stops: ['#a', '#b']} — no type, bare-string stops, invalid
+ * hex — went to the engine as a plain colour and drew NOTHING, with success
+ * (round 9 ads, 1.82). The shape the tools document is {type: 'linear' |
+ * 'radial', stops: [{color, offset}], origin?, destination?}. Near-misses are
+ * normalised (a missing type is linear; bare stops get even offsets); what
+ * cannot be read is refused by name, with the shape.
+ */
+function normalizeGradientSpec(v, key) {
+    const o = v;
+    const rawStops = Array.isArray(o.stops) ? o.stops : null;
+    const shape = `${key} as a gradient is {type: 'linear' | 'radial', stops: [{color: '#rrggbb', offset: 0..1}, …], origin?: [x, y], destination?: [x, y]}.`;
+    if (!rawStops || rawStops.length < 2)
+        return { error: `${key} is an object but not a gradient with at least 2 stops, so nothing would be drawn. ${shape}` };
+    const hexOk = (c) => !c.startsWith('#') || /^#([0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i.test(c);
+    const n = rawStops.length;
+    const stops = [];
+    for (let i = 0; i < n; i++) {
+        const st = rawStops[i];
+        const color = typeof st === 'string' ? st : (st && typeof st.color === 'string' ? st.color : null);
+        const offset = typeof st === 'string' ? i / (n - 1) : Number(st.offset ?? i / (n - 1));
+        if (!color || !hexOk(color.trim()))
+            return { error: `${key} stop ${i} has colour ${JSON.stringify(color)}, which is not a colour (a hex needs 3, 4, 6 or 8 digits). ${shape}` };
+        if (!(offset >= 0 && offset <= 1))
+            return { error: `${key} stop ${i} has offset ${JSON.stringify(st.offset)}; offsets run 0 to 1. ${shape}` };
+        stops.push({ color: color.trim(), offset });
+    }
+    const type = o.type === 'radial' ? 'radial' : 'linear';
+    return { gradient: { ...o, type, stops } };
+}
 /**
  * Generate Paper.js gradient code for a fill color
  */
@@ -80,19 +113,79 @@ function generateBlendModeCode(itemVarName, blendMode) {
 /**
  * Template for creating items with support for gradients, shadows, and blend modes
  */
-function generateCreateItemCode(itemType, position, properties) {
+function generateCreateItemCode(itemType, position, properties, dataFlags, positionGiven = true) {
+    // Colour objects are gradient specs: normalised, or refused by name.
+    for (const key of ['color', 'fillColor', 'strokeColor']) {
+        const v = properties[key];
+        if (v && typeof v === 'object' && !Array.isArray(v)) {
+            const g = normalizeGradientSpec(v, key);
+            if ('error' in g) {
+                return `
+// Create ${itemType} — refused: an unreadable gradient would draw nothing
+({ success: false, error: ${JSON.stringify(g.error)} });`.trim();
+            }
+            properties = { ...properties, [key]: g.gradient };
+        }
+    }
     // Extract special properties that need separate handling
     const { color, fillColor, strokeColor, shadowColor, shadowBlur, shadowOffset, blendMode, opacity, contentType, contentFormat, countdownTarget, countdownEndText, ...baseProperties } = properties;
+    // A PATH KEEPS ITS OWN COORDINATES WHEN NO POSITION WAS ASKED FOR (round 9
+    // HH, 1.81). The schema defaults position to (400, 300), and the engine
+    // places pathData AT x / y (so origin-centred data can be positioned) — so a
+    // pathData path authored in canvas coordinates was moved to the default,
+    // off by (+99.5, -170). The segments form was untouched only by accident of
+    // the engine's branch. With no position from the caller, a coordinate-built
+    // item (path from pathData / segments, line, arc) gets no x / y at all.
+    const omitXY = !positionGiven && isCoordinateBuilt(itemType, properties);
+    // `fit` is applied through app.fitText after creation (below), not sent to
+    // create(), so a studio without it cannot half-read it.
+    const textFit = itemType === 'text' && baseProperties.fit && typeof baseProperties.fit === 'object' ? baseProperties.fit : null;
+    const { fit: _fitDropped, ...createProps } = baseProperties;
+    void _fitDropped;
+    let textDirection = itemType === 'text' ? takeDirection(createProps) : null;
+    // RIGHT-TO-LEFT TEXT WITH NO DIRECTION GIVEN. The engine's default is auto,
+    // but it records nothing, so nothing could confirm it. For content with any
+    // RTL script, auto is sent explicitly — recorded, so checkable — and the
+    // result says which way it resolved.
+    if (itemType === 'text' && !textDirection && typeof createProps.content === 'string' && RTL_SCRIPT.test(createProps.content)) {
+        createProps.direction = 'auto';
+        textDirection = { value: 'auto' };
+    }
+    if (textDirection && 'value' in textDirection && textDirection.value === 'auto' && typeof createProps.content === 'string') {
+        textDirection.resolved = baseDirection(createProps.content);
+    }
+    const textTabular = itemType === 'text' && wantsTabular(createProps) === true;
+    const textStrokePos = itemType === 'text' ? takeStrokePosition(createProps, false) : null;
     const params = {
-        x: position.x,
-        y: position.y,
-        ...withRadiusAxes(baseProperties),
+        ...(omitXY ? {} : { x: position.x, y: position.y }),
+        ...withRadiusAxes(createProps),
     };
+    // "NO FILL" HAS THREE SPELLINGS, AND NONE OF THEM WORKED (round 7 AA, 1.50).
+    // fillColor:null was dropped by a truthiness check, so the engine's default
+    // blue applied; 'transparent' reached Paper, which read it as black. A
+    // stroke-only rectangle — whiteboard line art — could not be made at create.
+    // All three now mean no fill, applied after the item exists.
+    const noFill = (v) => v === null || (typeof v === 'string' && /^(transparent|none)$/i.test(v.trim()));
+    const clearFill = (fillColor !== undefined && noFill(fillColor)) || (fillColor === undefined && color !== undefined && noFill(color));
+    // `color` ON A CLOSED PATH IS ITS FILL.
+    //
+    // The engine's path branch paints `color` as the STROKE whenever no fillColor
+    // is given — right for an open line, and the opposite of every shape, where
+    // color is the fill. So a closed blob or hand-drawn badge passed {color} came
+    // out as a hollow outline (round 6 U, 1.41). A closed path (closed:true, or
+    // pathData ending in Z) now takes color as its fill; an open one keeps the
+    // stroke it always had, so existing line drawings are unchanged.
+    const pathData = typeof baseProperties.pathData === 'string' ? baseProperties.pathData.trim() : '';
+    const closedPath = itemType === 'path'
+        && (baseProperties.closed === true || /z$/i.test(pathData));
+    if (closedPath && color && !isGradient(color) && fillColor === undefined && strokeColor === undefined) {
+        params.fillColor = color;
+    }
     // Handle simple solid colors in params
-    if (color && !isGradient(color)) {
+    if (color && !isGradient(color) && !noFill(color)) {
         params.color = color;
     }
-    if (fillColor && !isGradient(fillColor)) {
+    if (fillColor && !isGradient(fillColor) && !noFill(fillColor)) {
         params.fillColor = fillColor;
     }
     if (strokeColor && !isGradient(strokeColor)) {
@@ -126,28 +219,17 @@ function generateCreateItemCode(itemType, position, properties) {
 // ${itemType} — a render-time surface. Drawn per pixel by the cloud renderer;
 // stood in for locally by a flat plate so the layout still reads.
 const item = app.create('rectangle', ${JSON.stringify(plate, null, 2)});
-if (item && item.data) { item.data.renderAs = ${JSON.stringify(itemType)}; item.data.renderParams = ${JSON.stringify(params)}; }`;
-    }
-    // RTL IS NOT SUPPORTED, AND SILENCE WAS THE WORST WAY TO SAY SO.
-    //
-    // create('text', {direction:'rtl'}) dropped the property with no error and
-    // left the base direction LTR, so an Arabic sentence's final period landed
-    // at the reader's START — visibly wrong, and attributable to nothing. The
-    // engine has no text-direction support at all: `direction` there is an arc
-    // sweep and an animation direction, and `justification` is the only
-    // text-related alignment it reads.
-    //
-    // Refused by name rather than accepted-and-dropped, and rather than adding a
-    // prop that would be dropped one layer further on. The alignment half is
-    // real and is named, because it is what a caller can actually use today.
-    const rtlAsked = params.direction ?? params.textDirection;
-    if (rtlAsked !== undefined) {
-        return `
-// Create ${itemType} — refused, rather than silently left ltr
-({ success: false, error: ${JSON.stringify(`direction / textDirection is not supported: this studio has no text-direction support, so ${String(rtlAsked)} would have been accepted and the text left LTR. `
-            + 'That is visible as a right-to-left sentence whose final punctuation lands at the start. '
-            + "You can align with justification: 'right', which is read, but the BASE direction needs engine support — "
-            + 'pass pre-shaped text, or split the line, until it lands.')} });`.trim();
+if (item && item.data) { item.data.renderAs = ${JSON.stringify(itemType)}; item.data.renderParams = ${JSON.stringify(params)}; }
+// The snippet's value is its last statement's, which was the assignment above:
+// the caller got renderParams back and no itemId to address the item by.
+// ONE outer paren pair: the governor's wrapTrailingReturn reads a top-level
+// \`}\` as a statement end, so a bare ternary of object literals is not wrapped
+// and its value is lost.
+((item && item.data)
+  ? { itemId: item.data.registryId, type: ${JSON.stringify(itemType)}, position: { x: ${position.x}, y: ${position.y} },
+      localStandIn: true,
+      note: 'drawn here as a flat plate; the ${itemType} itself appears only in a cloud render. A local export shows the plate.' }
+  : { success: false, error: 'the stand-in plate for this ${itemType} was not created.' });`;
     }
     // AN UNKNOWN ANCHOR IS INVISIBLE OVER MCP.
     //
@@ -172,6 +254,25 @@ if (item && item.data) { item.data.renderAs = ${JSON.stringify(itemType)}; item.
         if (params.origin !== undefined)
             params.origin = normalized;
     }
+    // AN UNREAD PROPERTY IS DROPPED WITHOUT A WORD — SO SAY THE WORD HERE.
+    //
+    // `properties` is free-form and create() returns an item whatever it is
+    // given, so {blur: 12, backdropFilter: 'blur(8px)'} produced a crisp shape and
+    // a successful call; the caller learned only by rendering. The allowlist is
+    // generated from the engine (what create() and normalizeParams() read), and
+    // the handful this emitter consumes itself are added. Reported back, not
+    // refused: the item is still what the caller asked for in every other way,
+    // and a refusal would cost a re-issue over one typo.
+    //
+    // The generated allowlist says what create() READS, for any type; the text
+    // keys it reads apply only to text (the engine gates them on PointText). So
+    // on another type they are reported whatever the list says. `direction` is
+    // not among them: an arc reads it as its sweep.
+    const textOnly = (k) => TEXT_STYLE_KEYS.includes(k) || k === 'fit' || k === 'textDirection' || k === 'dir'
+        || TABULAR_KEYS.includes(k) || k === 'strokePosition';
+    const ignored = Object.keys(properties).filter((k) => itemType === 'text'
+        ? !CREATE_KNOWN_KEYS.has(k) && !textOnly(k) && !DIRECTION_KEYS.includes(k)
+        : !CREATE_KNOWN_KEYS.has(k) || textOnly(k));
     // Build the code
     let code = `
 // Create ${itemType} item
@@ -195,12 +296,51 @@ const item = app.create('${itemType}', ${JSON.stringify(params, null, 2)});`;
     if (blendMode) {
         code += '\n' + generateBlendModeCode('item', blendMode);
     }
+    if (clearFill)
+        code += `\nitem.fillColor = null;`;
+    // DASHES, CAPS AND JOINS FOR EVERY SHAPE (round 7 Z, 1.54). create() applies
+    // them only in its path / line / pattern branches; the shared tail sets a
+    // stroke's colour and width for every type but not these, so a dashed circle
+    // rendered solid and nothing said so (the key is on create()'s read list, so
+    // the unread-property report could not catch it). Re-applied here for every
+    // type; on a path it repeats the engine's own value.
+    const strokeStyle = [];
+    if (Array.isArray(properties.dashArray))
+        strokeStyle.push(`item.dashArray = ${JSON.stringify(properties.dashArray)};`);
+    if (typeof properties.strokeCap === 'string')
+        strokeStyle.push(`item.strokeCap = ${JSON.stringify(properties.strokeCap)};`);
+    if (typeof properties.strokeJoin === 'string')
+        strokeStyle.push(`item.strokeJoin = ${JSON.stringify(properties.strokeJoin)};`);
+    if (strokeStyle.length)
+        code += `\n${strokeStyle.join('\n')}`;
     // Add opacity support
     if (opacity !== undefined) {
         code += `\nitem.opacity = ${opacity};`;
     }
+    if (itemType === 'text')
+        code += emitTextStyle('item', properties);
+    // The vertical hold follows the anchor, as the engine's own create step
+    // derives it (1.90): without it the fit held the centre, and a top-left
+    // anchored headline's top edge drifted on every refit.
+    if (textDirection)
+        code += emitDirectionCheck('item', textDirection);
+    if (textTabular)
+        code += emitTabularCheck('item');
+    if (textStrokePos)
+        code += emitStrokePositionCheck('item', textStrokePos);
+    if (textFit)
+        code += `\nlet __textFit = null;${emitTextFit('item', textFit, JSON.stringify(anchorHold(properties.anchor ?? properties.origin) ?? null))}`;
+    // After opacity, so the "on" level of the lifetime is the item's own.
+    const hasLifetime = properties.bornAt !== undefined || properties.ttl !== undefined;
+    if (hasLifetime) {
+        code += `\nlet __lifetime = null;${emitLifetime('item', properties.bornAt, properties.ttl)}`;
+    }
     // Ensure item is visible above backgrounds/generators
     code += `\nif (item.bringToFront) item.bringToFront();`;
+    // selectable / isDraggable / isDecorative live on item.data, not in params.
+    if (dataFlags && Object.keys(dataFlags).length > 0) {
+        code += `\nif (item.data) Object.assign(item.data, ${JSON.stringify(dataFlags)});`;
+    }
     // Add dynamic content support for text items
     if (contentType && itemType === 'text') {
         const opts = {};
@@ -212,19 +352,440 @@ const item = app.create('${itemType}', ${JSON.stringify(params, null, 2)});`;
             opts.countdownEndText = countdownEndText;
         code += `\nif (app.setDynamicContent) app.setDynamicContent(item, '${contentType}', ${JSON.stringify(opts)});`;
     }
+    const loadsFont = itemType === 'text' && typeof properties.fontFamily === 'string' && properties.fontFamily.trim() !== '';
     code += `
 const itemId = item.data.registryId;
 app.historyManager.saveState();
 
 // Return item info
-({ itemId, type: '${itemType}', position: { x: ${position.x}, y: ${position.y} } });`;
+({ itemId, type: '${itemType}'${textFit ? ', textFit: __textFit' : ''}${textDirection ? ', direction: __direction' : ''}${textTabular ? ', tabularFigures: __tabular' : ''}${textStrokePos ? ', strokePosition: __strokePos' : ''}, position: ${omitXY ? `(item.position ? { x: item.position.x, y: item.position.y } : null)` : `{ x: ${position.x}, y: ${position.y} }`}${hasLifetime ? ', lifetime: __lifetime' : ''}${loadsFont ? ', ...(__font ? { font: __font } : {})' : ''}${ignored.length > 0
+        ? `, ignoredProperties: ${JSON.stringify(ignored)}, warning: ${JSON.stringify(`${ignored.join(', ')} ${ignored.length > 1 ? 'are' : 'is'} not read when creating an item, so ${ignored.length > 1 ? 'they had' : 'it had'} no effect. `
+            + 'Check the spelling against this item type\'s documented properties.')}`
+        : ''} });`;
+    // Loading a font is async, and it has to happen BEFORE create() measures the
+    // text — so only this case becomes an async IIFE; every other create stays a
+    // plain snippet ending in its (-led result.
+    if (loadsFont) {
+        const body = code.trim().replace(/\(\{ itemId([\s\S]*)\}\);$/, 'return { itemId$1 };');
+        return `(async function() {${emitEnsureFont(properties.fontFamily)}\n${body}\n})();`;
+    }
     return code.trim();
 }
+/**
+ * Every `properties` key modify_item can act on: what the engine's modify path
+ * and normalizeParams() read (generated), plus what generateModifyItemCode
+ * applies itself (dynamic content, audio level, lifetime, raster smoothing,
+ * the text properties modifyItem does not pass on).
+ */
+const MODIFY_KNOWN_KEYS = new Set([
+    ...MODIFY_CHANGE_READS,
+    ...NORMALIZE_PARAM_READS,
+    'contentType', 'contentFormat', 'countdownTarget', 'countdownEndText',
+    'audioGain', 'volume', 'gain', 'bornAt', 'ttl', 'smoothing',
+    'fontStyle', 'leading', 'lineHeight', 'skewX', 'skewY', 'matrix', 'fit', 'direction', 'textDirection', 'dir', 'tabularFigures', 'fontVariantNumeric', 'fontFeatures', 'strokePosition',
+]);
+/** Spellings callers reach for, and the key the engine actually reads. */
+const MODIFY_DID_YOU_MEAN = {
+    scaling: 'scale', size: 'width / height', rotate: 'rotation', angle: 'rotation', shear: 'skewX / skewY', skew: 'skewX / skewY',
+    alpha: 'opacity', text: 'content', stroke_width: 'strokeWidth', lineWidth: 'strokeWidth',
+};
+/**
+ * Every `properties` key create_item can act on: what the engine's create()
+ * and normalizeParams() read (generated — see shape-params.ts), plus the keys
+ * generateCreateItemCode consumes itself before the engine sees them.
+ */
+const CREATE_KNOWN_KEYS = new Set([
+    ...ACCEPTED_CREATE_PARAMS,
+    ...NORMALIZE_PARAM_READS,
+    // withRadiusAxes, gradients / shadow / blend / opacity emitted here, and
+    // setDynamicContent for text.
+    'radiusX', 'radiusY', 'contentType', 'contentFormat', 'countdownTarget', 'countdownEndText',
+    // Lifetimes. The editor's create() does not read them, but they are
+    // documented on ANY item and the scene renderer schedules by them — calling
+    // them "no effect" would steer a caller off the only way to cut between shots.
+    'bornAt', 'ttl',
+]);
+/**
+ * Load a font family before text is drawn with it, and say if it still is not there.
+ *
+ * `font list_available` names ~60 families, and drawing with one (Anton,
+ * Playfair Display) came out in a serif fallback with a console warning
+ * nobody over MCP can read. They are real — the studio's decorative Google
+ * Fonts sheet carries them — but it is fetched only when the editor's own UI
+ * asks, and text measures its bounds at creation, so a face arriving later
+ * leaves the layout measured in the fallback.
+ *
+ * So: ask checkFont; if missing, ensureFontsLoaded('all') and force the fetch
+ * with document.fonts.load (a registered @font-face is not a fetched one),
+ * then ask again. `__font` is set only when the first answer was "missing",
+ * so an available font adds nothing to the result. Needs an async context.
+ */
+export function emitEnsureFont(family) {
+    const primary = family.split(',')[0].trim().replace(/^['"]|['"]$/g, '');
+    return `
+let __font = null;
+if (typeof app.checkFont === 'function') {
+  const __v0 = app.checkFont(${JSON.stringify(family)});
+  if (__v0 && __v0.available === false) {
+    if (typeof app.ensureFontsLoaded === 'function') { try { await app.ensureFontsLoaded('all'); } catch (_) { /* reported below */ } }
+    try { if (typeof document !== 'undefined' && document.fonts) await document.fonts.load('16px ' + ${JSON.stringify(JSON.stringify(primary))}); } catch (_) { /* reported below */ }
+    let __v1 = app.checkFont(${JSON.stringify(family)});
+    let __via = 'studio';
+    // Not in the studio's own sheets (Monoton, a common neon face, is not):
+    // the page's CSP allows fonts.googleapis.com stylesheets and
+    // fonts.gstatic.com files, so ask Google Fonts for the family directly.
+    if (!(__v1 && __v1.available === true) && typeof document !== 'undefined' && document.head) {
+      __via = 'google-fonts';
+      await new Promise(function(res) {
+        const id = 'pp-gf-' + ${JSON.stringify(primary)}.replace(/[^a-z0-9]+/gi, '-');
+        if (document.getElementById(id)) return res();
+        const l = document.createElement('link');
+        l.id = id; l.rel = 'stylesheet';
+        l.href = 'https://fonts.googleapis.com/css2?family=' + encodeURIComponent(${JSON.stringify(primary)}).replace(/%20/g, '+') + '&display=swap';
+        l.onload = res; l.onerror = res; setTimeout(res, 5000);
+        document.head.appendChild(l);
+      });
+      try { if (document.fonts) await document.fonts.load('16px ' + ${JSON.stringify(JSON.stringify(primary))}); } catch (_) { /* reported below */ }
+      __v1 = app.checkFont(${JSON.stringify(family)});
+    }
+    __font = (__v1 && __v1.available === true)
+      ? { family: ${JSON.stringify(primary)}, available: true, loadedNow: true, via: __via }
+      : { family: ${JSON.stringify(primary)}, available: false,
+          warning: ${JSON.stringify(primary)} + ' could not be loaded, so this text is drawn in a fallback face. '
+            + ((__v1 && __v1.reason) || '') + ' font list_available names the families this studio can load.' };
+  }
+}`;
+}
+/**
+ * Auto-fit a text item to a box (FxTool 661224ef: app.fitText). Text that
+ * overran its slot — a German translation, a long name on a certificate, a
+ * feed value in a variant matrix — was the #1 blocker in rounds 6–9. The box
+ * is remembered by the engine, so later content changes refit. On a studio
+ * without fitText the result says so rather than leaving the text as it was
+ * in silence. `__textFit` must be declared by the caller.
+ */
+/**
+ * A text paragraph's base direction (FxTool a3b4e7c3, gap 1.16): 'auto' (the
+ * first strong character decides), 'ltr' or 'rtl', under three spellings.
+ *
+ * Pulled out of the changes and normalised to `direction`, the one spelling
+ * the engine reads on both create and modify (modify does not read `dir`). A
+ * value that is not a direction is refused here: the engine only console.warns
+ * it, which production strips.
+ */
+const DIRECTION_KEYS = ['direction', 'textDirection', 'dir'];
+// The engine's rule (FxTool js/core/TextDirection.js, UAX #9 P2/P3): the
+// first STRONG character decides. Mirrored so a result can say which way
+// 'auto' went.
+const RTL_SCRIPT = /[\p{Script=Hebrew}\p{Script=Arabic}\p{Script=Syriac}\p{Script=Thaana}\p{Script=Nko}\p{Script=Samaritan}\p{Script=Mandaic}\p{Script=Adlam}\p{Script=Hanifi_Rohingya}]/u;
+function baseDirection(text) {
+    for (const ch of text) {
+        if (RTL_SCRIPT.test(ch))
+            return 'rtl';
+        if (/\p{L}/u.test(ch))
+            return 'ltr';
+    }
+    return 'ltr';
+}
+function takeDirection(props) {
+    const key = DIRECTION_KEYS.find((k) => props[k] !== undefined && props[k] !== null && props[k] !== '');
+    const raw = key ? props[key] : undefined;
+    for (const k of DIRECTION_KEYS)
+        delete props[k];
+    if (raw === undefined)
+        return null;
+    const v = String(raw).trim().toLowerCase();
+    if (v === 'auto' || v === 'ltr' || v === 'rtl') {
+        props.direction = v;
+        return { value: v };
+    }
+    return { error: `direction ${JSON.stringify(String(raw))} is not one of auto, ltr, rtl — the text keeps its current direction.` };
+}
+/**
+ * Sets `__direction` (declared here) to whether the studio took the direction:
+ * an engine without RTL support accepts the key and draws left-to-right, so
+ * the only evidence is the value it records on the item.
+ */
+function emitDirectionCheck(itemExpr, req) {
+    if ('error' in req)
+        return `
+const __direction = ${JSON.stringify({ applied: false, error: req.error })};`;
+    const v = JSON.stringify(req.value);
+    return `
+const __direction = (function(it) {
+  if (!it || it.className !== 'PointText') return { applied: false, note: 'direction applies to text items only.' };
+  return it.data && it.data.direction === ${v}
+    ? { applied: true, value: ${v}${req.resolved ? `, resolved: ${JSON.stringify(req.resolved)}` : ''} }
+    : { applied: false, note: 'this studio does not set a paragraph direction (it needs an engine with RTL text support): the text is laid out left-to-right.' };
+})(${itemExpr});`;
+}
+/**
+ * Tabular (fixed-width) figures (FxTool 3354d51c): a counter or price column
+ * that does not jitter as its digits change. The engine reads all three
+ * spellings on create and modify itself; this only reports whether it took
+ * them, because an engine without them accepts the key and draws
+ * proportional digits.
+ */
+const TABULAR_KEYS = ['tabularFigures', 'fontVariantNumeric', 'fontFeatures'];
+function wantsTabular(p) {
+    if (!TABULAR_KEYS.some((k) => p[k] !== undefined))
+        return null;
+    if (p.tabularFigures === true)
+        return true;
+    if (typeof p.fontVariantNumeric === 'string' && /tabular-nums/.test(p.fontVariantNumeric))
+        return true;
+    const f = p.fontFeatures;
+    const list = Array.isArray(f) ? f.map(String) : typeof f === 'string' ? [f] : f && typeof f === 'object' ? Object.keys(f).filter((k) => f[k]) : [];
+    return list.some((x) => /\btnum\b/.test(x));
+}
+function emitTabularCheck(itemExpr) {
+    return `
+const __tabular = (function(it) {
+  if (!it || it.className !== 'PointText') return { applied: false, note: 'tabular figures apply to text items only.' };
+  return it.data && it.data.tabularFigures === true
+    ? { applied: true }
+    : { applied: false, note: 'this studio does not lay out tabular figures (it needs an engine with them): digits keep their proportional widths. A monospaced font is the fallback.' };
+})(${itemExpr});`;
+}
+function takeStrokePosition(props, allowNull) {
+    if (!('strokePosition' in props))
+        return null;
+    const raw = props.strokePosition;
+    if (raw === null && allowNull) {
+        props.strokePosition = 'center';
+        return { value: 'center' };
+    }
+    const v = String(raw ?? '').trim().toLowerCase();
+    if (v === 'outside') {
+        props.strokePosition = 'outside';
+        return { value: 'outside' };
+    }
+    if (v === 'center' || v === 'centre') {
+        props.strokePosition = 'center';
+        return { value: 'center' };
+    }
+    delete props.strokePosition;
+    return { error: `strokePosition ${JSON.stringify(raw)} is not 'outside' or 'center' — the stroke is unchanged.` };
+}
+function emitStrokePositionCheck(itemExpr, req) {
+    if ('error' in req)
+        return `\nconst __strokePos = ${JSON.stringify({ applied: false, error: req.error })};`;
+    if (req.value === 'center')
+        return `\nconst __strokePos = { applied: true, value: 'center' };`;
+    return `
+const __strokePos = (function(it) {
+  if (!it || it.className !== 'PointText') return { applied: false, note: 'strokePosition applies to text items only.' };
+  if (!(it.data && it.data.strokePosition === 'outside')) return { applied: false, note: 'this studio does not draw text strokes outside the glyph (it needs an engine with strokePosition): the stroke is centred on the outline, so a thick stroke thins the letters.' };
+  return (it.strokeColor && it.strokeWidth > 0) ? { applied: true, value: 'outside' } : { applied: true, value: 'outside', note: 'the text has no stroke yet: set strokeColor and strokeWidth to see it.' };
+})(${itemExpr});`;
+}
+/** 'top' / 'bottom' from a top-* / bottom-* anchor, as the engine derives it. */
+function anchorHold(anchor) {
+    const a = String(anchor ?? '').toLowerCase();
+    return /^top/.test(a) ? 'top' : /^bottom/.test(a) ? 'bottom' : undefined;
+}
+function emitTextFit(itemExpr, box, holdFallback = 'undefined') {
+    return `
+if (typeof app.fitText === 'function') {
+  const __fbox = ${JSON.stringify(box)};
+  if (__fbox.hold === undefined) { const __h = ${holdFallback}; if (__h) __fbox.hold = __h; }
+  const __fr = app.fitText(${itemExpr}, __fbox);
+  __textFit = __fr && __fr.ok !== false
+    ? Object.assign({ applied: true }, __fr, __fr.fits === false ? { warning: 'the text does not fit its box even at the minimum font size — shorten it or widen the box.' } : {})
+    : { applied: false, error: (__fr && __fr.error) || 'the studio refused the fit box' };
+} else {
+  __textFit = { applied: false, note: 'this studio cannot auto-fit text (no app.fitText): the text keeps its font size and may overrun the box.' };
+}`;
+}
+/**
+ * Paper text properties the engine's create() and modifyItem() never pass on.
+ *
+ * Line spacing, weight and italic are what editorial, Swiss and zine layouts
+ * are made of, and all three were dropped without a word: create('text')
+ * builds a PointText from content / fontFamily / fontSize / justification
+ * only. PointText itself supports them (`leading`, and `fontWeight`, which
+ * Paper writes into the canvas font shorthand — so italic rides in it as
+ * "italic 700"). Set after the fact, then re-anchored to the edge the engine
+ * anchored to, because a heavier weight or taller leading moves the bounds.
+ *
+ * lineHeight is the CSS habit: <= 4 is a multiple of fontSize, above that px.
+ */
+const TEXT_STYLE_KEYS = ['fontWeight', 'fontStyle', 'leading', 'lineHeight'];
+function emitTextStyle(itemExpr, props) {
+    const weight = props.fontWeight;
+    const italic = props.fontStyle === 'italic' || props.fontStyle === 'oblique';
+    const lh = typeof props.lineHeight === 'number' ? props.lineHeight : undefined;
+    const leading = typeof props.leading === 'number' ? props.leading : undefined;
+    if (weight === undefined && props.fontStyle === undefined && leading === undefined && lh === undefined)
+        return '';
+    return `
+(function(it) {
+  if (!it || it.className !== 'PointText') return;
+  const j = it.justification;
+  const edge = function(b) { return j === 'left' ? b.left : j === 'right' ? b.right : b.center.x; };
+  const b0 = it.bounds, ax = edge(b0), ay = b0.center.y;
+  ${weight !== undefined || props.fontStyle !== undefined
+        ? `it.fontWeight = ${JSON.stringify(`${italic ? 'italic ' : ''}${weight ?? 'normal'}`)};`
+        : ''}
+  ${leading !== undefined ? `it.leading = ${leading};` : ''}
+  ${lh !== undefined ? `it.leading = ${lh} <= 4 ? ${lh} * it.fontSize : ${lh};` : ''}
+  const b1 = it.bounds;
+  it.position = it.position.add([ax - edge(b1), ay - b1.center.y]);
+})(${itemExpr});`;
+}
+/**
+ * Which data keys a chart plots, when the caller did not say.
+ *
+ * ChartSystem defaults to fields named `x` and `y`. The tool's own documented
+ * example is [{category, value}], so that example drew NO bars — index labels
+ * "0 1 2 3 4" and success:true, dataPoints:5 (round 7 Z, 1.53). Inferred here
+ * from the data instead: x is a label-like key (category/label/name/…, else
+ * the first text key), y is value-like (value/count/…, else the first number
+ * key other than x). stackedBar picks its own series from every numeric key,
+ * so only x is inferred for it. A y that cannot be found is refused by name,
+ * listing the keys that were there, rather than drawn as nothing.
+ */
+function resolveChartFields(chartType, data, options) {
+    // No rows yet (a chart created empty and filled by update): nothing to infer.
+    if (data.length === 0)
+        return { options };
+    const row = data.find((d) => d && typeof d === 'object') ?? {};
+    const keys = Object.keys(row);
+    const out = { ...options };
+    const inferred = {};
+    const has = (k) => keys.includes(k);
+    if (out.xField === undefined && !has('x')) {
+        const x = ['category', 'label', 'name', 'date', 'month', 'year', 'key'].find(has)
+            ?? keys.find((k) => typeof row[k] === 'string') ?? keys[0];
+        if (x !== undefined) {
+            out.xField = x;
+            inferred.xField = x;
+        }
+    }
+    const xf = out.xField ?? 'x';
+    if (chartType !== 'stackedBar' && out.yField === undefined && !has('y')) {
+        const numeric = keys.filter((k) => k !== xf && typeof row[k] === 'number');
+        const y = ['value', 'count', 'amount', 'total', 'score'].find((k) => numeric.includes(k)) ?? numeric[0];
+        if (y === undefined) {
+            return { error: `no numeric field to plot: the data rows have ${keys.length ? keys.join(', ') : 'no keys'}, and none but ${xf} is a number. Pass options.yField naming the numeric key.` };
+        }
+        out.yField = y;
+        inferred.yField = y;
+    }
+    return Object.keys(inferred).length ? { options: out, inferred } : { options: out };
+}
+/**
+ * A lifetime (bornAt / ttl, seconds) as a VISIBILITY WINDOW, [bornAt, bornAt + ttl).
+ *
+ * THE ENGINE HAS NO LIFETIME, and the first answer here (5bfc480) wrote one as
+ * hard-cut opacity keys merged into the item's own track. That failed four
+ * ways once items also had keyframes (ads production): keyframe_animate
+ * replaced the track and the ttl cut was lost (1.83); opacity-only cut keys
+ * broke the position track through the engine's missing-property rule (2.30 →
+ * 1.84); authored opacity and the cuts blended instead of multiplying (1.85);
+ * and exact-time hand-offs left a blank frame (1.86).
+ *
+ * So it is no longer keys. ONE frame callback ('pp_lifetimes') sets
+ * item.visible from the window for every item with a lifetime, reading each
+ * item's live data.bornAt / ttl, from the frame's own time: event.sceneTime,
+ * which both the export's step and sceneAt supply, else app.playbackTime. The
+ * export runs frame callbacks inside app.update() before it draws each step
+ * (VideoExporter._advanceToTime), so exports honour it. visible, not opacity,
+ * so it composes with any keyframes — the engine's own clip window hides the
+ * same way for the same reason. A 1-microsecond tolerance makes a hand-off at
+ * an exact frame time show exactly one item.
+ *
+ * Runtime-only: a scene saved and reopened keeps data.bornAt / ttl (the cloud
+ * renderer reads those) but not the callback, until the studio reads the
+ * fields itself — the result says so. Lifetimes applied the old way are
+ * migrated: their tagged opacity keys are removed.
+ */
+function emitLifetime(itemExpr, bornAt, ttl) {
+    const b = Number(bornAt);
+    const t = Number(ttl);
+    const born = Number.isFinite(b) && b > 0 ? b : 0;
+    const span = Number.isFinite(t) && t > 0 ? t : null;
+    return `
+(function(it) {
+  if (!it || !it.data) return;
+  it.data.bornAt = ${born};
+  ${span === null ? 'delete it.data.ttl;' : `it.data.ttl = ${span};`}
+  if (Array.isArray(it.data.keyframes) && it.data.keyframes.some(function(k) { return k && k._lifetime; })) {
+    it.data.keyframes = it.data.keyframes.filter(function(k) { return !(k && k._lifetime); });
+  }
+  // THE STUDIO'S OWN LIFETIME, WHEN IT HAS ONE (FxTool bf1a656b): same window,
+  // same tolerance, applied in the frame loop, on scrub and in export — and it
+  // PERSISTS through save / reload, which the callback below cannot. Passed
+  // straight through; the callback is only the fallback for older studios.
+  if (typeof app.setLifetime === 'function') {
+    const __r = app.setLifetime(it, ${born}, ${span === null ? 'null' : span});
+    if (!__r || __r.ok === false) {
+      __lifetime = { bornAt: ${born}, ttl: ${span}, applied: false, error: (__r && __r.error) || 'the studio refused the lifetime' };
+      return;
+    }
+    const __G = globalThis.__ppMcp;
+    if (__G && __G.lifetimeApp === app && __G.lifetimeIds) __G.lifetimeIds.delete(it.data.registryId || it.data.id);
+    __lifetime = { bornAt: ${born}, ttl: ${span}, applied: true, via: 'engine', persists: true };
+    return;
+  }
+  const rid = it.data.registryId || it.data.id;
+  // MCP-owned page state lives on globalThis, not on app: it is not an engine
+  // member, and the engine-surface guard reads app.X as a claim that it is.
+  const __pp = globalThis.__ppMcp = globalThis.__ppMcp || {};
+  // Keyed to THIS studio: a re-initialised app has none of the old one's
+  // callbacks, so the registration and the id set start again with it.
+  if (__pp.lifetimeApp !== app) { __pp.lifetimeApp = app; __pp.lifetimeIds = new Set(); }
+  if (typeof app.addOnFrameCallback !== 'function' || !rid) {
+    __lifetime = { bornAt: ${born}, ttl: ${span}, applied: false, note: 'stored on the item, but this studio has no frame callbacks, so it shows for the whole local render (a cloud render honours it).' };
+    return;
+  }
+  __pp.lifetimeIds = __pp.lifetimeIds || new Set();
+  __pp.lifetimeIds.add(rid);
+  const within = function(x, now) {
+    const b0 = x.data.bornAt, t0 = x.data.ttl;
+    return now >= b0 - 1e-6 && (typeof t0 !== 'number' || now < b0 + t0 - 1e-6);
+  };
+  // The visibility pass itself, kept where a still export can call it too
+  // (a seek alone does not run frame callbacks).
+  __pp.applyLifetimes = function(now) {
+    __pp.lifetimeIds.forEach(function(id) {
+      const e = app.itemRegistry && app.itemRegistry.get(id);
+      const x = e && e.item;
+      if (!x || !x.data || typeof x.data.bornAt !== 'number') { __pp.lifetimeIds.delete(id); return; }
+      const vis = within(x, now);
+      if (x.visible !== vis) x.visible = vis;
+    });
+  };
+  // Registered EVERY time, not once behind a flag: clearCanvas / start_job
+  // remove frame callbacks, and a stale "already registered" flag left every
+  // later scene's lifetimes doing nothing (retest of 28a4a0e). Re-adding the
+  // same id replaces it.
+  app.addOnFrameCallback('pp_lifetimes', function(ev) {
+    const now = ev && typeof ev.sceneTime === 'number' ? ev.sceneTime : (typeof app.playbackTime === 'number' ? app.playbackTime : 0);
+    __pp.applyLifetimes(now);
+  });
+  it.visible = within(it, typeof app.playbackTime === 'number' ? app.playbackTime : 0);
+  __lifetime = { bornAt: ${born}, ttl: ${span}, applied: true, via: 'visibility',
+    note: 'applied as visibility, so it composes with keyframes. Runtime-only until the studio reads bornAt / ttl itself: a scene reopened in the editor keeps the fields (and a cloud render honours them) but must be re-timed to play locally.' };
+  if (it.data.clipInPoint !== undefined || it.data.clipOutPoint !== undefined) {
+    __lifetime.warning = 'this item also has a clip window (clipInPoint / clipOutPoint), which hides it by the same means — the two can fight. Use one.';
+  }
+})(${itemExpr});`;
+}
 /**
  * Template for modifying items
  */
-function generateModifyItemCode(itemId, properties) {
+function generateModifyItemCode(itemId, properties, dataFlags) {
     const { contentType, contentFormat, countdownTarget, countdownEndText, ...restProperties } = properties;
+    // A new fit box is applied here (emitTextFit, with the hold carried over),
+    // not by modifyItem: the engine's modify fits it with no hold, overwriting
+    // the one this reads back. fit: null still goes through — that is the
+    // engine's "stop fitting".
+    if (restProperties.fit && typeof restProperties.fit === 'object')
+        delete restProperties.fit;
+    const modDirection = takeDirection(restProperties);
+    const modTabular = wantsTabular(restProperties) === true;
+    const modStrokePos = takeStrokePosition(restProperties, true);
     // modifyItem(id, changes), NOT select() + modify().
     //
     // modify() operates on the SELECTION, so this selected an id and then edited
@@ -269,11 +830,101 @@ const entry = app.itemRegistry.get('${itemId}');
 if (entry && entry.item && app.setDynamicContent) app.setDynamicContent(entry.item, '${contentType}', ${JSON.stringify(opts)});`;
         }
     }
+    // AN AUDIO ITEM'S LEVEL IS NOT AN ITEM PROPERTY. modifyItem applies changes
+    // to the Paper item (an audio item's is an invisible sentinel), so
+    // {audioGain} / {volume} answered success and moved nothing (measured 0.0 dB).
+    // The mix reads registry properties.audioGain; the live player has its own
+    // volume. Both are set, and gain is kept in step for the editor.
+    const levelKey = ['audioGain', 'volume', 'gain'].find((k) => typeof properties[k] === 'number');
+    if (levelKey) {
+        const level = Math.max(0, Math.min(1, properties[levelKey]));
+        code += `
+const _ae = app.itemRegistry.get('${itemId}');
+if (_ae && _ae.type === 'audio') {
+  _ae.properties = _ae.properties || {};
+  _ae.properties.audioGain = ${level};
+  _ae.properties.gain = ${level};
+  const _A = (typeof window !== 'undefined') && window.PinePaperAgent;
+  const _m = _A && typeof _A.listMedia === 'function' ? _A.listMedia().find(function(x) { return x.registryId === '${itemId}'; }) : null;
+  if (_m && app.audioLayer && typeof app.audioLayer.setVolume === 'function') app.audioLayer.setVolume(${level}, _m.id);
+}`;
+    }
+    // Raster resampling (pixel art: 'off'). A Paper Raster property modifyItem
+    // does not pass on; applied to a raster, or to the raster an image group holds.
+    if (typeof properties.smoothing === 'string') {
+        code += `
+const _sm = app.itemRegistry.get('${itemId}');
+const _smR = _sm && _sm.item && (_sm.item.className === 'Raster' ? _sm.item
+  : (typeof _sm.item.getItem === 'function' ? _sm.item.getItem({ className: 'Raster' }) : null));
+if (_smR) _smR.smoothing = ${JSON.stringify(properties.smoothing)};`;
+    }
+    // No fill on modify too: null / 'transparent' / 'none' clear it outright,
+    // after modifyItem, which would otherwise read 'transparent' as black.
+    const fillNone = (v) => v === null || (typeof v === 'string' && /^(transparent|none)$/i.test(v.trim()));
+    if (fillNone(properties.fillColor) || (properties.fillColor === undefined && properties.color !== undefined && fillNone(properties.color))) {
+        code += `
+const _nf = app.itemRegistry.get('${itemId}');
+if (_nf && _nf.item) _nf.item.fillColor = null;`;
+    }
+    // SKEW AND AFFINE, FOR MOCKUPS (round 9 HH). A box face or a phone screen in
+    // perspective-ish mockups is a shear / affine map; modify_item reported
+    // skewX / shear / matrix as ignored and the only route was custom code.
+    // Paper does both: item.shear(tan x, tan y) about the centre, and
+    // item.transform(Matrix). They are APPLIED to the current shape — a second
+    // call compounds — not stored as settable properties; the result says so.
+    const skewX = typeof properties.skewX === 'number' ? properties.skewX : 0;
+    const skewY = typeof properties.skewY === 'number' ? properties.skewY : 0;
+    const matrix = Array.isArray(properties.matrix) && properties.matrix.length === 6 && properties.matrix.every((n) => typeof n === 'number')
+        ? properties.matrix : null;
+    const affine = skewX !== 0 || skewY !== 0 || matrix !== null;
+    if (affine) {
+        code += `
+const _af = app.itemRegistry.get('${itemId}');
+const _afi = _af && _af.item;
+if (_afi) {
+  ${skewX !== 0 || skewY !== 0 ? `_afi.shear(Math.tan(${skewX} * Math.PI / 180), Math.tan(${skewY} * Math.PI / 180), _afi.bounds.center);` : ''}
+  ${matrix ? `_afi.transform(new paper.Matrix(${matrix.join(', ')}));` : ''}
+}`;
+    }
+    const modFit = properties.fit && typeof properties.fit === 'object' ? properties.fit : null;
+    if (modFit) {
+        code += `
+let __textFit = null;
+const _tf = app.itemRegistry.get('${itemId}');${emitTextFit('_tf && _tf.item', modFit, JSON.stringify(anchorHold(properties.anchor ?? properties.origin) ?? null) + " || (_tf && _tf.item && _tf.item.data && _tf.item.data.fitBox && _tf.item.data.fitBox.hold)")}`;
+    }
+    const textStyle = emitTextStyle('_ts && _ts.item', properties);
+    if (textStyle) {
+        code += `
+const _ts = app.itemRegistry.get('${itemId}');${textStyle}`;
+    }
+    const modLifetime = properties.bornAt !== undefined || properties.ttl !== undefined;
+    if (modLifetime) {
+        code += `
+let __lifetime = null;
+const _lt = app.itemRegistry.get('${itemId}');${emitLifetime('_lt && _lt.item', properties.bornAt, properties.ttl)}`;
+    }
+    if (dataFlags && Object.keys(dataFlags).length > 0) {
+        code += `
+const _flagged = app.itemRegistry.get('${itemId}');
+if (_flagged && _flagged.item && _flagged.item.data) Object.assign(_flagged.item.data, ${JSON.stringify(dataFlags)});`;
+    }
+    const modFont = typeof properties.fontFamily === 'string' && properties.fontFamily.trim() !== '';
+    // AN UNREAD KEY HAD NO EFFECT, AND THE CALL SAID SUCCESS. {scaling: 8} on a
+    // raster answered success and left it 16 px; the engine reads `scale`. Same
+    // report create_item gives, against the engine's modify path (generated).
+    const modIgnored = Object.keys(properties).filter((k) => !MODIFY_KNOWN_KEYS.has(k));
+    const modWarning = modIgnored.length === 0 ? '' : `, ignoredProperties: ${JSON.stringify(modIgnored)}, warning: ${JSON.stringify(`${modIgnored.join(', ')} ${modIgnored.length > 1 ? 'are' : 'is'} not read when modifying an item, so ${modIgnored.length > 1 ? 'they had' : 'it had'} no effect.`
+        + modIgnored.filter((k) => MODIFY_DID_YOU_MEAN[k]).map((k) => ` Did you mean ${MODIFY_DID_YOU_MEAN[k]} (not ${k})?`).join(''))}`;
     code += `
 app.historyManager.saveState();
-return { success: true, itemId: '${itemId}' };`;
+${modDirection ? emitDirectionCheck(`app.getItemById('${itemId}')`, modDirection) : ''}${modTabular ? emitTabularCheck(`app.getItemById('${itemId}')`) : ''}${modStrokePos ? emitStrokePositionCheck(`app.getItemById('${itemId}')`, modStrokePos) : ''}
+return { success: true, itemId: '${itemId}'${modFit ? ', textFit: __textFit' : ''}${modDirection ? ', direction: __direction' : ''}${modTabular ? ', tabularFigures: __tabular' : ''}${modStrokePos ? ', strokePosition: __strokePos' : ''}${affine ? `, affine: ${JSON.stringify({ skewX, skewY, matrix, note: 'applied to the current shape: calling again compounds it. To undo, apply the inverse (negative skew, or the inverse matrix).' })}` : ''}${modLifetime ? ', lifetime: __lifetime' : ''}${modFont ? ', ...(__font ? { font: __font } : {})' : ''}${modWarning} };`;
     // Wrapped, because the body now RETURNS early on a miss rather than falling
-    // through to an unconditional success.
+    // through to an unconditional success. Async only when a font must load
+    // before modifyItem re-measures the text.
+    if (modFont) {
+        return `(async function() {${emitEnsureFont(properties.fontFamily)}\n${code.trim()}\n})();`;
+    }
     return `(function() {\n${code.trim()}\n})();`;
 }
 /**
@@ -310,18 +961,143 @@ function generateDeleteItemCode(itemId) {
  * Template for adding relations
  */
 function generateAddRelationCode(sourceId, targetId, relationType, params) {
+    // AN UNKNOWN ENDPOINT IS REFUSED, NOT STORED (round 9 GG, 1.74). The engine
+    // stores a relation to an id it cannot resolve, returns true, and says "it
+    // will be skipped every frame and nothing will move" only in a warning this
+    // tool never sees. Its own test for that warning — _isKnownRelationEndpoint:
+    // an item, the camera, a cursor target — is asked first here, after the same
+    // '#id' forgiveness the engine applies.
     return `
 // Add ${relationType} relation: ${sourceId} -> ${targetId}
-const success = app.addRelation('${sourceId}', '${targetId}', '${relationType}', ${JSON.stringify(params, null, 2)});
-if (!success) {
-  throw new Error('Failed to add relation');
-}
-app.historyManager.saveState();
-
-// Return success
-({ success: true, sourceId: '${sourceId}', targetId: '${targetId}', relationType: '${relationType}' });
+(function() {
+  const norm = function(id) { return typeof app._resolveRelationEndpoint === 'function' ? app._resolveRelationEndpoint(id) : id; };
+  if (typeof app._isKnownRelationEndpoint === 'function') {
+    const bad = [${JSON.stringify(sourceId)}, ${JSON.stringify(targetId)}].filter(function(id) { return !app._isKnownRelationEndpoint(norm(id)); });
+    if (bad.length) {
+      return { success: false, relationType: '${relationType}', error: bad.map(function(id) { return JSON.stringify(id); }).join(' and ')
+        + ' ' + (bad.length > 1 ? 'are not items' : 'is not an item') + ' on the canvas, so the relation would be stored and skipped every frame. Check the id (pinepaper_get_items lists them).' };
+    }
+  }
+  const success = app.addRelation('${sourceId}', '${targetId}', '${relationType}', ${JSON.stringify(params, null, 2)});
+  if (!success) {
+    return { success: false, relationType: '${relationType}', error: 'the studio refused the ${relationType} relation between ${sourceId} and ${targetId}.' };
+  }
+  app.historyManager.saveState();
+  return { success: true, sourceId: '${sourceId}', targetId: '${targetId}', relationType: '${relationType}' };
+})();
 `.trim();
 }
+/**
+ * moves_along_path, from the parameters a caller actually writes.
+ *
+ * The rule is a SELF relation reading params.path as a point array, with speed
+ * (1 = 150 px/s), closed, phase, easing, signal, equation. The natural call —
+ * targetId: <a path item>, params {pathId, duration, delay} — named none of
+ * those, so the relation had no path, returned success:true, and the whiteboard
+ * hand never moved (round 7 AA, 2.25). Here:
+ *   - a path ITEM (targetId other than the source, or params.pathId) is
+ *     sampled into points in the page, closed taken from the item;
+ *   - duration (seconds for one traversal) becomes speed;
+ *   - delay becomes the relation's window start (relation time is
+ *     window-relative, so the ride starts at `delay`);
+ *   - with neither points, a path item nor an equation, it is refused by name.
+ */
+function generateMovesAlongPathCode(sourceId, targetId, raw) {
+    const { pathId, duration, delay, offset, ...params } = raw;
+    const ref = (typeof pathId === 'string' && pathId) || (targetId && targetId !== sourceId ? targetId : null);
+    const off = Array.isArray(offset) && offset.length >= 2 ? [Number(offset[0]) || 0, Number(offset[1]) || 0] : null;
+    const hasDuration = typeof duration === 'number' && duration > 0;
+    const hasDelay = typeof delay === 'number' && delay > 0;
+    return `
+// moves_along_path: ${sourceId}${ref ? ` along ${ref}` : ''}
+(function() {
+  const params = ${JSON.stringify(params)};
+  const hasPoints = Array.isArray(params.path) && params.path.length >= 2;
+  // A STUDIO THAT RIDES THE PATH ITSELF. From FxTool c16c9dd3 the rule
+  // declares duration / delay / offset and, with a path item as its target and
+  // no points, follows that path's LIVE geometry on the playhead. Sampling it
+  // into static points here would shadow that, so on such a build everything
+  // is passed straight through and the target is the route.
+  const rule = app.relationRegistry && typeof app.relationRegistry.getRule === 'function'
+    ? app.relationRegistry.getRule('moves_along_path') : null;
+  const native = !!(rule && rule.params && rule.params.duration);
+  if (native && !hasPoints && !params.equation ${ref ? '' : '&& false'}) {
+    ${hasDuration ? `params.duration = ${duration};` : ''}
+    ${hasDelay ? `params.delay = ${delay};` : ''}
+    ${off ? `params.offset = ${JSON.stringify(off)};` : ''}
+    const okN = app.addRelation(${JSON.stringify(sourceId)}, ${JSON.stringify(ref ?? sourceId)}, 'moves_along_path', params);
+    if (!okN) return { success: false, error: 'the studio refused the moves_along_path relation.' };
+    app.historyManager.saveState();
+    return { success: true, sourceId: ${JSON.stringify(sourceId)}, relationType: 'moves_along_path', route: 'live-path', target: ${JSON.stringify(ref)}, params: params };
+  }
+  if (!hasPoints && !params.equation) {
+    ${ref ? `const e = app.itemRegistry && app.itemRegistry.get(${JSON.stringify(ref)});
+    let p = e && e.item;
+    if (p && p.className !== 'Path' && p.className !== 'CompoundPath' && typeof p.getItem === 'function') {
+      p = p.getItem({ className: 'Path' });
+    }
+    if (!p || typeof p.getPointAt !== 'function' || !(p.length > 0)) {
+      return { success: false, error: ${JSON.stringify(ref)} + ' is not a path with length — moves_along_path needs a path item, or params.path as points [[x, y], …].' };
+    }
+    const N = Math.min(240, Math.max(16, Math.ceil(p.length / 6)));
+    params.path = Array.from({ length: N + 1 }, function(_, i) { const q = p.getPointAt(Math.min(p.length, p.length * i / N)); return [q.x, q.y]; });
+    if (params.closed === undefined) params.closed = !!p.closed;` : `return { success: false, error: 'moves_along_path needs a path: pass targetId (or params.pathId) naming a path item, or params.path as points [[x, y], …], or params.equation. With none, the item would not move.' };`}
+  }
+  ${off ? `// offset, with the ENGINE's meaning (c16c9dd3): [dx, dy] is added to the
+  // point on the path to place the item — so a hand whose pen tip sits
+  // (-dx, -dy) from its centre keeps the tip on the stroke. The same value
+  // therefore behaves the same on a build that reads offset natively.
+  if (Array.isArray(params.path)) params.path = params.path.map(function(q) {
+    const x = Array.isArray(q) ? q[0] : q.x, y = Array.isArray(q) ? q[1] : q.y;
+    return [x + ${off[0]}, y + ${off[1]}];
+  });` : ''}
+  ${hasDuration ? `if (params.speed === undefined && Array.isArray(params.path)) {
+    const pts = params.path.map(function(q) { return Array.isArray(q) ? { x: q[0], y: q[1] } : q; });
+    const len = pts.slice(1).reduce(function(acc, q, i) { return acc + Math.hypot(q.x - pts[i].x, q.y - pts[i].y); }, 0);
+    if (len > 0) params.speed = len / (150 * ${duration});
+    if (params.closed === undefined) params.closed = false;
+  }` : ''}
+  ${hasDelay ? `if (!params.window) params.window = { start: ${delay} };` : ''}
+  // Before its window opens the relation does not run, so the item stays where
+  // it was left — the retest saw it parked at the path END. Put it at the start.
+  if (Array.isArray(params.path) && params.path.length) {
+    const src = app.itemRegistry && app.itemRegistry.get(${JSON.stringify(sourceId)});
+    const q0 = params.path[0];
+    if (src && src.item && src.item.position) { src.item.position.x = Array.isArray(q0) ? q0[0] : q0.x; src.item.position.y = Array.isArray(q0) ? q0[1] : q0.y; }
+  }
+  const ok = app.addRelation(${JSON.stringify(sourceId)}, ${JSON.stringify(sourceId)}, 'moves_along_path', params);
+  if (!ok) return { success: false, error: 'the studio refused the moves_along_path relation.' };
+  app.historyManager.saveState();
+  return { success: true, sourceId: ${JSON.stringify(sourceId)}, relationType: 'moves_along_path', route: 'sampled-points',
+    points: Array.isArray(params.path) ? params.path.length : 0, speed: params.speed, closed: params.closed,
+    ${ref ? `pathFrom: ${JSON.stringify(ref)},` : ''} window: params.window };
+})();`.trim();
+}
+/**
+ * Parameter names a generator's docs used that the engine does not read.
+ *
+ * drawWindField was documented with `direction` and `speed`; the engine reads
+ * windDirection and windSpeed, so the documented call drew wind blowing the
+ * default way (round 8 BB, 5.56). The docs are corrected, and the published
+ * spellings are mapped because callers followed them. An explicit engine name
+ * always wins.
+ */
+const GENERATOR_PARAM_ALIASES = {
+    drawWindField: { direction: 'windDirection', speed: 'windSpeed' },
+};
+function aliasGeneratorParams(name, params) {
+    const map = GENERATOR_PARAM_ALIASES[name];
+    if (!map)
+        return params;
+    const out = { ...params };
+    for (const [from, to] of Object.entries(map)) {
+        if (out[from] !== undefined && out[to] === undefined) {
+            out[to] = out[from];
+            delete out[from];
+        }
+    }
+    return out;
+}
 /**
  * Template for removing relations
  */
@@ -471,12 +1247,63 @@ function generateKeyframeAnimateCode(itemId, keyframes, duration, loop = false,
         opts.clipOutPoint = clipOutPoint;
     if (timeUnits !== undefined)
         opts.timeUnits = timeUnits;
+    // A FADE ON AN AUDIO ITEM WAS ACCEPTED AND NEVER HEARD. addAnimation keyframes
+    // the audio item's sentinel, and the mix reads one static audioGain per clip,
+    // so {audioGain: 0→1} answered success, duration 15, and exported at a flat
+    // level (measured). Refused by name, before anything is added, and only for
+    // audio items — a `volume` key on a shape is some other thing.
+    const levelKeys = [...new Set(keyframes.flatMap((k) => Object.keys(k.properties ?? {})))]
+        .filter((k) => k === 'audioGain' || k === 'volume' || k === 'gain');
+    // UNLESS THE STUDIO ANIMATES IT. From FxTool fcec0194 keyed gain / volume
+    // are real — fades and ducks bake into the export at the measured level —
+    // and listAnimatableProperties lists them with appliesTo 'audio'. That list
+    // is the feature check: a key it names for audio passes through, anything
+    // else on an audio item is still refused (prod, until that build ships).
+    const audioLevelGuard = levelKeys.length === 0 ? '' : `
+  const __ae = app.itemRegistry && app.itemRegistry.get('${itemId}');
+  let __audioKeyed = [];
+  try {
+    const __l = typeof app.listAnimatableProperties === 'function' ? app.listAnimatableProperties() : null;
+    __audioKeyed = ((__l && __l.properties) || []).filter(function(p) { return p && p.appliesTo === 'audio'; }).map(function(p) { return p.name; });
+  } catch (_) { /* treat as unsupported */ }
+  const __unsupported = ${JSON.stringify(levelKeys)}.filter(function(k) { return __audioKeyed.indexOf(k) === -1; });
+  if (__ae && __ae.type === 'audio' && __unsupported.length) {
+    return { success: false, itemId: '${itemId}', error: __unsupported.join(', ') + ' cannot be keyframed on an audio item in this studio: it mixes each audio clip at one fixed level, so a fade would be accepted and not heard. Nothing was added. '
+      + (__audioKeyed.length ? 'Keyable on audio here: ' + __audioKeyed.join(', ') + '. ' : '')
+      + 'Set a static level with pinepaper_modify_item {audioGain: 0..1}.' };
+  }`;
+    // Easing is read from the DESTINATION keyframe, so easing on the first one
+    // never applies — a Ken Burns eased only there rendered linear. Said in the
+    // result rather than silently moved: moving it would change what the other
+    // keys the caller wrote mean.
+    // A KEY THAT LEAVES A PROPERTY OUT (round 9 HH, engine 2.30): the engine
+    // treats the gap as a break in that property's track rather than holding or
+    // interpolating across it, silently. Named here — which keys lack which
+    // properties — with the fix a caller can make now: give every key the full set.
+    const propSets = keyframes.map((k) => Object.keys(k.properties ?? {}));
+    const allProps = [...new Set(propSets.flat())];
+    const gaps = keyframes
+        .map((k, i) => ({ time: k.time, missing: allProps.filter((p) => !propSets[i].includes(p)) }))
+        .filter((g) => g.missing.length);
+    const gapNote = gaps.length && keyframes.length > 1
+        ? `, propertyGaps: ${JSON.stringify(gaps.slice(0, 10))}, gapWarning: ${JSON.stringify(`${gaps.length} keyframe(s) leave out a property other keys animate (${[...new Set(gaps.flatMap((g) => g.missing))].join(', ')}). The engine can break that property's track at such a key; repeat the value on every key — hold it by repeating the previous value.`)}`
+        : '';
+    const first = [...keyframes].sort((a, b) => a.time - b.time)[0];
+    // loop:true repeats in the editor; an export of the measured build played
+    // the keyframes ONCE and held (round 7, 2.24). Said where it is set, with
+    // the two ways that do export, until the engine's export clock wraps them.
+    const loopNote = loop
+        ? `, loopNote: ${JSON.stringify('loop:true repeats in the editor, but has been measured playing ONCE in an exported video and then holding the last keyframe. For an export longer than one cycle, check a frame in the second cycle — if it holds, write the keyframes out per cycle, or use a loop preset (pinepaper_animate), which does cycle in export.')}`
+        : '';
+    const easingNote = first?.easing && first.easing !== 'linear'
+        ? `, note: ${JSON.stringify(`easing '${first.easing}' is on the first keyframe, where it has no effect: easing shapes the segment ARRIVING at a keyframe. Put it on the keyframe you are moving to.`)}`
+        : '';
     return `
 // Apply keyframe animation to ${itemId}
 (function() {
-  ${requireItem(itemId, 'the animation')}
+  ${requireItem(itemId, 'the animation')}${audioLevelGuard}
   app.addAnimation('${itemId}', ${keyframesJson}, ${JSON.stringify(opts)});
-  return { success: true, itemId: '${itemId}', duration: ${calculatedDuration}, loop: ${loop}${timeOffset !== undefined ? `, timeOffset: ${timeOffset}` : ''}${clipInPoint !== undefined ? `, clipInPoint: ${clipInPoint}` : ''}${clipOutPoint !== undefined ? `, clipOutPoint: ${clipOutPoint}` : ''} };
+  return { success: true, itemId: '${itemId}', duration: ${calculatedDuration}, loop: ${loop}${timeOffset !== undefined ? `, timeOffset: ${timeOffset}` : ''}${clipInPoint !== undefined ? `, clipInPoint: ${clipInPoint}` : ''}${clipOutPoint !== undefined ? `, clipOutPoint: ${clipOutPoint}` : ''}${easingNote}${loopNote}${gapNote} };
 })();
 `.trim();
 }
@@ -514,17 +1341,41 @@ function generateImportMotionCaptureCode(bvh, mode, skeletonId, opts = {}) {
 })()`;
 }
 function generateExecuteGeneratorCode(generatorName, params, region) {
-    // FxTool signature: app.executeGenerator(name, params, options).
-    // region lives in options (added in FxTool c81781c).
-    const options = region ? { region } : {};
+    const where = !region ? '' : region.width !== undefined
+        ? ` in region ${region.width}×${region.height} @ (${region.x},${region.y})`
+        : ` in the shape of ${region.shape.itemId}`;
     return `
-// Execute ${generatorName} generator${region ? ` in region ${region.width}×${region.height} @ (${region.x},${region.y})` : ''}
-(async function() {
-  await app.executeGenerator('${generatorName}', ${JSON.stringify(params, null, 2)}, ${JSON.stringify(options)});
-  return { success: true, generator: '${generatorName}'${region ? ', region: ' + JSON.stringify(region) : ''} };
+// Execute ${generatorName} generator${where}
+(async function() {${emitGeneratorRun(generatorName, JSON.stringify(params, null, 2), region)}
 })();
 `.trim();
 }
+/**
+ * Run a generator, optionally into a region, and return its result. Shared by
+ * execute_generator and the batch op. FxTool signature:
+ * app.executeGenerator(name, params, options), region in options (c81781c).
+ *
+ * A SHAPED REGION (c68524a2) falls back to a plain rectangle with only a
+ * console.warn — for a missing item, or one that is not a path — and an older
+ * engine drops the shape without a word (and, given only {itemId}, has no box
+ * at all and draws full-canvas). So the item is checked first and refused by
+ * name, and the result says whether this studio clips to shapes.
+ */
+function emitGeneratorRun(generatorName, paramsJson, region) {
+    const options = JSON.stringify(region ? { region } : {});
+    const itemId = region && typeof region.shape === 'object' ? region.shape.itemId : null;
+    const shaped = !!region && region.shape !== undefined && region.shape !== 'rect';
+    return `${itemId ? `
+  {
+    const __se = app.itemRegistry && app.itemRegistry.get(${JSON.stringify(itemId)});
+    const __si = __se && __se.item;
+    if (!__si) return { success: false, error: ${JSON.stringify(`region.shape names no item "${itemId}" — nothing was drawn. List items with pinepaper_get_items.`)} };
+    if (__si.className !== 'Path' && __si.className !== 'CompoundPath') return { success: false, error: ${JSON.stringify(`region.shape item "${itemId}" is a `)} + __si.className + ', and a clip needs a path (a shape, not text, a group or an image) — nothing was drawn.' };
+  }` : ''}
+  await app.executeGenerator('${generatorName}', ${paramsJson}, ${options});${shaped ? `
+  const __shapes = !!(app.generatorRegistry && typeof app.generatorRegistry._regionClipPath === 'function');` : ''}
+  return { success: true, generator: '${generatorName}'${region ? `, region: ${JSON.stringify(region)}` : ''}${shaped ? `, ...(__shapes ? {} : { regionShapeApplied: false, warning: ${JSON.stringify(`this studio does not clip generator regions to a shape, so ${typeof region.shape === 'object' ? 'the region had no box and the generator drew across the whole canvas' : `the ${region.shape} was drawn as a rectangle`}. It needs an engine with region shapes.`)} })` : ''} };`;
+}
 /**
  * Template for applying effects
  */
@@ -829,6 +1680,21 @@ const size = app.getCanvasSize();
 ({ width: size.width, height: size.height });
 `.trim();
 }
+/**
+ * Uploaded audio / video, removed through the media pipeline.
+ *
+ * clearCanvas empties the item groups and registries, but an uploaded clip
+ * also lives in the audio / video layers — so a video from the previous job
+ * survived agent_start_job {clearCanvas:true} and played in the next scene
+ * (round 8 retest, 1.66). removeMedia is the full removal (registry entry,
+ * stored blob, layer). Run before clearCanvas; forEach, not a generated loop.
+ */
+const MEDIA_PURGE = `
+  let __mediaRemoved = 0;
+  const __PA = (typeof window !== 'undefined') && window.PinePaperAgent;
+  if (__PA && typeof __PA.listMedia === 'function' && typeof __PA.removeMedia === 'function') {
+    __PA.listMedia().forEach(function(m) { try { if (__PA.removeMedia(m.id)) __mediaRemoved++; } catch (_) { /* keep clearing */ } });
+  }`;
 /**
  * Template for clearing all items from canvas
  */
@@ -841,6 +1707,7 @@ function generateClearCanvasCode() {
 // entries don't expose those — getItemById wants the registry id), so it
 // removed 0 items, and it called the non-existent app.clearAllRelations.
 const before = app.itemRegistry ? app.itemRegistry.getAll().length : 0;
+${MEDIA_PURGE}
 
 if (typeof app.clearCanvas === 'function') {
   app.clearCanvas();
@@ -856,7 +1723,7 @@ if (app.historyManager) app.historyManager.saveState();
 
 const remaining = app.itemRegistry ? app.itemRegistry.getAll().length : 0;
 
-({ success: true, removedCount: Math.max(0, before - remaining), remainingItems: remaining });
+({ success: true, removedCount: Math.max(0, before - remaining), remainingItems: remaining, mediaRemoved: __mediaRemoved });
 `.trim();
 }
 /**
@@ -1034,64 +1901,100 @@ export function planKeyframeMerges(operations) {
     return plan;
 }
 /**
- * Template for batch create - creates multiple items with single history save
+ * A create / modify snippet as the body of a function that RETURNS its value.
+ * Such a snippet's value is its last top-level (-led statement; the
+ * font-loading form is an async IIFE, which is awaited instead.
+ */
+function asReturningBody(snippet) {
+    const single = snippet.trim();
+    if (single.startsWith('(async function()'))
+        return `return await ${single.replace(/;\s*$/, '')};`;
+    const lines = single.split('\n');
+    let at = -1;
+    lines.forEach((l, i) => { if (l.startsWith('('))
+        at = i; });
+    if (at >= 0)
+        lines[at] = 'return ' + lines[at];
+    return lines.join('\n');
+}
+/**
+ * Template for batch create — create_item for each item, one history save.
+ *
+ * This called app.batchCreate, a third create path, and dropped fontWeight
+ * (and every other create_item fix) with no ignoredProperties (round 9 II,
+ * 1.79) — the same drift f1d0b05 removed from agent_batch_execute. Each item
+ * now runs create_item's own emitter with its per-item history save taken
+ * out, and the batch saves once at the end, which is what batchCreate was
+ * for. An item that fails is reported by index; the rest are still created.
  */
 function generateBatchCreateCode(items) {
-    const itemsJson = JSON.stringify(items, null, 2);
+    const blocks = items.map((it, i) => {
+        const { x, y, position, ...props } = (it.params || {});
+        const p = Array.isArray(position) ? { x: Number(position[0]), y: Number(position[1]) }
+            : (position && typeof position === 'object') ? { x: Number(position.x), y: Number(position.y) }
+                : { x: typeof x === 'number' ? x : 400, y: typeof y === 'number' ? y : 300 };
+        const given = position !== undefined || typeof x === 'number' || typeof y === 'number';
+        const body = asReturningBody(generateCreateItemCode(it.type, p, props, undefined, given))
+            .replace(/app\.historyManager\.saveState\(\);/g, '');
+        return `
+  try {
+    const r${i} = await (async function() {
+${body}
+    })();
+    if (r${i} && r${i}.success === false) errors.push({ index: ${i}, error: r${i}.error });
+    else results.push(Object.assign({ index: ${i} }, r${i}));
+  } catch (e) { errors.push({ index: ${i}, error: (e && e.message) || String(e) }); }`;
+    });
     return `
-// Batch create ${items.length} items
-const itemSpecs = ${itemsJson};
-const createdItems = app.batchCreate(itemSpecs);
-
-// Return created item IDs and info
-const results = createdItems.map(item => ({
-  itemId: item.data?.registryId || item.id,
-  type: item.className || 'unknown',
-  position: item.position ? { x: item.position.x, y: item.position.y } : null
-}));
-
-({ success: true, items: results, count: results.length });
-`.trim();
+// Batch create ${items.length} items — create_item for each, one history save
+(async function() {
+  const results = [];
+  const errors = [];
+${blocks.join('\n')}
+  if (app.historyManager) app.historyManager.saveState();
+  return { success: errors.length === 0, items: results, count: results.length, errors: errors };
+})();`.trim();
 }
 /**
- * Template for batch modify - modifies multiple items with single history save
+ * Template for batch modify — modify_item for each item, one history save.
+ *
+ * This called app.batchModify, which applies raw params and so missed every
+ * modify_item fix (text weight / leading, font loading, audio level, no-fill,
+ * lifetimes, smoothing, the unread-property report) — the drift f1d0b05 and
+ * 8f9b075 removed from the other batch paths. Each item now runs modify_item's
+ * own emitter with its history save removed; the batch saves once. The
+ * result keeps the old shape (count, requested, skipped with reasons, and an
+ * error naming the skipped when any were).
  */
 function generateBatchModifyCode(modifications) {
-    const modsJson = JSON.stringify(modifications, null, 2);
+    const blocks = modifications.map((m, i) => {
+        const snippet = generateModifyItemCode(m.itemId, (m.params || {})).trim()
+            .replace(/app\.historyManager\.saveState\(\);/g, '')
+            .replace(/;\s*$/, '');
+        return `
+  try {
+    const r${i} = await ${snippet};
+    if (r${i} && r${i}.success === false) skipped.push({ itemId: ${JSON.stringify(m.itemId)}, reason: r${i}.error || 'not modified' });
+    else { count++; if (r${i} && r${i}.ignoredProperties) ignored.push({ itemId: ${JSON.stringify(m.itemId)}, ignoredProperties: r${i}.ignoredProperties }); }
+  } catch (e) { skipped.push({ itemId: ${JSON.stringify(m.itemId)}, reason: (e && e.message) || String(e) }); }`;
+    });
     return `
-// Batch modify ${modifications.length} items
-const modifications = ${modsJson};
-// TWO BUGS, ONE CALL, AND BOTH FAILED LOUDLY IN THE WRONG PLACE.
-//
-// 1. The engine takes { item, params } with a LIVE ITEM, or { itemId, params }
-//    with a registry id. This put the id STRING into the item field, which is
-//    truthy — so the engine's own id lookup never ran, the string was treated
-//    as an item, and Object.assign got a string: "Cannot convert undefined or
-//    null to object", from a call that named the id correctly.
-// 2. batchModify returns a COUNT, not an array. Calling .map on a number
-//    is the second reported error, and it fires even when the modify worked.
-const results = app.batchModify(modifications.map(mod => ({
-  itemId: mod.itemId,
-  params: mod.params
-})));
-
-// The engine records what it could not do rather than throwing — read it,
-// instead of reporting a clean success over a half-applied batch.
-//
-// Read defensively (|| []): the property arrived with the engine-side
-// batchModify fix, so an older studio reports a count and no skip list rather
-// than failing. The batch still works; only the explanation is thinner.
-const skipped = app.lastBatchModifySkipped || [];
-const count = typeof results === 'number' ? results : (Array.isArray(results) ? results.length : 0);
-
-({
-  success: skipped.length === 0 && count === modifications.length,
-  count,
-  requested: modifications.length,
-  skipped: skipped.map(s => ({ itemId: s.itemId, reason: s.reason })),
-  ...(skipped.length ? { error: 'batch_modify changed ' + count + ' of ' + modifications.length + ' items; skipped: ' + skipped.map(s => s.itemId + ' (' + s.reason + ')').join(', ') } : {}),
-});
-`.trim();
+// Batch modify ${modifications.length} items — modify_item for each, one history save
+(async function() {
+  let count = 0;
+  const skipped = [];
+  const ignored = [];
+${blocks.join('\n')}
+  if (app.historyManager) app.historyManager.saveState();
+  return {
+    success: skipped.length === 0 && count === ${modifications.length},
+    count: count,
+    requested: ${modifications.length},
+    skipped: skipped,
+    ...(ignored.length ? { ignoredProperties: ignored } : {}),
+    ...(skipped.length ? { error: 'batch_modify changed ' + count + ' of ${modifications.length} items; skipped: ' + skipped.map(function(s) { return s.itemId + ' (' + s.reason + ')'; }).join(', ') } : {}),
+  };
+})();`.trim();
 }
 /**
  * Template for create grid - convenience method for creating line grids
@@ -1148,6 +2051,8 @@ const PLATFORM_TO_CANVAS_PRESET = {
     web: 'hd-720p', // 1280x720
     'print-a4': 'a4-portrait',
     'print-letter': 'letter-portrait',
+    'print-a4-landscape': 'a4-landscape',
+    'print-letter-landscape': 'letter-landscape',
 };
 /** The engine key for a platform, falling back to the value itself. */
 export function canvasPresetFor(platform) {
@@ -1293,6 +2198,7 @@ export class PinePaperCodeGenerator {
      */
     generateCreateItem(input) {
         const validated = CreateItemInputSchema.parse(input);
+        const positionGiven = input.position !== undefined;
         const properties = { ...validated.properties };
         if (validated.animationType !== undefined)
             properties.animationType = validated.animationType;
@@ -1304,14 +2210,16 @@ export class PinePaperCodeGenerator {
             properties.animationDelay = validated.animationDelay;
         if (validated.keyframes !== undefined)
             properties.keyframes = validated.keyframes;
-        return generateCreateItemCode(validated.itemType, validated.position, properties);
+        if (validated.anchor !== undefined && properties.anchor === undefined && properties.origin === undefined)
+            properties.anchor = validated.anchor;
+        return generateCreateItemCode(validated.itemType, validated.position, properties, validated.data, positionGiven);
     }
     /**
      * Generate code for modifying an item
      */
     generateModifyItem(input) {
         const validated = ModifyItemInputSchema.parse(input);
-        return generateModifyItemCode(validated.itemId, validated.properties);
+        return generateModifyItemCode(validated.itemId, validated.properties, validated.data);
     }
     /**
      * Generate code for deleting an item
@@ -1346,6 +2254,9 @@ export class PinePaperCodeGenerator {
   return { success: true, presetId: ${JSON.stringify(validated.presetId)}, relationType: r.relationType, params: r.params, values: r.values };
 })();`.trim();
         }
+        if (validated.relationType === 'moves_along_path') {
+            return generateMovesAlongPathCode(validated.sourceId, validated.targetId ?? undefined, (validated.params ?? {}));
+        }
         return generateAddRelationCode(validated.sourceId, validated.targetId || validated.sourceId, validated.relationType, validated.params);
     }
     /**
@@ -1400,7 +2311,7 @@ export class PinePaperCodeGenerator {
      */
     generateExecuteGenerator(input) {
         const validated = ExecuteGeneratorInputSchema.parse(input);
-        return generateExecuteGeneratorCode(validated.generatorName, validated.params, validated.region);
+        return generateExecuteGeneratorCode(validated.generatorName, aliasGeneratorParams(validated.generatorName, (validated.params ?? {})), validated.region);
     }
     /**
      * Generate code for applying an effect
@@ -1932,72 +2843,41 @@ if (typeof _gen === 'function') {
         for (const item of items) {
             const { name, itemType, position = { x: 400, y: 300 }, properties = {} } = item;
             // Build properties string
-            const propsEntries = Object.entries(properties)
-                .map(([key, value]) => `${key}: ${JSON.stringify(value)}`)
-                .join(', ');
-            const propsStr = propsEntries ? `, ${propsEntries}` : '';
+            // CREATE_SCENE HAND-BUILT ITS OWN SHAPES, AND MOST OF THEM WERE WRONG.
+            //
+            // This emitted a per-type switch of raw Paper constructors — a parallel
+            // implementation of app.create covering four cases, whose DEFAULT branch
+            // made a 30px circle. So ellipse, triangle, polygon, path, line and arc —
+            // six of the ten types this schema declares — silently rendered as a
+            // small blue circle, and every property the switch did not name was
+            // dropped. A pilot reported ellipse width/height being ignored; the same
+            // values work through batch because batch calls app.create.
+            //
+            // Routed through app.create now, which is the only thing that knows all
+            // 28 item types, the shape registry's own parameters, anchor, label,
+            // rotation and the registry id. Deleting the copy is the fix: a second
+            // implementation of "make a shape" could only ever drift from the first.
+            const sceneParams = {
+                x: position.x,
+                y: position.y,
+                ...properties,
+            };
             codeParts.push(`
 // Create item: ${name}
 (function() {
-  const itemParams = {
-    type: '${itemType}',
-    position: { x: ${position.x}, y: ${position.y} }${propsStr}
-  };
-
-  let item;
-  switch ('${itemType}') {
-    case 'circle':
-      item = new paper.Path.Circle({
-        center: [${position.x}, ${position.y}],
-        radius: ${properties.radius || 50},
-        fillColor: '${properties.color || properties.fillColor || '#3b82f6'}',
-        parent: app.textItemGroup
-      });
-      break;
-    case 'rectangle':
-      item = new paper.Path.Rectangle({
-        point: [${position.x - (properties.width || 100) / 2}, ${position.y - (properties.height || 60) / 2}],
-        size: [${properties.width || 100}, ${properties.height || 60}],
-        fillColor: '${properties.color || properties.fillColor || '#3b82f6'}',
-        parent: app.textItemGroup
-      });
-      break;
-    case 'star':
-      item = new paper.Path.Star({
-        center: [${position.x}, ${position.y}],
-        points: ${properties.points || 5},
-        radius1: ${properties.radius1 || 40},
-        radius2: ${properties.radius2 || 20},
-        fillColor: '${properties.color || properties.fillColor || '#fbbf24'}',
-        parent: app.textItemGroup
-      });
-      break;
-    case 'text':
-      item = new paper.PointText({
-        point: [${position.x}, ${position.y}],
-        content: '${properties.content || 'Text'}',
-        fontSize: ${properties.fontSize || 24},
-        fillColor: '${properties.color || properties.fillColor || '#ffffff'}',
-        fontFamily: '${properties.fontFamily || 'Inter'}',
-        justification: 'center',
-        parent: app.textItemGroup
-      });
-      break;
-    default:
-      item = new paper.Path.Circle({
-        center: [${position.x}, ${position.y}],
-        radius: 30,
-        fillColor: '${properties.color || properties.fillColor || '#3b82f6'}',
-        parent: app.textItemGroup
-      });
+  const item = app.create('${itemType}', ${JSON.stringify(sceneParams)});
+  if (!item) {
+    results.items.push({ name: '${name}', error: 'app.create returned nothing for type ${itemType} — check the type and its properties.' });
+    return;
   }
-
-  const itemId = app.registerItem(item, '${name}', { source: 'mcp-scene' });
+  // create() registers and mints the id; only fall back for an older studio.
+  const itemId = (item.data && item.data.id)
+    ? item.data.id
+    : app.registerItem(item, '${itemType}', { source: 'mcp-scene' });
   if (item.bringToFront) item.bringToFront();
   nameToId['${name}'] = itemId;
   results.items.push({ name: '${name}', itemId, type: '${itemType}' });
-})();
-`);
+})();`);
         }
         // Establish relations
         for (const relation of relations) {
@@ -2018,8 +2898,12 @@ if (typeof _gen === 'function') {
         }
         // Apply animations
         for (const animation of animations) {
-            const { target, type, speed = 1.0, params = {} } = animation;
-            const paramsStr = JSON.stringify({ ...params, speed });
+            const { target, type, speed = 1.0, startTime, params = {} } = animation;
+            const paramsStr = JSON.stringify({
+                ...params,
+                speed,
+                ...(startTime !== undefined ? { animationDelay: startTime } : {}),
+            });
             codeParts.push(`
 // Apply animation: ${type} to ${target}
 (function() {
@@ -2028,8 +2912,13 @@ if (typeof _gen === 'function') {
     const targetItem = app.itemRegistry.get(targetId);
     if (targetItem) {
       const params = ${paramsStr};
+      // startTime becomes animationDelay, which is what the engine reads
+      // (PinePaper.js stores it on item.data.animationDelay). These are ambient
+      // loops with no end, so there is no duration to map and none is invented
+      // — staggering the STARTS is what makes a scene read as choreographed
+      // rather than everything moving at once from frame zero.
       app.animate(targetItem, { animationType: '${type}', ...params });
-      results.animations.push({ target: '${target}', type: '${type}' });
+      results.animations.push({ target: '${target}', type: '${type}'${startTime !== undefined ? `, startTime: ${startTime}` : ''} });
     }
   }
 })();
@@ -2400,7 +3289,7 @@ throw new Error('Unknown diagram mode action: ${action}');
 `;
         if (shouldClear) {
             code += `
-  // Clear canvas
+  // Clear canvas — uploaded media first (it lives outside the item groups)${MEDIA_PURGE}
   if (app.clearCanvas) {
     app.clearCanvas();
   } else {
@@ -2463,7 +3352,9 @@ throw new Error('Unknown diagram mode action: ${action}');
      */
     generateAgentEndJob(input) {
         const validated = AgentEndJobInputSchema.parse(input);
-        const { takeScreenshot, analyzeContent } = validated;
+        const { analyzeContent } = validated;
+        // includeScreenshot is the published name; takeScreenshot the older one.
+        const takeScreenshot = validated.includeScreenshot ?? validated.takeScreenshot;
         const shouldAnalyze = analyzeContent !== false;
         let code = `
 // End agent job
@@ -2761,21 +3652,22 @@ throw new Error('Unknown diagram mode action: ${action}');
     generateBatchOperationCode(op, index, mergePlan) {
         switch (op.type) {
             case 'create': {
+                // THE SAME CREATE AS create_item, NOT A SECOND ONE.
+                //
+                // This case was its own app.create call, and every create_item fix since
+                // — fontWeight / leading, font loading, countdown content, no-fill,
+                // dashes, lifetimes, the unread-property report — passed it by: a batch
+                // read fontWeight 700 back as normal and a countdown stayed at 00:10
+                // for a 12 s MP4 (round 8 DD, 1.67). It now runs generateCreateItemCode,
+                // the exact emitter create_item uses, adapted to return its result
+                // inside this op's function.
                 const pos = op.position || { x: 400, y: 300 };
                 const createProps = withRadiusAxes((op.properties || {}));
-                const props = JSON.stringify(createProps);
+                const returning = asReturningBody(generateCreateItemCode(op.itemType, pos, { ...(op.properties || {}) }, undefined, op.position !== undefined));
                 let createCode = `
-const item = app.create('${op.itemType}', { position: { x: ${pos.x}, y: ${pos.y} }, ...${props} });
-const itemId = item.data && item.data.id ? item.data.id : app.registerItem(item, '${op.itemType}', { source: 'mcp-batch' });`;
-                // app.create() does not read blendMode/opacity from its params, but the
-                // underlying Paper.js item supports them directly — apply post-create so
-                // callers can pass them inline in `properties` and have them take effect.
-                if (createProps.blendMode !== undefined) {
-                    createCode += `\nif ('blendMode' in item) item.blendMode = ${JSON.stringify(createProps.blendMode)};`;
-                }
-                if (createProps.opacity !== undefined) {
-                    createCode += `\nif ('opacity' in item) item.opacity = ${JSON.stringify(createProps.opacity)};`;
-                }
+const __created = await (async function() {
+${returning}
+})();`;
                 // Coordinate-built items (path from segments/pathData, line/arc from
                 // from/through/to) derive their geometry from those coordinates and
                 // IGNORE params.position — so `create` at a point silently produced an
@@ -2787,30 +3679,35 @@ const itemId = item.data && item.data.id ? item.data.id : app.registerItem(item,
                     createCode += `
 // create() builds this item type from its own coordinates and ignores
 // params.position — apply the caller's explicit position after the fact.
-if (item.position) item.position = new paper.Point(${pos.x}, ${pos.y});`;
+const __it = __created && __created.itemId ? app.getItemById(__created.itemId) : null;
+if (__it && __it.position) __it.position = new paper.Point(${pos.x}, ${pos.y});`;
                 }
                 createCode += `
-// Ensure item is visible above backgrounds/generators
-if (item.bringToFront) item.bringToFront();
-return { itemId };
+return __created;
 `;
                 return createCode;
             }
-            case 'modify':
+            case 'modify': {
                 const itemRef = op.itemId?.startsWith('$')
                     ? `itemIds[${op.itemId.substring(1)}]`
                     : `'${op.itemId}'`;
-                const modifyProps = JSON.stringify(op.properties || {});
-                return `
-const targetId = ${itemRef};
-// modifyItem(id, changes), not select() + modify(). modify() edits the
-// SELECTION, so an id that does not resolve left the PREVIOUS selection to be
-// edited instead — and this then reported modified:true either way.
-if (app.modifyItem(targetId, ${modifyProps}) === false) {
-  return { success: false, itemId: targetId, error: 'no item ' + targetId + ' — nothing was modified' };
-}
-return { itemId: targetId, modified: true };
+                // modify_item's own emitter, as create is create_item's (see above):
+                // the batch's modifyItem call missed text styles, font loading, audio
+                // level, no-fill, lifetimes, smoothing and the unread-property report.
+                // The emitter embeds the id as a literal; a batch ref ($N) is only known
+                // at run time, so it is generated with a placeholder and the runtime
+                // variable put in its place.
+                const single = generateModifyItemCode('__MID__', (op.properties || {})).trim()
+                    .replace(/'__MID__'/g, '__mid')
+                    .replace(/__MID__/g, "' + __mid + '")
+                    .replace(/;\s*$/, '');
+                return `
+const __mid = ${itemRef};
+const __r = await ${single};
+if (__r && __r.success !== false) __r.modified = true;
+return __r;
 `;
+            }
             case 'animate':
                 const animItemRef = op.itemId?.startsWith('$')
                     ? `itemIds[${op.itemId.substring(1)}]`
@@ -2872,11 +3769,8 @@ return { success: true, backgroundColor: '${bgColor}' };
 `;
             case 'execute_generator':
                 const genName = op.generatorName || 'drawSunburst';
-                const genParams = JSON.stringify(op.generatorParams || {});
-                const genOptions = JSON.stringify(op.generatorRegion ? { region: op.generatorRegion } : {});
-                return `
-await app.executeGenerator('${genName}', ${genParams}, ${genOptions});
-return { success: true, generator: '${genName}'${op.generatorRegion ? ', region: ' + JSON.stringify(op.generatorRegion) : ''} };
+                const genParams = JSON.stringify(aliasGeneratorParams(genName, (op.generatorParams || {})));
+                return `${emitGeneratorRun(genName, genParams, op.generatorRegion)}
 `;
             case 'set_canvas_size': {
                 const w = op.width || 1080;
@@ -3051,7 +3945,32 @@ 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 } = 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, ad: adOpts } = validated;
+        // Encoder options (FxTool 16719759); the schema keeps them to mp4 / webm.
+        const videoEncodeOpts = {};
+        if (broadcast)
+            videoEncodeOpts.broadcast = true;
+        // Headroom defaults to 12 with broadcast (retest of caa9560): on a
+        // hard-edged white-on-black scene it measured 17-233 with nothing out of
+        // range, where 0 left 0.34% out and a post-hoc clip made it worse. 0 is
+        // still available by asking for it.
+        const headroomDefaulted = !!broadcast && broadcastHeadroom === undefined;
+        if (broadcast)
+            videoEncodeOpts.broadcastHeadroom = broadcastHeadroom ?? 12;
+        if (bitrate !== undefined)
+            videoEncodeOpts.bitrate = bitrate;
+        if (minBitrate !== undefined)
+            videoEncodeOpts.minBitrate = minBitrate;
+        if (bitrateMode !== undefined)
+            videoEncodeOpts.bitrateMode = bitrateMode;
+        // A transparent WebM (FxTool 1833b397) rides the store route too.
+        const webmAlpha = format === 'webm' && transparent === true;
+        if (webmAlpha) {
+            videoEncodeOpts.transparent = true;
+            if (alphaQuantizer !== undefined)
+                videoEncodeOpts.alphaQuantizer = alphaQuantizer;
+        }
+        const encodeOptsJs = Object.keys(videoEncodeOpts).length ? `, ...${JSON.stringify(videoEncodeOpts)}` : '';
         const qualityLevel = quality || 'standard';
         const videoDuration = duration ?? 5;
         // Quality settings (bitrate in bps for VideoEncoder)
@@ -3072,6 +3991,8 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
             'web': { width: 800, height: 600, staticFormat: 'svg', animatedFormat: 'svg' },
             'print-a4': { width: 2480, height: 3508, staticFormat: 'pdf', animatedFormat: 'pdf' },
             'print-letter': { width: 2550, height: 3300, staticFormat: 'pdf', animatedFormat: 'pdf' },
+            'print-a4-landscape': { width: 3508, height: 2480, staticFormat: 'pdf', animatedFormat: 'pdf' },
+            'print-letter-landscape': { width: 3300, height: 2550, staticFormat: 'pdf', animatedFormat: 'pdf' },
         };
         const preset = platformPresets[platform] || platformPresets['web'];
         // SCALE is the only honest size control this surface has.
@@ -3118,6 +4039,51 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
         // for by name. Dimensions, framing, fps and bitrate are all absent rather
         // than passed and ignored.
         // @engine-methods renderSoundtrackWav exportEngine.sceneHasAudio ensureHeavyModules
+        // CAPTIONS AS A FILE (round 8 EE, 8.19). format 'srt' was "Invalid input",
+        // yet caption text staged with bornAt / ttl already carries frame-exact
+        // times on item.data — the cues are in the scene. Every text item with a
+        // lifetime becomes one cue, in start order; a text item without one is
+        // on screen for the whole piece and is not a caption, so it is left out
+        // and counted.
+        // scc (CEA-608, 8.37) takes the same cues; the server encodes them
+        // (src/utils/scc.ts), where the byte work is testable.
+        if (exportFormat === 'srt' || exportFormat === 'vtt' || exportFormat === 'scc') {
+            const fmt = exportFormat;
+            return `
+// Export: captions (${fmt}) from text items with a lifetime
+(function() {
+  if (!app.itemRegistry || typeof app.itemRegistry.getAll !== 'function') {
+    return { success: false, format: '${fmt}', error: 'this studio cannot list items (app.itemRegistry.getAll) — update PinePaper Studio.' };
+  }
+  const texts = app.itemRegistry.getAll().filter(function(e) {
+    const it = e && e.item;
+    return it && it.className === 'PointText' && typeof it.content === 'string' && it.content.trim() !== '';
+  });
+  const timed = texts.filter(function(e) { return e.item.data && typeof e.item.data.bornAt === 'number'; });
+  if (!timed.length) {
+    return { success: false, format: '${fmt}', error: 'no captions to export: no text item has a lifetime. Stage each caption with properties.bornAt / ttl (seconds) on create_item or modify_item, then export ${fmt}.', untimedText: texts.length };
+  }
+  const end = ${videoDuration};
+  const ts = function(t, sep) {
+    const ms = Math.max(0, Math.round(t * 1000));
+    const h = Math.floor(ms / 3600000), m = Math.floor(ms / 60000) % 60, s = Math.floor(ms / 1000) % 60, r = ms % 1000;
+    const p = function(n, w) { return String(n).padStart(w, '0'); };
+    return p(h, 2) + ':' + p(m, 2) + ':' + p(s, 2) + sep + p(r, 3);
+  };
+  const cues = timed.map(function(e) {
+    const d = e.item.data;
+    const start = d.bornAt;
+    const stop = typeof d.ttl === 'number' ? start + d.ttl : end;
+    return { start: start, stop: Math.max(start, stop), text: e.item.content.trim() };
+  }).sort(function(a, b) { return a.start - b.start; });
+${fmt === 'scc' ? `  return { success: true, format: 'scc', sccCues: cues, cues: cues.length, untimedText: texts.length - timed.length };
+` : ''}  const body = cues.map(function(c, i) {
+    return ${fmt === 'srt' ? `(i + 1) + '\\n' + ts(c.start, ',') + ' --> ' + ts(c.stop, ',')` : `ts(c.start, '.') + ' --> ' + ts(c.stop, '.')`} + '\\n' + c.text;
+  }).join('\\n\\n') + '\\n';
+  const text = ${fmt === 'vtt' ? `'WEBVTT\\n\\n' + body` : 'body'};
+  return { success: true, format: '${fmt}', data: text, mimeType: '${fmt === 'srt' ? 'application/x-subrip' : 'text/vtt'}', size: text.length, cues: cues.length, untimedText: texts.length - timed.length };
+})();`.trim();
+        }
         if (exportFormat === 'wav') {
             const sr = validated.sampleRate ?? 48000;
             const bd = validated.bitDepth ?? 16;
@@ -3195,7 +4161,30 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
   const __even = (n) => Math.max(2, Math.round((n * ${scale !== undefined ? scale : 1}) / 2) * 2);
   const dimensions = (__canvasDims && __canvasDims.width && __canvasDims.height)
     ? { width: __even(__canvasDims.width), height: __even(__canvasDims.height) }
-    : __presetDims;` : `  const dimensions = ${JSON.stringify(scaled)};`}
+    : __presetDims;
+  const __fit = null;` : `  // A PRESET IS A SIZE, NOT PERMISSION TO STRETCH.
+  //
+  // 'instagram' is 1080x1080, and a 4:5 (1080x1350) canvas exported under it
+  // came out squashed to 0.8 vertically, text distorted, with nothing said —
+  // 4:5 is itself a valid Instagram feed size. When the canvas aspect differs
+  // from the preset's, the canvas aspect is kept and its SHORT edge takes the
+  // preset's short edge: 4:5 on instagram is 1080x1350, a square canvas on
+  // youtube is 1080x1080. The result says so in platformFit.
+  const __presetBox = ${JSON.stringify(scaled)};
+  const __cv = app.canvasSize || (app.view && app.view.viewSize) || null;
+  let dimensions = __presetBox;
+  let __fit = null;
+  if (__cv && __cv.width > 0 && __cv.height > 0) {
+    const ca = __cv.width / __cv.height, pa = __presetBox.width / __presetBox.height;
+    if (Math.abs(ca / pa - 1) > 0.01) {
+      const short = Math.min(__presetBox.width, __presetBox.height);
+      const ev = (n) => Math.max(2, Math.round(n / 2) * 2);
+      dimensions = ca >= 1 ? { width: ev(short * ca), height: ev(short) } : { width: ev(short), height: ev(short / ca) };
+      __fit = { preset: __presetBox.width + 'x' + __presetBox.height, used: dimensions.width + 'x' + dimensions.height,
+        canvas: __cv.width + 'x' + __cv.height,
+        note: 'the canvas aspect differs from the ' + platform + ' preset, so the canvas aspect was kept rather than stretched. Resize the canvas to the preset to get exactly ' + __presetBox.width + 'x' + __presetBox.height + '.' };
+    }
+  }`}
 
   // WHAT THIS SCENE LOSES TO THIS FORMAT, asked at the moment you would care.
   //
@@ -3204,17 +4193,97 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
   // silence. The engine derived it so that 117 tool descriptions would not
   // have to answer "does this survive export?" by hand and drift.
   //
-  // Reported ONLY when there is something to report. An empty list would read
-  // as "this format is lossless", and it does not mean that — it means this
-  // scene has nothing THIS format will lose. Omitting it entirely is the one
-  // shape that cannot be misread, and it keeps a clean export quiet.
+  // THREE STATES, ALL DISTINGUISHABLE. This used to be reported only when
+  // there was something to report, so that an empty list could not be misread
+  // as "this format is lossless". That solved one misreading and created a
+  // worse one: a caller could not tell "checked, nothing lost" from "never
+  // checked", and a pilot reported fidelity as null in EVERY scene with no way
+  // to know whether that was good news or a broken check.
+  //
+  // So it is always present: available:false when the studio cannot check,
+  // warnings:[] plus a note when it checked and found nothing, and the
+  // warnings themselves otherwise. The note carries the caveat that absence
+  // was standing in for.
+  //
+  // STAND-INS ARE THIS TOOL'S OWN DOING, SO THIS TOOL REPORTS THEM. create_item
+  // draws 'shader' and 'field' locally as a flat plate tagged data.renderAs; the
+  // engine's check sees an ordinary rectangle and cannot know a surface was
+  // meant. So a local export of a sea came out a flat blue slab with nothing
+  // said. Reported whatever the engine check can or cannot do.
+  function standIns() {
+    try {
+      // Probed with === : a studio without it degrades to "no stand-ins".
+      const canList = app.itemRegistry && typeof app.itemRegistry.getAll === 'function';
+      if (!canList) return [];
+      const found = {};
+      for (const entry of app.itemRegistry.getAll()) {
+        const kind = entry && entry.item && entry.item.data && entry.item.data.renderAs;
+        if (kind === 'shader' || kind === 'field') (found[kind] = found[kind] || []).push(entry.itemId);
+      }
+      return Object.keys(found).map(function(kind) {
+        const ids = found[kind];
+        return {
+          code: 'render_time_surface_stand_in',
+          message: ids.length + ' ' + kind + ' item' + (ids.length > 1 ? 's are' : ' is')
+            + ' exported as the flat plate that stands in for ' + (ids.length > 1 ? 'them' : 'it')
+            + ' on a local canvas. The surface itself is drawn only by a cloud render.',
+          items: ids.slice(0, 6),
+        };
+      });
+    } catch (e) { return []; }
+  }
+  // TRANSPARENCY THE FORMAT CANNOT CARRY. A scene with no background exported
+  // to webm came out on BLACK while the engine's check said it lost nothing
+  // (round 7, 8.12). Only said when the scene is evidently transparent — no
+  // solid CSS background colour AND nothing in the background layer — so a
+  // generator or pattern backdrop never trips it.
+  function alphaLoss(fmt) {
+    try {
+      if (['mp4', 'jpg'${format === 'webm' && transparent === true ? '' : ", 'webm'"}${format === 'apng' && transparent === false ? ", 'apng'" : ''}].indexOf(fmt) === -1) return [];
+      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 [];
+      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'
+        ? 'jpg has no transparency and this scene has no background, so transparent areas are filled white. Use png or webp to keep them.'
+        : fmt + ' is exported without transparency and this scene has no background, so transparent areas come out BLACK. Set a background colour, or export apng (animated, full alpha) or png to keep it.' }];
+    } catch (e) { return []; }
+  }
+  // TEXT THAT DOES NOT FIT (FxTool 661224ef: textOverflowReport) — text past
+  // its fit box at the minimum size, or off the frame. The pre-batch check for
+  // certificates, speaker cards and localised variants, on every export.
+  function textOverflow() {
+    try {
+      const rep = (typeof app.textOverflowReport === 'function' && app.textOverflowReport()) || [];
+      return rep.slice(0, 10).map(function(o) {
+        return { code: 'text_overflow', message: (o.id || 'a text item') + ' (' + JSON.stringify(String(o.content || '').slice(0, 40)) + '): ' + (o.reason || 'overflows'), items: [o.id] };
+      });
+    } catch (e) { return []; }
+  }
   function fidelity(fmt) {
+    const own = standIns().concat(alphaLoss(fmt), textOverflow());
     try {
-      if (!app.exportEngine || typeof app.exportEngine.exportFidelity !== 'function') return {};
+      if (!app.exportEngine || typeof app.exportEngine.exportFidelity !== 'function') {
+        return { fidelity: { available: false, reason: 'this studio cannot check export fidelity — update PinePaper Studio.', ...(own.length ? { warnings: own } : {}) } };
+      }
       const r = app.exportEngine.exportFidelity(fmt);
-      if (!r || !r.warnings || r.warnings.length === 0) return {};
-      return { fidelity: { warnings: r.warnings, checked: r.checked } };
-    } catch (e) { return {}; }
+      if (!r) { return { fidelity: { available: false, reason: 'the fidelity check returned nothing.', ...(own.length ? { warnings: own } : {}) } }; }
+      const warnings = (r.warnings || []).concat(own);
+      return {
+        fidelity: {
+          available: true,
+          warnings: warnings,
+          checked: r.checked,
+          ...(warnings.length === 0
+            ? { note: 'this scene loses nothing to ' + fmt + '. That is a statement about THIS SCENE, not a claim that the format is lossless.' }
+            : {}),
+        },
+      };
+    } catch (e) {
+      return { fidelity: { available: false, reason: (e && e.message) || 'the fidelity check threw.', ...(own.length ? { warnings: own } : {}) } };
+    }
   }
 
   // Preflight: same resolved settings as the real export, but render nothing.
@@ -3256,8 +4325,8 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
   // drives motion during export — framing only fixes the output frame.
   let cameraDims = null;
   if (framing === 'camera') {
-    if (!['gif', 'mp4', 'webm'].includes(format)) {
-      return { success: false, platform, format, framing, error: 'framing: "camera" is only supported for video formats (gif, mp4, webm). Use format: "mp4" / "gif" / "webm" or omit framing.' };
+    if (!['gif', 'apng', 'mp4', 'webm'].includes(format)) {
+      return { success: false, platform, format, framing, error: 'framing: "camera" is only supported for animated formats (gif, apng, mp4, webm). Use format: "mp4" / "gif" / "webm" or omit framing.' };
     }
     const rr = app.relationRegistry;
     const hasWalkthrough = rr && typeof rr.hasCameraAnimation === 'function' && rr.hasCameraAnimation();
@@ -3302,10 +4371,65 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
     cameraDims = { width: camBase.width, height: camBase.height };
   }
 
-  let result = { success: false, platform, format, quality, framing };
+  // AN EXPORTER ANSWERS A BLOB OR A RECORD AROUND ONE.
+  //
+  // Declared ABOVE the switch. They used to be consts inside the video case's
+  // block, so the pdf case — which 04ea8d2 pointed at asBlob — threw
+  // "asBlob is not defined" on every PDF export.
+  //
+  // exportPDF resolves to {blob, width, height, format}, and this passed
+  // the whole record to FileReader.readAsDataURL — "parameter 1 is not of
+  // type 'Blob'", every PDF export, with an error naming FileReader and
+  // nothing about PDFs. The engine has the same normaliser for the same
+  // reason (AgentMode._asBlob), so this matches its behaviour rather than
+  // inventing a second convention.
+  const asBlob = (r) => {
+    if (typeof Blob !== 'undefined' && r instanceof Blob) return r;
+    if (r && typeof Blob !== 'undefined' && r.blob instanceof Blob) return r.blob;
+    // Duck-typed last resort: a studio may hand back something Blob-like
+    // that fails instanceof across a realm boundary.
+    if (r && typeof r.size === 'number' && typeof r.slice === 'function') return r;
+    if (r && r.blob && typeof r.blob.size === 'number') return r.blob;
+    return null;
+  };
+  const blobToDataUrl = (b) => new Promise(resolve => {
+    const r = new FileReader();
+    r.onloadend = () => resolve(r.result);
+    r.readAsDataURL(b);
+  });
 
+  let result = { success: false, platform, format, quality, framing };
+  // A STILL SHOWS WHAT IS ALIVE AT ITS MOMENT. Lifetimes that fall back to the
+  // MCP's frame callback are applied by the frame loop, and a seek does not run
+  // it — so a png at time 0.8 s drew nothing staged at 0.8 s, and an item past
+  // its ttl still showed (retest). The visibility pass runs here for stills.
+  if (['png', 'jpg', 'webp', 'svg', 'pdf'].indexOf(format) !== -1) {
+    const __L = globalThis.__ppMcp;
+    if (__L && __L.lifetimeApp === app && typeof __L.applyLifetimes === 'function') {
+      try { __L.applyLifetimes(${stillTime !== undefined ? stillTime : "typeof app.playbackTime === 'number' ? app.playbackTime : 0"}); } catch (_) { /* the still renders either way */ }
+    }
+  }
+  // The engine's report on the audio track of THIS export (FxTool b41860aa:
+  // encoder delay compensated, padding past the picture dropped). Cleared
+  // first so a report left by an earlier export is never read as this one's.
+  const __vx = app.exportEngine && app.exportEngine.videoExporter;
+  if (__vx && 'lastAudioReport' in __vx) __vx.lastAudioReport = null;
+  if (__vx && 'lastVideoReport' in __vx) __vx.lastVideoReport = null;
+${stillTime !== undefined ? `
+  // A STILL AT A CHOSEN MOMENT (round 7 X, 1.57). Without this a png is
+  // whatever frame the playhead is on — two identical builds gave PNGs that
+  // differed in the animated streak while their MP4s were byte-identical.
+  // Seek, render, and put the playhead back afterwards.
+  const __prevT = typeof app.playbackTime === 'number' ? app.playbackTime : 0;
+  if (typeof app.setPlaybackTime !== 'function') {
+    return { success: false, platform, format, error: 'app.setPlaybackTime unavailable — this studio cannot render a still at a chosen time.' };
+  }
+  app.setPlaybackTime(${stillTime});
+  if (typeof paper !== 'undefined' && paper.view && typeof paper.view.update === 'function') paper.view.update();
+` : ''}
   try {
-    switch (format) {
+    // jpg / webp render as png, then re-encode below.
+    switch ((format === 'jpg' || format === 'webp') ? 'png' : format) {
       case 'svg':
         const svgString = app.exportAnimatedSVG ? app.exportAnimatedSVG() : app.exportSVGWithCSS();
         result = {
@@ -3320,6 +4444,59 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
         break;
 
       case 'png':
+        ${region ? `// A REGION, not the whole board — carousel slices, crops. renderRegionToDataURL
+        // re-renders that world rect offscreen without touching the live view;
+        // it was reachable only from custom code. A differing output aspect is
+        // covered by the engine, not stretched.
+        if (typeof app.renderRegionToDataURL !== 'function') {
+          result = { success: false, platform, format: 'png', error: 'app.renderRegionToDataURL unavailable — update PinePaper Studio to export a region.' };
+          break;
+        }
+        {
+          const rw = ${region.outputWidth ?? Math.round(region.width)}, rh = ${region.outputHeight ?? Math.round(region.height)};
+          // OWNERSHIP BY CENTRE (1.78, FxTool 78ec5916): excludeForeign hides, for
+          // this render, a top-level item that reaches in but is centred outside —
+          // a neighbouring card's overflowing headline. Older studios ignore the
+          // fourth argument, and leave lastRegionExcluded unset.
+          if ('lastRegionExcluded' in app) app.lastRegionExcluded = null;
+          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
+          // recipe — one big canvas, one region per card — text that overflows
+          // its cell spills into the next card's export (up to 5,826 foreign px),
+          // silently. A region cannot know which card an item belongs to, so it
+          // cannot clip per card; it can name every item that is only partly
+          // inside it, which is exactly the overflow in either direction.
+          const __rx = ${region.x}, __ry = ${region.y}, __rr = ${region.x + region.width}, __rb = ${region.y + region.height};
+          const crossing = [], coveringExcluded = [];
+          if (app.itemRegistry && typeof app.itemRegistry.getAll === 'function') {
+            app.itemRegistry.getAll().forEach(function(e) {
+              const b = e && e.item && e.item.visible !== false && e.item.bounds;
+              if (!b || !(b.width > 0)) return;
+              const r = b.x + b.width, bt = b.y + b.height;
+              const intersects = b.x < __rr && r > __rx && b.y < __rb && bt > __ry;
+              const inside = b.x >= __rx - 0.5 && r <= __rr + 0.5 && b.y >= __ry - 0.5 && bt <= __rb + 0.5;
+              const covers = b.x <= __rx && r >= __rr && b.y <= __ry && bt >= __rb; // a full-bleed backdrop is not overflow
+              if (intersects && !inside && !covers && crossing.length < 20) crossing.push(e.itemId);
+              if (covers && __excluded && (__excluded.indexOf(e.itemId) >= 0 || (e.item.data && __excluded.indexOf(e.item.data.id) >= 0))) coveringExcluded.push(e.itemId);
+            });
+          }
+          result = { success: true, platform, format: 'png', data: regionUrl, mimeType: 'image/png',
+            size: Math.round(String(regionUrl).length * 0.75), dimensions: { width: rw, height: rh },
+            region: ${JSON.stringify({ x: region.x, y: region.y, width: region.width, height: region.height })} };
+          if (__excluded && __excluded.length) {
+            result.excludedItems = __excluded;
+            result.excludedNote = 'centred outside this region, so treated as belonging to a neighbouring region and left out of this image.';
+          }
+          if (coveringExcluded.length) {
+            result.warning = 'backdrop item(s) ' + coveringExcluded.join(', ') + ' cover this whole region but are centred outside it, so they were left out as foreign — this image has no background from them. Re-export with region.excludeForeign: false, or give each card its own backdrop.';
+          }
+          if (crossing.length) {
+            result.crossingItems = crossing;
+            result.warning = (result.warning ? result.warning + ' ' : '') + crossing.length + ' item(s) are only partly inside this region, so part of them is cut off here or spills into a neighbouring region: ' + crossing.join(', ') + '. In a sheet of cards this is text overflowing its card — shorten it, shrink it, or wrap it.';
+          }
+        }
+        break;` : ''}
         if (app.exportEngine && app.exportEngine.exportPNG) {
           // PNG IGNORED THE PLATFORM ENTIRELY.
           //
@@ -3367,10 +4544,52 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
         }
         break;
 
+      case 'html5-ad':
+      case 'playable': {
+        // AN AD FROM THE WIDGET PAGE (8.21 / 8.24). The page is the studio's
+        // standalone widget; the server adds the network's wrapper and builds
+        // the zip (src/utils/ad-package.ts). Here: the page, its size, the CTA
+        // box in percent of the canvas, and a backup image for html5-ad.
+        if (!app.exportEngine || typeof app.exportEngine.exportWidgetHTML !== 'function') {
+          result = { success: false, platform, format, error: 'this studio cannot export its standalone widget page (no exportWidgetHTML), which an ad is built from.' };
+          break;
+        }
+        // The artboard, never the canvas element: its backing store is scaled
+        // by the renderer, and an ad's size is what was asked for.
+        const __as = (typeof app.getCanvasSize === 'function' && app.getCanvasSize()) || app.canvasSize || { width: 0, height: 0 };
+        const __cw = __as.width, __ch = __as.height;
+        let __cta = null;
+        ${adOpts?.ctaItemId ? `{
+          const __ce = app.itemRegistry && app.itemRegistry.get(${JSON.stringify(adOpts.ctaItemId)});
+          const __cb = __ce && __ce.item && __ce.item.bounds;
+          if (!__cb || !(__cb.width > 0) || !(__cw > 0)) {
+            result = { success: false, platform, format, error: ${JSON.stringify(`ad.ctaItemId "${adOpts.ctaItemId}" is not an item on the canvas with a size — nothing was exported. List items with pinepaper_get_items.`)} };
+            break;
+          }
+          __cta = { left: __cb.x / __cw * 100, top: __cb.y / __ch * 100, width: __cb.width / __cw * 100, height: __cb.height / __ch * 100 };
+        }` : ''}
+        const __w = await app.exportEngine.exportWidgetHTML({ download: false });
+        if (!__w || typeof __w.html !== 'string' || !__w.html) {
+          result = { success: false, platform, format, error: 'the studio returned no widget page to build the ad from.' };
+          break;
+        }
+        let __backup = null;
+        if (format === 'html5-ad' && typeof app.captureFrameDataURL === 'function') {
+          try { __backup = app.captureFrameDataURL(1); } catch (_) { __backup = null; }
+        }
+        // The background the PNG export uses (the canvas element's). The widget
+        // page prefers another record that can be stale, which served a white
+        // page under white text (8.9 again); the server pins this one.
+        const __bgc = (app.canvasEl && app.canvasEl.style && app.canvasEl.style.backgroundColor) || null;
+        result = { success: true, platform, format, adPage: __w.html, adSize: { width: __cw, height: __ch }, cta: __cta, backupImage: __backup, background: __bgc };
+        break;
+      }
+
       case 'gif':
+      case 'apng':
       case 'mp4':
       case 'webm': {
-        const videoMimeType = { mp4: 'video/mp4', webm: 'video/webm', gif: 'image/gif' }[format];
+        const videoMimeType = { mp4: 'video/mp4', webm: 'video/webm', gif: 'image/gif', apng: 'image/apng' }[format];
         // FxTool VideoExporter._calculateBitrate multiplies a per-resolution
         // base by settings.quality (0.5-1.0). Our existing per-tier compression
         // values (0.6 / 0.85 / 0.95) map directly to that scale. Without this,
@@ -3380,12 +4599,10 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
         // width/height ride along ONLY when a scale was asked for. The buffered
         // fallback paths otherwise export at canvas size, and quietly changing
         // that for every existing caller is not what a new optional knob does.
-        const baseVideoSettings = { format, fps: settings.fps, quality: settings.compression, duration: ${videoDuration}${scale !== undefined && scale !== 1 ? ', width: dimensions.width, height: dimensions.height' : ''} };
-        const blobToDataUrl = (b) => new Promise(resolve => {
-          const r = new FileReader();
-          r.onloadend = () => resolve(r.result);
-          r.readAsDataURL(b);
-        });
+        // loop rides in the BASE settings for a gif, so every route carries it:
+        // the direct one below, and also camera framing and a studio without
+        // _quickExportVideo, which build from these and used to drop it.
+        const baseVideoSettings = { format, fps: settings.fps, quality: settings.compression, duration: ${videoDuration}${scale !== undefined && scale !== 1 ? ', width: dimensions.width, height: dimensions.height' : ''}${gifLoop !== undefined ? `, ...(format === 'gif' || format === 'apng' ? { loop: ${JSON.stringify(gifLoop)} } : {})` : ''}${encodeOptsJs}${transparent !== undefined ? `, transparent: ${transparent}` : ''} };
 
         // THE EXPORT STORE. A long export cannot come back as one base64
         // string: base64 of a gigabyte is larger than the gigabyte, and it
@@ -3403,7 +4620,7 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
           && typeof app.exportEngine.readExport === 'function')
           ? app.exportEngine : null;
 
-        if (store && format !== 'gif') {
+        if (store && format !== 'gif' && format !== 'apng') {
           const stored = await store.exportToStore({
             format,
             duration: baseVideoSettings.duration,
@@ -3414,7 +4631,10 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
             // VideoEncoder.configure.
             quality: settings.compression,
             width: cameraDims ? cameraDims.width : dimensions.width,
-            height: cameraDims ? cameraDims.height : dimensions.height,
+            height: cameraDims ? cameraDims.height : dimensions.height,${encodeOptsJs ? `
+            // Broadcast / bitrate. A store that rebuilds its options without
+            // them is caught by the video report below, not assumed.
+            ${encodeOptsJs.slice(2)},` : ''}
           });
           if (!stored || stored.ok === false) {
             result = { success: false, platform, format, error: (stored && stored.reason) || 'the export store refused the export without saying why' };
@@ -3450,7 +4670,11 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
         // refusing.
         const INLINE_MAX_BYTES = ${INLINE_MAX_BYTES};
         const mb = (n) => (n / (1024 * 1024)).toFixed(1);
-        const deliver = async (blob) => {
+        const deliver = async (raw) => {
+          // Normalise first: a {blob, …} record would otherwise be reported as
+          // "streamed to a file instead of returning bytes", which is a true
+          // sentence about the wrong problem.
+          const blob = asBlob(raw) || raw;
           if (!blob || typeof blob.size !== 'number' || typeof blob.slice !== 'function') {
             return {
               success: false, platform, format,
@@ -3469,7 +4693,20 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
 
         // Camera framing requires going direct to videoExporter so width/height
         // pass through — _quickExportVideo strips dim fields.
-        if (cameraDims && app.exportEngine && app.exportEngine.videoExporter) {
+        // ANIMATED PNG (8.12, FxTool 76312a55): stepped PNG frames with full
+        // alpha, transparent unless transparent: false. Asked of the exporter
+        // directly; a studio that lacks it says so in its capability table, and
+        // is refused by name rather than handed a format it would reject.
+        const __apngVx = format === 'apng' ? (app.exportEngine && app.exportEngine.videoExporter) : null;
+        if (format === 'apng' && !(__apngVx && typeof __apngVx.export === 'function' && __apngVx.constructor
+            && typeof __apngVx.constructor.getCapabilities === 'function' && __apngVx.constructor.getCapabilities().apng)) {
+          result = { success: false, platform, format, error: 'this studio cannot export APNG (it needs an engine with animated PNG). For animation with alpha, export a png sequence (pinepaper_interchange export_png_sequence with options.transparent: true); gif keeps only 1-bit transparency.' };
+        } else if (format === 'apng') {
+          const blob = await __apngVx.export(cameraDims ? { ...baseVideoSettings, width: cameraDims.width, height: cameraDims.height } : baseVideoSettings);
+          result = await deliver(blob);
+          if (result.success) result.transparent = ${transparent !== false};
+          if (result.success && cameraDims) result.dimensions = cameraDims;
+        } else if (cameraDims && app.exportEngine && app.exportEngine.videoExporter) {
           const blob = await app.exportEngine.videoExporter.export({ ...baseVideoSettings, width: cameraDims.width, height: cameraDims.height });
           result = await deliver(blob);
           if (result.success) result.dimensions = cameraDims;
@@ -3481,12 +4718,43 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
         } else if (app.exportEngine && app.exportEngine._quickExportVideo) {
           // GIF path (working): _quickExportVideo forwards gifQuality to
           // gif.js. Also serves as the fallback if videoExporter is absent.
-          const videoResult = await app.exportEngine._quickExportVideo(format, baseVideoSettings, false);
+          ${gifLoop !== undefined ? `// A LOOP COUNT (8.30): _quickExportVideo rebuilds its settings without
+          // it, so a GIF with loop set goes straight to videoExporter.export.
+          // true = forever, false / 0 / 1 = once, n = n plays (engine 952d6d35).
+          const videoResult = (format === 'gif' && app.exportEngine.videoExporter && typeof app.exportEngine.videoExporter.export === 'function')
+            ? { blob: await app.exportEngine.videoExporter.export(Object.assign({}, baseVideoSettings, { format: 'gif', loop: ${JSON.stringify(gifLoop)} })) }
+            : await app.exportEngine._quickExportVideo(format, baseVideoSettings, false);` : `const videoResult = await app.exportEngine._quickExportVideo(format, baseVideoSettings, false);`}
           if (videoResult && videoResult.blob) {
             result = await deliver(videoResult.blob);
           } else {
             result = { success: false, error: format.toUpperCase() + ' export returned no data' };
           }
+          ${maxBytes !== undefined ? `// A BYTE BUDGET (round 9 GG, 8.31 — email wants <= 1 MB). gif.js has no
+          // colour-count knob, so size is the lever: GIF bytes scale roughly with
+          // pixel count, so the frame is shrunk by sqrt(budget / size) with a
+          // margin and re-encoded, at most twice. Every attempt is reported.
+          if (format === 'gif' && result && result.success && result.size > ${maxBytes}) {
+            const attempts = [{ width: dimensions.width, height: dimensions.height, bytes: result.size }];
+            let w = dimensions.width, h = dimensions.height;
+            for (let k = 0; k < 2 && result.success && result.size > ${maxBytes}; k++) {
+              const f = Math.sqrt(${maxBytes} / result.size) * 0.9;
+              w = Math.max(16, Math.round(w * f / 2) * 2); h = Math.max(16, Math.round(h * f / 2) * 2);
+              // videoExporter.export, not _quickExportVideo: the latter rebuilds
+              // its settings without width / height, so a "smaller" retry
+              // through it came out the same size.
+              if (!app.exportEngine.videoExporter || typeof app.exportEngine.videoExporter.export !== 'function') break;
+              const again = await app.exportEngine.videoExporter.export(Object.assign({}, baseVideoSettings, { format: 'gif', width: w, height: h }${gifLoop !== undefined ? `, { loop: ${JSON.stringify(gifLoop)} }` : ''}));
+              if (!again) break;
+              result = await deliver(again);
+              attempts.push({ width: w, height: h, bytes: result.size });
+            }
+            result.budget = { maxBytes: ${maxBytes}, met: !!(result.success && result.size <= ${maxBytes}), attempts: attempts };
+            if (result.success && result.size > ${maxBytes}) {
+              result.warning = 'still ' + result.size + ' bytes after shrinking to ' + w + 'x' + h + ' — over the ' + ${maxBytes} + '-byte budget. Lower fps, shorten duration, or use quality "draft".';
+            } else if (result.success) {
+              result.dimensions = { width: w, height: h };
+            }
+          }` : ''}
         } else if (app.exportEngine && app.exportEngine.videoExporter) {
           const blob = await app.exportEngine.videoExporter.export(baseVideoSettings);
           result = await deliver(blob);
@@ -3497,14 +4765,156 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
       }
 
       case 'pdf':
+        ${pdfOpts?.pages ? `// ONE PAGE PER SCENE (round 7 Z, 8.16). exportPDF renders the current
+        // canvas only, so a deck of 8 saved scenes exported 1 page. Built here
+        // the way exportPDF builds its one page — the engine's jsPDF, a frame
+        // from captureFrameDataURL, the scene's own size at the canvas DPI —
+        // one scene at a time, and the scene the user was on is put back.
+        {
+          const SM = app.sceneManager;
+          if (!SM || typeof SM.listScenes !== 'function' || typeof SM.loadScene !== 'function') {
+            result = { success: false, platform, format: 'pdf', error: 'scenes are unavailable on this studio (app.sceneManager) — a multi-page PDF needs saved scenes.' }; break;
+          }
+          if (!app.exportEngine || typeof app.exportEngine._loadPDFLibraries !== 'function' || typeof app.captureFrameDataURL !== 'function') {
+            result = { success: false, platform, format: 'pdf', error: 'this studio cannot build a multi-page PDF (no PDF library loader or frame capture) — update PinePaper Studio.' }; break;
+          }
+          const all = SM.listScenes();
+          const wanted = ${JSON.stringify(pdfOpts.pages)};
+          // A page is { id, size? }. Scenes do not record their canvas size —
+          // their "dimensions" is the browser viewport and loadScene does not
+          // resize the canvas — so without a size every page is the current
+          // canvas (the retest: three pages, all square).
+          const pageSpecs = wanted === 'scenes'
+            ? all.map(function(sc) { return { id: sc.id }; })
+            : wanted.map(function(w) { return typeof w === 'string' ? { id: w } : { id: w.sceneId, size: { width: w.width, height: w.height } }; });
+          const ids = pageSpecs.map(function(p) { return p.id; });
+          const sized = pageSpecs.some(function(p) { return p.size; });
+          const missing = ids.filter(function(id) { return !all.some(function(sc) { return sc.id === id; }); });
+          if (!ids.length || missing.length) {
+            result = { success: false, platform, format: 'pdf', error: ids.length ? 'no saved scene ' + missing.join(', ') + '. Saved: ' + all.map(function(sc) { return sc.id; }).join(', ') : 'there are no saved scenes — save each page with pinepaper_manage_scenes first.' }; break;
+          }
+          const back = SM.currentSceneId;
+          const backSize = app.canvasSize ? { width: app.canvasSize.width, height: app.canvasSize.height } : null;
+          const lib = await app.exportEngine._loadPDFLibraries();
+          const targetDpi = ${pdfOpts.dpi ?? 'settings.dpi'};
+          // JPEG pages: a PNG per page made a 3-slide deck 34 MB.
+          const toJpeg = function(url) {
+            return new Promise(function(resolve) {
+              const img = new Image();
+              img.onload = function() {
+                const c = document.createElement('canvas');
+                c.width = img.naturalWidth; c.height = img.naturalHeight;
+                const x = c.getContext('2d');
+                x.fillStyle = '#ffffff'; x.fillRect(0, 0, c.width, c.height);
+                x.drawImage(img, 0, 0);
+                resolve(c.toDataURL('image/jpeg', settings.compression));
+              };
+              img.onerror = function() { resolve(null); };
+              img.src = url;
+            });
+          };
+          let doc = null;
+          const pagesOut = [];
+          // A SEARCHABLE TEXT LAYER PER PAGE (8.10, FxTool 3e22c0df): the
+          // engine lays the loaded scene's text invisibly over the page box;
+          // the per-page reports are summed into result.pdf.
+          const __wantLayer = ${pdfOpts.searchableText !== false};
+          const __layer = __wantLayer && typeof app.exportEngine.addTextLayer === 'function';
+          const __tl = { written: 0, skipped: 0, reasons: [], fonts: null };
+          try {
+            for (const spec of pageSpecs) {
+              const id = spec.id;
+              await SM.loadScene(id);
+              if (spec.size && typeof app.setCanvasSize === 'function') app.setCanvasSize({ width: spec.size.width, height: spec.size.height });
+              const cs = app.canvasSize || { width: app.canvasEl.width, height: app.canvasEl.height };
+              const dpi = (typeof app.getDPI === 'function' && app.getDPI()) || 96;
+              const wMM = cs.width / dpi * 25.4, hMM = cs.height / dpi * 25.4;
+              const orient = wMM > hMM ? 'landscape' : 'portrait';
+              const png = app.captureFrameDataURL(Math.max(1, targetDpi / dpi));
+              const jpg = await toJpeg(png);
+              const __first = !doc;
+              if (!doc) doc = new lib.jsPDF({ orientation: orient, unit: 'mm', format: [wMM, hMM] });
+              else doc.addPage([wMM, hMM], orient);
+              // The scene's fonts (FxTool dbe8441d). Once per document on an
+              // engine whose repeat call re-registers over page 1's face; per
+              // page (this page's scene) where the engine caches faces on the
+              // document — it leaves doc.__ppFontCache after the first call
+              // (3b9499f2), which is the evidence, not a version guess.
+              if (__layer && typeof app.exportEngine.embedTextFonts === 'function' && (__first || doc.__ppFontCache)) {
+                try {
+                  const fr = await app.exportEngine.embedTextFonts(doc);
+                  if (!__tl.fonts) __tl.fonts = fr;
+                  else if (fr) {
+                    const seen = {};
+                    __tl.fonts.families = (__tl.fonts.families || []).concat(fr.families || []).filter(function(f) {
+                      const k = f && (f.family + '|' + f.weight + '|' + f.italic);
+                      if (!k || seen[k]) return false; seen[k] = true; return true;
+                    });
+                    if (typeof fr.embedded === 'number') __tl.fonts.embedded = fr.embedded; // cumulative for the document
+                    if (typeof fr.hiddenTextItems === 'number') __tl.fonts.hiddenTextItems = (__tl.fonts.hiddenTextItems || 0) + fr.hiddenTextItems;
+                  }
+                } catch (e) { if (!__tl.fonts) __tl.fonts = { embedded: 0, reason: e && e.message }; }
+              }
+              if (jpg) doc.addImage(jpg, 'JPEG', 0, 0, wMM, hMM); else doc.addImage(png, 'PNG', 0, 0, wMM, hMM);
+              if (__layer) {
+                try {
+                  const tr = await app.exportEngine.addTextLayer(doc, { x: 0, y: 0, width: wMM, height: hMM });
+                  if (tr && tr.ok !== false) { __tl.written += tr.linesWritten || 0; __tl.skipped += tr.linesSkipped || 0; }
+                  else __tl.reasons.push(id + ': ' + ((tr && tr.reason) || 'refused'));
+                } catch (e) { __tl.reasons.push(id + ': ' + e.message); }
+              }
+              pagesOut.push({ sceneId: id, widthMM: Math.round(wMM * 10) / 10, heightMM: Math.round(hMM * 10) / 10 });
+            }
+          } finally {
+            if (sized && backSize && typeof app.setCanvasSize === 'function') { try { app.setCanvasSize(backSize); } catch (_) { /* best effort */ } }
+            if (back && typeof SM.loadScene === 'function') { try { await SM.loadScene(back); } catch (_) { /* reported by the page count */ } }
+          }
+          const blob = doc.output('blob');
+          const dataUrl = await blobToDataUrl(blob);
+          result = { success: true, platform, format: 'pdf', data: dataUrl, mimeType: 'application/pdf', size: blob.size, pages: pagesOut.length, pageList: pagesOut,
+            pdf: !__wantLayer ? { searchableText: false, reason: 'off' }
+              : !__layer ? { searchableText: false, reason: 'this studio adds no text layer to multi-page PDFs' }
+              : Object.assign({ searchableText: __tl.written > 0 || __tl.reasons.length < pagesOut.length, linesWritten: __tl.written, linesSkipped: __tl.skipped },
+                  __tl.fonts ? { fonts: __tl.fonts } : {},
+                  __tl.reasons.length ? { pagesWithoutLayer: __tl.reasons } : {},
+                  __tl.written === 0 && __tl.reasons.length === pagesOut.length ? { reason: __tl.reasons.join('; ') } : {}) };
+          if (!sized) result.warning = 'every page used the current canvas size: saved scenes do not record theirs. To give a page its own size, pass pages as [{sceneId, width, height}, …].';
+        }
+        break;` : ''}
         if (app.exportEngine && app.exportEngine.exportPDF) {
-          const blob = await app.exportEngine.exportPDF({ dpi: settings.dpi });
-          const reader = new FileReader();
-          const dataUrl = await new Promise(resolve => {
-            reader.onloadend = () => resolve(reader.result);
-            reader.readAsDataURL(blob);
+          // Print options reach the engine (they were engine-only before), and
+          // download:false, because the tool delivers the bytes itself.
+          // lastPdfReport is a report PROPERTY (9917cfa5), read through the
+          // engine object like the exporter's audio / video reports, and only
+          // when present.
+          const __pee = app.exportEngine;
+          if ('lastPdfReport' in __pee) __pee.lastPdfReport = null;
+          const pdfOut = await app.exportEngine.exportPDF({
+            dpi: ${pdfOpts?.dpi ?? 'settings.dpi'},
+            download: false,${pdfOpts?.searchableText === false ? '\n            searchableText: false,' : ''}${pdfOpts?.paperFormat ? `\n            format: ${JSON.stringify(pdfOpts.paperFormat)},` : ''}${pdfOpts?.orientation ? `\n            orientation: ${JSON.stringify(pdfOpts.orientation)},` : ''}${pdfOpts?.bleed !== undefined ? `\n            includeBleed: ${pdfOpts.bleed > 0}, bleed: ${pdfOpts.bleed},` : ''}${pdfOpts?.trimMarks !== undefined ? `\n            trimMarks: ${pdfOpts.trimMarks},` : ''}
           });
-          result = { success: true, platform, format: 'pdf', data: dataUrl, mimeType: 'application/pdf', size: blob.size, dpi: settings.dpi };
+          const blob = asBlob(pdfOut);
+          if (!blob) {
+            const got = pdfOut === null ? 'null'
+              : typeof pdfOut === 'object' ? 'an object with keys [' + Object.keys(pdfOut).join(', ') + ']'
+                : typeof pdfOut;
+            result = { success: false, platform, format: 'pdf',
+              error: 'the PDF export did not produce a file: expected a Blob, got ' + got + '.' };
+            break;
+          }
+          const dataUrl = await blobToDataUrl(blob);
+          result = {
+            success: true, platform, format: 'pdf', data: dataUrl,
+            mimeType: 'application/pdf', size: blob.size, dpi: settings.dpi,
+            // The record carries the page geometry the engine chose; it is the
+            // only place a caller can learn it.
+            ...(pdfOut && pdfOut.width ? { dimensions: { width: pdfOut.width, height: pdfOut.height } } : {}),
+            ...(pdfOut && pdfOut.format ? { paperFormat: pdfOut.format } : {}),${pdfOpts?.paperFormat && pdfOpts.paperFormat !== 'custom' && ((pdfOpts.bleed ?? 0) > 0 || pdfOpts.trimMarks) ? `
+            // Bleed and trim marks on a NAMED paper size: the studio keeps the
+            // page at that size and centres the art, so neither appears (prod
+            // retest: MediaBox = TrimBox = A4, no marks). Said, not silent.
+            warnings: [${JSON.stringify(`bleed / trimMarks were passed with paperFormat '${pdfOpts.paperFormat}', and this studio applies them only to paperFormat 'custom' (page = canvas + bleed): the page stayed ${pdfOpts.paperFormat} with no bleed and no marks. For print with bleed, size the canvas with a PRINT preset (agent_start_job canvasPreset 'print-a4' / 'print-letter' / 'print-a4-landscape' / 'print-letter-landscape', which carry 300 dpi — a plain 2480x3508 canvas is read at 96 dpi and comes out ~656 mm wide) and pass paperFormat 'custom'.`)}],` : ''}
+          };
         } else {
           result = { success: false, error: 'PDF export failed' };
         }
@@ -3520,7 +4930,172 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
   // One site, after every branch has set its result: a successful export says
   // what this scene lost to this format, rather than the caller finding out by
   // opening the file. Only when there is something to say — see fidelity().
+  // RE-ENCODE A STILL FOR A BYTE BUDGET. The png path rendered it (whole board
+  // or region); the browser's own encoder makes jpg / webp at the tier's
+  // compression. jpg has no alpha, so it is flattened onto the scene background
+  // (white when there is none) rather than left to the encoder's black.
+  if (result && result.success && (format === 'jpg' || format === 'webp') && typeof result.data === 'string') {
+    const mime = format === 'jpg' ? 'image/jpeg' : 'image/webp';
+    try {
+      const encoded = await new Promise(function(resolve, reject) {
+        const img = new Image();
+        img.onload = function() {
+          const c = document.createElement('canvas');
+          c.width = img.naturalWidth; c.height = img.naturalHeight;
+          const x = c.getContext('2d');
+          // The scene's own background when one is set — white text on a
+          // transparent board vanished into a white flatten. White otherwise.
+          if (mime === 'image/jpeg') {
+            const bg = app.canvasEl && app.canvasEl.style && app.canvasEl.style.backgroundColor;
+            x.fillStyle = (bg && !/^(transparent|rgba\\([^)]*,\\s*0\\))$/i.test(bg)) ? bg : '#ffffff';
+            x.fillRect(0, 0, c.width, c.height);
+          }
+          x.drawImage(img, 0, 0);
+          resolve(c.toDataURL(mime, settings.compression));
+        };
+        img.onerror = function() { reject(new Error('the rendered frame could not be decoded for re-encoding')); };
+        img.src = result.data;
+      });
+      if (String(encoded).indexOf('data:' + mime) !== 0) {
+        result = { success: false, platform, format, error: 'this browser cannot encode ' + format + ' (it returned ' + String(encoded).slice(5, 20) + '…).' };
+      } else {
+        result = Object.assign({}, result, { format, data: encoded, mimeType: mime, size: Math.round(String(encoded).length * 0.75), encodeQuality: settings.compression });
+      }
+    } catch (e) {
+      result = { success: false, platform, format, error: (e && e.message) || String(e) };
+    }
+  }
+
   if (result && result.success) Object.assign(result, fidelity(format));
+  if (result && result.success && __fit) result.platformFit = __fit;
+  // AUDIO TIMING, WHERE THE STUDIO REPORTS IT (6.27). An MP4's AAC track used
+  // to start ~44 ms late and run past the picture — a 6.000 s bumper with sound
+  // then failed its cap. The engine now reports the track; it is surfaced as
+  // result.audio, and its warning (sound in the trimmed lead-in) and any audio
+  // longer than the picture go into fidelity.warnings, where a caller looks.
+  // WHAT THE ENCODER WAS GIVEN AND WHAT IT MADE (FxTool 16719759, 8.34-8.36).
+  // The browser's H.264 treats a bitrate as a ceiling, so an 8 Mbps broadcast
+  // request can come out at 1.8 — the engine measures it and warns. A request
+  // the report does not reflect (an engine without the options, or a route
+  // that rebuilt its settings without them) is named, not assumed.
+  // A PDF'S TEXT LAYER (8.10, FxTool 9917cfa5): invisible text at each line's
+  // drawn position, so the PDF is searchable and screen-readable. The built-in
+  // font is WinAnsi only, so Arabic / Hebrew / CJK lines are left out of the
+  // layer (drawn, but not selectable) — counted by the engine, said here.
+  const __ee = app.exportEngine;
+  const __pr = format === 'pdf' && ((result && result.pdf) || (__ee && __ee.lastPdfReport));
+  if (result && result.success && __pr && typeof __pr === 'object') {
+    result.pdf = __pr;
+    const __pw = [];
+    // Which scripts a PDF can carry depends on the studio: older ones have
+    // only the built-in Latin font, newer ones embed the scene's fonts. So the
+    // cause is the engine's report (fonts it could not embed), not a claim here.
+    const __ff = (__pr.fonts && Array.isArray(__pr.fonts.families)) ? __pr.fonts.families.filter(function(f) { return f && f.reason; }) : [];
+    const __fnames = __ff.slice(0, 4).map(function(f) { return f.family + ' (' + f.reason + ')'; }).join('; ');
+    if (__pr.searchableText && __pr.linesSkipped > 0) __pw.push({ code: 'pdf_text_lines_skipped', message: __pr.linesSkipped + ' text line(s) are not in the searchable layer — no font in the PDF covers their characters — so they are drawn but cannot be selected, searched or read by a screen reader.' + (__fnames ? ' Fonts that could not be embedded: ' + __fnames + '.' : '') });
+    // Text hidden at the render moment (a lifetime window, visible: false,
+    // opacity 0) is in neither the picture nor the layer (FxTool 3b9499f2).
+    const __hid = __pr.fonts && typeof __pr.fonts.hiddenTextItems === 'number' ? __pr.fonts.hiddenTextItems : 0;
+    if (__hid > 0) __pw.push({ code: 'pdf_text_hidden', message: __hid + ' text item(s) were hidden when the PDF was rendered (outside their bornAt / ttl window, visible: false, or opacity 0), so they are not in it. Export at a time they show (time), or change their lifetime.' });
+    if (__ff.length && !(__pr.linesSkipped > 0)) __pw.push({ code: 'pdf_font_not_embedded', message: 'these fonts could not be embedded, so their text uses a fallback font in the searchable layer: ' + __fnames + '.' });
+    if (__pr.searchableText && __pr.pagesWithoutLayer) __pw.push({ code: 'pdf_no_text_layer', message: 'some pages have no searchable text layer — ' + __pr.pagesWithoutLayer.join('; ') });
+    if (!__pr.searchableText && __pr.reason && __pr.reason !== 'off') __pw.push({ code: 'pdf_no_text_layer', message: 'no searchable text layer was written (' + __pr.reason + '): the text is drawn but cannot be selected, searched or read by a screen reader.' });
+    if (__pw.length) {
+      result.fidelity = result.fidelity || { warnings: [] };
+      result.fidelity.warnings = (result.fidelity.warnings || []).concat(__pw);
+      if (result.fidelity.note) delete result.fidelity.note;
+    }
+  }
+  const __vr = __vx && __vx.lastVideoReport;
+  if (result && result.success && __vr && typeof __vr === 'object') result.video = __vr;${webmAlpha ? `
+  // A TRANSPARENT WEBM is confirmed from the encoder's own record: an alpha
+  // stream with frames in it. A studio without WebM alpha writes an opaque
+  // file that looks like it worked.
+  if (result && result.success) {
+    const __al = __vr && __vr.alpha;
+    const __aw = [];
+    if (!(__al && __al.frames > 0)) __aw.push({ code: 'alpha_not_applied', message: 'transparent was asked for, but this studio wrote no alpha stream: the WebM is opaque (transparent areas black). Export apng, or a png sequence, for transparency here.' });
+    else if (__al.keyframeMismatches > 0) __aw.push({ code: 'alpha_keyframe_mismatch', message: __al.keyframeMismatches + ' frame(s) had colour and alpha keyframes out of step; some players may show those frames without transparency.' });
+    if (__aw.length) {
+      result.fidelity = result.fidelity || { warnings: [] };
+      result.fidelity.warnings = (result.fidelity.warnings || []).concat(__aw);
+      if (result.fidelity.note) delete result.fidelity.note;
+    }
+  }` : ''}${headroomDefaulted ? `
+  // 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.' };` : ''}
+  // 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.
+  const __vd = __vr && __vr.dimensions;
+  if (result && result.success && __vd && Array.isArray(__vd.requested) && Array.isArray(__vd.output)
+      && (__vd.requested[0] !== __vd.output[0] || __vd.requested[1] !== __vd.output[1])) {
+    result.dimensions = { width: __vd.output[0], height: __vd.output[1] };
+    result.fidelity = result.fidelity || { warnings: [] };
+    result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'dimensions_rounded',
+      message: 'the file is ' + __vd.output[0] + 'x' + __vd.output[1] + ', not the requested ' + __vd.requested[0] + 'x' + __vd.requested[1] + ': H.264 needs even dimensions, so an odd side was rounded up by 1 px (the extra row / column is background). For an exact-pixel spec, use an even canvas size, or crop the extra line when re-encoding (ffmpeg -vf crop=' + __vd.requested[0] + ':' + __vd.requested[1] + ':0:0).' }]);
+    if (result.fidelity.note) delete result.fidelity.note;
+  }
+  // LUMA OUTSIDE 16-235 (8.35, FxTool 4f1ec3ae). The broadcast encode is
+  // decoded back and measured: H.264 ringing at hard edges puts a fraction of
+  // a percent of samples out of range, which QC rejects. broadcastHeadroom
+  // cuts it but never to zero, so a legaliser pass is the requirement.
+  if (result && result.success && __vr && __vr.luma && __vr.luma.outOfRange > 0 && result.fidelity) {
+    result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'luma_out_of_range',
+      message: 'broadcast QC will reject this as delivered: ' + ((__vr.luma.outOfRangeFraction || 0) * 100).toFixed(3) + '% of decoded luma is outside 16-235 (min ' + __vr.luma.min + ', max ' + __vr.luma.max + ', broadcastHeadroom ' + (typeof __vr.headroom === 'number' ? __vr.headroom : ${JSON.stringify(broadcastHeadroom ?? 12)}) + '). First re-export with a larger broadcastHeadroom (12 measured clean on hard white-on-black edges; up to 40). Otherwise a legaliser pass is REQUIRED before delivery — clip into a NARROWER band and re-encode at high quality, because a plain 16-235 clip followed by a re-encode brings the edge overshoot back: ffmpeg -i in.mp4 -vf "lutyuv=y=clip(val\\\\,28\\\\,223):u=clip(val\\\\,16\\\\,240):v=clip(val\\\\,16\\\\,240)" -c:v libx264 -crf 18 -color_range tv -colorspace bt709 -color_primaries bt709 -color_trc bt709 -c:a copy out.mp4 (measured 20-229). Verify the luma range after re-encoding.' }]);
+    if (result.fidelity.note) delete result.fidelity.note;
+  }
+${Object.keys(videoEncodeOpts).length ? `  if (result && result.success) {
+    const __asked = ${JSON.stringify(videoEncodeOpts)};
+    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) {
+      __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') {
+      __vw.push({ code: 'encode_options_not_applied', message: 'this studio did not report its encode, so ' + Object.keys(__asked).join(', ') + ' cannot be confirmed — it likely has no broadcast / bitrate support, and the file is an ordinary web encode.' });
+    } else {
+      if (__asked.broadcast && __vr.broadcast !== true) __vw.push({ code: 'broadcast_not_applied', message: 'broadcast was asked for but the encode was not broadcast-safe (the export route dropped the option): full-range, untagged colour.' });
+      if (__asked.bitrate !== undefined && typeof __vr.bitrate === 'number' && __vr.bitrate < __asked.bitrate * 0.99) __vw.push({ code: 'bitrate_not_applied', message: 'bitrate ' + __asked.bitrate + ' was asked for; the encoder was given ' + __vr.bitrate + '.' });
+    }
+    if (__vw.length && result.fidelity) {
+      result.fidelity.warnings = (result.fidelity.warnings || []).concat(__vw);
+      if (result.fidelity.note) delete result.fidelity.note;
+    }
+  }
+` : ''}  const __ar = __vx && __vx.lastAudioReport;
+  if (result && result.success && __ar && typeof __ar === 'object') {
+    result.audio = __ar;
+    const __aw = [];
+    if (__ar.warning) __aw.push({ code: 'audio_lead_trimmed', message: String(__ar.warning) });
+    if (typeof __ar.audioDurationS === 'number' && typeof __ar.videoDurationS === 'number' && __ar.audioDurationS > __ar.videoDurationS + 0.0105) {
+      __aw.push({ code: 'audio_longer_than_video', message: 'the audio track is ' + __ar.audioDurationS.toFixed(4) + ' s against ' + __ar.videoDurationS.toFixed(4) + ' s of picture — a platform with a hard length cap may read the longer one.' });
+    }
+    if (__aw.length && result.fidelity) {
+      result.fidelity.warnings = (result.fidelity.warnings || []).concat(__aw);
+      if (result.fidelity.note) delete result.fidelity.note;
+    }
+  }
+${(() => {
+            // A DURATION THAT OVERRUNS AT AN NTSC RATE (round 9 FF, 1.76): 6 s at
+            // 29.97 is round(6 x 30000/1001) = 180 frames = 6.006 s, over a 6.000 s
+            // bumper cap, silently. Said, with the longest duration that fits.
+            if (fps === undefined || Number.isInteger(fps))
+                return '';
+            const frames = Math.round(videoDuration * fps);
+            const actual = frames / fps;
+            if (actual <= videoDuration + 1e-9)
+                return '';
+            const fit = Math.floor(videoDuration * fps) / fps;
+            return `  if (result && result.success && ['mp4', 'webm', 'gif', 'apng'].indexOf(format) !== -1) result.timing = ${JSON.stringify({
+                frames, seconds: Math.round(actual * 1e6) / 1e6, requested: videoDuration,
+                warning: `${frames} frames at ${Math.round(fps * 1000) / 1000} fps is ${actual.toFixed(3)} s — ${((actual - videoDuration) * 1000).toFixed(1)} ms over the ${videoDuration} s asked for. For a hard cap (e.g. a 6 s bumper) use duration ${fit.toFixed(4)} (${Math.floor(videoDuration * fps)} frames).`,
+            })};\n`;
+        })()}
+${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) { /* the still is already rendered */ }
+  if (result && result.success) result.time = ${stillTime};` : ''}
 
   return result;
 })();
@@ -5256,7 +6831,7 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
 `.trim();
     }
     generateImportImage(input) {
-        const { url, position, maxWidth, maxHeight, mask } = input;
+        const { url, position, maxWidth, maxHeight, mask, smoothing } = 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
@@ -5325,7 +6900,10 @@ ${usesCanvasSize ? `  // 'auto': the canvas's own size, with the preset only as
     const entry = await app.imageTools.uploadFromURL(src);
     const opts = ${optsLiteral};
     const raster = await app.imageTools.placeImage(entry.id, Object.keys(opts).length > 0 ? opts : undefined);
-${mask ? `    app.imageTools.applyMask(raster, '${mask}');\n` : ''}    // The REGISTRY id is \`data.id\`. \`data.itemId\` has never existed, so this
+${smoothing ? `    // Pixel art wants 'off': Paper's Raster draws with smoothing 'low' by
+    // default, which blurs every scaled-up pixel edge. Read at every draw,
+    // export frames included. Set before a mask, which clones the raster.
+    if (raster && 'smoothing' in raster) raster.smoothing = ${JSON.stringify(smoothing)};\n` : ''}    // The REGISTRY id is \`data.id\`. \`data.itemId\` has never existed, so this
     // fell through to \`raster.id\` — a Paper.js NUMBER — and the handle the tool
     // returned could not be used as a relation endpoint or with modify/animate.
     // Register the raster if placeImage somehow left it unregistered, so the
@@ -5337,11 +6915,28 @@ ${mask ? `    app.imageTools.applyMask(raster, '${mask}');\n` : ''}    // The RE
     if (!itemId) {
       return { error: 'Image placed but not registered — no usable item id. This is a bug; report the scene.' };
     }
+    let placed = raster;
+${mask ? `    // A MASK REPLACES THE RASTER (round 8 DD, 4.10). applyMask builds a
+    // clipping group from a CLONE and removes the original, so the id and bounds
+    // read off \`raster\` afterwards described an item no longer on the canvas.
+    // The group is what is drawn: the registry id is rebound to it (the
+    // registry's own method for exactly this), and a mask that did not apply is
+    // refused instead of answered with the raster's bounds.
+    const masked = app.imageTools.applyMask(raster, ${JSON.stringify(mask)});
+    if (!masked) {
+      return { success: false, itemId: itemId, error: 'the ${mask} mask was not applied — the image may not be a raster yet. The unmasked image is on the canvas as ' + itemId + '.' };
+    }
+    if (app.itemRegistry && typeof app.itemRegistry.rebind === 'function') app.itemRegistry.rebind(itemId, masked);
+    placed = masked;
+` : ''}    const b = placed.bounds;
+    if (!b || !(b.width > 0) || !(b.height > 0)) {
+      return { success: false, itemId: itemId, error: 'the image was placed with no size (' + (b ? b.width + 'x' + b.height : 'no bounds') + ') — it may not have loaded. Nothing visible was drawn.' };
+    }
     return {
       success: true,
       itemId: itemId,
       message: 'Image imported and placed on canvas.',
-      bounds: { x: raster.bounds.x, y: raster.bounds.y, width: raster.bounds.width, height: raster.bounds.height }${mask ? `,\n      mask: '${mask}'` : ''}
+      bounds: { x: b.x, y: b.y, width: b.width, height: b.height }${mask ? `,\n      mask: '${mask}'` : ''}
     };
   } catch (e) {
     return { error: 'Failed to import image: ' + e.message };
@@ -5721,9 +7316,27 @@ ${mask ? `    app.imageTools.applyMask(raster, '${mask}');\n` : ''}    // The RE
     return { success: false, error: 'apply needs itemIds, in the order the stagger should follow (row-major for a grid)' };
   }
   const r = app.staggerItems(ids, ${S(validated.opts || {})});
+  // KEYFRAME TRACKS DO NOT READ animationDelay (round 7 X, 2.2). staggerItems
+  // writes the delay to data.animationDelay, which the loop presets honour;
+  // a tile that already had a keyframe fly-in ignored it, and all 64 tiles of
+  // a shatter mosaic arrived on the same frames. A keyframed item's clock is
+  // its clip offset, data.timeOffset, so the delay goes there too — on top of
+  // the offset it had before the first stagger (remembered), so re-staggering
+  // replaces rather than stacks.
+  let shiftedTracks = 0;
+  if (r && r.ok && Array.isArray(r.delays)) {
+    const items = ids.map(function(id) { const e = app.itemRegistry && app.itemRegistry.get(id); return e && e.item; }).filter(Boolean);
+    items.forEach(function(item, i) {
+      if (!item.data || !Array.isArray(item.data.keyframes) || !item.data.keyframes.length) return;
+      if (item.data._staggerBaseOffset === undefined) item.data._staggerBaseOffset = Number(item.data.timeOffset) || 0;
+      item.data.timeOffset = item.data._staggerBaseOffset + (Number(r.delays[i]) || 0);
+      shiftedTracks++;
+    });
+  }
   return {
     success: r && r.ok === true,
     action: 'apply',
+    shiftedKeyframeTracks: shiftedTracks,
     // 'applied' can be lower than the ids given — an id that resolves to
     // nothing is skipped, and a stagger that silently covered fewer items than
     // asked for is the failure worth seeing.
@@ -5890,7 +7503,25 @@ ${mask ? `    app.imageTools.applyMask(raster, '${mask}');\n` : ''}    // The RE
     generateBrandKit(input) {
         const opts = JSON.stringify({ ...(input.selectionOnly ? { selectionOnly: true } : {}) });
         const method = input.action === 'plan' ? 'planBrandKit' : 'applyBrandKit';
-        return this._facadeCall(method, `${JSON.stringify(input.kit)}, ${opts}`, `Brand kit: ${input.action}`);
+        const facade = this._facadeCall(method, `${JSON.stringify(input.kit)}, ${opts}`, `Brand kit: ${input.action}`);
+        // A KIT'S FONTS ARE LOADED BEFORE IT RESTYLES TEXT — the same fallback as
+        // create_item (see emitEnsureFont): the kit named Anton, the headings were
+        // re-measured in Times. Each family is checked, loaded if missing, and the
+        // outcome for any that needed it rides on the facade's own result.
+        const fonts = input.kit.fonts;
+        const families = [...new Set(Object.values(fonts ?? {}).filter((f) => typeof f === 'string' && f.trim() !== ''))];
+        if (input.action !== 'apply' || families.length === 0)
+            return facade;
+        const loads = families.map((f) => `  r = await (async function() {${emitEnsureFont(f).replace(/\n/g, '\n  ')}\n    return __font;\n  })();\n  if (r) __fonts.push(r);`).join('\n');
+        return `
+// Brand kit: load the kit's fonts, then apply
+(async function() {
+  const __fonts = [];
+  let r;
+${loads}
+  const out = await ${facade.replace(/^\/\/[^\n]*\n/, '').replace(/;\s*$/, '')};
+  return __fonts.length && out && typeof out === 'object' ? { ...out, fonts: __fonts } : out;
+})();`.trim();
     }
     generateComponent(input) {
         const ids = JSON.stringify(input.itemIds || []);
@@ -5909,13 +7540,55 @@ ${mask ? `    app.imageTools.applyMask(raster, '${mask}');\n` : ''}    // The RE
   const r = app.defineComponent(items, ${JSON.stringify({ name: input.name })});
   return { success: r.ok !== false, ...r };
 })();`.trim();
+            // A COMPONENT'S PARTS, BY THE KEY AN OVERRIDE NEEDS (round 9 II, 1.80).
+            // Overrides are {componentKey: {prop: value}}, and the keys are generated
+            // names (ck_12) — list gave only a count and instantiate returned a raw
+            // Paper item with no id, so the component route to batch creative was
+            // unusable. Both now return parts: each key with its part's type, name and
+            // text, which is how a caller finds the headline's key.
             case 'list':
-                return this._facadeCall('listComponents', '', 'Component: list');
+                return `
+// Component: list, with each definition's parts
+(function() {
+  if (typeof app.listComponents !== 'function') return { success: false, error: 'app.listComponents() unavailable — update PinePaper Studio.' };
+  const partsOf = function(root) {
+    const out = [];
+    const walk = function(n) { if (!n) return; if (n.data && n.data.componentKey) out.push(Object.assign({ key: n.data.componentKey, type: n.className }, typeof n.content === 'string' ? { content: n.content } : {}, n.name ? { name: n.name } : {})); (n.children || []).forEach(walk); };
+    (root && root.children || []).forEach(walk);
+    return out;
+  };
+  const defs = app._components;
+  const components = app.listComponents().map(function(c) {
+    let parts = null;
+    try {
+      const d = defs && typeof defs.get === 'function' ? defs.get(c.id) : null;
+      if (d && d.json && typeof paper !== 'undefined') {
+        const g = new paper.Group({ insert: false });
+        g.importJSON(d.json);
+        parts = partsOf(g.children.length === 1 && g.children[0].children ? g.children[0] : g);
+        g.remove();
+      }
+    } catch (_) { /* parts unknown on this build */ }
+    return Object.assign({}, c, parts ? { parts: parts } : {});
+  });
+  return { success: true, components: components, count: components.length };
+})();`.trim();
             case 'instantiate':
-                return this._facadeCall('instantiateComponent', `${JSON.stringify(input.componentId || '')}, ${JSON.stringify({
+                return `
+// Component: instantiate — the instance id, and the keys its overrides use
+(function() {
+  if (typeof app.instantiateComponent !== 'function') return { success: false, error: 'app.instantiateComponent() unavailable — update PinePaper Studio.' };
+  const r = app.instantiateComponent(${JSON.stringify(input.componentId || '')}, ${JSON.stringify({
                     ...(input.position ? { position: input.position } : {}),
                     ...(input.overrides ? { overrides: input.overrides } : {}),
-                })}`, 'Component: instantiate');
+                })});
+  if (!r || r.ok === false) return { success: false, error: (r && r.error) || 'the component was not placed' };
+  const parts = [];
+  const walk = function(n) { if (!n) return; if (n.data && n.data.componentKey) parts.push(Object.assign({ key: n.data.componentKey, type: n.className }, typeof n.content === 'string' ? { content: n.content } : {}, n.name ? { name: n.name } : {})); (n.children || []).forEach(walk); };
+  walk(r.item);
+  return { success: true, instanceId: r.id, itemId: r.id, parts: parts, orphaned: r.orphaned || [],
+    ...(r.orphaned && r.orphaned.length ? { warning: 'overrides for ' + r.orphaned.map(function(o) { return o.key; }).join(', ') + ' matched no part of this component and were not applied. parts lists the keys it has.' } : {}) };
+})();`.trim();
             case 'set_override':
                 return this._facadeCall('setComponentOverride', `${JSON.stringify(input.instanceId || '')}, ${JSON.stringify(input.componentKey || '')}, ${JSON.stringify(input.prop || '')}, ${JSON.stringify(input.value ?? null)}`, 'Component: set override');
             case 'sync':
@@ -6018,14 +7691,48 @@ ${mask ? `    app.imageTools.applyMask(raster, '${mask}');\n` : ''}    // The RE
         }
     }
     generateAudioBeats(input) {
+        // UPLOADED MEDIA IS THE AUDIO A CALLER HAS, AND IT WAS NOT A SOURCE.
+        //
+        // analyzeAudio treats a bare id as a storage asset and wants its data as a
+        // string, so the id or registryId that upload_audio returned gave "could not
+        // decode audio" — while the detector itself is accurate (3.4 ms mean error,
+        // measured). An uploaded clip's player already holds its bytes at a blob:
+        // URL, which analyzeAudio does accept; either id resolves to that here.
+        // Anything else (asset id, data:, URL) passes through untouched.
+        // @engine-methods analyzeAudio animateToBeat
+        const resolveSource = `  let __src = ${JSON.stringify(input.source || '')};
+  const __A = (typeof window !== 'undefined') && window.PinePaperAgent;
+  const __m = (__src && __A && typeof __A.listMedia === 'function')
+    ? __A.listMedia().find(function(x) { return x.id === __src || x.registryId === __src; })
+    : null;
+  if (__m) {
+    const layer = __m.kind === 'video' ? app.videoLayer && app.videoLayer.videos : app.audioLayer && app.audioLayer.audios;
+    const raster = layer && typeof layer.get === 'function' ? layer.get(__m.id) : null;
+    if (!raster || !raster.url) {
+      return { success: false, error: 'uploaded media ' + JSON.stringify(__src) + ' has no playable source to analyse in this studio.' };
+    }
+    __src = raster.url;
+  }`;
+        const call = (method, args, label) => `
+// ${label}
+(async function() {
+  if (typeof app.${method} !== 'function') {
+    return { success: false, error: 'app.${method}() unavailable — update PinePaper Studio to a build that has it.' };
+  }
+${resolveSource}
+  const r = await app.${method}(${args});
+  if (r && typeof r === 'object' && 'ok' in r) {
+    return { success: r.ok !== false, ...r };
+  }
+  return { success: true, result: r };
+})();`.trim();
         if (input.action === 'analyze') {
-            return this._facadeCall('analyzeAudio', `${JSON.stringify(input.source || '')}, ${JSON.stringify({
+            return call('analyzeAudio', `__src, ${JSON.stringify({
                 ...(input.sensitivity !== undefined ? { sensitivity: input.sensitivity } : {}),
                 ...(input.minGap !== undefined ? { minGap: input.minGap } : {}),
             })}`, 'Audio: analyze beats');
         }
-        return this._facadeCall('animateToBeat', `${JSON.stringify(input.itemId || '')}, ${JSON.stringify({
-            ...(input.source ? { source: input.source } : {}),
+        const opts = JSON.stringify({
             ...(input.beats ? { beats: input.beats } : {}),
             ...(input.grid ? { grid: true } : {}),
             ...(input.property ? { property: input.property } : {}),
@@ -6033,19 +7740,111 @@ ${mask ? `    app.imageTools.applyMask(raster, '${mask}');\n` : ''}    // The RE
             ...(input.accent !== undefined ? { accent: input.accent } : {}),
             ...(input.decay !== undefined ? { decay: input.decay } : {}),
             ...(input.sensitivity !== undefined ? { sensitivity: input.sensitivity } : {}),
-        })}`, 'Audio: animate to beat');
+        });
+        return call('animateToBeat', `${JSON.stringify(input.itemId || '')}, Object.assign(${opts}, __src ? { source: __src } : {})`, 'Audio: animate to beat');
     }
     generateTemplateParams(input) {
         if (input.action === 'get') {
             return this._facadeCall('getTemplateParams', JSON.stringify(input.templateId), 'Template params: get');
         }
-        return this._facadeCall('applyTemplateWithParams', `${JSON.stringify(input.templateId)}, ${JSON.stringify(input.params || {})}`, 'Template params: apply');
+        // AN UNDECLARED PARAM CHANGED NOTHING, AND THE CALL SAID SUCCESS.
+        // apply {templateId:'sale-announcement', params:{headline, date}} loaded
+        // the template, left its text untouched, and answered success:true — and 0
+        // of 195 templates declare any params (round 7 Z, 1.52). The template's own
+        // declaration is read first and anything outside it is named in the result;
+        // the template still loads, because the caller did ask for it.
+        // @engine-methods getTemplateParams applyTemplateWithParams
+        const params = input.params || {};
+        return `
+// Template params: apply, naming params the template does not declare
+(async function() {
+  if (typeof app.applyTemplateWithParams !== 'function') {
+    return { success: false, error: 'app.applyTemplateWithParams() unavailable — update PinePaper Studio to a build that has it.' };
+  }
+  const given = ${JSON.stringify(Object.keys(params))};
+  let declared = null;
+  if (typeof app.getTemplateParams === 'function') {
+    try {
+      const d = await app.getTemplateParams(${JSON.stringify(input.templateId)});
+      if (d && Array.isArray(d.params)) declared = d.params.map(function(p) { return p && (p.name || p.key || p.id); }).filter(Boolean);
+    } catch (_) { /* reported as unknown below */ }
+  }
+  const r = await app.applyTemplateWithParams(${JSON.stringify(input.templateId)}, ${JSON.stringify(params)});
+  const out = (r && typeof r === 'object' && 'ok' in r) ? Object.assign({ success: r.ok !== false }, r)
+    : { success: r !== false, templateId: ${JSON.stringify(input.templateId)} };
+  if (given.length && declared) {
+    const ignored = given.filter(function(k) { return declared.indexOf(k) === -1; });
+    if (ignored.length) {
+      out.ignoredParams = ignored;
+      out.declaredParams = declared;
+      out.warning = declared.length === 0
+        ? 'this template declares no parameters, so ' + ignored.join(', ') + ' changed nothing — the template loaded as designed. Edit its text items with pinepaper_modify_item instead.'
+        : ignored.join(', ') + ' ' + (ignored.length > 1 ? 'are' : 'is') + ' not declared by this template and changed nothing. It declares: ' + declared.join(', ') + '.';
+    }
+  } else if (given.length && !declared) {
+    out.warning = 'could not read which parameters this template declares, so whether ' + given.join(', ') + ' applied is unverified.';
+  }
+  return out;
+})();`.trim();
     }
     generateSceneDiff(input) {
         if (input.action === 'version') {
             return this._facadeCall('diffAgainstVersion', JSON.stringify(input.versionId || ''), 'Scene diff: vs version');
         }
-        return this._facadeCall('diffHistoryStates', `${input.indexA ?? 0}, ${input.indexB ?? 0}`, 'Scene diff: history');
+        // "NO CHANGES" AND "THE SNAPSHOTS DO NOT REFLECT THE CANVAS" ARE DIFFERENT
+        // ANSWERS.
+        //
+        // A pilot added six items and six tracks and was told nothing had changed,
+        // with unchanged:0 — the tell, since a real "no changes" compares items and
+        // finds them equal, so it can never report zero of everything.
+        //
+        // I FIRST DIAGNOSED THIS WRONG, and the wrong cause was in this file's
+        // emitted error for one commit. I read that HistoryManager stores entries
+        // as JSON strings and concluded diffScenes never parsed them. It does:
+        // SceneDiff's asObject() JSON.parses a string at the extraction entry, and
+        // fxtool-f2 verified it two ways — a stringified Paper tree diffs correctly,
+        // and a live browser run on string-stored history returned real added ids.
+        //
+        // The actual cause was GeneratedCodeRunner writing its single history entry
+        // only when items were CREATED, so a run that merely applied an effect, a
+        // style or a keyframe track wrote none. The two entries in those histories
+        // were both empty scenes, and two empty snapshots honestly diffed ARE "no
+        // changes". Fixed in FxTool c95c1d72.
+        //
+        // The backstop stays, for a reason that outlives that fix: a snapshot pair
+        // that does not reflect the canvas must never present as an affirmative
+        // nothing-changed. HistoryManager's own _itemIdsOf states the rule —
+        // "null means could not tell, never empty" — and this is the same rule at
+        // the tool boundary. It no longer guesses WHY, because guessing why is
+        // exactly what went wrong.
+        return `
+// Scene diff: what changed between two history states
+(function() {
+  if (typeof app.diffHistoryStates !== 'function') {
+    return { success: false, error: 'app.diffHistoryStates unavailable — update PinePaper Studio.' };
+  }
+  const d = app.diffHistoryStates(${input.indexA ?? 0}, ${input.indexB ?? 0});
+  if (!d || d.ok === false) {
+    return { success: false, error: (d && (d.error || d.reason)) || 'the diff refused without saying why' };
+  }
+  const saw = (d.added || []).length + (d.removed || []).length + (d.changed || []).length + (d.unchanged || 0);
+  const live = (app.itemRegistry && typeof app.itemRegistry.getAll === 'function')
+    ? (app.itemRegistry.getAll() || []).length
+    : 0;
+  if (saw === 0 && live > 0) {
+    return {
+      success: false,
+      error: 'the diff read NO items from either history state while the canvas holds ' + live
+        + ' — so those snapshots do not reflect this canvas, which is not the same as "nothing changed". '
+        + 'The usual cause is that no history entry was written for the changes you made: some studio builds '
+        + 'snapshot only when items are CREATED, so applying an effect, a style or a keyframe track records nothing. '
+        + 'Compare with pinepaper_get_items before and after instead, or use action "version".',
+      liveItems: live,
+      raw: d,
+    };
+  }
+  return { success: true, ...d };
+})();`.trim();
     }
     generateTransform(input) {
         switch (input.action) {
@@ -6167,6 +7966,28 @@ ${mask ? `    app.imageTools.applyMask(raster, '${mask}');\n` : ''}    // The RE
     // IMAGE PROCESSING
     // ===========================================================================
     generateImageFilter(input) {
+        // BLUR TAKES `radius`, AND THIS TOOL'S OWN EXAMPLE SAID `amount`.
+        //
+        // FilterSystem's blur reads params.radius and does Math.floor(undefined) =
+        // NaN, which passes its own `radius <= 0` guard and then blurs by nothing.
+        // So {amount: 18} was accepted, ran, and changed no pixels — while the
+        // schema example told callers to write exactly that. The example is fixed;
+        // the alias stays because the wrong spelling was documented and anyone who
+        // followed it should not have to discover the difference twice.
+        //
+        // BLUR ONLY. grain, bloom, chromaticAberration, displace, datamosh and
+        // paletteMap all read a real `amount`; renaming it for them would turn a
+        // working call into the same silent no-op this alias exists to prevent.
+        const blurAlias = (name, params) => {
+            const out = { ...(params ?? {}) };
+            if (name === 'blur' && out.amount !== undefined && out.radius === undefined) {
+                out.radius = out.amount;
+                delete out.amount;
+            }
+            return out;
+        };
+        const filterParams = blurAlias(input.filterName, input.params);
+        const chainFilters = (input.filters || []).map((f) => ({ ...f, params: blurAlias(f.name, f.params) }));
         // Resolve the raster from the registry id (unwrapping groups when the
         // build has the _resolveRaster helper), then use the real GPU-filter
         // facades. The previous emitter called app.imageTools.applyFilter, a
@@ -6183,7 +8004,13 @@ ${mask ? `    app.imageTools.applyMask(raster, '${mask}');\n` : ''}    // The RE
 (async function() {
 ${resolve}
   try {
-    await app.applyImageFilter(item, ${JSON.stringify(input.filterName || '')}, ${JSON.stringify(input.params || {})});
+    const r = await app.applyImageFilter(item, ${JSON.stringify(input.filterName || '')}, ${JSON.stringify(filterParams)});
+    // applyImageFilter THROWS for a missing raster and answers the item
+    // otherwise; a falsy answer is a refusal it did not raise.
+    if (r === false || r === null) {
+      return { success: false, action: 'apply', itemId: ${JSON.stringify(input.itemId)},
+        error: 'the filter did not apply — ${input.filterName || ''} may not be available on this studio.' };
+    }
     return { success: true, action: 'apply', itemId: ${JSON.stringify(input.itemId)}, filter: ${JSON.stringify(input.filterName || '')} };
   } catch (e) {
     return { error: 'Failed to apply filter: ' + e.message };
@@ -6195,7 +8022,7 @@ ${resolve}
 (async function() {
 ${resolve}
   try {
-    const filters = ${JSON.stringify(input.filters || [])};
+    const filters = ${JSON.stringify(chainFilters)};
     await app.applyImageFilterChain(item, filters);
     return { success: true, action: 'chain', itemId: ${JSON.stringify(input.itemId)}, filterCount: filters.length };
   } catch (e) {
@@ -6243,11 +8070,84 @@ ${resolve}
         // a caller in a mode it cannot get out of or complete.
         //
         // Refused by name, with the tools that do the same job without a pointer.
-        const why = 'the lasso is an interactive mouse tool (app.lassoTool: activate, then startStroke/continueStroke/endStroke as the user draws). '
-            + 'There is no headless call that completes an extraction, so this tool could never work over MCP. '
+        const why = 'activate / apply drive the interactive, mouse-based lasso. Use action "cut" with itemId and points (a polygon in canvas coordinates) — it drives the same lasso headlessly. '
             + 'To cut a region without a pointer, use pinepaper_extract_object (detects and extracts by description), '
             + 'or pinepaper_cutout_style / the mask actions on pinepaper_image_tools to shape an existing raster.';
         switch (input.action) {
+            case 'cut': {
+                // A POLYGON CUT, DRIVEN THROUGH THE LASSO'S OWN CLICK PATH (round 7 X,
+                // 1.55). The interactive tool has no headless form, but its polygon
+                // mode is click-by-click: startStroke/endStroke at a point adds a vertex,
+                // and a click within 12 px of the first vertex closes the shape. That is
+                // public API, so this drives it exactly as a user would, then applies.
+                //
+                // applyLasso DELETES the image it cut from ("chosen behaviour" in the
+                // editor). Over MCP that removed the photo a parallax needs underneath,
+                // silently. keepOriginal (default) cuts from a temporary clone, which is
+                // what gets consumed; the result says which happened.
+                const pts = (input.points ?? []).map((p) => (Array.isArray(p) ? { x: p[0], y: p[1] } : p));
+                if (!input.itemId)
+                    return `({ success: false, action: 'cut', error: 'cut needs itemId — the image to cut from.' });`;
+                if (pts.length < 3)
+                    return `({ success: false, action: 'cut', error: 'cut needs at least 3 points (canvas coordinates) around the region.' });`;
+                const keep = input.keepOriginal !== false;
+                return `
+// Lasso cut along a polygon
+(async function() {
+  const L = app.lassoTool;
+  if (!L || typeof L.activate !== 'function' || typeof L.applyLasso !== 'function') {
+    return { success: false, action: 'cut', error: 'app.lassoTool unavailable — update PinePaper Studio.' };
+  }
+  const entry = app.itemRegistry && app.itemRegistry.get(${JSON.stringify(input.itemId)});
+  const original = entry && entry.item;
+  if (!original) return { success: false, action: 'cut', error: 'no item ' + ${JSON.stringify(input.itemId)} };
+  const target = ${keep} ? original.clone() : original;
+  // A clone carries a COPY of data — including the registry id — and
+  // applyLasso deletes by that id, which would take the original anyway.
+  if (${keep} && target.data) {
+    target.data = Object.assign({}, target.data);
+    delete target.data.registryId; delete target.data.id;
+  }
+  const pts = ${JSON.stringify(pts)}.map(function(p) { return new paper.Point(p.x, p.y); });
+  const first = pts[0];
+  let skipped = 0;
+  L.activate(target);
+  // POLYGON MODE, SET — not assumed. On production the lasso's remembered mode
+  // was 'freehand', where a click adds no vertex, so every cut was refused as
+  // "did not close". The user's own mode is put back afterwards.
+  const __prevMode = L._forcedMode;
+  if (typeof L.setMode === 'function') L.setMode('polygon');
+  try {
+    L.startStroke(first); L.endStroke(first);
+    for (let i = 1; i < pts.length; i++) {
+      if (pts[i].getDistance(first) < 12) { skipped++; continue; }
+      L.startStroke(pts[i]); L.endStroke(pts[i]);
+    }
+    L.startStroke(first); L.endStroke(first); // a click at the first vertex closes it
+    if (!L.isDrawn()) {
+      L.cancel();
+      if (${keep}) target.remove();
+      return { success: false, action: 'cut', error: 'the polygon did not close — it needs at least 3 vertices at least 12 px from the first one.', skipped: skipped };
+    }
+    const cutout = await L.applyLasso();
+    if (!cutout) {
+      if (${keep} && target.parent) target.remove();
+      return { success: false, action: 'cut', error: 'the lasso produced no cutout — the item may not be an image.' };
+    }
+    let cutoutId = cutout.data && (cutout.data.registryId || cutout.data.id);
+    if (!cutoutId && typeof app.registerItem === 'function') cutoutId = app.registerItem(cutout, 'image', { source: 'mcp-lasso' });
+    return { success: true, action: 'cut', cutoutId: cutoutId, originalId: ${JSON.stringify(input.itemId)},
+      originalKept: ${keep}, vertices: pts.length - skipped, skipped: skipped,
+      bounds: { x: cutout.bounds.x, y: cutout.bounds.y, width: cutout.bounds.width, height: cutout.bounds.height } };
+  } catch (e) {
+    try { L.cancel(); } catch (_) { /* already down */ }
+    if (${keep} && target && target.parent) target.remove();
+    return { success: false, action: 'cut', error: (e && e.message) || String(e) };
+  } finally {
+    if (typeof L.setMode === 'function' && __prevMode) { try { L.setMode(__prevMode); } catch (_) { /* cosmetic */ } }
+  }
+})();`.trim();
+            }
             case 'activate':
             case 'apply':
                 return `
@@ -6914,7 +8814,28 @@ if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
 (async function() {
   if (!app.exportEngine || !app.exportEngine.exportWidget) return { error: 'Widget export not available' };
   const result = await app.exportEngine.exportWidget(${JSON.stringify(opts)});
-  return { success: true, json: result.json, filename: result.filename, embedCode: result.embedCode, metadata: result.data?.metadata };
+  // THE EMBED BOX WAS ALWAYS 16:9, AND IT IS NOT SELF-CONTAINED (round 9 GG,
+  // 8.32). The engine writes aspect-ratio: 16/9 and max-width: 800px whatever
+  // the scene, so a 300x250 ad sat letterboxed in a wide box. The box is sized
+  // from the canvas here. The embed also loads PineWidget.js from
+  // pinepaper.studio and fetches the scene JSON at runtime — said, with the
+  // zero-dependency alternative.
+  const cs = (typeof app.getCanvasSize === 'function' && app.getCanvasSize()) || app.canvasSize || null;
+  let embedCode = String(result.embedCode || '');
+  if (cs && cs.width > 0 && cs.height > 0) {
+    // RegExp from strings with no backslashes — a template literal eats them.
+    embedCode = embedCode
+      .replace(new RegExp('aspect-ratio:[ ]*[0-9.]+[ ]*/[ ]*[0-9.]+'), 'aspect-ratio: ' + cs.width + '/' + cs.height)
+      .replace(new RegExp('max-width:[ ]*[0-9.]+px'), 'max-width: ' + cs.width + 'px');
+  }
+  const deps = [];
+  const scriptSrc = /<script[^>]+src="([^"]+)"/.exec(embedCode);
+  if (scriptSrc) deps.push({ kind: 'script', url: scriptSrc[1] });
+  if (result.filename) deps.push({ kind: 'scene-json', url: result.filename, note: 'fetched at runtime — host it beside the page' });
+  return { success: true, json: result.json, filename: result.filename, embedCode: embedCode, metadata: result.data?.metadata,
+    size: cs ? { width: cs.width, height: cs.height } : null,
+    dependencies: deps,
+    note: 'this embed needs the files in dependencies at runtime. For a single self-contained file with no network calls (ads, email-safe hosting), use pinepaper_export_widget_html.' };
 })();`.trim();
     }
     generateExportWidgetHtml(input) {
@@ -6928,7 +8849,26 @@ if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
 (async function() {
   if (!app.exportEngine || !app.exportEngine.exportWidgetHTML) return { error: 'Widget HTML export not available' };
   const result = await app.exportEngine.exportWidgetHTML(${JSON.stringify(opts)});
-  return { success: true, html: result.html, estimatedSize: result.estimatedSize, analysis: { itemTypes: [...result.analysis.itemTypes], relationTypes: [...result.analysis.relationTypes], hasSimpleAnimations: result.analysis.hasSimpleAnimations, hasKeyframeAnimations: result.analysis.hasKeyframeAnimations, hasMasks: result.analysis.hasMasks } };
+  ${input.lang || input.dir || input.alt ? `// lang / dir / alt on the engine's page (it writes <html lang="en"> and no
+  // text alternative). Applied as string edits on the one <html> tag and the
+  // first <canvas>; the result says which landed.
+  const __esc = function(v) { return String(v).replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;'); };
+  let __html = String(result.html || '');
+  const __applied = [];
+  ${input.lang || input.dir ? `__html = __html.replace(/<html\\b[^>]*>/i, function() { __applied.push('html'); return '<html lang="' + __esc(${JSON.stringify(input.lang ?? 'en')}) + '"' + ${JSON.stringify(input.dir ? ` dir="${input.dir}"` : '')} + '>'; });` : ''}
+  ${input.alt ? `// The engine's widget draws its canvas from script, so there is no <canvas>
+  // tag to label (prod retest): its accessible name is div#w's aria-label,
+  // mirrored in the screen-reader text #w-desc. Both carry the alt; a literal
+  // <canvas> is labelled too when a page has one. RegExp from strings, so no
+  // backslash escapes pass through this template.
+  const __alt = __esc(${JSON.stringify(input.alt)});
+  __html = __html.replace(new RegExp('<div id="w"([^>]*?)aria-label="[^"]*"', 'i'), function(m, mid) { __applied.push('widget-label'); return '<div id="w"' + mid + 'aria-label="' + __alt + '"'; });
+  __html = __html.replace(new RegExp('(<div[^>]*id="w-desc"[^>]*>)[^<]*(</div>)', 'i'), function(m, open, close) { __applied.push('widget-desc'); return open + __alt + close; });
+  __html = __html.replace(new RegExp('<canvas(?=[\\\\s>])', 'i'), function(m) { __applied.push('canvas'); return m + ' role="img" aria-label="' + __alt + '"'; });
+  __html = __html.replace(/<head>/i, function(m) { __applied.push('meta'); return m + '<meta name="description" content="' + __esc(${JSON.stringify(input.alt)}) + '">'; });` : ''}
+  result.html = __html;
+  result.a11y = __applied;` : ''}
+  return { success: true, html: result.html,${input.lang || input.dir || input.alt ? ' a11y: result.a11y,' : ''} estimatedSize: result.estimatedSize, analysis: { itemTypes: [...result.analysis.itemTypes], relationTypes: [...result.analysis.relationTypes], hasSimpleAnimations: result.analysis.hasSimpleAnimations, hasKeyframeAnimations: result.analysis.hasKeyframeAnimations, hasMasks: result.analysis.hasMasks } };
 })();`.trim();
     }
     // ===========================================================================
@@ -6942,8 +8882,11 @@ if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
                     return `(function() { return { error: 'chartType is required for create' }; })();`;
                 if (!input.data)
                     return `(function() { return { error: 'data is required for create' }; })();`;
+                const fields = resolveChartFields(input.chartType, input.data, input.options || {});
+                if ('error' in fields)
+                    return `(function() { return { success: false, error: ${JSON.stringify(fields.error)} }; })();`;
                 const dataStr = JSON.stringify(input.data);
-                const optsStr = JSON.stringify(input.options || {});
+                const optsStr = JSON.stringify(fields.options);
                 return `
 // Create chart
 (function() {
@@ -6951,7 +8894,7 @@ if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
   const group = app.createChart(${JSON.stringify(input.chartType)}, ${dataStr}, ${optsStr});
   if (!group) return { error: 'Failed to create chart' };
   const chartId = app.chartSystem.getLastChartId();
-  return { success: true, action: 'create', chartType: ${JSON.stringify(input.chartType)}, chartId, dataPoints: ${input.data.length} };
+  return { success: true, action: 'create', chartType: ${JSON.stringify(input.chartType)}, chartId, dataPoints: ${input.data.length}${fields.inferred ? `, fields: ${JSON.stringify(fields.inferred)}` : ''} };
 })();`.trim();
             }
             case 'update': {
@@ -7270,6 +9213,23 @@ if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
      * with asNodes promotes each detection to a typed, image-anchored design node
      * (pp:Detected*) instead of a labeled box. Async (runs an on-device ML model).
      */
+    // THE MODEL CANNOT BE DOWNLOADED, AND THE ERROR SAID ONLY "Failed to fetch".
+    //
+    // Detection runs transformers.js in the page, which pulls the model weights
+    // from huggingface.co. pinepaper.studio's connect-src lists neither that host
+    // nor its CDN (checked against the served header), so the download is refused
+    // for every page on production — an agent read "Failed to fetch
+    // (huggingface.co)" and could not tell whether to retry, pass another image,
+    // or give up. It is a deployment fix (allow the host, or serve the weights
+    // from the studio's own origin), and the error now says so.
+    static MODEL_FETCH_HINT = `function(msg) {
+    if (/fail(ed)? to fetch|networkerror|load failed/i.test(msg) && /huggingface|hf\\.co/i.test(msg)) {
+      return 'the detection model could not be downloaded: the page could not fetch its weights from huggingface.co. '
+        + 'The studio has to allow that host in its content-security policy, or serve the weights itself — no argument to this call works around it, and retrying will not help. '
+        + 'Other image tools are unaffected. (' + msg + ')';
+    }
+    return msg;
+  }`;
     generateDetectObjects(input) {
         const args = JSON.stringify({
             ...(input.itemId !== undefined ? { itemId: input.itemId } : {}),
@@ -7285,8 +9245,10 @@ if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
   }
   try {
     const res = await app.detectObjects(${args});
-    return Object.assign({ success: !!(res && res.ok) }, res || {});
-  } catch (e) { return { success: false, error: String((e && e.message) || e) }; }
+    const out = Object.assign({ success: !!(res && res.ok) }, res || {});
+    if (!out.success && typeof out.error === 'string') out.error = (${PinePaperCodeGenerator.MODEL_FETCH_HINT})(out.error);
+    return out;
+  } catch (e) { return { success: false, error: (${PinePaperCodeGenerator.MODEL_FETCH_HINT})(String((e && e.message) || e)) }; }
 })();`.trim();
     }
     /**
@@ -7309,8 +9271,10 @@ if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
   }
   try {
     const res = await app.extractObject(${args});
-    return Object.assign({ success: !!(res && res.ok) }, res || {});
-  } catch (e) { return { success: false, error: String((e && e.message) || e) }; }
+    const out = Object.assign({ success: !!(res && res.ok) }, res || {});
+    if (!out.success && typeof out.error === 'string') out.error = (${PinePaperCodeGenerator.MODEL_FETCH_HINT})(out.error);
+    return out;
+  } catch (e) { return { success: false, error: (${PinePaperCodeGenerator.MODEL_FETCH_HINT})(String((e && e.message) || e)) }; }
 })();`.trim();
     }
     /**
@@ -7367,7 +9331,10 @@ if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
   app.groupManager.addItemsToGroup(items, group);
   if (app.historyManager) app.historyManager.saveState();
   const groupId = (group.data && (group.data.registryId || group.data.groupId)) || null;
-  return { success: true, groupId: groupId, groupName: group.data && group.data.groupName, itemCount: items.length };`;
+  // itemId too (round 8 BB, 1.70): every other create answers itemId, and a
+  // group is an item every other tool addresses by that id. In a batch this
+  // does not claim a $N slot — only create ops do.
+  return { success: true, groupId: groupId, itemId: groupId, groupName: group.data && group.data.groupName, itemCount: items.length };`;
     }
     /**
      * Group a set of items into one draggable entity, or ungroup one back into loose
@@ -7386,7 +9353,7 @@ if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
   if (!result || !result.parts || !result.parts.length) return { success: false, error: 'Nothing to break apart (no sub-parts found)' };
   const partIds = result.parts.map(function(p) { return p && p.data && (p.data.registryId || p.data.id); }).filter(Boolean);
   const groupId = (result.group && result.group.data && (result.group.data.registryId || result.group.data.groupId)) || null;
-  return { success: true, action: 'break_apart', groupId: groupId, partIds: partIds, partCount: partIds.length };
+  return { success: true, action: 'break_apart', groupId: groupId, itemId: groupId, partIds: partIds, partCount: partIds.length };
 })();`.trim();
         }
         if (input.action === 'ungroup') {
@@ -7442,6 +9409,68 @@ if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
      * sceneAt(t). Returns a cheap per-frame hash by default (token-light) so an agent can
      * verify determinism (re-run → identical hashes) and whether frames actually change.
      */
+    /**
+     * Measurements for pinepaper_accessibility_check; the verdicts are made on
+     * the server (src/utils/a11y.ts). Text: fill, size, weight, and the solid
+     * fill of the topmost item under its centre. Flash: mean relative luminance
+     * of a 3 x 3 grid per sampled frame, through captureFramesAt (deterministic
+     * seek). Pixel work is native reduce / Array.from, not generated loops, so
+     * the loop budget does not count it.
+     */
+    generateAccessibilityCheck(input) {
+        const checks = input.checks ?? ['contrast', 'flash'];
+        const fps = input.fps ?? 20;
+        const duration = input.duration ?? 5;
+        const n = Math.min(1200, Math.max(3, Math.round(duration * fps)));
+        return `
+// Accessibility measurements (${checks.join(', ')})
+(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('flash') ? `  if (typeof app.captureFramesAt !== 'function') {
+    out.flashUnavailable = 'this studio has no deterministic frame capture (app.captureFramesAt), so flashing was not checked.';
+  } else {
+    const W = 48, H = 27;
+    const small = document.createElement('canvas');
+    small.width = W; small.height = H;
+    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) {
+      // Transparent canvas shows the page's CSS background, so composite on it.
+      ctx.fillStyle = out.page || '#ffffff';
+      ctx.fillRect(0, 0, W, H);
+      ctx.drawImage(c, 0, 0, W, H);
+      const px = ctx.getImageData(0, 0, W, H).data;
+      const acc = Array.prototype.reduce.call(px, function(a, v, k) {
+        if (k % 4 !== 3) return a;
+        const p = (k - 3) / 4, x = p % W, y = (p - x) / W;
+        const cell = Math.min(2, Math.floor(y * 3 / H)) * 3 + Math.min(2, Math.floor(x * 3 / W));
+        a.sum[cell] += 0.2126 * lut[px[k - 3]] + 0.7152 * lut[px[k - 2]] + 0.0722 * lut[px[k - 1]];
+        a.n[cell] += 1;
+        return a;
+      }, { sum: [0, 0, 0, 0, 0, 0, 0, 0, 0], n: [0, 0, 0, 0, 0, 0, 0, 0, 0] });
+      return acc.sum.map(function(s, i) { return acc.n[i] ? s / acc.n[i] : 0; });
+    } });
+  }
+` : ''}  return out;
+})();`.trim();
+    }
     generateCaptureFrames(input) {
         const timesJson = JSON.stringify(input.times);
         const seed = input.seed !== undefined ? input.seed : 0;
@@ -7453,7 +9482,18 @@ if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
     return { success: false, error: 'app.captureFramesAt unavailable — update FxTool to a build with the deterministic capture entrypoint' };
   }
   const includeDataUrls = ${includeDataUrls};
-  const hashStr = function(s) { let h = 5381; for (let i = 0; i < s.length; i++) { h = (((h << 5) + h) ^ s.charCodeAt(i)) >>> 0; } return h.toString(16); };
+  // THE HASH LOOP RAN ONCE PER CHARACTER OF A DATA URL, inside generated code,
+  // where every loop site is budgeted at 2,000,000 iterations — so any frame
+  // over ~2 MB (three photos, a shader backdrop) died "Loop budget exceeded".
+  // app.hashFrame is the same djb2-xor in engine code, outside the budget, so
+  // hashes stay comparable with builds that only have the fallback.
+  const hashStr = (typeof app.hashFrame === 'function')
+    ? function(s) { return app.hashFrame(s); }
+    // The fallback must not be a for loop either: the budget is per loop SITE
+    // across the whole run, so 50 frames of ~40 KB data URLs exhausted it on a
+    // 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}, {
     seed: ${seed},
     capture: function(c, t, i) {
@@ -7571,6 +9611,47 @@ if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
     generateMedia(input) {
         const guard = `  const A = (typeof window !== 'undefined') && window.PinePaperAgent;
   if (!A || typeof A.uploadVideo !== 'function') { return { success: false, error: 'window.PinePaperAgent media API unavailable — update FxTool to a media-capable build' }; }`;
+        // The URL to upload from: the staged bytes when the handler put a large
+        // data: URL on window.__ppStage (see pinepaper_media in handlers.ts).
+        //
+        // A data: URL IS DECODED HERE INTO A File, NOT HANDED OVER AS A URL. The
+        // engine's upload fetch()es a string, and production's CSP refuses fetch()
+        // of data: — so every data: upload failed on prod with "Failed to fetch ()"
+        // at every size (a local engine without the CSP accepted small ones, which
+        // is what made it look like a size limit). uploadAudio/uploadVideo take a
+        // File directly. Uint8Array.from with a map, not a for loop: a generated
+        // loop is budgeted per iteration and a few MB of audio would exhaust it.
+        const srcExpr = (url, kind) => `(function(u) {
+    if (u.indexOf('__ppStage:') === 0) {
+      const k = u.slice('__ppStage:'.length);
+      const v = window.__ppStage && window.__ppStage[k];
+      if (!v) throw new Error('the media bytes were staged as ' + k + ' and are not on the page — a bug in the MCP server, not your call.');
+      u = v;
+    }
+    if (u.indexOf('data:') !== 0) return u;
+    const comma = u.indexOf(',');
+    const meta = u.slice(5, comma);
+    const mime = meta.split(';')[0] || '${kind === 'audio' ? 'audio/mpeg' : 'video/mp4'}';
+    const body = u.slice(comma + 1);
+    const bin = /;base64/i.test(meta) ? atob(body) : decodeURIComponent(body);
+    const bytes = Uint8Array.from(bin, function(c) { return c.charCodeAt(0); });
+    const ext = (mime.split('/')[1] || '${kind === 'audio' ? 'mp3' : 'mp4'}').replace(/[^a-z0-9]/gi, '');
+    return new File([bytes], '${kind}.' + ext, { type: mime });
+  })(${JSON.stringify(url ?? '')})`;
+        // TWO ID SPACES, AND THE CALLER HOLDS THE WRONG ONE.
+        //
+        // upload answers {id, registryId}; every other tool on this surface speaks
+        // registry ids (item_N), so that is the one callers keep. But remove,
+        // setMediaPlaybackRate and setMediaClip look the id up in the audio/video
+        // layers, which are keyed by MEDIA id — so set_playback_rate with the
+        // registryId returned false, reported as a failure with no reason. Either
+        // form is resolved here; a miss names the id and what was looked for.
+        const resolveMedia = `  const __ref = ${JSON.stringify(input.id ?? '')};
+  const __m = (typeof A.listMedia === 'function')
+    ? A.listMedia().find(function(x) { return x.id === __ref || x.registryId === __ref; })
+    : null;
+  const __mid = __m ? __m.id : __ref;
+  const __miss = { success: false, error: 'no uploaded audio or video matches ' + JSON.stringify(__ref) + ' — pass the id or registryId that upload returned (media list shows both).' };`;
         switch (input.action) {
             case 'upload_video': {
                 const opts = JSON.stringify({
@@ -7584,7 +9665,7 @@ if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
 // Upload video from URL
 (async function() {
 ${guard}
-  const info = await A.uploadVideo(${JSON.stringify(input.url)}, ${opts});
+  const info = await A.uploadVideo(${srcExpr(input.url, 'video')}, ${opts});
   return { success: true, action: 'upload_video', media: info };
 })();`.trim();
             }
@@ -7599,7 +9680,13 @@ ${guard}
 // Upload audio from URL
 (async function() {
 ${guard}
-  const info = await A.uploadAudio(${JSON.stringify(input.url)}, ${opts});
+  const info = await A.uploadAudio(${srcExpr(input.url, 'audio')}, ${opts});${input.volume !== undefined ? `
+  // THE LEVEL IS STORED UNDER ONE KEY AND EXPORTED FROM ANOTHER. The upload
+  // records volume as \`gain\` on the registry entry; the video exporter's mix
+  // reads \`audioGain\`. So a bed uploaded at 0.25 exported at unity (measured:
+  // 0.0 dB change). Written to both until the engine reads one.
+  const __ae = info && info.registryId && app.itemRegistry ? app.itemRegistry.get(info.registryId) : null;
+  if (__ae) { __ae.properties = __ae.properties || {}; __ae.properties.audioGain = ${input.volume}; }` : ''}
   return { success: true, action: 'upload_audio', media: info };
 })();`.trim();
             }
@@ -7615,16 +9702,24 @@ ${guard}
 // Remove media
 (function() {
 ${guard}
-  const removed = A.removeMedia(${JSON.stringify(input.id)});
-  return { success: removed, action: 'remove', id: ${JSON.stringify(input.id)}, removed: removed };
+${resolveMedia}
+  if (!__m) return __miss;
+  const removed = A.removeMedia(__mid);
+  return removed
+    ? { success: true, action: 'remove', id: __mid, registryId: __m.registryId, removed: true }
+    : { success: false, action: 'remove', id: __mid, error: 'the studio did not remove ' + __mid + '.' };
 })();`.trim();
             case 'set_playback_rate':
                 return `
 // Set media playback rate
 (function() {
 ${guard}
-  const ok = A.setMediaPlaybackRate(${JSON.stringify(input.id)}, ${input.rate});
-  return { success: ok, action: 'set_playback_rate', id: ${JSON.stringify(input.id)}, rate: ${input.rate} };
+${resolveMedia}
+  if (!__m) return __miss;
+  const ok = A.setMediaPlaybackRate(__mid, ${input.rate});
+  return ok
+    ? { success: true, action: 'set_playback_rate', id: __mid, registryId: __m.registryId, rate: ${input.rate} }
+    : { success: false, action: 'set_playback_rate', id: __mid, error: 'the studio refused rate ${input.rate} for ' + __mid + '.' };
 })();`.trim();
             case 'set_clip':
                 return `
@@ -7632,8 +9727,12 @@ ${guard}
 (function() {
 ${guard}
   if (typeof A.setMediaClip !== 'function') { return { success: false, error: 'setMediaClip unavailable — update FxTool' }; }
-  const ok = A.setMediaClip(${JSON.stringify(input.id)}, ${input.inPoint}, ${input.outPoint});
-  return { success: ok, action: 'set_clip', id: ${JSON.stringify(input.id)}, inPoint: ${input.inPoint}, outPoint: ${input.outPoint} };
+${resolveMedia}
+  if (!__m) return __miss;
+  const ok = A.setMediaClip(__mid, ${input.inPoint}, ${input.outPoint});
+  return ok
+    ? { success: true, action: 'set_clip', id: __mid, registryId: __m.registryId, inPoint: ${input.inPoint}, outPoint: ${input.outPoint} }
+    : { success: false, action: 'set_clip', id: __mid, error: 'the studio refused the clip window ${input.inPoint}–${input.outPoint} for ' + __mid + '.' };
 })();`.trim();
             // ── Video-editing actions (v1.6.4) — these live on `app` (PinePaper
             // facades), not the agent media API, so they carry their own guards.
@@ -7645,7 +9744,33 @@ ${guard}
 (function() {
   if (typeof app.setTimeRemap !== 'function') { return { success: false, error: 'app.setTimeRemap unavailable — update FxTool to a time-remap-capable build' }; }
   const r = app.setTimeRemap(${S(input.id)}, ${S(input.remapTrack ?? null)});
-  return r && r.ok ? { success: true, action: 'set_time_remap', points: r.points } : { success: false, error: (r && r.error) || 'remap failed' };
+  if (!(r && r.ok)) return { success: false, error: (r && r.error) || 'remap failed' };
+  // WHAT THE REMAP CANNOT DO, READ BACK FROM WHAT WAS STORED. The clip is on
+  // the timeline only for its trimmed window, and past that it is HIDDEN
+  // whatever the curve says — a remap to 6.5 s on a 5 s clip cut to black at
+  // 5.0 s. Source values outside [inPoint, outPoint] are clamped, so that part
+  // of the curve is a hold. Both answered success before.
+  const __rid = typeof app._resolveId === 'function' ? app._resolveId(${S(input.id)}) : ${S(input.id)};
+  const __e = __rid && app.itemRegistry && app.itemRegistry.get(__rid);
+  const __p = (__e && __e.properties) || {};
+  const __tr = Array.isArray(__p.timeRemap) ? __p.timeRemap : [];
+  const __warnings = [];
+  const __out = typeof __p.outPoint === 'number' ? __p.outPoint : __p.duration;
+  if (__tr.length > 1 && Number.isFinite(__out)) {
+    const __in = typeof __p.inPoint === 'number' ? __p.inPoint : 0;
+    const __start = typeof __p.clipStartTime === 'number' ? __p.clipStartTime : 0;
+    const __end = __start + Math.max(0.001, __out - __in);
+    const __last = __tr[__tr.length - 1].time;
+    if (__last > __end + 0.001) {
+      __warnings.push('the remap runs to ' + __last + ' s but the clip is on the timeline only until ' + __end.toFixed(3) + ' s (start + trimmed length); after that it is hidden, not extended. Lengthen the clip window first.');
+    }
+    const __vals = __tr.map(function(k) { return k.value; });
+    const __hi = Math.max.apply(null, __vals), __lo = Math.min.apply(null, __vals);
+    if (__hi > __out + 0.001 || __lo < __in - 0.001) {
+      __warnings.push('remap source times run ' + __lo.toFixed(3) + '–' + __hi.toFixed(3) + ' s but the clip only has ' + __in.toFixed(3) + '–' + __out.toFixed(3) + ' s; the part outside is clamped, which plays as a hold.');
+    }
+  }
+  return Object.assign({ success: true, action: 'set_time_remap', points: r.points }, __warnings.length ? { warnings: __warnings } : {});
 })();`.trim();
             }
             case 'speed_ramp': {
@@ -7655,7 +9780,33 @@ ${guard}
 (function() {
   if (typeof app.speedRamp !== 'function') { return { success: false, error: 'app.speedRamp unavailable — update FxTool to a time-remap-capable build' }; }
   const r = app.speedRamp(${S(input.id)}, ${S(input.segments)});
-  return r && r.ok ? { success: true, action: 'speed_ramp', points: r.points } : { success: false, error: (r && r.error) || 'speed ramp failed' };
+  if (!(r && r.ok)) return { success: false, error: (r && r.error) || 'speed ramp failed' };
+  // WHAT THE REMAP CANNOT DO, READ BACK FROM WHAT WAS STORED. The clip is on
+  // the timeline only for its trimmed window, and past that it is HIDDEN
+  // whatever the curve says — a remap to 6.5 s on a 5 s clip cut to black at
+  // 5.0 s. Source values outside [inPoint, outPoint] are clamped, so that part
+  // of the curve is a hold. Both answered success before.
+  const __rid = typeof app._resolveId === 'function' ? app._resolveId(${S(input.id)}) : ${S(input.id)};
+  const __e = __rid && app.itemRegistry && app.itemRegistry.get(__rid);
+  const __p = (__e && __e.properties) || {};
+  const __tr = Array.isArray(__p.timeRemap) ? __p.timeRemap : [];
+  const __warnings = [];
+  const __out = typeof __p.outPoint === 'number' ? __p.outPoint : __p.duration;
+  if (__tr.length > 1 && Number.isFinite(__out)) {
+    const __in = typeof __p.inPoint === 'number' ? __p.inPoint : 0;
+    const __start = typeof __p.clipStartTime === 'number' ? __p.clipStartTime : 0;
+    const __end = __start + Math.max(0.001, __out - __in);
+    const __last = __tr[__tr.length - 1].time;
+    if (__last > __end + 0.001) {
+      __warnings.push('the remap runs to ' + __last + ' s but the clip is on the timeline only until ' + __end.toFixed(3) + ' s (start + trimmed length); after that it is hidden, not extended. Lengthen the clip window first.');
+    }
+    const __vals = __tr.map(function(k) { return k.value; });
+    const __hi = Math.max.apply(null, __vals), __lo = Math.min.apply(null, __vals);
+    if (__hi > __out + 0.001 || __lo < __in - 0.001) {
+      __warnings.push('remap source times run ' + __lo.toFixed(3) + '–' + __hi.toFixed(3) + ' s but the clip only has ' + __in.toFixed(3) + '–' + __out.toFixed(3) + ' s; the part outside is clamped, which plays as a hold.');
+    }
+  }
+  return Object.assign({ success: true, action: 'speed_ramp', points: r.points }, __warnings.length ? { warnings: __warnings } : {});
 })();`.trim();
             }
             case 'match_cut': {
@@ -7797,9 +9948,19 @@ ${guard}
 // Text: write it as STROKED handwriting — a path, not a glyph
 (function() {
   if (typeof app.createCursiveText !== 'function') { return { success: false, error: 'app.createCursiveText unavailable — update FxTool' }; }
-  const item = app.createCursiveText(${S(input.text)}, ${S(input.cursiveOptions ?? {})});
-  if (!item) { return { success: false, error: 'the cursive text produced no path' }; }
-  return { success: true, itemId: item.data && item.data.id };
+  // createCursiveText answers { items, group, totalWidth, bounds } — not an
+  // item — so reading .data.id off the answer returned no id, every time. The
+  // group is registered only on one of its two branches; the other is
+  // registered here so the caller always gets an addressable id.
+  const r = app.createCursiveText(${S(input.text)}, ${S(input.cursiveOptions ?? {})});
+  const g = r && (r.group || (r.data ? r : null));
+  if (!g) { return { success: false, error: 'the cursive text produced no path' }; }
+  let itemId = g.data && (g.data.id || g.data.registryId);
+  if (!itemId && app.itemRegistry && typeof app.itemRegistry.register === 'function') {
+    itemId = app.itemRegistry.register(g, 'cursiveText', { content: ${S(input.text)} }, 'user');
+  }
+  if (!itemId) { return { success: false, error: 'the cursive text was drawn but not registered — no usable item id.' }; }
+  return { success: true, itemId: itemId, strokes: (r.items || []).length, width: r.totalWidth };
 })();`.trim();
             case 'wrap':
                 return `
@@ -8283,6 +10444,25 @@ ${needWorld}
                         mesh.rotY = mesh.rotYDegrees * Math.PI / 180;
                     delete mesh.rotYDegrees;
                 }
+                // A COLOUR, NOT A BLACK MESH (round 9 HH, 5.64). The default mesh
+                // shader reads `uniform vec3 diffuse` (0..1) plus metalness / roughness,
+                // and extrude / lathe passed no uniforms — so every authored mesh
+                // rendered black and there was no parameter to change it. color (hex,
+                // [r,g,b] 0..255 or 0..1) becomes diffuse; with none given it is a
+                // neutral light grey, which lights readably. Explicit uniforms win.
+                {
+                    const uniforms = { ...(mesh.uniforms ?? {}) };
+                    if (uniforms.diffuse === undefined)
+                        uniforms.diffuse = mesh.color !== undefined ? world3dColor(mesh.color) : [0.8, 0.8, 0.8];
+                    if (uniforms.metalness === undefined && typeof mesh.metalness === 'number')
+                        uniforms.metalness = mesh.metalness;
+                    if (uniforms.roughness === undefined)
+                        uniforms.roughness = typeof mesh.roughness === 'number' ? mesh.roughness : 0.6;
+                    delete mesh.color;
+                    delete mesh.metalness;
+                    delete mesh.roughness;
+                    mesh.uniforms = uniforms;
+                }
                 return `
 // World3D: ${input.action} — a canvas path becomes real geometry
 (async function() {
@@ -8784,6 +10964,14 @@ ${guard('exportBVH')}
 // Interchange: one PNG per frame
 (async function() {
 ${guard('exportPNGSequence')}
+  // The studio does not size a sequence to the scene: without duration / fps
+  // it writes its own default (measured 45 frames = 3 s at 15 fps for a 1 s
+  // scene, 29 of them duplicates). Said in the result when that happened.
+  const __pngSeqDefaults = ${JSON.stringify((() => {
+                    const o = (input.options ?? {});
+                    const missing = ['duration', 'fps'].filter((k) => o[k] === undefined);
+                    return missing.length ? { defaultsUsed: missing, note: `${missing.join(' and ')} not given, so the studio's own default length was used — it does not follow the scene (runs have measured 45 and 90 frames). Pass options.duration and options.fps to match the scene.` } : {};
+                })())};
   const out = await app.exportPNGSequence(${opts});
   if (!out) { return { success: false, error: 'PNG sequence produced nothing' }; }
   // A BLOB SERIALISES TO {}. exporter.export() answers a Blob, and returning it
@@ -8798,7 +10986,7 @@ ${guard('exportPNGSequence')}
       fr.onerror = function() { rej(new Error('could not read the PNG sequence')); };
       fr.readAsDataURL(out);
     });
-    return { success: true, format: 'png-sequence', data: dataUrl, mimeType: out.type || 'application/zip', size: out.size };
+    return Object.assign({ success: true, format: 'png-sequence', data: dataUrl, mimeType: out.type || 'application/zip', size: out.size }, __pngSeqDefaults);
   }
   if (Array.isArray(out)) {
     return { success: true, format: 'png-sequence', frames: out.length,
@@ -8967,6 +11155,51 @@ ${guard('createSound')}
   // setSoundPlacement the separate action calls.
   ${placement ? `if (_sid && app.setSoundPlacement) { app.setSoundPlacement(_sid, ${S(placement)}); }` : ''}
   return { success: true, itemId: _sid, itemType: 'sound'${placement ? `, placement: ${S(placement)}` : ''} };
+})();`.trim();
+            }
+            case 'sequence': {
+                // ONE CALL FOR A WHOLE BED.
+                //
+                // Every cue was create + set_placement, so a 112-cue music bed cost 112
+                // round trips once visual.startTime landed and 224 before it. Nothing
+                // about the work needs a trip each: the cues are independent, they
+                // differ only in time and spec, and the page can loop.
+                //
+                // Each cue is reported individually. A bed where three cues failed and
+                // 109 worked is not a failure, and it is not a success either — the
+                // caller needs to know WHICH, so placed/failed come back by index.
+                const cues = (input.cues ?? []);
+                return `
+// Sound: a whole sequence of cues, created and placed in one pass
+(function() {
+${guard('createSound')}
+  const cues = ${S(cues)};
+  const placed = [];
+  const failed = [];
+  for (let i = 0; i < cues.length; i++) {
+    const c = cues[i];
+    try {
+      const spec = c.spec || (c.preset ? { preset: c.preset, note: c.note } : null);
+      if (!spec) { failed.push({ index: i, t: c.t, error: 'neither spec nor preset' }); continue; }
+      const item = app.createSound(spec, c.visual || {});
+      if (!item) { failed.push({ index: i, t: c.t, error: 'the cue produced no waveform path' }); continue; }
+      const id = item.data && item.data.id;
+      if (id && app.setSoundPlacement) {
+        app.setSoundPlacement(id, { startTime: c.t, ...(c.duration ? { duration: c.duration } : {}) });
+      }
+      placed.push({ index: i, itemId: id, t: c.t });
+    } catch (e) {
+      failed.push({ index: i, t: c.t, error: (e && e.message) || 'cue failed' });
+    }
+  }
+  return {
+    success: failed.length === 0,
+    action: 'sequence',
+    placed: placed.length,
+    itemIds: placed.map(function(p) { return p.itemId; }),
+    cues: placed,
+    ...(failed.length ? { failed: failed, error: failed.length + ' of ' + cues.length + ' cues did not sound — see failed[] for which.' } : {}),
+  };
 })();`.trim();
             }
             case 'timbre_from_path':