@pinepaper.studio/mcp-server 1.6.8 → 1.6.10

package/dist/types/code-generator.js

@@ -886,19 +886,36 @@ function generateBatchModifyCode(modifications) {
     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 => ({
-  item: mod.itemId,
+  itemId: mod.itemId,
   params: mod.params
 })));
 
-// Return modification results
-const formatted = results.map(r => ({
-  itemId: r.item?.data?.registryId || r.itemId,
-  success: r.success,
-  error: r.error || null
-}));
+// 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: formatted.every(r => r.success), results: formatted, count: formatted.length });
+({
+  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();
 }
 /**
@@ -972,6 +989,28 @@ export function canvasPresetFor(platform) {
  * inside the encode.
  */
 export const INLINE_MAX_BYTES = 96 * 1024 * 1024;
+/**
+ * Wait for the export subsystem before reading it.
+ *
+ * `app.exportEngine` is a LAZY getter over a code-split chunk: it returns
+ * undefined until `ensureHeavyModules()` has run, which the engine idle-prefetches
+ * roughly 1.2s after boot. An agent connecting and exporting immediately —
+ * which is the whole shape of an automated session — beats that prefetch, so
+ * every `app.exportEngine.*` read below found undefined and the generated code
+ * reported the studio as too old to export. The build was fine; the chunk had
+ * not landed yet. Awaiting it is the difference between a check and a race.
+ *
+ * The guards that follow this are left exactly as they are: after the await,
+ * an absent exportEngine really does mean a studio that cannot export.
+ *
+ * Emitted only into the two doors an agent can reach cold. `readExport` and
+ * `releaseExport` are only reachable after an export has already succeeded, by
+ * which point the chunk is resident by construction.
+ */
+const ENSURE_EXPORT_ENGINE = `
+  if (!app.exportEngine && typeof app.ensureHeavyModules === 'function') {
+    try { await app.ensureHeavyModules(); } catch (_) { /* the guards below still speak */ }
+  }`;
 export class PinePaperCodeGenerator {
     /**
      * Generate code for creating an item
@@ -1233,12 +1272,41 @@ throw new Error('Either svgString or url must be provided');
   if (!app.importMermaid) return { success: false, error: 'importMermaid not available — diagramSystem missing' };
   const mermaidText = \`${escaped}\`;
   const result = app.importMermaid(mermaidText, ${optsJson});
+
+  // NEVER RETURN THE RAW NODES. They are Paper.js items, and a Paper item
+  // refers to its project, which refers back — JSON.stringify dies on the cycle
+  // with "property '_scope' closes the circle", and the tool reported "Failed
+  // to execute code in browser" for an import that had worked. Summarised to
+  // ids, labels and bounds, which is what a caller can act on anyway.
+  const safeNode = (n) => {
+    const item = n && (n.item || n);
+    const b = item && item.bounds;
+    return {
+      id: (item && item.data && item.data.registryId) || (n && n.id) || null,
+      label: (n && (n.label ?? n.text)) ?? null,
+      bounds: b ? { x: Math.round(b.x), y: Math.round(b.y), width: Math.round(b.width), height: Math.round(b.height) } : null,
+    };
+  };
+  const nodes = (result.nodes || []).map(safeNode);
+  const edges = (result.edges || []).map((e) => ({ from: e?.from ?? e?.source ?? null, to: e?.to ?? e?.target ?? null, label: e?.label ?? null }));
+
+  // A zero-item import is NOT a success. The engine reported success:true with
+  // itemsCreated:0 and the tool passed it on, so a diagram that drew nothing
+  // read as a diagram that drew.
+  if (!nodes.length) {
+    return {
+      success: false,
+      error: 'the mermaid import created no items. The text parsed but produced nothing to draw — check the diagram type is one this build supports, and that the body is not empty.',
+      nodeCount: 0, edgeCount: edges.length, errors: result.errors || [],
+    };
+  }
+
   return {
     success: !!result.success,
-    nodeCount: result.nodes ? result.nodes.length : 0,
-    edgeCount: result.edges ? result.edges.length : 0,
-    nodes: result.nodes || [],
-    edges: result.edges || [],
+    nodeCount: nodes.length,
+    edgeCount: edges.length,
+    nodes,
+    edges,
     errors: result.errors || [],
   };
 })();
@@ -1553,8 +1621,11 @@ bg.sendToBack();
         if (backgroundGenerator) {
             codeParts.push(`
 // Execute background generator
-if (typeof app.generators !== 'undefined' && app.generators['${backgroundGenerator}']) {
-  app.generators['${backgroundGenerator}']();
+const _gen = app.generatorRegistry?.get('${backgroundGenerator}');
+if (typeof _gen === 'function') {
+  _gen();
+} else if (_gen && typeof _gen.generate === 'function') {
+  _gen.generate();
 }
 `);
         }
@@ -1691,8 +1762,9 @@ results;
         const labelStr = label ? JSON.stringify(label) : 'null';
         return `
 // Create diagram shape: ${shapeType}
+// POSITIONAL: createShape(shapeType, config). The type was being passed
+// INSIDE the config object, where nothing reads it.
 const shapeConfig = {
-  shapeType: '${shapeType}',
   position: { x: ${position.x}, y: ${position.y} },
   width: ${widthVal},
   height: ${heightVal},
@@ -1700,7 +1772,8 @@ const shapeConfig = {
   style: ${styleStr}
 };
 
-const shape = app.diagramManager.createShape(shapeConfig);
+const shape = app.diagramSystem.createShape('${shapeType}', shapeConfig);
+if (!shape) throw new Error('createShape returned nothing for shapeType "${shapeType}" — call pinepaper_get_diagram_shapes for the registered types.');
 const itemId = shape.data?.registryId || shape.id;
 app.historyManager.saveState();
 
@@ -1744,7 +1817,7 @@ if (!sourceItem) throw new Error('Source item not found: ${sourceItemId}');
 if (!targetItem) throw new Error('Target item not found: ${targetItemId}');
 
 const config = ${JSON.stringify(config, null, 2)};
-const connector = app.diagramManager.connect(sourceItem, targetItem, config);
+const connector = app.diagramSystem.connect(sourceItem, targetItem, config);
 const connectorId = connector.data?.registryId || connector.id;
 app.historyManager.saveState();
 
@@ -1772,7 +1845,7 @@ if (!sourceItem) throw new Error('Source item not found: ${sourceItemId}');
 if (!targetItem) throw new Error('Target item not found: ${targetItemId}');
 
 const config = ${configStr};
-const connector = app.diagramManager.connectPorts(
+const connector = app.diagramSystem.connectPorts(
   sourceItem, '${sourcePort}',
   targetItem, '${targetPort}',
   config
@@ -1789,21 +1862,31 @@ app.historyManager.saveState();
     generateAddPorts(input) {
         const validated = AddPortsInputSchema.parse(input);
         const { itemId, portType, ports, count } = validated;
-        const portsStr = ports ? JSON.stringify(ports, null, 2) : 'undefined';
-        const countVal = count !== undefined ? count : 'undefined';
+        // THE SCHEMA PROMISES MORE THAN THE ENGINE HAS. `addPorts(item, type)` takes
+        // a type string and lays out that type's port set; there is no per-port
+        // placement and no count. The old emitter passed {portType, ports, count}
+        // as the second argument, which the engine tried to iterate — "t.forEach is
+        // not a function" — so every call failed and the two extra fields looked
+        // like they might have worked. Refused by name instead of dropped.
+        if (ports !== undefined || count !== undefined) {
+            const named = [ports !== undefined && 'ports', count !== undefined && 'count'].filter(Boolean).join(' and ');
+            throw new Error(`add_ports cannot honour ${named}: this engine lays out a whole port SET by type `
+                + `(portType '${portType}'), with no per-port placement or count. Drop ${named}, or place `
+                + 'individual connection points as items and join them with pinepaper_connect.');
+        }
         return `
 // Add ports to item: ${itemId}
 const item = app.getItemById('${itemId}');
 if (!item) throw new Error('Item not found: ${itemId}');
 
-const result = app.diagramManager.addPorts(item, {
-  portType: '${portType}',
-  ports: ${portsStr},
-  count: ${countVal}
-});
+// The second argument is a TYPE STRING, not a config object. Passing an
+// object made the engine iterate it as a list — "t.forEach is not a function".
+const result = app.diagramSystem.addPorts(item, '${portType}');
 app.historyManager.saveState();
 
-({ itemId: '${itemId}', portsAdded: result.portsAdded || 0, portType: '${portType}' });
+// addPorts returns the ports it made; older builds returned a count object.
+const _added = Array.isArray(result) ? result.length : (result?.portsAdded ?? 0);
+({ itemId: '${itemId}', portsAdded: _added, portType: '${portType}' });
 `.trim();
     }
     /**
@@ -1816,13 +1899,26 @@ app.historyManager.saveState();
         const optionsStr = options ? JSON.stringify(options, null, 2) : '{}';
         return `
 // Apply auto-layout: ${layoutType}
+// Wrapped: applyLayout is async, and a bare top-level await only works on the
+// governed path. A paren-led IIFE also keeps the trailing-expression capture.
+(async function() {
 const itemIds = ${itemIdsStr};
 const options = ${optionsStr};
 
-const result = app.diagramManager.autoLayout('${layoutType}', itemIds, options);
+// applyLayout(items, type, options) — ITEMS first, and it takes live items
+// rather than ids. It is async, and it resolves to undefined: reading
+// result.itemsAffected off that throws, which is how a layout that worked
+// reported as a crash.
+const items = itemIds
+  ? itemIds.map((id) => app.getItemById(id)).filter(Boolean)
+  : (app.itemRegistry?.getAll?.() ?? []);
+if (!items.length) throw new Error('auto_layout found no items to lay out' + (itemIds ? ' for the given itemIds' : ' on the canvas'));
+
+await app.diagramSystem.applyLayout(items, '${layoutType}', options);
 app.historyManager.saveState();
 
-({ layoutType: '${layoutType}', itemsAffected: result.itemsAffected || 0, success: result.success });
+return { layoutType: '${layoutType}', itemsAffected: items.length, success: true };
+})();
 `.trim();
     }
     /**
@@ -1835,7 +1931,10 @@ app.historyManager.saveState();
         return `
 // Get available diagram shapes
 const category = ${categoryFilter};
-const shapes = app.diagramManager.getAvailableShapes(category);
+// The library is the registry; diagramSystem has no getAvailableShapes.
+const _lib = app.diagramSystem?.shapeLibrary;
+if (!_lib) throw new Error('app.diagramSystem.shapeLibrary unavailable — update FxTool');
+const shapes = category ? _lib.getByCategory(category) : _lib.getAll();
 
 ({ shapes, count: shapes.length, category: ${categoryFilter} || 'all' });
 `.trim();
@@ -1863,10 +1962,44 @@ const connector = app.getItemById('${connectorId}');
 if (!connector) throw new Error('Connector not found: ${connectorId}');
 
 const updates = ${updatesStr};
-app.diagramManager.updateConnector(connector, updates);
-app.historyManager.saveState();
 
-({ connectorId: '${connectorId}', updated: true });
+// THERE IS NO updateConnector. ConnectorManager publishes removeConnector,
+// findConnector and updateSelectedStyle — nothing that edits one connector's
+// properties in place. The old emitter called app.diagramSystem.updateConnector
+// and reported updated:true, so a caller changing a connector's colour got a
+// success and an unchanged connector.
+//
+// Applied directly where the property is a plain Paper.js one, and refused by
+// name where it is not, rather than claiming a change that did not happen.
+// The engine gained getConnector(id) / updateConnector(id, style), which is
+// the call this tool always wanted: addressable by the id a connector is
+// created and serialised with. Guarded, because a studio predating that still
+// has to do something sensible rather than throw.
+if (typeof app.diagramSystem?.updateConnector === 'function') {
+  const res = app.diagramSystem.updateConnector('${connectorId}', updates);
+  if (res && res.ok === false) { return { success: false, error: res.reason || 'the connector could not be updated' }; }
+  app.historyManager.saveState();
+  return { connectorId: '${connectorId}', updated: true, applied: Object.keys(updates) };
+}
+
+const _applied = [];
+const _unsupported = [];
+for (const [k, v] of Object.entries(updates)) {
+  if (k === 'lineColor' && connector.strokeColor !== undefined) { connector.strokeColor = v; _applied.push(k); }
+  else if (k === 'lineWidth' && connector.strokeWidth !== undefined) { connector.strokeWidth = v; _applied.push(k); }
+  else _unsupported.push(k);
+}
+if (_applied.length) { app.historyManager.saveState(); app._scheduleRepaint?.(); }
+if (_unsupported.length && !_applied.length) {
+  throw new Error(
+    'this build cannot update ' + _unsupported.join(', ') + ' on an existing connector — '
+    + 'this build has no per-connector update — app.diagramSystem.updateConnector arrived later. '
+    + 'Update the studio for it. Removing and recreating the connector works, but mints a NEW id '
+    + 'and orphans anything holding the old one, so it is a last resort rather than the fix.'
+  );
+}
+
+({ connectorId: '${connectorId}', updated: _applied.length > 0, applied: _applied, unsupported: _unsupported });
 `.trim();
     }
     /**
@@ -1880,7 +2013,7 @@ app.historyManager.saveState();
 const connector = app.getItemById('${connectorId}');
 if (!connector) throw new Error('Connector not found: ${connectorId}');
 
-app.diagramManager.removeConnector(connector);
+app.diagramSystem.connectorManager.removeConnector(connector);
 app.historyManager.saveState();
 
 ({ connectorId: '${connectorId}', removed: true });
@@ -1896,19 +2029,19 @@ app.historyManager.saveState();
             case 'activate':
                 return `
 // Activate diagram mode
-app.diagramManager.activate();
+app.diagramSystem.activate();
 ({ action: 'activate', active: true });
 `.trim();
             case 'deactivate':
                 return `
 // Deactivate diagram mode
-app.diagramManager.deactivate();
+app.diagramSystem.deactivate();
 ({ action: 'deactivate', active: false });
 `.trim();
             case 'toggle':
                 return `
 // Toggle diagram mode
-const isActive = app.diagramManager.toggle();
+const isActive = app.diagramSystem.toggle();
 ({ action: 'toggle', active: isActive });
 `.trim();
             case 'setMode':
@@ -1916,7 +2049,7 @@ const isActive = app.diagramManager.toggle();
                 const shapeStr = shapeType ? `, '${shapeType}'` : '';
                 return `
 // Set diagram tool mode
-app.diagramManager.setMode(${modeStr}${shapeStr});
+app.diagramSystem.setMode(${modeStr}${shapeStr});
 ({ action: 'setMode', mode: ${modeStr}${shapeType ? `, shapeType: '${shapeType}'` : ''} });
 `.trim();
             default:
@@ -2075,7 +2208,7 @@ throw new Error('Unknown diagram mode action: ${action}');
 
   // FxTool has no animationManager — animations are detected via item.data.animationType walk above
   // Check timeline for active animations
-  if (app.timeline && (app.timeline.isPlaying || app.timeline.animations?.length > 0)) {
+  if (app.timelineState?.isPlaying || app.animatedItems?.size > 0) {
     analysis.hasAnimations = true;
     animationSet.add('timeline');
   }
@@ -2204,6 +2337,17 @@ throw new Error('Unknown diagram mode action: ${action}');
         let code = `
 // Batch execute ${operations.length} operations
 (async function() {
+  // An op's own verdict. Deliberately narrow, matching the server-side rule:
+  // only an explicit success:false or ok:false is a failure, because most ops
+  // return a bare value (an id, a count) and treating a missing field as
+  // refusal would fail every one of them.
+  const _opFailure = (v) => {
+    if (!v || typeof v !== 'object') return null;
+    if (v.success !== false && v.ok !== false) return null;
+    return (typeof v.error === 'string' && v.error)
+      || (typeof v.reason === 'string' && v.reason)
+      || 'the operation reported failure without naming a reason';
+  };
   const results = [];
   const itemIds = [];
   let success = true;
@@ -2228,10 +2372,24 @@ throw new Error('Unknown diagram mode action: ${action}');
       const result${index} = await (async () => {
         ${opCode}
       })();
-      results.push({ index: ${index}, success: true, result: result${index} });
-      ${claimsItemSlot ? `if (result${index} && result${index}.itemId) {
-        itemIds.push(result${index}.itemId);
-      }` : ''}
+      // NOT THROWING IS NOT SUCCEEDING. An op that RETURNS { success: false }
+      // — a guard that found a facade missing, a preset the engine does not
+      // have, a precondition unmet — raises nothing, so this recorded it as a
+      // success and the batch reported success over it. Measured on
+      // applyAnimatedMask(item, 'star'): the per-op error was perfectly good
+      // and the batch still said everything worked.
+      const failed${index} = _opFailure(result${index});
+      if (failed${index}) {
+        // ATOMIC: throw WITHOUT recording, and let the catch below record it
+        // once. Doing both put two entries in for one failed op.
+        ${isAtomic ? `throw new Error(failed${index});` : `results.push({ index: ${index}, success: false, error: failed${index}, result: result${index} });
+        success = false;`}
+      } else {
+        results.push({ index: ${index}, success: true, result: result${index} });
+        ${claimsItemSlot ? `if (result${index} && result${index}.itemId) {
+          itemIds.push(result${index}.itemId);
+        }` : ''}
+      }
     } catch (opError) {
       results.push({ index: ${index}, success: false, error: opError.message });
       ${isAtomic ? 'throw opError;' : 'success = false;'}
@@ -2243,7 +2401,14 @@ throw new Error('Unknown diagram mode action: ${action}');
     if (app.historyManager) app.historyManager.saveState();
 
     const _cs = app.getCanvasSize ? app.getCanvasSize() : { width: 800, height: 600 };
-    return { success, itemIds, results, operationCount: ${operations.length}, canvasSize: { width: _cs.width || 800, height: _cs.height || 600 } };
+    // Name WHICH ops failed on the result itself. A caller reading a failed
+    // 60-op batch should not have to scan sixty entries to learn that op 41
+    // could not find a preset.
+    const _failed = results.filter((r) => !r.success);
+    return { success, itemIds, results, operationCount: ${operations.length},
+      failedCount: _failed.length,
+      ...(_failed.length ? { error: _failed.map((r) => 'op ' + r.index + ': ' + r.error).join('; ') } : {}),
+      canvasSize: { width: _cs.width || 800, height: _cs.height || 600 } };
   } catch (e) {
     const _cs = app.getCanvasSize ? app.getCanvasSize() : { width: 800, height: 600 };
     return { success: false, error: e.message, itemIds, results, operationCount: ${operations.length}, canvasSize: { width: _cs.width || 800, height: _cs.height || 600 } };
@@ -2435,7 +2600,15 @@ return { success: !!maskedGroup, itemId: targetId, preset: '${preset}' };
 const targetId = ${effItemRef};
 const item = app.getItemById(targetId);
 if (!item) throw new Error('Item not found: ' + targetId);
-app.applyEffect(item, '${op.effectType || 'sparkle'}', ${effParams});
+// PROPAGATE the engine's verdict. This discarded it and returned its own
+// shape, so an effect the engine refused — an unknown preset, a facade that
+// is not loaded — was recorded as applied. The batch cannot report what the
+// op never tells it.
+const _eff = app.applyEffect(item, '${op.effectType || 'sparkle'}', ${effParams});
+if (_eff && (_eff.success === false || _eff.ok === false)) {
+  return { success: false, itemId: targetId, effectType: '${op.effectType || 'sparkle'}',
+    error: _eff.error || _eff.reason || 'the effect was refused without a reason' };
+}
 return { itemId: targetId, effectType: '${op.effectType || 'sparkle'}' };
 `;
             }
@@ -2490,6 +2663,25 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
     return { ok: false, reason: 'app.exportEngine.readExport unavailable — update FxTool' };
   }
   return await app.exportEngine.readExport(${JSON.stringify(exportId)}, ${JSON.stringify(range)});
+})();`.trim();
+    }
+    /**
+     * What the studio is still holding.
+     *
+     * `id` IS the OPFS filename and OPFS is origin-persistent, so this survives a
+     * page reload: an export whose id was lost — to a dropped tool result, a
+     * crashed session, a reload — is recoverable from here rather than only by
+     * rendering it again. Newest first, which is the order a caller looking for
+     * "the one I just made" wants.
+     */
+    generateListExports() {
+        return `
+// What the export store is holding
+(async function() {${ENSURE_EXPORT_ENGINE}
+  if (!app.exportEngine || typeof app.exportEngine.listExports !== 'function') {
+    return { ok: false, reason: 'app.exportEngine.listExports unavailable — update FxTool' };
+  }
+  return { ok: true, exports: await app.exportEngine.listExports() };
 })();`.trim();
     }
     /**
@@ -2510,7 +2702,7 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
     }
     generateAgentExport(input) {
         const validated = AgentExportInputSchema.parse(input);
-        const { platform, format, quality, framing, duration, estimateOnly } = validated;
+        const { platform, format, quality, framing, duration, estimateOnly, scale, fps } = validated;
         const qualityLevel = quality || 'standard';
         const videoDuration = duration ?? 5;
         // Quality settings (bitrate in bps for VideoEncoder)
@@ -2533,6 +2725,22 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
             'print-letter': { width: 2550, height: 3300, staticFormat: 'pdf', animatedFormat: 'pdf' },
         };
         const preset = platformPresets[platform] || platformPresets['web'];
+        // SCALE is the only honest size control this surface has.
+        //
+        // A caller who wants a smaller file reaches for a bitrate, and there is
+        // nowhere to put one: VideoExporter computes its own target from
+        // resolution, quality and fps via _calculateBitrate and never reads a
+        // caller-supplied value — passing one would be a knob that silently does
+        // nothing. Resolution is an INPUT to that calculation, so halving the
+        // frame genuinely halves the encode target, and it is also what makes a
+        // preview render fast. One number, both jobs, and it is real.
+        //
+        // Rounded to EVEN: H.264 chroma subsampling is 4:2:0, and an odd dimension
+        // is rejected by the encoder rather than rounded for you.
+        const even = (n) => Math.max(2, Math.round(n / 2) * 2);
+        const scaled = scale !== undefined && scale !== 1
+            ? { width: even(preset.width * scale), height: even(preset.height * scale) }
+            : { width: preset.width, height: preset.height };
         // Resolve "auto" format to the platform's recommended format
         const exportFormat = (!format || format === 'auto') ? preset.staticFormat : format;
         // AUDIO-ONLY EXPORT, off the visual path entirely.
@@ -2547,13 +2755,13 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
         // No platform preset resolves to wav, so reaching here means it was asked
         // for by name. Dimensions, framing, fps and bitrate are all absent rather
         // than passed and ignored.
-        // @engine-methods renderSoundtrackWav exportEngine.sceneHasAudio
+        // @engine-methods renderSoundtrackWav exportEngine.sceneHasAudio ensureHeavyModules
         if (exportFormat === 'wav') {
             const sr = validated.sampleRate ?? 48000;
             const bd = validated.bitDepth ?? 16;
             return `
 // Export: the soundtrack on its own, rendered offline
-(function() {
+(async function() {${ENSURE_EXPORT_ENGINE}
   if (typeof app.renderSoundtrackWav !== 'function') {
     return { success: false, format: 'wav', error: 'app.renderSoundtrackWav unavailable — update FxTool. This build cannot export audio on its own; mp4/webm still mux the soundtrack into the video.' };
   }
@@ -2607,13 +2815,17 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
         }
         return `
 // Smart export for ${platform}
-(async function() {
+(async function() {${ENSURE_EXPORT_ENGINE}
   const platform = '${platform}';
   const format = '${exportFormat}';
   const quality = '${qualityLevel}';
   const framing = '${framing}';
-  const settings = ${JSON.stringify(qualitySettings)};
-  const dimensions = ${JSON.stringify({ width: preset.width, height: preset.height })};
+  // An explicit fps wins over the tier's. The tiers bundle frame rate with
+  // compression (draft 15 / standard 30 / high 60), so "higher quality" also
+  // doubled the frame count and the render time — a surprise the schema used
+  // to hide because there was no way to ask for one without the other.
+  const settings = ${JSON.stringify(fps !== undefined ? { ...qualitySettings, fps } : qualitySettings)};
+  const dimensions = ${JSON.stringify(scaled)};
 
   // Preflight: same resolved settings as the real export, but render nothing.
   // Branching HERE rather than in a separate tool is deliberate — the estimate
@@ -2679,7 +2891,7 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
   try {
     switch (format) {
       case 'svg':
-        const svgString = app.exportAnimatedSVG ? app.exportAnimatedSVG() : app.exportSVG();
+        const svgString = app.exportAnimatedSVG ? app.exportAnimatedSVG() : app.exportSVGWithCSS();
         result = {
           success: true,
           platform,
@@ -2728,7 +2940,10 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
         // ExportEngine._quickExportVideo overrides quality with undefined for
         // mp4/webm, _calculateBitrate yields NaN, and VideoEncoder.configure
         // rejects with 'malformed bitrate value'.
-        const baseVideoSettings = { format, fps: settings.fps, quality: settings.compression, duration: ${videoDuration} };
+        // 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);
@@ -2931,7 +3146,7 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
 
   // FxTool has no animationManager — animations are detected via item.data.animationType walk above
   // Check timeline for active animations
-  if (app.timeline && (app.timeline.isPlaying || app.timeline.animations?.length > 0)) {
+  if (app.timelineState?.isPlaying || app.animatedItems?.size > 0) {
     analysis.hasAnimations = true;
     animationSet.add('timeline');
   }
@@ -3077,8 +3292,15 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
     return { success: false, error: 'Letter collage animation not available' };
   }
 
-  const result = app.animateLetterCollage(collageId, {
-    animationType,
+  // POSITIONAL, and it was not: the engine signature is
+  // animateLetterCollage(collageId, animationType, options), in PinePaper.js.
+  // Passing one object put it in the animationType slot, so the type the caller
+  // asked for was discarded on EVERY call and the collage animated as whatever
+  // the engine falls back to. Silent: the call still returned, still reported
+  // success, and the collage still moved a little, which is why it read as
+  // "the flagship text effect doesn't survive export" rather than as a
+  // dropped argument.
+  const result = app.animateLetterCollage(collageId, animationType, {
     staggerDelay,
     animationSpeed
   });
@@ -3458,7 +3680,7 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
   }
 
   try {
-    app.mapSystem.stopAnimations({
+    app.mapSystem.stopRegionAnimations({
       regions: ${regionsStr},
       resetColors: ${validated.resetColors !== false}
     });
@@ -3502,7 +3724,7 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
   }
 
   try {
-    const result = app.mapSystem.exportRegionCSV({
+    const result = app.mapSystem.exportRegionDataCSV({
       includeHighlighted: ${validated.includeHighlighted !== false},
       includeSelected: ${validated.includeSelected !== false},
       includeColors: ${validated.includeColors !== false},
@@ -3531,8 +3753,9 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
   }
 
   try {
-    const result = app.mapSystem.importRegionCSV({
-      csvText: \`${escapedCsv}\`,
+    // importRegionDataCSV(csvText, options) — the TEXT is positional, and it
+    // was being passed inside the options bag where nothing read it.
+    const result = app.mapSystem.importRegionDataCSV(\`${escapedCsv}\`, {
       applyColors: ${validated.applyColors !== false},
       applyHighlight: ${validated.applyHighlight !== false},
       applySelection: ${validated.applySelection !== false}
@@ -3841,7 +4064,15 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
         if (item.strokeColor) itemData.properties.strokeColor = item.strokeColor.toCSS ? item.strokeColor.toCSS() : item.strokeColor;
         if (item.strokeWidth) itemData.properties.strokeWidth = item.strokeWidth;
         if (item.opacity !== undefined) itemData.properties.opacity = item.opacity;
-        if (item.rotation) itemData.properties.rotation = item.rotation;
+        // TRUE ROTATION, not the property. create() BAKES an angle into the path
+        // segments under Paper's applyMatrix default, so item.rotation reads back 0 on
+        // an item that is visibly rotated. Reporting that 0 is why "I could not rotate
+        // a rectangle" was filed against an engine that rotates correctly. The engine
+        // records the baked offset at item.data._bakedRotation and sums the two itself
+        // (PinePaper.js does exactly this); read the same sum rather than the half of
+        // it that happens to be zero.
+        const _rot = (item.data?._bakedRotation || 0) + (item.rotation || 0);
+        if (_rot) itemData.properties.rotation = _rot;
         if (item.data?.content) itemData.properties.content = item.data.content;
         if (item.visible === false) itemData.properties.visible = false;
 
@@ -3895,7 +4126,7 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
     }
 
     // Get background color and canvas size
-    const backgroundColor = app.getBackgroundColor ? app.getBackgroundColor() : null;
+    const backgroundColor = app.canvasEl?.style?.backgroundColor || null;
     const canvasSize = app.getCanvasSize ? app.getCanvasSize() : { width: 800, height: 600 };
 
     return {
@@ -3959,10 +4190,15 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
   }
 
   try {
-    const result = app.mapSystem.exportOriginalGeoJSON({
-      download: ${download},
-      filename: ${JSON.stringify(filename)}
-    });
+    // Two methods, not one with a flag: getOriginalGeoJSON() returns the data,
+    // downloadOriginalGeoJSON(filename) hands it to the browser.
+    // exportOriginalGeoJSON has never existed.
+    const result = ${download}
+      ? app.mapSystem.downloadOriginalGeoJSON(${JSON.stringify(filename)})
+      : app.mapSystem.getOriginalGeoJSON();
+    if (result === null || result === undefined) {
+      return { success: false, error: 'no map is loaded, so there is no source GeoJSON to return' };
+    }
     return result;
   } catch (error) {
     return { success: false, error: error.message };
@@ -3982,7 +4218,7 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
   }
 
   try {
-    const result = app.mapSystem.getSourceInfo();
+    const result = app.mapSystem.getMapSourceInfo();
     return result;
   } catch (error) {
     return { success: false, error: error.message };
@@ -4079,9 +4315,25 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
     generateExecuteCustomCode(input) {
         const validated = ExecuteCustomCodeInputSchema.parse(input);
         const description = validated.description || 'Execute custom code';
+        // ASYNC, because the code inside is not ours.
+        //
+        // This wrapped the caller's snippet in a SYNC IIFE, which does two things
+        // to async work. A top-level `await` is a syntax error inside a
+        // non-async function, so a snippet that awaits anything fails to parse at
+        // all. And async work started without await returns a promise nobody
+        // holds: the IIFE returns immediately, the tool reports success, and the
+        // next call reads a canvas where the work has not happened yet.
+        //
+        // That is the whole async half of the engine — export, image import,
+        // rigging bake, layout — unreachable from the one tool whose entire
+        // purpose is reaching things the tool surface does not cover.
+        //
+        // An async IIFE is still a `(`-led expression statement, so the governor
+        // captures its value, and executeCode's eval fallback already resolves a
+        // returned promise. Both paths await it; neither needed changing.
         return `
 // ${description}
-(function() {
+(async function() {
   try {
     ${validated.code}
   } catch (error) {
@@ -4335,7 +4587,41 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
     return { error: 'Image tools not available. Make sure PinePaper Studio is loaded.' };
   }
   try {
-    const entry = await app.imageTools.uploadFromURL('${url}');
+    // FETCH IT OURSELVES FIRST, to find out WHY when it fails.
+    //
+    // uploadFromURL sets img.src and rejects with a bare "Failed to load image
+    // from URL" — an <img> onerror genuinely carries no reason, so that message
+    // is the browser's limit rather than the engine being unhelpful. fetch()
+    // has the reason: a status code, a CORS rejection, a refused connection, a
+    // DNS failure. A caller cannot debug what the tool will not show them.
+    //
+    // The bytes then go in as a DATA URL, which img.src loads without touching
+    // the network again — so a host that allows fetch but blocks the image
+    // load (CORS on <img>, a tainted-canvas refusal) now works too.
+    let src = '${url}';
+    if (!src.startsWith('data:')) {
+      let res;
+      try {
+        res = await fetch(src);
+      } catch (netErr) {
+        return { success: false, error: 'could not reach ' + src + ' — ' + (netErr && netErr.message ? netErr.message : 'network request failed')
+          + '. This is the browser\'s network stack: check the host resolves, the port is open, and that any proxy passes plain HTTP as well as HTTPS CONNECT.' };
+      }
+      if (!res.ok) {
+        return { success: false, error: 'the server refused ' + src + ' — HTTP ' + res.status + ' ' + (res.statusText || ''), status: res.status };
+      }
+      const blob = await res.blob();
+      if (!blob.type.startsWith('image/')) {
+        return { success: false, error: src + ' returned ' + (blob.type || 'an unknown content type') + ', not an image. Check the URL serves the file itself rather than a web page around it.', contentType: blob.type };
+      }
+      src = await new Promise((resolve, reject) => {
+        const fr = new FileReader();
+        fr.onloadend = () => resolve(fr.result);
+        fr.onerror = () => reject(new Error('could not read the downloaded image'));
+        fr.readAsDataURL(blob);
+      });
+    }
+    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
@@ -5313,8 +5599,23 @@ ${resolve}
 (function() {
   const itemIds = ${JSON.stringify(input.itemIds || [])};
   const opts = ${JSON.stringify(opts)};
-  const precomp = app.createPrecomp(itemIds, opts);
-  return { success: true, action: 'create', precompId: precomp?.id || precomp, name: ${JSON.stringify(input.name || '')} };
+
+  // createPrecomp wants LIVE ITEMS. Handing it registry ids put strings into
+  // Paper.js's insertChildren, which fails as "l._remove is not a function" —
+  // a minified internal, from a schema that promises ids work. Resolved here,
+  // and a missing one is named rather than silently dropped from the group.
+  const items = [];
+  const missing = [];
+  for (const id of itemIds) {
+    const item = app.getItemById(id);
+    if (item) items.push(item); else missing.push(id);
+  }
+  if (missing.length) return { success: false, error: 'precomp: no such item(s): ' + missing.join(', ') };
+  if (!items.length) return { success: false, error: 'precomp needs at least one item' };
+
+  const precomp = app.createPrecomp(items, opts);
+  if (!precomp) return { success: false, error: 'createPrecomp returned nothing' };
+  return { success: true, action: 'create', precompId: precomp?.id || precomp, itemCount: items.length, name: ${JSON.stringify(input.name || '')} };
 })();`.trim();
             }
             case 'add':
@@ -5406,7 +5707,7 @@ ${resolve}
     bounds: item.bounds ? { x: item.bounds.x, y: item.bounds.y, width: item.bounds.width, height: item.bounds.height } : null,
     visible: item.visible,
     opacity: item.opacity,
-    rotation: item.rotation,
+    rotation: (item.data?._bakedRotation || 0) + (item.rotation || 0),
     selected: item.selected,
   };
 })();`.trim();
@@ -5742,7 +6043,11 @@ ${resolve}
     // SPRITE SHEETS
     // ===========================================================================
     generateSpriteSheet(input) {
-        const guard = `if (!app.spriteSheetSystem) return { error: 'SpriteSheetSystem not available' };`;
+        // spriteSystem is _defineLazyHeavy: undefined until ensureHeavyModules()
+        // lands, so the bare guard reported "not available" on a fresh session for
+        // a studio that has it. Same bug as app.exportEngine in 1.6.9.
+        const guard = `if (!app.spriteSystem && typeof app.ensureHeavyModules === 'function') { try { await app.ensureHeavyModules(); } catch (_) {} }
+if (!app.spriteSystem) return { error: 'SpriteSheetSystem not available' };`;
         switch (input.action) {
             case 'generate': {
                 const opts = {};
@@ -5762,7 +6067,7 @@ ${resolve}
 // Generate sprite sheet from skeleton
 (async function() {
   ${guard}
-  const sheet = await app.spriteSheetSystem.generateSpriteSheet(${JSON.stringify(input.skeletonId || '')}, ${JSON.stringify(opts)});
+  const sheet = await app.generateSpriteSheet(${JSON.stringify(input.skeletonId || '')}, ${JSON.stringify(opts)});
   return { success: true, action: 'generate', spriteSheetId: sheet.id, name: sheet.name, width: sheet.atlasWidth, height: sheet.atlasHeight, frameCount: sheet.frames?.size ?? sheet.frames?.length ?? 0 };
 })();`.trim();
             }
@@ -5782,7 +6087,7 @@ ${resolve}
 // Play sprite sheet animation
 (async function() {
   ${guard}
-  const player = await app.spriteSheetSystem.playSpriteSheet(${JSON.stringify(input.spriteSheetId || '')}, ${JSON.stringify(opts)});
+  const player = await app.playSpriteSheet(${JSON.stringify(input.spriteSheetId || '')}, ${JSON.stringify(opts)});
   return { success: true, action: 'play', playerId: player.id };
 })();`.trim();
             }
@@ -5791,7 +6096,7 @@ ${resolve}
 // Export sprite sheet
 (async function() {
   ${guard}
-  const result = await app.spriteSheetSystem.exportSpriteSheet(${JSON.stringify(input.spriteSheetId || '')}, { format: '${input.format || 'png'}', download: true, includeMetadata: true });
+  const result = await app.exportSpriteSheet(${JSON.stringify(input.spriteSheetId || '')}, { format: '${input.format || 'png'}', download: true, includeMetadata: true });
   return { success: true, action: 'export', format: '${input.format || 'png'}' };
 })();`.trim();
             default:
@@ -6149,7 +6454,8 @@ ${resolve}
 // Toggle rulers
 (function() {
   ${guard}
-  app.measurementSystem.setRulersVisible(${enabled});
+  // showRulers()/hideRulers(), not a boolean setter — setRulersVisible never existed.
+  app.measurementSystem[${enabled} ? 'showRulers' : 'hideRulers']();
   return { success: true, action: 'set_rulers', enabled: ${enabled} };
 })();`.trim();
             }
@@ -6159,7 +6465,8 @@ ${resolve}
 // Toggle grid
 (function() {
   ${guard}
-  app.measurementSystem.setGridVisible(${enabled});
+  // showGrid()/hideGrid(), not a boolean setter — setGridVisible never existed.
+  app.measurementSystem[${enabled} ? 'showGrid' : 'hideGrid']();
   return { success: true, action: 'set_grid', enabled: ${enabled} };
 })();`.trim();
             }
@@ -6174,17 +6481,21 @@ ${resolve}
   const entry = app.itemRegistry.get(${itemIdStr});
   if (!entry || !entry.item) return { error: 'Item not found: ' + ${itemIdStr} };
   const b = entry.item.bounds;
-  return { success: true, action: 'get_dimensions', itemId: ${itemIdStr}, x: b.x, y: b.y, width: b.width, height: b.height, rotation: entry.item.rotation || 0 };
+  return { success: true, action: 'get_dimensions', itemId: ${itemIdStr}, x: b.x, y: b.y, width: b.width, height: b.height, rotation: (entry.item.data?._bakedRotation || 0) + (entry.item.rotation || 0) };
 })();`.trim();
             }
             case 'set_snap': {
-                const enabled = input.enabled !== false;
+                // `enabled` is deliberately unread: there is no mode to set either way.
                 return `
-// Toggle snap to grid
+// Snap to grid — refused, see below
 (function() {
   ${guard}
-  app.measurementSystem.setSnapToUnitEnabled(${enabled});
-  return { success: true, action: 'set_snap', enabled: ${enabled} };
+  // NO EQUIVALENT. MeasurementSystem publishes snapCoordinate(), which snaps a
+  // coordinate you hand it, and nothing that turns snapping on as a mode —
+  // setSnapToUnitEnabled has never existed, so this reported success over a
+  // setting that was never changed. Refused by name, with the thing that works.
+  return { success: false, action: 'set_snap',
+    error: 'this build has no snap-to-unit MODE to switch: the measurement system snaps a coordinate on request rather than holding a setting. Snap positions yourself before creating or moving items, or set a grid with the grid action and place on its multiples.' };
 })();`.trim();
             }
             default:
@@ -6696,8 +7007,19 @@ ${guard}
   const r = app.setFontAxes(${S(input.itemId)}, ${S(input.axes)});
   if (!r || !r.ok) { return { success: false, error: (r && r.error) || 'axes failed' }; }
   // rejected is the interesting half: an axis silently ignored is the failure
-  // mode this surface exists to prevent.
-  return { success: true, action: 'set_font_axes', applied: r.applied, rejected: r.rejected || [] };
+  // mode this surface exists to prevent. And NOTHING applied while something
+  // was rejected is not a success — it is the call doing nothing under a
+  // success, which is the same shape as an empty batch reporting ok.
+  const _applied = r.applied || {};
+  const _rejected = r.rejected || [];
+  const _appliedCount = Array.isArray(_applied) ? _applied.length : Object.keys(_applied).length;
+  if (_appliedCount === 0 && _rejected.length) {
+    return { success: false, action: 'set_font_axes', applied: _applied, rejected: _rejected,
+      error: 'no axis was applied. The font does not have: ' + _rejected.join(', ')
+        + (r.note ? '. ' + r.note : '') };
+  }
+  return { success: true, action: 'set_font_axes', applied: _applied, rejected: _rejected,
+    ...(r.note ? { note: r.note } : {}) };
 })();`.trim();
             }
             case 'list_styles': {
@@ -7540,7 +7862,15 @@ ${needWorld}
   if (typeof app.storyFromText !== 'function') { return { success: false, error: 'app.storyFromText unavailable — update FxTool' }; }
   const r = await app.storyFromText(${S(input.text)}, ${opts});
   if (!r || r.ok === false) { return { success: false, error: (r && (r.reason || r.error)) || 'the story did not assemble' }; }
-  return { success: true, ...r };
+  // NAMED FIELDS, not a spread. assembleStory returns its parts as live Paper
+  // Groups, and a Paper item's graph reaches the editor's EVENT HANDLERS.
+  // Structured clone — which is what the bridge uses — refuses to carry a
+  // function, so the whole result threw DataCloneError and the message did not
+  // survive the wrapping: an empty error string for a story that assembled
+  // fine in-page. Not a cycle; JSON.stringify succeeded on this the whole time.
+  // The groups have to stay for in-page callers, so the wrapper takes what
+  // travels: the spec, the ids, the count.
+  return { success: true, spec: r.spec, partIds: r.partIds, partCount: r.partCount, beats: r.beats };
 })();`.trim();
             case 'apply_spec':
                 return `
@@ -7964,11 +8294,23 @@ ${guard('unlockAllItems')}${pass('app.unlockAllItems()')}
   return { success: true, action: 'create_skeleton', skeletonId: skeletonId };`);
             }
             case 'add_bone': {
+                // DEGREES IN, RADIANS OUT. The schema says degrees and every other
+                // angle on this surface is degrees, but RiggingSystem stores what it is
+                // given and _solveFKRecursive feeds it straight to Math.cos/Math.sin.
+                // So a documented 90 was read as 90 radians and the character exploded
+                // on the first pose — silently, because a wrong pose is not an error.
+                // Converted here so the tool keeps the vocabulary it advertises.
+                // BOTH SPELLINGS, deliberately. The engine's _angleRad prefers
+                // `angleDegrees` and converts it, so the new build reads the caller's
+                // intent verbatim instead of trusting arithmetic done out here. `angle`
+                // carries the same value already in radians, which is what an older
+                // build reads — it has no angleDegrees and would see 0. Identical
+                // result on both, and the units are stated rather than implied.
                 const config = S({
                     ...(input.name !== undefined ? { name: input.name } : {}),
                     ...(input.parentBoneId !== undefined ? { parentBoneId: input.parentBoneId } : {}),
                     ...(input.length !== undefined ? { length: input.length } : {}),
-                    ...(input.angle !== undefined ? { angle: input.angle } : {}),
+                    ...(input.angle !== undefined ? { angleDegrees: input.angle, angle: (input.angle * Math.PI) / 180 } : {}),
                     ...(input.flexibility !== undefined ? { flexibility: input.flexibility } : {}),
                     ...(input.segments !== undefined ? { segments: input.segments } : {}),
                 });
@@ -8008,7 +8350,15 @@ ${guard('unlockAllItems')}${pass('app.unlockAllItems()')}
                     ...(input.movingHold !== undefined ? { movingHold: input.movingHold } : {}),
                     ...(input.holdDrift !== undefined ? { holdDrift: input.holdDrift } : {}),
                 });
-                return wrap('Rigging: add pose keyframe', `  const ok = R.addPoseKeyframe(${S(input.skeletonId)}, ${input.time}, ${S(input.pose)}, ${S(input.easing ?? 'linear')}, ${opts});
+                // Same unit conversion as add_bone: an inline pose is { boneId: angleDeg }
+                // by the schema, and the solver reads radians. A SAVED pose is a string
+                // id and is passed through untouched — those angles are already in the
+                // engine's own units.
+                const poseArg = (input.pose !== null && typeof input.pose === 'object')
+                    ? S(Object.fromEntries(Object.entries(input.pose)
+                        .map(([bone, deg]) => [bone, (deg * Math.PI) / 180])))
+                    : S(input.pose);
+                return wrap('Rigging: add pose keyframe', `  const ok = R.addPoseKeyframe(${S(input.skeletonId)}, ${input.time}, ${poseArg}, ${S(input.easing ?? 'linear')}, ${opts});
   if (app.historyManager) app.historyManager.saveState();
   if (!ok) { return { success: false, action: 'add_pose_keyframe', error: "no such skeleton, or 'pose' named a saved pose that does not exist. Pass an inline { boneId: angleDeg } map instead, or list_poses for the saved ones" }; }
   return { success: true, action: 'add_pose_keyframe', time: ${input.time} };`);