@pinepaper.studio/mcp-server 1.6.19 → 1.6.20

package/dist/types/code-generator.js

@@ -4,12 +4,13 @@
  * Converts MCP tool inputs to executable PinePaper JavaScript code.
  * This code is designed to run in the browser context where window.PinePaper is available.
  */
+import { compileChoreography } from '../tools/choreograph.js';
 import { normalizeSvgSize } from '../utils/svg-size.js';
 import { WORLD3D_COLOR_PATHS } from '../tools/engine-lists.js';
 import { REQUIRED_ENGINE_METHODS, OPTIONAL_ENGINE_METHODS } from '../tools/engine-methods.js';
 import { ACCEPTED_CREATE_PARAMS, NORMALIZE_PARAM_READS, MODIFY_CHANGE_READS } from '../tools/shape-params.js';
 import { generateP5DrawCode } from '../tools/p5-compat/p5-helpers.js';
-import { CreateItemInputSchema, ImportMotionCaptureInputSchema, ModifyItemInputSchema, AddRelationInputSchema, AnimateItemInputSchema, KeyframeAnimateInputSchema, ExecuteGeneratorInputSchema, ApplyEffectInputSchema, SetBackgroundColorInputSchema, SetCanvasSizeInputSchema, CreateGlossySphereInputSchema, CreateDiagonalStripesInputSchema, BatchCreateInputSchema, BatchModifyInputSchema, CreateGridInputSchema, CreateSceneInputSchema, 
+import { CreateItemInputSchema, ScreenSpaceSchema, StepTimingSchema, CounterSchema, ImportMotionCaptureInputSchema, ModifyItemInputSchema, AddRelationInputSchema, AnimateItemInputSchema, KeyframeAnimateInputSchema, ExecuteGeneratorInputSchema, ApplyEffectInputSchema, SetBackgroundColorInputSchema, SetCanvasSizeInputSchema, CreateGlossySphereInputSchema, CreateDiagonalStripesInputSchema, BatchCreateInputSchema, BatchModifyInputSchema, CreateGridInputSchema, CreateSceneInputSchema, 
 // Diagram types
 CreateDiagramShapeInputSchema, ConnectInputSchema, ConnectPortsInputSchema, AddPortsInputSchema, AutoLayoutInputSchema, GetDiagramShapesInputSchema, UpdateConnectorInputSchema, RemoveConnectorInputSchema, DiagramModeInputSchema, 
 // Agent flow mode types
@@ -1955,6 +1956,108 @@ export function planKeyframeMerges(operations) {
  * Such a snippet's value is its last top-level (-led statement; the
  * font-loading form is an async IIFE, which is awaited instead.
  */
+/**
+ * The active brand's defaults for a new item (D69): only what the caller did
+ * not name. Closed shapes take colors.primary; text takes colors.text (or
+ * primary) and the heading font from 32 px up, else the body font. Applied
+ * through modifyItem after create, so the engine's own bookkeeping runs.
+ */
+const BRAND_FILL_TYPES = new Set(['circle', 'star', 'rectangle', 'triangle', 'polygon', 'ellipse', 'pentagon', 'hexagon', 'diamond', 'arrow', 'heart']);
+function withBrandDefaults(code, itemType, props) {
+    if (props.noBrand === true)
+        return code;
+    const isText = itemType === 'text';
+    if (!isText && !BRAND_FILL_TYPES.has(itemType))
+        return code;
+    const hasColor = ['color', 'fillColor', 'fill'].some((k) => props[k] !== undefined);
+    const hasFont = props.fontFamily !== undefined;
+    if (hasColor && (!isText || hasFont))
+        return code;
+    const size = typeof props.fontSize === 'number' ? props.fontSize : 36;
+    const anchor = 'const itemId = item.data.registryId;';
+    if (!code.includes(anchor))
+        return code;
+    const patch = `
+// Active brand (D69): fill in what this call did not name.
+const __bk = (typeof window !== 'undefined' && window.__ppActiveBrand) || null;
+let __brand = null;
+if (__bk && __bk.colors && app.modifyItem) {
+  const __bm = {};
+  ${hasColor ? '' : `__bm.color = ${isText ? '__bk.colors.text || __bk.colors.primary' : '__bk.colors.primary'};`}
+  ${isText && !hasFont ? `const __f = __bk.fonts && (${size >= 32 ? '__bk.fonts.heading || __bk.fonts.body' : '__bk.fonts.body || __bk.fonts.heading'}); if (__f) __bm.fontFamily = __f;` : ''}
+  if (Object.keys(__bm).length) { app.modifyItem(itemId, __bm); __brand = __bm; }
+}`;
+    return code.replace(anchor, anchor + patch).replace(/\(\{ itemId, type:/, '({ itemId, ...(__brand ? { brand: __brand } : {}), type:');
+}
+const ITEM_SETTERS = [
+    { key: 'screenSpace', fn: 'setScreenSpace', what: 'screen-space (HUD) items', since: 'D20' },
+    { key: 'stepTiming', fn: 'setStepTiming', what: 'step timing', since: 'D11' },
+    { key: 'counter', fn: 'setCounter', what: 'counters', since: 'D70' },
+];
+/** Lift screenSpace / hud / stepTiming out of a properties bag (mutated), explicit fields winning. */
+function takeItemSetters(props, explicit = {}) {
+    const out = {};
+    // From properties a caller may write hud: 1; it means on. The top-level
+    // field is still a strict boolean.
+    const ss = explicit.screenSpace ?? (props.screenSpace ?? props.hud);
+    if (ss !== undefined)
+        out.screenSpace = explicit.screenSpace !== undefined ? ScreenSpaceSchema.parse(ss) : !!ss;
+    const st = explicit.stepTiming !== undefined ? explicit.stepTiming : props.stepTiming;
+    if (st !== undefined)
+        out.stepTiming = StepTimingSchema.parse(st);
+    // A counter from properties is lifted only when it is a valid spec; anything
+    // else stays where it was, for the engine to read and refuse by name.
+    let liftCounter = explicit.counter !== undefined;
+    if (liftCounter)
+        out.counter = CounterSchema.parse(explicit.counter);
+    else if (props.counter !== undefined && CounterSchema.safeParse(props.counter).success) {
+        out.counter = props.counter;
+        liftCounter = true;
+    }
+    delete props.screenSpace;
+    delete props.hud;
+    delete props.stepTiming;
+    if (liftCounter)
+        delete props.counter;
+    return out;
+}
+function hasItemSetters(s) {
+    return s.screenSpace !== undefined || s.stepTiming !== undefined || s.counter !== undefined;
+}
+/** Statements: refuse, before anything changes, when a requested setter is missing. */
+function itemSettersPreflightJs(s) {
+    return ITEM_SETTERS.filter((d) => s[d.key] !== undefined).map((d) => `  if (typeof app.${d.fn} !== 'function') { return { success: false, error: 'this studio has no ${d.what} (app.${d.fn}) — it predates FxTool ${d.since}; nothing was changed.' }; }`).join('\n');
+}
+/** Statements: apply each setter to idExpr, folding the verdict into resVar. */
+function itemSettersApplyJs(s, idExpr, resVar) {
+    return ITEM_SETTERS.filter((d) => s[d.key] !== undefined).map((d) => {
+        const arg = JSON.stringify(s[d.key]);
+        return `  {
+    const __sr = app.${d.fn}(${idExpr}, ${arg});
+    if (!__sr || __sr.ok === false) {
+      return Object.assign({}, ${resVar}, { success: false, error: '${d.key} was not applied to ' + ${idExpr} + ': ' + ((__sr && (__sr.reason || __sr.error)) || 'refused by the studio') });
+    }
+    ${resVar}.${d.key} = ${d.key === 'screenSpace' ? arg : `(__sr.${d.key} !== undefined ? __sr.${d.key} : ${arg})`};${d.key === 'counter' ? `\n    if (__sr.text !== undefined) ${resVar}.counterText = __sr.text;` : ''}
+  }`;
+    }).join('\n');
+}
+/** Wrap a create / modify snippet so the setters run after it, on its item. */
+function withItemSetters(code, s, idExpr) {
+    if (!hasItemSetters(s))
+        return code;
+    return `(async function() {
+${itemSettersPreflightJs(s)}
+  const __res = await (async function() {
+${asReturningBody(code)}
+  })();
+  if (!__res || __res.success === false) return __res;
+  const __sid = ${idExpr};
+  if (!__sid) return __res;
+${itemSettersApplyJs(s, '__sid', '__res')}
+  if (__res.success === undefined) __res.success = true;
+  return __res;
+})();`;
+}
 function asReturningBody(snippet) {
     const single = snippet.trim();
     if (single.startsWith('(async function()'))
@@ -2398,17 +2501,27 @@ export class PinePaperCodeGenerator {
             properties.keyframes = validated.keyframes;
         if (validated.anchor !== undefined && properties.anchor === undefined && properties.origin === undefined)
             properties.anchor = validated.anchor;
-        return generateCreateItemCode(validated.itemType, validated.position, properties, validated.data, positionGiven);
+        const setters = takeItemSetters(properties, { screenSpace: validated.screenSpace, stepTiming: validated.stepTiming, counter: validated.counter });
+        const brandProps = { ...properties };
+        delete properties.noBrand;
+        return withItemSetters(withBrandDefaults(generateCreateItemCode(validated.itemType, validated.position, properties, validated.data, positionGiven), validated.itemType, brandProps), setters, '__res.itemId');
     }
     /**
      * Generate code for modifying an item
      */
     generateModifyItem(input) {
         const validated = ModifyItemInputSchema.parse(input);
+        const props = { ...validated.properties };
+        const setters = takeItemSetters(props, { screenSpace: validated.screenSpace, stepTiming: validated.stepTiming, counter: validated.counter });
+        const idExpr = JSON.stringify(validated.itemId);
         if (validated.atTime !== undefined) {
-            return generateAutoKeyCode(validated.itemId, validated.properties, validated.atTime, validated.easing);
+            return withItemSetters(generateAutoKeyCode(validated.itemId, props, validated.atTime, validated.easing), setters, idExpr);
+        }
+        // Only a setter asked for: no property edit to run.
+        if (hasItemSetters(setters) && Object.keys(props).length === 0 && !validated.data) {
+            return withItemSetters(`({ success: true, itemId: ${idExpr} });`, setters, idExpr);
         }
-        return generateModifyItemCode(validated.itemId, validated.properties, validated.data);
+        return withItemSetters(generateModifyItemCode(validated.itemId, props, validated.data), setters, idExpr);
     }
     /**
      * Generate code for deleting an item
@@ -2452,7 +2565,15 @@ export class PinePaperCodeGenerator {
         if (validated.relationType === 'moves_along_path') {
             return generateMovesAlongPathCode(validated.sourceId, validated.targetId ?? undefined, (validated.params ?? {}));
         }
-        return generateAddRelationCode(validated.sourceId, validated.targetId || validated.sourceId, validated.relationType, validated.params);
+        const code = generateAddRelationCode(validated.sourceId, validated.targetId || validated.sourceId, validated.relationType, validated.params);
+        // NO TARGET (event reactions like on_event_play_sound, self-relations): the
+        // engine is handed the source as the target, but the reply must not say
+        // "item_2 → item_2" — a model reads that as the event wired to itself.
+        if (validated.targetId)
+            return code;
+        return code
+            .replace(`return { success: true, sourceId: '${validated.sourceId}', targetId: '${validated.sourceId}',`, `return { success: true, sourceId: '${validated.sourceId}', targetId: null,`)
+            .replace(`relation between ${validated.sourceId} and ${validated.sourceId}.`, `relation on ${validated.sourceId} (no target).`);
     }
     /**
      * Generate code for removing a relation
@@ -2478,7 +2599,19 @@ export class PinePaperCodeGenerator {
      */
     generateKeyframeAnimate(input) {
         const validated = KeyframeAnimateInputSchema.parse(input);
-        return generateKeyframeAnimateCode(validated.itemId, validated.keyframes, validated.duration, validated.loop, validated.timeOffset, validated.clipInPoint, validated.clipOutPoint, validated.timeUnits, validated.append);
+        // Hold keys (FxTool D11) on an engine without them would interpolate in
+        // silence; refuse before anything is written. setStepTiming ships in the
+        // same change, so it is the probe.
+        const holds = validated.keyframes.some((k) => k.interpolation === 'hold' || k.hold === true);
+        const code = generateKeyframeAnimateCode(validated.itemId, validated.keyframes, validated.duration, validated.loop, validated.timeOffset, validated.clipInPoint, validated.clipOutPoint, validated.timeUnits, validated.append);
+        if (!holds)
+            return code;
+        return `(async function() {
+  if (!(typeof app.setStepTiming === 'function')) { return { success: false, error: 'this studio has no hold keys (interpolation: \\'hold\\') — it predates FxTool D11; nothing was written. Use two keys a frame apart for a cut.' }; }
+  return await (async function() {
+${asReturningBody(code)}
+  })();
+})();`;
     }
     /**
      * Generate code for importing / retargeting a motion-capture clip
@@ -2726,6 +2859,15 @@ throw new Error('Either svgString or url must be provided');
     success: !!result.success,
     nodeCount: nodes.length,
     edgeCount: edges.length,
+    // CANVAS ids, the ones auto_layout / animate / add_relation take. The
+    // engine's own nodeIds are the MERMAID ids (A, B…), which resolve to
+    // nothing on the canvas (gate D45). Newer engines return nodeItemIds;
+    // otherwise they are read off the registered nodes.
+    nodeItemIds: Array.isArray(result.nodeItemIds) && result.nodeItemIds.length
+      ? result.nodeItemIds
+      : nodes.map((n) => n.id).filter((id) => typeof id === 'string' && /^item_/.test(id)),
+    ...(result.nodeIdMap && typeof result.nodeIdMap === 'object' ? { nodeIdMap: result.nodeIdMap } : {}),
+    ...(Array.isArray(result.edgeIds) && result.edgeIds.length ? { edgeIds: result.edgeIds } : {}),
     nodes,
     edges,
     errors: result.errors || [],
@@ -3596,6 +3738,8 @@ throw new Error('Unknown diagram mode action: ${action}');
         let code = `
 // End agent job
 (async function() {
+  // Close the studio's job (D92). It never reloads.
+  try { if (typeof window !== 'undefined' && window.PinePaperAgent && window.PinePaperAgent.endJob) window.PinePaperAgent.endJob(); } catch (_) { /* older studio */ }
   const result = {
     success: true,
     jobEnded: true
@@ -3900,12 +4044,19 @@ throw new Error('Unknown diagram mode action: ${action}');
                 // the exact emitter create_item uses, adapted to return its result
                 // inside this op's function.
                 const pos = op.position || { x: 400, y: 300 };
-                const createProps = withRadiusAxes((op.properties || {}));
-                const returning = asReturningBody(generateCreateItemCode(op.itemType, pos, { ...(op.properties || {}) }, undefined, op.position !== undefined));
-                let createCode = `
+                const opProps = { ...(op.properties || {}) };
+                const opSetters = takeItemSetters(opProps, { screenSpace: op.screenSpace, stepTiming: op.stepTiming, counter: op.counter });
+                const createProps = withRadiusAxes(opProps);
+                const opBrand = { ...opProps };
+                delete opProps.noBrand;
+                const returning = asReturningBody(withBrandDefaults(generateCreateItemCode(op.itemType, pos, { ...opProps }, undefined, op.position !== undefined), op.itemType, opBrand));
+                let createCode = `${hasItemSetters(opSetters) ? `\n${itemSettersPreflightJs(opSetters)}` : ''}
 const __created = await (async function() {
 ${returning}
-})();`;
+})();${hasItemSetters(opSetters) ? `
+if (__created && __created.success !== false && __created.itemId) {
+${itemSettersApplyJs(opSetters, '__created.itemId', '__created')}
+}` : ''}`;
                 // Coordinate-built items (path from segments/pathData, line/arc from
                 // from/through/to) derive their geometry from those coordinates and
                 // IGNORE params.position — so `create` at a point silently produced an
@@ -5481,6 +5632,34 @@ ${(() => {
         })()}
 ${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) { /* the still is already rendered */ }
   if (result && result.success) result.time = ${stillTime};` : ''}
+  // SCREEN-SPACE ITEMS (FxTool D20): SVG and Lottie write geometry, not the
+  // camera's frame map, so a HUD item is placed as if the camera had not moved.
+  if (result && result.success && typeof app.screenSpaceItems === 'function' && ['svg', 'lottie', 'dotlottie'].indexOf(${JSON.stringify(format)}) !== -1) {
+    try {
+      const __hud = app.screenSpaceItems() || [];
+      if (__hud.length) {
+        result.fidelity = result.fidelity || { warnings: [] };
+        result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'screen_space_ignored', message: __hud.length + ' screen-space (HUD) item(s) are written at their frame coordinates in world space: ${format} has no camera frame, so they do not stay fixed under the camera move. Export mp4, webm, gif or png to keep them fixed.' }]);
+      }
+    } catch (_) { /* the export stands */ }
+  }
+  // WHICH STUDIO MADE THIS FILE (D92): a service worker can serve a stale
+  // build right after a deploy, and a retest then judges old code. The
+  // engine's own identity, version + build sha, rides on every export reply.
+  try { if (result && typeof result === 'object' && app.buildId) result.studioBuild = app.buildId; } catch (_) { /* older studio */ }
+  // A STALE STUDIO (D92): the file was made by an old build. Said in the
+  // fidelity warnings the reply shows, not only as a field.
+  try {
+    const __bs = app.buildStatus ? app.buildStatus() : null;
+    if (result && typeof result === 'object' && __bs) {
+      result.liveBuild = __bs.liveBuildId;
+      if (__bs.stale) {
+        result.stale = true;
+        result.fidelity = result.fidelity || { warnings: [] };
+        result.fidelity.warnings = (result.fidelity.warnings || []).concat([{ code: 'stale_build', message: 'this studio is running an old build (' + __bs.buildId + '; the live build is ' + __bs.liveBuildId + '): this file was made by the old code. Start a new job (pinepaper_agent_start_job, which reloads it) and export again.' }]);
+      }
+    }
+  } catch (_) { /* older studio */ }
   // RELIGHT (FxTool D5): applied to png / pdf / mp4 / webm, not gif / apng
   // or the vector formats; and it is what makes a video export slow.
   if (result && result.success && typeof app.getRelight === 'function') {
@@ -6792,7 +6971,11 @@ ${stillTime !== undefined ? `  try { app.setPlaybackTime(__prevT); } catch (_) {
   if (typeof app.captureProjectDocument !== 'function') { return { success: false, error: 'app.captureProjectDocument unavailable — update FxTool' }; }
   ${SCENE_COUNTS_JS}
   const doc = app.captureProjectDocument(${JSON.stringify(name ? { name } : {})});
-  return { success: true, json: JSON.stringify(doc), counts: __ppSceneCounts() };
+  // What the document CANNOT carry (D29): render hooks added as raw functions
+  // and frame callbacks from generated code. Named, never dropped in silence.
+  const __un = (doc && Array.isArray(doc.unserialized)) ? doc.unserialized
+    : (app.listUnserializedCallbacks ? app.listUnserializedCallbacks() : []);
+  return { success: true, json: JSON.stringify(doc), counts: __ppSceneCounts(), unserialized: __un };
 })();`.trim();
     }
     /** Load a staged project document (window.__ppStage.projectDoc), replacing the scene. */
@@ -7709,13 +7892,22 @@ ${mask ? `    // A MASK REPLACES THE RASTER (round 8 DD, 4.10). applyMask builds
                     opts.push(`defaultTransition: ${JSON.stringify(input.defaultTransition)}`);
                 if (input.transitionDuration !== undefined)
                     opts.push(`transitionDuration: ${input.transitionDuration * 1000}`);
+                if (input.cutSound !== undefined)
+                    opts.push(`cutSound: ${JSON.stringify(input.cutSound)}`);
                 const optsStr = opts.length > 0 ? `, { ${opts.join(', ')} }` : '';
                 return `
 // Create scene chain for sequential playback
 (function() {
   ${guard}
-  app.sceneManager.createChain(${JSON.stringify(input.sceneIds)}${optsStr});
-  return { success: true, action: 'create_chain', sceneIds: ${JSON.stringify(input.sceneIds)}${input.loop !== undefined ? `, loop: ${input.loop}` : ''}${input.defaultDuration !== undefined ? `, defaultDuration: ${input.defaultDuration}` : ''} };
+  const __cr = app.sceneManager.createChain(${JSON.stringify(input.sceneIds)}${optsStr});
+  // An unknown cut sound comes back {ok:false, reason} (FxTool D85); a
+  // studio without cut sounds ignores the option, which the cuts readback shows.
+  if (__cr && __cr.ok === false) { return { success: false, action: 'create_chain', error: __cr.reason || 'the chain was refused' }; }
+  const __res = { success: true, action: 'create_chain', sceneIds: ${JSON.stringify(input.sceneIds)}${input.loop !== undefined ? `, loop: ${input.loop}` : ''}${input.defaultDuration !== undefined ? `, defaultDuration: ${input.defaultDuration}` : ''} };
+${input.cutSound !== undefined ? `  const __cuts = (__cr && __cr.cuts) || (app.sceneManager.getChainCuts ? app.sceneManager.getChainCuts() : null);
+  if (__cuts) __res.cuts = __cuts;
+  else __res.warning = 'this studio placed no cut sounds: it predates them (FxTool D85). The chain plays without them.';
+` : ''}  return __res;
 })();
 `.trim();
             }
@@ -8143,6 +8335,32 @@ ${mask ? `    // A MASK REPLACES THE RASTER (round 8 DD, 4.10). applyMask builds
 })();`.trim();
     }
     generateBrandKit(input) {
+        // THE ACTIVE BRAND (D69). apply recolours what is on the canvas once; a
+        // later beat's new items knew nothing of it. 'set' applies AND makes the
+        // kit the studio's active brand, which every create reads (withBrandDefaults).
+        // It lives in the PAGE, not this process: one cloud server serves many
+        // studios, and a brand must not cross between them.
+        if (input.action === 'get' || input.action === 'clear') {
+            return `
+// Brand kit: ${input.action} the active brand
+(function() {
+  const b = (typeof window !== 'undefined' && window.__ppActiveBrand) || null;
+  ${input.action === 'clear' ? 'if (typeof window !== "undefined") window.__ppActiveBrand = null;' : ''}
+  return { success: true, action: ${JSON.stringify(input.action)}, ${input.action === 'clear' ? 'cleared: !!b' : 'brand: b'} };
+})();`.trim();
+        }
+        if (input.action === 'set') {
+            const applied = this.generateBrandKit({ ...input, action: 'apply' });
+            return `
+// Brand kit: apply, then make it the active brand every new item inherits
+(async function() {
+  const out = await ${applied.replace(/^\/\/[^\n]*\n/, '').replace(/;\s*$/, '')};
+  if (out && (out.success === false || out.ok === false)) return out;
+  if (typeof window !== 'undefined') window.__ppActiveBrand = ${JSON.stringify(input.kit)};
+  return Object.assign({}, out, { success: true, action: 'set', active: true,
+    note: 'new shapes take colors.primary and new text colors.text with the heading (32 px and up) or body font, wherever the call names none; noBrand: true opts an item out. The active brand lives with this studio session: set it again after a reload.' });
+})();`.trim();
+        }
         const opts = JSON.stringify({ ...(input.selectionOnly ? { selectionOnly: true } : {}) });
         const method = input.action === 'plan' ? 'planBrandKit' : 'applyBrandKit';
         const facade = this._facadeCall(method, `${JSON.stringify(input.kit)}, ${opts}`, `Brand kit: ${input.action}`);
@@ -8667,8 +8885,8 @@ ${resolveSource}
         const resolve = `  const item = (typeof app._resolveRaster === 'function')
     ? app._resolveRaster(${JSON.stringify(input.itemId)})
     : (app.itemRegistry ? app.itemRegistry.getItem(${JSON.stringify(input.itemId)}) : null);
-  if (!item) return { error: 'Item not found or not a raster: ' + ${JSON.stringify(input.itemId)} };
-  if (typeof app.applyImageFilter !== 'function') return { error: 'GPU image filters unavailable — update FxTool' };`;
+  if (!item) return { success: false, error: 'Item not found or not a raster: ' + ${JSON.stringify(input.itemId)} };
+  if (typeof app.applyImageFilter !== 'function') return { success: false, error: 'GPU image filters unavailable — update FxTool' };`;
         switch (input.action) {
             case 'apply':
                 return `
@@ -8685,7 +8903,7 @@ ${resolve}
     }
     return { success: true, action: 'apply', itemId: ${JSON.stringify(input.itemId)}, filter: ${JSON.stringify(input.filterName || '')} };
   } catch (e) {
-    return { error: 'Failed to apply filter: ' + e.message };
+    return { success: false, action: 'apply', error: 'Failed to apply filter: ' + e.message };
   }
 })();`.trim();
             case 'chain':
@@ -8698,7 +8916,7 @@ ${resolve}
     await app.applyImageFilterChain(item, filters);
     return { success: true, action: 'chain', itemId: ${JSON.stringify(input.itemId)}, filterCount: filters.length };
   } catch (e) {
-    return { error: 'Failed to apply filter chain: ' + e.message };
+    return { success: false, action: 'chain', error: 'Failed to apply filter chain: ' + e.message };
   }
 })();`.trim();
             default:
@@ -11006,6 +11224,293 @@ ${guard}
      * costs ~0.42 s per 1080p frame on the CPU, so a set says what an export
      * will pay.
      */
+    /**
+     * pinepaper_choreograph (D67). The compiler runs IN THE STUDIO, serialised
+     * by toString, because the track depends on the actor's live size, scale,
+     * rotation and the export frame. Merged into the actor's track, read back
+     * the way keyframe_animate reads its own.
+     */
+    generateChoreograph(input) {
+        const S = (v) => JSON.stringify(v);
+        const id = S(input.itemId);
+        return `
+// Choreograph ${input.beats.length} beat(s) for ${input.itemId}
+(function() {
+  const __it = (app.getItemById && app.getItemById(${id}))
+    || (app.itemRegistry && app.itemRegistry.get && (app.itemRegistry.get(${id}) || {}).item);
+  if (!__it || !__it.bounds) { return { success: false, error: ${id} + ' is not on the canvas — check the id with pinepaper_get_items.' }; }
+  const __sc = __it.scaling || { x: 1, y: 1 };
+  const __b = __it.bounds;
+  const __baked = (__it.data && typeof __it.data._bakedRotation === 'number') ? __it.data._bakedRotation : 0;
+  const __fr = (typeof app.exportFrameRect === 'function' && app.exportFrameRect()) || (app.getCanvasSize && app.getCanvasSize()) || { width: 1920, height: 1080 };
+  const __frame = { x: __fr.x || 0, y: __fr.y || 0, width: __fr.width, height: __fr.height };
+  const __actor = { x: __it.position.x, y: __it.position.y,
+    w: __b.width / (Math.abs(__sc.x) || 1), h: __b.height / (Math.abs(__sc.y) || 1),
+    sx: __sc.x || 1, sy: __sc.y || 1, rot: (__it.rotation || 0) + __baked };
+  const __r = (${compileChoreography.toString()})(__actor, __frame, ${S(input.beats)});
+  if (__r.error) { return { success: false, itemId: ${id}, error: __r.error }; }
+  const __prev = (__it.data && Array.isArray(__it.data.keyframes)) ? __it.data.keyframes : [];
+  const __prevTimes = __prev.map(function (k) { return k && k.time; });
+  const __ours = ['x', 'y', 'scaleX', 'scaleY', 'rotation', 'opacity'];
+  const __other = __prev.reduce(function (acc, k) { Object.keys((k && k.properties) || {}).forEach(function (p) { if (__ours.indexOf(p) < 0 && acc.indexOf(p) < 0) acc.push(p); }); return acc; }, []);
+  app.addAnimation(${id}, __r.keyframes, { duration: Math.max(__r.end, __prev.reduce(function (m, k) { return Math.max(m, (k && k.time) || 0); }, 0)), loop: false, mode: 'merge' });
+  const __now = (__it.data && Array.isArray(__it.data.keyframes)) ? __it.data.keyframes.map(function (k) { return k && k.time; }) : [];
+  const __warnings = (__r.warnings || []).slice();
+  if (__prevTimes.length && !__prevTimes.every(function (t) { return __now.indexOf(t) >= 0; })) {
+    __warnings.push('this studio replaced the existing track of the actor (' + __prevTimes.length + ' key(s)) instead of merging: put the other keys in after choreographing.');
+  }
+  if (__other.length) {
+    __warnings.push('the actor already animates ' + __other.join(', ') + '; the beat keys leave those out, which the engine can break at the beat keys. Re-key ' + __other.join(', ') + ' with every key carrying them, after choreographing.');
+  }
+  if (__r.final && !__r.final.onScreen) __warnings.push('after the last beat the actor is off screen at [' + __r.final.x + ', ' + __r.final.y + '].');
+  const __res = { success: true, itemId: ${id}, beats: ${input.beats.length}, keyframes: __r.keyframes.length, duration: __r.end, final: __r.final };
+${input.sound ? `  // SOUND ON THE ACTION (D68): one placed sound per moment the motion makes —
+  // pop, launch, contact, shake — loud as the moment is strong. A sound that
+  // does not place is reported; it never undoes the motion.
+  const __map = Object.assign({ pop: 'pop', whoosh: 'whoosh', contact: 'tom', shake: 'hat' }, ${S(typeof input.sound === 'object' ? Object.fromEntries(Object.entries(input.sound).filter(([k]) => k !== 'gain')) : {})});
+  const __gain = ${S(typeof input.sound === 'object' && input.sound.gain !== undefined ? input.sound.gain : 0.8)};
+  const __sounds = [];
+  const __silent = [];
+  if (typeof app.createSound !== 'function' || (typeof app.sfxSpec !== 'function' && typeof app.percussionSpec !== 'function')) {
+    __warnings.push('no sound was placed: this studio cannot place synthesized sounds (app.createSound / sfxSpec). The motion is written.');
+  } else {
+    (__r.events || []).forEach(function (e) {
+      const name = __map[e.kind];
+      if (name === false || name === undefined) return;
+      const base = (typeof app.sfxSpec === 'function' && app.sfxSpec(name)) || (typeof app.percussionSpec === 'function' && app.percussionSpec(name));
+      if (!base) { if (__silent.indexOf(name) < 0) __silent.push(name); return; }
+      const spec = Object.assign({}, base, { gain: Math.round(((base.gain || 0.8) * __gain * (0.35 + 0.65 * e.strength)) * 1000) / 1000 });
+      // MP4 (AAC) encoder priming swallows the first ~50 ms of audio, and this
+      // muxer writes no edit list (the engine reports audio_lead_trimmed): a pop
+      // at 0 s exported as silence (prod retest of D68). 60 ms later is in sync
+      // to the eye and audible in every format.
+      const at = e.time < 0.06 ? 0.06 : e.time;
+      const it = app.createSound(spec, { startTime: at, duration: spec.duration || 0.5 });
+      if (it && it.data) __sounds.push(Object.assign({ t: at, kind: e.kind, sound: name, itemId: it.data.id }, at !== e.time ? { movedFrom: e.time } : {}));
+    });
+    if (__silent.length) __warnings.push('not in the sound catalogue, so silent: ' + __silent.join(', ') + ' (pinepaper_sound list_sfx / list_percussion for the names).');
+  }
+  __res.sounds = __sounds;
+` : ''}
+  if (__warnings.length) __res.warnings = __warnings;
+  return __res;
+})();`.trim();
+    }
+    /**
+     * pinepaper_morph_sequence (D73): ONE element through N states — R8's pill →
+     * input → dot → grid → composer → orb. The engine already chains morphs_to
+     * on one shape (per-relation state since gap 2.27); what a model could not
+     * do was time the chain, make the reference shapes, and ride the camera on
+     * the same curve. Compiled here to that chain, a camera track and sounds.
+     */
+    generateMorphSequence(input) {
+        const S = (v) => JSON.stringify(v);
+        const states = [...input.states].sort((a, b) => a.at - b.at).map((st) => ({ at: st.at, duration: st.duration ?? 0.8, to: st.to ?? null, shape: st.shape ?? null }));
+        const cam = input.camera === true ? { fill: 0.45 } : (input.camera || null);
+        const sound = input.sound === true ? 'whoosh' : (input.sound || null);
+        return `
+// Morph sequence: ${states.length} state(s)
+(function() {
+  const src = app.getItemById && app.getItemById(${S(input.itemId)});
+  if (!src) { return { success: false, error: ${S(input.itemId)} + ' is not on the canvas.' }; }
+  if (typeof app.addRelation !== 'function') { return { success: false, error: 'this studio cannot add relations.' }; }
+  const states = ${S(states)};
+  const done = [];
+  for (let i = 0; i < states.length; i++) {
+    const st = states[i];
+    let tid = st.to;
+    if (!tid) {
+      const p = Object.assign({}, st.shape.properties || {}, { x: st.shape.position.x, y: st.shape.position.y });
+      const made = app.create(st.shape.itemType, p);
+      tid = made && made.data && made.data.registryId;
+      if (!tid) { return { success: false, error: 'state ' + i + ': could not make the ' + st.shape.itemType + ' reference shape', states: done }; }
+    } else if (!(app.getItemById && app.getItemById(tid))) {
+      return { success: false, error: 'state ' + i + ': ' + tid + ' is not on the canvas', states: done };
+    }
+    const ok = app.addRelation(${S(input.itemId)}, tid, 'morphs_to', { duration: st.duration, delay: st.at, easing: ${S(input.easing ?? 'easeInOut')}, hideTarget: true });
+    if (ok === false) { return { success: false, error: 'state ' + i + ': the studio refused the morph into ' + tid, states: done }; }
+    done.push({ at: st.at, duration: st.duration, targetId: tid });
+  }
+  const res = { success: true, itemId: ${S(input.itemId)}, states: done, end: done[done.length - 1].at + done[done.length - 1].duration };
+  const n = app.getRelations ? app.getRelations(${S(input.itemId)}, 'morphs_to').length : null;
+  if (n !== null && n < done.length) res.warning = 'only ' + n + ' of ' + done.length + ' morphs are on the element.';
+${cam ? `  // The camera rides the SAME timing: framing each state as its morph lands.
+  {
+    const fr = (typeof app.exportFrameRect === 'function' && app.exportFrameRect()) || (app.getCanvasSize && app.getCanvasSize()) || { width: 1920, height: 1080 };
+    const fill = ${S(cam.fill ?? 0.45)};
+    const frameOf = function (it) { const b = it.bounds; return { focus: [b.center.x, b.center.y], zoom: Math.max(0.2, Math.min(8, fill * Math.min(fr.width / Math.max(1, b.width), fr.height / Math.max(1, b.height)))) }; };
+    const f0 = frameOf(src);
+    const kfs = [{ time: 0, zoom: f0.zoom, focus: f0.focus }];
+    done.forEach(function (d) {
+      const t = app.getItemById(d.targetId);
+      const f = frameOf(t);
+      const prev = kfs[kfs.length - 1];
+      kfs.push({ time: d.at, zoom: prev.zoom, focus: prev.focus });
+      kfs.push({ time: d.at + d.duration, zoom: f.zoom, focus: f.focus, easing: ${S(cam.easing ?? 'easeInOut')} });
+    });
+    // The SAME door pinepaper_camera_animate uses: app.camera.animate where the
+    // build has it, else the camera_animates relation — prod has only the
+    // relation, and probing app.camera.animate alone reported "no camera" there.
+    const r = app.camera && app.camera.animate
+      ? app.camera.animate(kfs, res.end, false, 0, {})
+      : app.addRelation('camera', 'camera', 'camera_animates', { keyframes: kfs, duration: res.end, loop: false, delay: 0 });
+    // Read the track back where the engine keeps it.
+    const rr = app.relationRegistry;
+    const written = rr && rr.getCameraAnimationParams ? rr.getCameraAnimationParams() : null;
+    if (r === false || (rr && rr.getCameraAnimationParams && !written)) {
+      res.warning = (res.warning ? res.warning + ' ' : '') + 'the camera track was not written; the morphs run without it.';
+    } else {
+      res.camera = { keyframes: kfs.length };
+    }
+  }
+` : ''}${sound ? `  // A sound on each morph (D68's placement, with its MP4-lead nudge).
+  const base = (app.sfxSpec && app.sfxSpec(${S(sound)})) || (app.percussionSpec && app.percussionSpec(${S(sound)}));
+  if (base && app.createSound) {
+    res.sounds = done.map(function (d) { const at = d.at < 0.06 ? 0.06 : d.at; const it = app.createSound(Object.assign({}, base), { startTime: at, duration: base.duration || 0.5 }); return { t: at, itemId: it && it.data && it.data.id }; });
+  } else { res.warning = (res.warning ? res.warning + ' ' : '') + ${S(`no sound placed: ${sound} is not in the catalogue, or this studio cannot place sounds.`)}; }
+` : ''}  return res;
+})();`.trim();
+    }
+    /**
+     * pinepaper_original_character (D66): app.createCharacter and its schema
+     * helpers. The helpers read the SAME table the validator uses, so a model
+     * reads the legal values (describe) before it guesses; a wrong one is
+     * refused by name and nothing is drawn.
+     */
+    generateOriginalCharacter(input) {
+        const S = (v) => JSON.stringify(v);
+        const guard = `if (typeof app.createCharacter !== 'function') { return { success: false, error: 'this studio has no original characters (app.createCharacter) — it predates FxTool D66.' }; }`;
+        switch (input.action) {
+            case 'bases':
+                return `(function() {\n  ${guard}\n  return { success: true, action: 'bases', bases: app.listCharacterBases() };\n})();`;
+            case 'describe':
+                return `(function() {\n  ${guard}\n  return { success: true, action: 'describe', schema: app.describeCharacterVariantSchema(${input.base ? S(input.base) : ''}) };\n})();`;
+            case 'random':
+                return `(function() {\n  ${guard}\n  const r = app.randomCharacterVariant(${S(input.base)}, ${S(input.seed)}${input.fixed ? `, { fixed: ${S(input.fixed)} }` : ''});\n  if (!r || r.ok === false) return { success: false, action: 'random', error: (r && r.errors && r.errors.join('; ')) || 'no variant' };\n  return { success: true, action: 'random', base: ${S(input.base)}, seed: ${S(input.seed)}, variant: r.variant };\n})();`;
+            default: {
+                const spec = { base: input.base, ...(input.variant ? { variant: input.variant } : {}), ...(input.at ? { x: input.at.x, y: input.at.y } : {}),
+                    ...(input.height !== undefined ? { height: input.height } : {}), ...(input.scale !== undefined ? { scale: input.scale } : {}), ...(input.rig !== undefined ? { rig: input.rig } : {}) };
+                return `
+// Original character: create
+(async function() {
+  ${guard}
+  const r = await app.createCharacter(${S(spec)});
+  if (!r || r.ok === false) return { success: false, action: 'create', errors: (r && r.errors) || [], error: (r && r.errors && r.errors.join('; ')) || 'the character was refused' };
+  return { success: true, action: 'create', itemId: r.id, rigId: r.rigId, parts: r.parts, name: r.name, base: r.base, look: r.look, variant: r.variant };
+})();`.trim();
+            }
+        }
+    }
+    /**
+     * pinepaper_look (D64): one look over an item, a subtree or the whole scene
+     * — ids, keys and relations kept, removable pixel for pixel. Every apply
+     * carries the look's own FIDELITY grade, and anything below 'convincing'
+     * says so in the reply, so a weak approximation is never handed over as
+     * the finished style.
+     */
+    generateLook(input) {
+        const S = (v) => JSON.stringify(v);
+        const guard = `if (typeof app.applyLook !== 'function') { return { success: false, error: 'this studio has no looks (app.applyLook) — it predates FxTool D64.' }; }`;
+        const target = S(input.target ?? 'scene');
+        switch (input.action) {
+            case 'list':
+                return `(function() {\n  ${guard}\n  return { success: true, action: 'list', looks: app.listLooks(), note: 'fidelity is the engine grade: native (the medium itself), faithful (close, approximations named), impression (an evocation, not the real style). Describe one before promising it.' };\n})();`;
+            case 'describe':
+                return `(function() {\n  ${guard}\n  const r = app.describeLook(${S(input.look)});\n  if (!r || r.ok === false) return { success: false, action: 'describe', error: (r && r.error) || 'unknown look', known: r && r.known };\n  return { success: true, action: 'describe', fidelity: r.look && r.look.fidelity, approximations: (r.look && r.look.approximations) || [], recipe: r.look, enginePaths: r.enginePaths, sceneOnly: r.sceneOnly };\n})();`;
+            case 'get':
+                return `(function() {\n  ${guard}\n  return { success: true, action: 'get', target: ${target}, look: app.getLook(${target}) || null };\n})();`;
+            case 'remove':
+                return `
+// Look: remove (restores what was there)
+(async function() {
+  ${guard}
+  const r = await app.removeLook(${target});
+  if (!r || r.ok === false) return { success: false, action: 'remove', error: (r && r.error) || 'nothing to remove' };
+  return { success: true, action: 'remove', target: ${target}, removed: r.removed, scene: r.scene };
+})();`.trim();
+            case 'grid':
+                return `
+// Look: a contact sheet of looks over the current scene
+(async function() {
+  ${guard}
+  const r = await app.renderLookGrid(${input.looks ? S(input.looks) : 'undefined'}, ${S({ ...(input.cols ? { cols: input.cols } : {}), ...(input.cellWidth ? { cellWidth: input.cellWidth } : {}), ...(input.t !== undefined ? { t: input.t } : {}) })});
+  if (!r || r.ok === false || !r.dataURL) return { success: false, action: 'grid', error: (r && r.error) || 'the grid did not render' };
+  return { success: true, action: 'grid', data: r.dataURL, mimeType: 'image/png', cells: (r.cells || []).map(function (c) { return { id: c.id, name: c.name, fidelity: c.fidelity }; }), cols: r.cols, rows: r.rows };
+})();`.trim();
+            default: {
+                const opts = input.scope ? { scope: input.scope } : {};
+                return `
+// Look: apply
+(async function() {
+  ${guard}
+  const d = app.describeLook(${S(input.look)});
+  const r = await app.applyLook(${target}, ${S(input.look)}, ${S(opts)});
+  if (!r || r.ok === false) return { success: false, action: 'apply', error: (r && r.error) || 'the look was refused', known: r && r.known };
+  const fidelity = (d && d.look && d.look.fidelity) || (r.look && r.look.fidelity) || null;
+  const res = { success: true, action: 'apply', target: ${target}, look: r.look && (r.look.id || r.look.name), fidelity: fidelity,
+    restyled: r.restyled, texts: r.texts, images: r.images, brushed: r.brushed, keyframes: r.keyframes, filters: r.filters, ids: r.ids,
+    approximations: r.approximations || [], warnings: r.warnings || [] };
+  // The engine's grades: native (the medium itself), faithful (close, with
+  // named approximations), impression (an evocation), custom (an ad-hoc spec).
+  const __approx = (res.approximations && res.approximations.length) ? res.approximations.join('; ') : '';
+  if (fidelity === 'impression') {
+    res.warning = 'this look is an IMPRESSION of the style (the engine\\'s grade)' + (__approx ? ' — it approximates: ' + __approx : '') + '. Present it as an approximation of the style, not the finished style.';
+  } else if (fidelity === 'faithful' && __approx) {
+    res.note = 'a faithful look; what it approximates: ' + __approx + '.';
+  } else if (fidelity === 'custom') {
+    res.note = 'a custom look spec: the engine has no fidelity grade for it.';
+  }
+  return res;
+})();`.trim();
+            }
+        }
+    }
+    /** pinepaper_emitter (D29): create('emitter', spec) / setEmitter(id, patch). */
+    generateEmitter(input) {
+        const S = (v) => JSON.stringify(v);
+        if (input.action === 'set') {
+            return `
+// Emitter: change a spec
+(function() {
+  if (typeof app.setEmitter !== 'function') { return { success: false, error: 'this studio has no emitter item (app.setEmitter) — it predates FxTool D29.' }; }
+  const r = app.setEmitter(${S(input.itemId)}, ${S(input.spec)});
+  if (!r || r.ok === false) { return { success: false, error: (r && r.error) || 'the emitter change was refused' }; }
+  return { success: true, action: 'set', itemId: ${S(input.itemId)}, spec: r.spec };
+})();`.trim();
+        }
+        return `
+// Emitter: create
+(function() {
+  if (typeof app.setEmitter !== 'function') { return { success: false, error: 'this studio has no emitter item (app.setEmitter) — it predates FxTool D29.' }; }
+  const it = app.create('emitter', ${S(input.spec)});
+  // A bad spec comes back null with an emitter-invalid warning; the reason
+  // reaches this reply through the governor's warnings.
+  if (!it) { return { success: false, error: 'the emitter spec was refused' }; }
+  const id = it.data && (it.data.registryId || it.data.id);
+  if (!id) { return { success: false, error: 'the emitter was made but not registered — no usable id' }; }
+  return { success: true, action: 'create', itemId: id };
+})();`.trim();
+    }
+    /** pinepaper_render_hook (D29): drawing saved as source, re-installed on load. */
+    generateRenderHook(input) {
+        const S = (v) => JSON.stringify(v);
+        const guard = `if (typeof app.registerRenderHook !== 'function') { return { success: false, error: 'this studio has no saved render hooks (app.registerRenderHook) — it predates FxTool D29.' }; }`;
+        if (input.action === 'list') {
+            return `(function() {\n  ${guard}\n  return { success: true, action: 'list', hooks: app.listRenderHooks() };\n})();`;
+        }
+        if (input.action === 'unregister') {
+            return `(function() {\n  ${guard}\n  const had = app.unregisterRenderHook(${S(input.id)});\n  if (!had) return { success: false, error: 'no render hook ' + ${S(input.id)} };\n  return { success: true, action: 'unregister', id: ${S(input.id)} };\n})();`;
+        }
+        const spec = { id: input.id, source: input.source, ...(input.layer ? { layer: input.layer } : {}), ...(input.deterministic !== undefined ? { deterministic: input.deterministic } : {}), ...(input.seed !== undefined ? { seed: input.seed } : {}) };
+        return `
+// Render hook: register (saved as source)
+(function() {
+  ${guard}
+  const r = app.registerRenderHook(${S(spec)});
+  if (!r || r.ok === false) { return { success: false, error: (r && r.error) || 'the render hook was refused' }; }
+  return { success: true, action: 'register', id: r.id, layer: r.layer, deterministic: r.deterministic, seed: r.seed };
+})();`.trim();
+    }
     generateRelight(input) {
         const S = (v) => JSON.stringify(v);
         const missing = (fn) => `if (typeof app.${fn} !== 'function') { return { success: false, action: ${S(input.action)}, error: 'this studio has no relight pass (app.${fn}) — it predates FxTool D5.' }; }`;
@@ -11151,7 +11656,7 @@ ${body}
     }
     return { success: true, action: 'apply', medium: ${S(input.medium)}, fidelity: r.fidelity, itemId: r.id || ${S(input.itemId)}, inPlace: true, styled: __styled, ...(r.note ? { note: r.note } : {}) };
   }
-  return { success: true, action: 'apply', medium: r.medium || ${S(input.medium)}, fidelity: r.fidelity, itemId: r.id, ...(r.note ? { note: r.note } : {}) };
+  return { success: true, action: 'apply', medium: r.medium || ${S(input.medium)}, fidelity: r.fidelity, itemId: r.id, ...(r.filter ? { filter: r.filter } : {}), ...(r.note ? { note: r.note } : {}) };
 })();`.trim();
             case 'sdf_stroke': {
                 // FxTool D5: an SDF capsule stroke rendered to a bitmap and created as a
@@ -12080,7 +12585,14 @@ ${needWorld}
      */
     generateStory(input) {
         const S = (v) => JSON.stringify(v);
-        const opts = S(input.options ?? {});
+        // nav decides the story's FORM (D109): 'scenes' = a scene chain (video),
+        // 'panels' = tabs (widget). storyFromText reads options.nav; a spec carries
+        // its own nav, which a top-level nav fills in when the spec has none.
+        const opts = S({ ...(input.options ?? {}), ...(input.nav ? { nav: input.nav } : {}) });
+        const spec = input.spec && input.nav && input.spec.nav === undefined ? { ...input.spec, nav: input.nav } : input.spec;
+        const cuts = input.nav === 'scenes'
+            ? `\n  // The video form's cut times (s), for checking the edit.\n  try { if (app.sceneManager && app.sceneManager.getChainCuts) __out.cuts = app.sceneManager.getChainCuts(); } catch (_) {}`
+            : '';
         switch (input.action) {
             case 'distill':
                 return `
@@ -12106,16 +12618,18 @@ ${needWorld}
   // 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 };
+  const __out = { success: true, nav: (r.spec && r.spec.nav) || ${S(input.nav ?? 'panels')}, spec: r.spec, partIds: r.partIds, partCount: r.partCount, beats: r.beats };${cuts}
+  return __out;
 })();`.trim();
             case 'apply_spec':
                 return `
 // Story: assemble a spec you already have
 (async function() {
   if (typeof app.applyStorySpec !== 'function') { return { success: false, error: 'app.applyStorySpec unavailable — update FxTool' }; }
-  const r = await app.applyStorySpec(${S(input.spec)}, ${opts});
+  const r = await app.applyStorySpec(${S(spec)}, ${opts});
   if (!r || r.ok === false) { return { success: false, error: (r && (r.reason || r.error)) || 'the spec did not assemble' }; }
-  return { success: true, ...r };
+  const __out = { success: true, ...r };${cuts}
+  return __out;
 })();`.trim();
             case 'plan_book':
                 return `
@@ -13134,7 +13648,7 @@ ${guard('unlockAllItems')}${pass('app.unlockAllItems()')}
     generateEvent(input) {
         if (input.action === 'create') {
             const nameJson = JSON.stringify(input.name);
-            const optsJson = JSON.stringify({ payloadType: input.payloadType, x: input.x, y: input.y });
+            const optsJson = JSON.stringify({ payloadType: input.payloadType, x: input.x, y: input.y, ...(input.at !== undefined ? { at: input.at } : {}) });
             return `
 // Create event: ${input.name}
 (function() {
@@ -13144,7 +13658,7 @@ ${guard('unlockAllItems')}${pass('app.unlockAllItems()')}
   const eventId = app.createEvent(${nameJson}, ${optsJson});
   if (!eventId) { return { success: false, error: 'Event creation failed' }; }
   if (app.historyManager) app.historyManager.saveState();
-  return { success: true, action: 'create', eventId };
+  return { success: true, action: 'create', eventId${input.at !== undefined ? `, at: ${JSON.stringify(input.at)}` : ''} };
 })();`.trim();
         }
         // pulse — a runtime fire, not a scene edit (no history save)