@pinepaper.studio/mcp-server 1.6.9 → 1.6.11

package/dist/types/code-generator.js

@@ -181,12 +181,27 @@ app.historyManager.saveState();
  */
 function generateModifyItemCode(itemId, properties) {
     const { contentType, contentFormat, countdownTarget, countdownEndText, ...restProperties } = properties;
+    // modifyItem(id, changes), NOT select() + modify().
+    //
+    // modify() operates on the SELECTION, so this selected an id and then edited
+    // whatever was selected — on an id that does not resolve, select changes
+    // nothing and modify edits the PREVIOUS selection instead. modifyItem takes
+    // the reference and returns false when it cannot resolve it, which is the
+    // answer this emitter needs and never asked for.
+    //
+    // The warning the engine logs on that path is console.warn, which production
+    // strips, so the failure was invisible twice over.
     let code = `
 // Modify item ${itemId}
-app.select('${itemId}');`;
-    // Pass non-dynamic-content properties to app.modify
+let _modified = true;`;
     if (Object.keys(restProperties).length > 0) {
-        code += `\napp.modify(${JSON.stringify(restProperties, null, 2)});`;
+        code += `
+_modified = app.modifyItem('${itemId}', ${JSON.stringify(restProperties, null, 2)}) !== false;
+if (!_modified) { return { success: false, error: 'no item ${itemId} — nothing was modified' }; }`;
+    }
+    else {
+        code += `
+if (!app.getItemById('${itemId}')) { return { success: false, error: 'no item ${itemId}' }; }`;
     }
     // Handle dynamic content type changes
     if (contentType !== undefined) {
@@ -212,10 +227,10 @@ if (entry && entry.item && app.setDynamicContent) app.setDynamicContent(entry.it
     }
     code += `
 app.historyManager.saveState();
-
-// Return success
-({ success: true, itemId: '${itemId}' });`;
-    return code.trim();
+return { success: true, itemId: '${itemId}' };`;
+    // Wrapped, because the body now RETURNS early on a miss rather than falling
+    // through to an unconditional success.
+    return `(function() {\n${code.trim()}\n})();`;
 }
 /**
  * Template for deleting items
@@ -675,9 +690,24 @@ function generateSetCanvasSizeCode(width, height, preset) {
         : `{ width: ${width}, height: ${height} }`;
     return `
 // Set canvas size
-app.setCanvasSize(${sizeArg});
-app.historyManager.saveState();
-({ success: true, width: ${width}, height: ${height} });
+(function() {
+  // READ THE VERDICT. This called setCanvasSize and then declared success with
+  // the dimensions it had ASKED for — so an unknown preset, or a width of -5,
+  // came back as a successful resize while the canvas was left exactly as it
+  // was. The engine now refuses by name; older builds return undefined, which
+  // is not a refusal and must not be read as one.
+  const r = app.setCanvasSize(${sizeArg});
+  if (r && r.ok === false) {
+    return { success: false, error: r.reason || 'the canvas size was refused',
+      ...(r.known ? { knownPresets: r.known } : {}) };
+  }
+  app.historyManager.saveState();
+  // Report what the canvas ACTUALLY took where the engine says so, rather than
+  // echoing the request back.
+  return { success: true, width: (r && r.width) || ${width}, height: (r && r.height) || ${height},
+    ...(r && r.preset ? { preset: r.preset } : {}),
+    ...(r && r.unbounded !== undefined ? { unbounded: r.unbounded } : {}) };
+})();
 `.trim();
 }
 /**
@@ -886,19 +916,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();
 }
 /**
@@ -1203,19 +1250,33 @@ export class PinePaperCodeGenerator {
         if (url) {
             return `
 // Import SVG from URL${source === 'figma' ? ' (Figma-normalised)' : ''}
-const response = await fetch('${url}');
-const svgText = await response.text();
-const _r = ${importExpr('svgText')};
-const imported = _r.item;
-if (imported) {
+// WRAPPED, because these were bare top-level statements with an await. That
+// parses under the governor, which builds an AsyncFunction, and is a SYNTAX
+// ERROR on the eval fallback — so importing an SVG by URL never ran at all on
+// a studio without runGenerated. A paren-led async IIFE parses on both and
+// still gives the governor a trailing expression to capture.
+(async function() {
+  let response;
+  try {
+    response = await fetch('${url}');
+  } catch (netErr) {
+    return { success: false, error: 'could not reach ${url} — ' + ((netErr && netErr.message) || 'network request failed') };
+  }
+  if (!response.ok) {
+    return { success: false, error: 'the server refused ${url} — HTTP ' + response.status + ' ' + (response.statusText || ''), status: response.status };
+  }
+  const svgText = await response.text();
+  const _r = ${importExpr('svgText')};
+  const imported = _r.item;
+  if (!imported) {
+    return { success: false, error: 'the response from ${url} did not parse as SVG. Check the URL serves the file itself rather than a page around it.' };
+  }
   imported.position = new paper.Point(${position.x}, ${position.y});
   imported.scale(${scale});
   const itemId = app.registerItem(imported, 'svg-import', { source: 'mcp' });
   app.historyManager.saveState();
-  ({ success: true, itemId, changes: _r.changes, position: { x: ${position.x}, y: ${position.y} } });
-} else {
-  throw new Error('Failed to import SVG from URL');
-}
+  return { success: true, itemId, changes: _r.changes, position: { x: ${position.x}, y: ${position.y} } };
+})();
 `.trim();
         }
         if (svgString) {
@@ -1255,12 +1316,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 || [],
   };
 })();
@@ -1575,8 +1665,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();
 }
 `);
         }
@@ -1713,8 +1806,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},
@@ -1722,7 +1816,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();
 
@@ -1766,7 +1861,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();
 
@@ -1794,7 +1889,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
@@ -1811,21 +1906,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();
     }
     /**
@@ -1838,13 +1943,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();
     }
     /**
@@ -1857,7 +1975,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();
@@ -1885,10 +2006,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();
     }
     /**
@@ -1902,7 +2057,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 });
@@ -1918,19 +2073,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':
@@ -1938,7 +2093,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:
@@ -2097,7 +2252,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');
   }
@@ -2226,6 +2381,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;
@@ -2250,10 +2416,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;'}
@@ -2265,7 +2445,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 } };
@@ -2322,8 +2509,12 @@ return { itemId };
                 const modifyProps = JSON.stringify(op.properties || {});
                 return `
 const targetId = ${itemRef};
-app.select(targetId);
-app.modify(${modifyProps});
+// 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 };
 `;
             case 'animate':
@@ -2398,9 +2589,16 @@ return { success: true, generator: '${genName}'${op.generatorRegion ? ', region:
                 const h = op.height || 1080;
                 const sizeArg = op.preset ? `'${op.preset}'` : `{ width: ${w}, height: ${h} }`;
                 return `
-app.setCanvasSize(${sizeArg});
+// Read the verdict, as the standalone tool now does: an unknown preset or an
+// out-of-range dimension is refused by name, and reporting the size we ASKED
+// for left the batch claiming a resize that never happened.
+const _cs = app.setCanvasSize(${sizeArg});
+if (_cs && _cs.ok === false) {
+  return { success: false, error: _cs.reason || 'the canvas size was refused',
+    ...(_cs.known ? { knownPresets: _cs.known } : {}) };
+}
 await new Promise(r => setTimeout(r, 50));
-return { success: true, width: ${w}, height: ${h} };
+return { success: true, width: (_cs && _cs.width) || ${w}, height: (_cs && _cs.height) || ${h} };
 `;
             }
             case 'keyframe_animate': {
@@ -2457,7 +2655,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'}' };
 `;
             }
@@ -2551,7 +2757,7 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
     }
     generateAgentExport(input) {
         const validated = AgentExportInputSchema.parse(input);
-        const { platform, format, quality, framing, duration, estimateOnly, scale } = 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)
@@ -2669,7 +2875,11 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
   const format = '${exportFormat}';
   const quality = '${qualityLevel}';
   const framing = '${framing}';
-  const settings = ${JSON.stringify(qualitySettings)};
+  // 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.
@@ -2736,7 +2946,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,
@@ -2991,7 +3201,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');
   }
@@ -3525,7 +3735,7 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
   }
 
   try {
-    app.mapSystem.stopAnimations({
+    app.mapSystem.stopRegionAnimations({
       regions: ${regionsStr},
       resetColors: ${validated.resetColors !== false}
     });
@@ -3569,7 +3779,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},
@@ -3598,8 +3808,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}
@@ -3908,7 +4119,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 = typeof app.authoredRotation === 'function' ? app.authoredRotation(item) : ((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;
 
@@ -3962,7 +4181,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 {
@@ -4026,10 +4245,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 };
@@ -4049,7 +4273,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 };
@@ -4146,9 +4370,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) {
@@ -4248,6 +4488,33 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
   }
 })();
 `.trim();
+    }
+    /**
+     * What THIS item can animate, from the engine's own table.
+     *
+     * The table is derived from the applier rather than written beside it, so it
+     * cannot drift from what actually gets applied — and it is filtered by item
+     * type, because the trim/dash four only exist on a path and a rectangle has
+     * no fontSize.
+     *
+     * `interpolates: false` is passed through VERBATIM and never flattened away.
+     * `content` and `blendMode` are DISCRETE — they hold their value until the
+     * next keyframe rather than blending toward it — and treating content as
+     * tweenable is what made every word in a cycler appear half a beat early.
+     * A list that says only "animatable" rebuilds that bug in the next agent.
+     */
+    generateListItemAnimatableProperties(itemId) {
+        return `
+// Animatable properties of ${JSON.stringify(itemId)}
+(function() {
+  if (typeof app.listAnimatableProperties !== 'function') {
+    return { success: false, error: 'app.listAnimatableProperties unavailable — update the studio. The keyframe tool lists the properties it accepts in its own description meanwhile.' };
+  }
+  const item = app.getItemById(${JSON.stringify(itemId)});
+  if (!item) { return { success: false, error: 'no item ${itemId}' }; }
+  const r = app.listAnimatableProperties(item);
+  return { success: true, ...r };
+})();`.trim();
     }
     generateGetAnimatableProperties() {
         return `
@@ -4402,7 +4669,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
@@ -4610,7 +4911,21 @@ ${mask ? `    app.imageTools.applyMask(raster, '${mask}');\n` : ''}    // The RE
 // Toggle loop mode
 (function() {
   ${guard}
-  app.sceneManager.setLoop(${input.enabled ?? true});
+  // chainLoop is a PROPERTY, set by createChain({loop}) and read by the chain
+  // advance. setLoop has never existed, so this reported a toggle it had not
+  // performed — and a chain built without loop went on not looping.
+  if (typeof app.sceneManager.setLoop === 'function') {
+    app.sceneManager.setLoop(${input.enabled ?? true});
+  } else if ('chainLoop' in app.sceneManager) {
+    app.sceneManager.chainLoop = ${input.enabled ?? true};
+  } else {
+    return { success: false, action: 'toggle_loop',
+      error: 'this build has no chain-loop control to set. Pass loop:true to create_chain instead, which is where the setting is read from.' };
+  }
+  if (!app.sceneManager.sceneChain || !app.sceneManager.sceneChain.length) {
+    return { success: true, action: 'toggle_loop', enabled: ${input.enabled ?? true},
+      note: 'no chain exists yet — this setting applies to the next one created, and create_chain takes loop directly.' };
+  }
   return { success: true, action: 'toggle_loop', enabled: ${input.enabled ?? true} };
 })();
 `.trim();
@@ -5380,8 +5695,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':
@@ -5473,7 +5803,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: typeof app.authoredRotation === 'function' ? app.authoredRotation(item) : ((item.data?._bakedRotation || 0) + (item.rotation || 0)),
     selected: item.selected,
   };
 })();`.trim();
@@ -5809,7 +6139,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 = {};
@@ -5829,7 +6163,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();
             }
@@ -5849,7 +6183,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();
             }
@@ -5858,7 +6192,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:
@@ -6216,7 +6550,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();
             }
@@ -6226,7 +6561,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();
             }
@@ -6241,17 +6577,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: typeof app.authoredRotation === 'function' ? app.authoredRotation(entry.item) : ((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:
@@ -6746,10 +7086,25 @@ ${guard}
                 });
                 return `
 // Display text style: ${input.styleKey} — stacked-layer title, id adopted from the text
-(function() {
+(async function() {
   if (typeof app.applyTextStyle !== 'function') { return { success: false, error: 'app.applyTextStyle unavailable — update FxTool to a text-styles build' }; }
+  // LOAD THE FACES FIRST. The decorative stylesheet is fetched on pointerenter
+  // over the style grid — a gesture no agent ever makes — so every decorative
+  // family was missing in production and a style asking for one silently drew
+  // the fallback and reported success. ensureFontsLoaded is the fix; guarded,
+  // because a studio without it behaves as it always did.
+  if (typeof app.ensureFontsLoaded === 'function') {
+    try { await app.ensureFontsLoaded('decorative'); } catch (_) { /* the pending flag below still reports it */ }
+  }
   const r = app.applyTextStyle(${S(input.itemId)}, ${S(input.styleKey)}, ${opts});
   if (!r || !r.ok) { return { success: false, error: (r && r.error) || 'style failed' }; }
+  // fontPending: the face is not there YET, so this drew in the fallback. Said
+  // out loud rather than left to be discovered in the export.
+  if (r.fontPending) {
+    return { success: true, action: 'apply_style', id: r.id, style: r.style, layers: r.layers,
+      palette: r.palette, bounds: r.bounds, fontPending: true,
+      warning: 'the face for this style had not loaded, so it drew in a FALLBACK font. Re-apply the style, or call pinepaper_font check with the family and your text to see what is really being used.' };
+  }
   // The styled group ADOPTS the text item's registry id — r.id is the SAME id
   // the caller passed, so their handle keeps working. Say so in the result.
   return { success: true, action: 'apply_style', id: r.id, style: r.style, layers: r.layers, palette: r.palette, bounds: r.bounds };
@@ -6763,8 +7118,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': {
@@ -7607,7 +7973,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 `
@@ -8031,11 +8405,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 } : {}),
                 });
@@ -8075,7 +8461,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} };`);