@pinepaper.studio/mcp-server 1.5.4 → 1.6.0

package/dist/types/code-generator.js

@@ -10,20 +10,19 @@ import { CreateItemInputSchema, ModifyItemInputSchema, AddRelationInputSchema, A
 CreateDiagramShapeInputSchema, ConnectInputSchema, ConnectPortsInputSchema, AddPortsInputSchema, AutoLayoutInputSchema, GetDiagramShapesInputSchema, UpdateConnectorInputSchema, RemoveConnectorInputSchema, DiagramModeInputSchema, 
 // Agent flow mode types
 AgentStartJobInputSchema, AgentEndJobInputSchema, AgentResetInputSchema, AgentBatchExecuteInputSchema, AgentExportInputSchema, AgentAnalyzeInputSchema, 
-// Interactive/Trigger types
-AddTriggerInputSchema, RemoveTriggerInputSchema, QueryTriggersInputSchema, 
-// Quiz types
-CreateQuizInputSchema, GetQuizStateInputSchema, ResetQuizInputSchema, 
 // Letter collage types
 CreateLetterCollageInputSchema, AnimateLetterCollageInputSchema, 
 // Map types
 LoadMapInputSchema, HighlightRegionsInputSchema, UnhighlightRegionsInputSchema, ApplyDataColorsInputSchema, AddMarkerInputSchema, AddMapLabelsInputSchema, PanMapInputSchema, ZoomMapInputSchema, ImportCustomMapInputSchema, GetRegionAtPointInputSchema, 
 // Map animation/CSV types
 AnimateMapRegionsInputSchema, AnimateMapWaveInputSchema, StopMapAnimationsInputSchema, ExportMapRegionCSVInputSchema, ImportMapRegionCSVInputSchema, SelectMapRegionsInputSchema, DeselectMapRegionsInputSchema, 
+// Globe + world tour types
+GlobeEnableInputSchema, GlobeRotateToInputSchema, GlobeSpinInputSchema, WorldTourInputSchema, StopWorldTourInputSchema, PinToGlobeInputSchema, TourItemInputSchema, 
 // Custom relation/code types
 RegisterCustomRelationInputSchema, ExecuteCustomCodeInputSchema, 
 // Mask types
 ApplyAnimatedMaskInputSchema, ApplyCustomMaskInputSchema, RemoveMaskInputSchema, } from './schemas.js';
+import { OntologyCompiler } from '../ontology/ontology-compiler.js';
 // =============================================================================
 // HELPER FUNCTIONS
 // =============================================================================
@@ -277,7 +276,9 @@ const relations = results.map(r => ({
 /**
  * Template for simple animation
  */
-function generateAnimateCode(itemId, animationType, speed) {
+function generateAnimateCode(itemId, animationType, speed, intensity, delay) {
+    const extra = (intensity !== undefined ? `,\n  animationIntensity: ${intensity}` : '') +
+        (delay !== undefined ? `,\n  animationDelay: ${delay}` : '');
     return `
 // Apply ${animationType} animation to ${itemId}
 const item = app.getItemById('${itemId}');
@@ -286,17 +287,33 @@ if (!item) {
 }
 app.animate(item, {
   animationType: '${animationType}',
-  animationSpeed: ${speed}
+  animationSpeed: ${speed}${extra}
 });
 
 ({ success: true, itemId: '${itemId}', animationType: '${animationType}' });
 `.trim();
 }
+/**
+ * PinePaper's keyframe interpolator only tweens `position` when it is an [x, y]
+ * ARRAY. Callers (and other agents) routinely pass a { x, y } object, which is
+ * silently ignored — the item then stays frozen for the whole animation. Accept
+ * both shapes by normalizing { x, y } -> [x, y] before the keyframes are emitted.
+ */
+function normalizeKeyframePositions(keyframes) {
+    return (keyframes || []).map((kf) => {
+        const props = kf?.properties;
+        const p = props?.position;
+        if (p && !Array.isArray(p) && typeof p === 'object' && 'x' in p && 'y' in p) {
+            return { ...kf, properties: { ...props, position: [p.x, p.y] } };
+        }
+        return kf;
+    });
+}
 /**
  * Template for keyframe animation
  */
-function generateKeyframeAnimateCode(itemId, keyframes, duration, loop = false, timeOffset, clipInPoint, clipOutPoint) {
-    const keyframesJson = JSON.stringify(keyframes, null, 2);
+function generateKeyframeAnimateCode(itemId, keyframes, duration, loop = false, timeOffset, clipInPoint, clipOutPoint, timeUnits) {
+    const keyframesJson = JSON.stringify(normalizeKeyframePositions(keyframes), null, 2);
     const calculatedDuration = duration || Math.max(...keyframes.map(k => k.time));
     const opts = { duration: calculatedDuration, loop };
     if (timeOffset !== undefined)
@@ -305,6 +322,8 @@ function generateKeyframeAnimateCode(itemId, keyframes, duration, loop = false,
         opts.clipInPoint = clipInPoint;
     if (clipOutPoint !== undefined)
         opts.clipOutPoint = clipOutPoint;
+    if (timeUnits !== undefined)
+        opts.timeUnits = timeUnits;
     return `
 // Apply keyframe animation to ${itemId}
 app.addAnimation('${itemId}', ${keyframesJson}, ${JSON.stringify(opts)});
@@ -315,12 +334,15 @@ app.addAnimation('${itemId}', ${keyframesJson}, ${JSON.stringify(opts)});
 /**
  * Template for executing generators
  */
-function generateExecuteGeneratorCode(generatorName, params) {
+function generateExecuteGeneratorCode(generatorName, params, region) {
+    // FxTool signature: app.executeGenerator(name, params, options).
+    // region lives in options (added in FxTool c81781c).
+    const options = region ? { region } : {};
     return `
-// Execute ${generatorName} generator
+// Execute ${generatorName} generator${region ? ` in region ${region.width}×${region.height} @ (${region.x},${region.y})` : ''}
 (async function() {
-  await app.executeGenerator('${generatorName}', ${JSON.stringify(params, null, 2)});
-  return { success: true, generator: '${generatorName}' };
+  await app.executeGenerator('${generatorName}', ${JSON.stringify(params, null, 2)}, ${JSON.stringify(options)});
+  return { success: true, generator: '${generatorName}'${region ? ', region: ' + JSON.stringify(region) : ''} };
 })();
 `.trim();
 }
@@ -389,12 +411,12 @@ const items = filtered.map(entry => ({
 /**
  * Template for timeline control
  */
-function generatePlayTimelineCode(action, duration, loop, time) {
+function generatePlayTimelineCode(action, duration, loop, time, deterministic) {
     switch (action) {
         case 'play':
             return `
 // Play keyframe timeline
-app.playKeyframeTimeline(${duration || 5}, ${loop ?? false});
+app.playKeyframeTimeline(${duration || 5}, ${loop ?? false}, { timeUnits: 'seconds' });
 ({ success: true, action: 'play', duration: ${duration || 5}, loop: ${loop ?? false} });
 `.trim();
         case 'pause':
@@ -410,6 +432,18 @@ app.stopKeyframeTimeline();
 ({ success: true, action: 'stop' });
 `.trim();
         case 'seek':
+            if (deterministic) {
+                return `
+// Deterministic seek — evaluate the whole scene at the exact time (keyframes + relations + generators)
+(function() {
+  const t = ${time || 0};
+  if (typeof app.sceneAt === 'function') { app.sceneAt(t); return { success: true, action: 'seek', time: t, deterministic: true }; }
+  // Fallback for older FxTool builds without sceneAt
+  app.setPlaybackTime(t);
+  return { success: true, action: 'seek', time: t, deterministic: false, note: 'app.sceneAt unavailable — used setPlaybackTime (keyframe state only); update FxTool for deterministic relations/generators' };
+})();
+`.trim();
+            }
             return `
 // Seek to time
 app.setPlaybackTime(${time || 0});
@@ -456,35 +490,29 @@ const size = app.getCanvasSize();
  */
 function generateClearCanvasCode() {
     return `
-// Clear all items from canvas
-const entries = app.itemRegistry.getAll();
-const itemIds = entries.map(entry => entry.id || entry.itemId);
-let removedCount = 0;
-
-for (const itemId of itemIds) {
-  try {
-    const item = app.getItemById(itemId);
-    if (item) {
-      item.remove();
-      app.itemRegistry.remove(itemId);
-      removedCount++;
-    }
-  } catch (e) {
-    console.warn('Failed to remove item:', itemId, e);
-  }
-}
-
-// Also clear any relations
-if (app.clearAllRelations) {
-  app.clearAllRelations();
+// Clear all items from canvas. Prefer app.clearCanvas() — the canonical
+// reset that also tears down relations, the (virtual) camera animation,
+// generators, effects and background. The old manual loop here was broken:
+// it keyed item lookups on entry.id/entry.itemId (the registry getAll()
+// entries don't expose those — getItemById wants the registry id), so it
+// removed 0 items, and it called the non-existent app.clearAllRelations.
+const before = app.itemRegistry ? app.itemRegistry.getAll().length : 0;
+
+if (typeof app.clearCanvas === 'function') {
+  app.clearCanvas();
+} else {
+  // Fallback for older builds without clearCanvas().
+  if (app.textItemGroup) app.textItemGroup.removeChildren();
+  if (app.patternGroup) app.patternGroup.removeChildren();
+  if (app.itemRegistry) app.itemRegistry.clear();
+  if (app.relationRegistry) app.relationRegistry.clear();
 }
 
-app.historyManager.saveState();
+if (app.historyManager) app.historyManager.saveState();
 
-// Verify canvas is empty
-const remaining = app.itemRegistry.getAll().length;
+const remaining = app.itemRegistry ? app.itemRegistry.getAll().length : 0;
 
-({ success: true, removedCount, remainingItems: remaining });
+({ success: true, removedCount: Math.max(0, before - remaining), remainingItems: remaining });
 `.trim();
 }
 /**
@@ -549,6 +577,82 @@ const formatted = generators.map(g => ({
 ({ generators: formatted });
 `.trim();
 }
+/**
+ * True when app.create() derives this item's geometry from explicit coordinates
+ * and therefore ignores params.position:
+ *   - path  built from `segments` or `pathData`
+ *   - line  built from `from`/`to`
+ *   - arc   built from `from`/`through`/`to`
+ * Without those coordinate props these types fall back to the position-derived
+ * point, so create() already places them correctly and we must not interfere.
+ */
+export function isCoordinateBuilt(itemType, props) {
+    switch (itemType) {
+        case 'path':
+            return props.segments !== undefined || props.pathData !== undefined;
+        case 'line':
+            return props.from !== undefined || props.to !== undefined;
+        case 'arc':
+            return props.from !== undefined || props.through !== undefined || props.to !== undefined;
+        default:
+            return false;
+    }
+}
+/**
+ * app.addAnimation() REPLACES data.keyframes wholesale, so two
+ * keyframe_animate ops targeting one item meant the first track was silently
+ * discarded — the batch still reported success while (e.g.) a rotation channel
+ * vanished because a later op set a colour channel on the same item.
+ *
+ * Plan a merge: fold every duplicate target's keyframes into its FIRST op
+ * (keeping author order), union by timestamp with later ops winning on a
+ * per-property conflict. Op slots are preserved so `results` stays 1:1 with
+ * `operations` and `$N` indices are untouched; the folded slots emit an
+ * explicit `{ merged: true }` marker so the merge is visible to the caller
+ * rather than being another silent rewrite.
+ */
+export function planKeyframeMerges(operations) {
+    const byTarget = new Map();
+    operations.forEach((op, i) => {
+        if (op.type !== 'keyframe_animate' || !op.itemId)
+            return;
+        const list = byTarget.get(op.itemId) || [];
+        list.push(i);
+        byTarget.set(op.itemId, list);
+    });
+    const plan = { merged: new Map(), foldedInto: new Map() };
+    for (const indices of byTarget.values()) {
+        if (indices.length < 2)
+            continue;
+        const first = indices[0];
+        // Union keyframes by time; later ops shallow-merge over earlier ones.
+        const byTime = new Map();
+        let duration = 0;
+        let loop = false;
+        for (const i of indices) {
+            const op = operations[i];
+            for (const kf of op.keyframes || []) {
+                const prev = byTime.get(kf.time);
+                byTime.set(kf.time, {
+                    time: kf.time,
+                    properties: { ...(prev?.properties || {}), ...(kf.properties || {}) },
+                    ...((kf.easing ?? prev?.easing) !== undefined ? { easing: kf.easing ?? prev?.easing } : {}),
+                });
+            }
+            const opMax = op.keyframes?.length ? Math.max(...op.keyframes.map(k => k.time)) : 0;
+            duration = Math.max(duration, op.duration || opMax);
+            loop = loop || op.loop === true;
+            if (i !== first)
+                plan.foldedInto.set(i, first);
+        }
+        plan.merged.set(first, {
+            keyframes: [...byTime.values()].sort((a, b) => a.time - b.time),
+            duration: duration || 5,
+            loop,
+        });
+    }
+    return plan;
+}
 /**
  * Template for batch create - creates multiple items with single history save
  */
@@ -632,6 +736,10 @@ export class PinePaperCodeGenerator {
             properties.animationType = validated.animationType;
         if (validated.animationSpeed !== undefined)
             properties.animationSpeed = validated.animationSpeed;
+        if (validated.animationIntensity !== undefined)
+            properties.animationIntensity = validated.animationIntensity;
+        if (validated.animationDelay !== undefined)
+            properties.animationDelay = validated.animationDelay;
         if (validated.keyframes !== undefined)
             properties.keyframes = validated.keyframes;
         return generateCreateItemCode(validated.itemType, validated.position, properties);
@@ -673,21 +781,21 @@ export class PinePaperCodeGenerator {
      */
     generateAnimate(input) {
         const validated = AnimateItemInputSchema.parse(input);
-        return generateAnimateCode(validated.itemId, validated.animationType, validated.speed);
+        return generateAnimateCode(validated.itemId, validated.animationType, validated.speed, validated.intensity, validated.delay);
     }
     /**
      * Generate code for keyframe animation
      */
     generateKeyframeAnimate(input) {
         const validated = KeyframeAnimateInputSchema.parse(input);
-        return generateKeyframeAnimateCode(validated.itemId, validated.keyframes, validated.duration, validated.loop, validated.timeOffset, validated.clipInPoint, validated.clipOutPoint);
+        return generateKeyframeAnimateCode(validated.itemId, validated.keyframes, validated.duration, validated.loop, validated.timeOffset, validated.clipInPoint, validated.clipOutPoint, validated.timeUnits);
     }
     /**
      * Generate code for executing a generator
      */
     generateExecuteGenerator(input) {
         const validated = ExecuteGeneratorInputSchema.parse(input);
-        return generateExecuteGeneratorCode(validated.generatorName, validated.params);
+        return generateExecuteGeneratorCode(validated.generatorName, validated.params, validated.region);
     }
     /**
      * Generate code for applying an effect
@@ -705,8 +813,8 @@ export class PinePaperCodeGenerator {
     /**
      * Generate code for timeline control
      */
-    generatePlayTimeline(action, duration, loop, time) {
-        return generatePlayTimelineCode(action, duration, loop, time);
+    generatePlayTimeline(action, duration, loop, time, deterministic) {
+        return generatePlayTimelineCode(action, duration, loop, time, deterministic);
     }
     /**
      * Generate code for setting background color
@@ -864,6 +972,28 @@ throw new Error('Either svgString or url must be provided');
     viewport: ctx.viewport,
   };
 })();
+`.trim();
+    }
+    /**
+     * Generate code for semantic validation (FxTool OntologyValidator) — runs in the
+     * browser against the live scene and returns structured diagnostics.
+     */
+    generateValidate(input) {
+        const mode = input.mode || 'scene';
+        const opJson = JSON.stringify(input.op ?? null);
+        return `
+// Semantic validation — structured diagnostics
+(function() {
+  if (typeof app.validateScene !== 'function' || typeof app.validateOp !== 'function') {
+    return {
+      success: false,
+      error: 'app.validateScene/validateOp not available — requires FxTool with OntologyValidator v1 (commit 7f151f4 or later).',
+    };
+  }
+  var mode = ${JSON.stringify(mode)};
+  var result = (mode === 'op') ? app.validateOp(${opJson}) : app.validateScene();
+  return { success: true, mode: mode, ok: result.ok, diagnostics: result.diagnostics };
+})();
 `.trim();
     }
     /**
@@ -1178,13 +1308,9 @@ if (typeof app.generators !== 'undefined' && app.generators['${backgroundGenerat
   const sourceId = nameToId['${source}'];
   const targetId = nameToId['${target}'];
   if (sourceId && targetId) {
-    const sourceItem = app.itemRegistry.get(sourceId);
-    const targetItem = app.itemRegistry.get(targetId);
-    if (sourceItem && targetItem) {
-      const params = ${paramsStr};
-      app.relationManager.addRelation(sourceItem, targetItem, '${type}', params);
-      results.relations.push({ source: '${source}', target: '${target}', type: '${type}' });
-    }
+    const params = ${paramsStr};
+    app.addRelation(sourceId, targetId, '${type}', params);
+    results.relations.push({ source: '${source}', target: '${target}', type: '${type}' });
   }
 })();
 `);
@@ -1601,14 +1727,7 @@ throw new Error('Unknown diagram mode action: ${action}');
     if (item.shadowColor || item.shadowBlur) analysis.hasShadows = true;
   });
 
-  // Check animation manager for registered animations
-  if (app.animationManager) {
-    const animations = app.animationManager.getAll ? app.animationManager.getAll() : (app.animationManager.animations || []);
-    if (animations.length > 0) {
-      analysis.hasAnimations = true;
-      animationSet.add('managed');
-    }
-  }
+  // 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)) {
     analysis.hasAnimations = true;
@@ -1733,6 +1852,9 @@ throw new Error('Unknown diagram mode action: ${action}');
         const validated = AgentBatchExecuteInputSchema.parse(input);
         const { operations, atomic } = validated;
         const isAtomic = atomic !== false;
+        // Fold duplicate keyframe_animate targets so a later op can't silently
+        // clobber an earlier track (app.addAnimation replaces, never merges).
+        const mergePlan = planKeyframeMerges(operations);
         let code = `
 // Batch execute ${operations.length} operations
 (async function() {
@@ -1743,7 +1865,17 @@ throw new Error('Unknown diagram mode action: ${action}');
   try {
 `;
         operations.forEach((op, index) => {
-            const opCode = this.generateBatchOperationCode(op, index);
+            const opCode = this.generateBatchOperationCode(op, index, mergePlan);
+            // $N variable references are documented as "items CREATED in earlier
+            // operations" — only `create` results may extend the itemIds array.
+            // animate/keyframe_animate/modify/delete also return { itemId } (the
+            // TARGET's id), and unconditionally pushing those shifted every later
+            // $N reference: a batch of [create ×5, keyframe_animate ×5, create ×5,
+            // keyframe_animate ×5] silently re-animated the FIRST five items and
+            // left the second five without keyframes (mis-oriented/mis-animated
+            // vehicles, 2026-07-30). `group` already follows this rule by
+            // returning groupId instead of itemId.
+            const claimsItemSlot = op.type === 'create';
             code += `
     // Operation ${index}: ${op.type}
     try {
@@ -1751,9 +1883,9 @@ throw new Error('Unknown diagram mode action: ${action}');
         ${opCode}
       })();
       results.push({ index: ${index}, success: true, result: result${index} });
-      if (result${index} && result${index}.itemId) {
+      ${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;'}
@@ -1777,18 +1909,44 @@ throw new Error('Unknown diagram mode action: ${action}');
     /**
      * Generate code for a single batch operation
      */
-    generateBatchOperationCode(op, index) {
+    generateBatchOperationCode(op, index, mergePlan) {
         switch (op.type) {
-            case 'create':
+            case 'create': {
                 const pos = op.position || { x: 400, y: 300 };
-                const props = JSON.stringify(op.properties || {});
-                return `
+                const createProps = (op.properties || {});
+                const props = JSON.stringify(createProps);
+                let createCode = `
 const item = app.create('${op.itemType}', { position: { x: ${pos.x}, y: ${pos.y} }, ...${props} });
-const itemId = item.data && item.data.id ? item.data.id : app.registerItem(item, '${op.itemType}', { source: 'mcp-batch' });
+const itemId = item.data && item.data.id ? item.data.id : app.registerItem(item, '${op.itemType}', { source: 'mcp-batch' });`;
+                // app.create() does not read blendMode/opacity from its params, but the
+                // underlying Paper.js item supports them directly — apply post-create so
+                // callers can pass them inline in `properties` and have them take effect.
+                if (createProps.blendMode !== undefined) {
+                    createCode += `\nif ('blendMode' in item) item.blendMode = ${JSON.stringify(createProps.blendMode)};`;
+                }
+                if (createProps.opacity !== undefined) {
+                    createCode += `\nif ('opacity' in item) item.opacity = ${JSON.stringify(createProps.opacity)};`;
+                }
+                // 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
+                // item at its raw coordinates instead. Re-seat it after create when the
+                // caller explicitly asked for a position. Guarded on an explicit
+                // op.position so absolute-coordinate geometry (the common case, which
+                // passes no position) is never snapped to the injected default.
+                if (op.position && isCoordinateBuilt(op.itemType, createProps)) {
+                    createCode += `
+// create() builds this item type from its own coordinates and ignores
+// params.position — apply the caller's explicit position after the fact.
+if (item.position) item.position = new paper.Point(${pos.x}, ${pos.y});`;
+                }
+                createCode += `
 // Ensure item is visible above backgrounds/generators
 if (item.bringToFront) item.bringToFront();
 return { itemId };
 `;
+                return createCode;
+            }
             case 'modify':
                 const itemRef = op.itemId?.startsWith('$')
                     ? `itemIds[${op.itemId.substring(1)}]`
@@ -1842,6 +2000,17 @@ item.remove();
 if (app.itemRegistry) app.itemRegistry.unregister(targetId);
 return { itemId: targetId, deleted: true };
 `;
+            case 'group': {
+                // Resolve each ref ($N → itemIds[N]; literal → quoted id) into a JS array.
+                const refs = (op.itemIds || []).map((ref) => ref?.startsWith('$') ? `itemIds[${ref.substring(1)}]` : `'${ref}'`);
+                const idsArrayExpr = `[${refs.join(', ')}]`;
+                const nameExpr = op.groupName !== undefined ? JSON.stringify(op.groupName) : 'undefined';
+                // Returns { groupId, ... } (no itemId) so it does NOT shift $N indices — like relation.
+                return `
+return (function() {${this.groupCodeBody(idsArrayExpr, nameExpr)}
+})();
+`;
+            }
             case 'set_background':
                 const bgColor = op.backgroundColor || op.properties?.color || '#000000';
                 return `
@@ -1851,9 +2020,10 @@ return { success: true, backgroundColor: '${bgColor}' };
             case 'execute_generator':
                 const genName = op.generatorName || 'drawSunburst';
                 const genParams = JSON.stringify(op.generatorParams || {});
+                const genOptions = JSON.stringify(op.generatorRegion ? { region: op.generatorRegion } : {});
                 return `
-await app.executeGenerator('${genName}', ${genParams});
-return { success: true, generator: '${genName}' };
+await app.executeGenerator('${genName}', ${genParams}, ${genOptions});
+return { success: true, generator: '${genName}'${op.generatorRegion ? ', region: ' + JSON.stringify(op.generatorRegion) : ''} };
 `;
             case 'set_canvas_size': {
                 const w = op.width || 1080;
@@ -1866,12 +2036,25 @@ return { success: true, width: ${w}, height: ${h} };
 `;
             }
             case 'keyframe_animate': {
+                // Folded into an earlier op on the same target (see planKeyframeMerges).
+                const foldTarget = mergePlan?.foldedInto.get(index);
+                if (foldTarget !== undefined) {
+                    return `
+// Keyframes merged into operation ${foldTarget} (same target). A keyframe track
+// is replaced wholesale, so emitting both here would silently drop one.
+return { itemId: ${op.itemId?.startsWith('$') ? `itemIds[${op.itemId.substring(1)}]` : `'${op.itemId}'`}, merged: true, mergedInto: ${foldTarget} };
+`;
+                }
+                const mergedPayload = mergePlan?.merged.get(index);
                 const kfItemRef = op.itemId?.startsWith('$')
                     ? `itemIds[${op.itemId.substring(1)}]`
                     : `'${op.itemId}'`;
-                const kfJson = JSON.stringify(op.keyframes || []);
-                const kfDuration = op.duration || (op.keyframes?.length ? Math.max(...op.keyframes.map(k => k.time)) : 5);
-                const kfLoop = op.loop ?? false;
+                const kfSource = mergedPayload ? mergedPayload.keyframes : (op.keyframes || []);
+                const kfJson = JSON.stringify(normalizeKeyframePositions(kfSource));
+                const kfDuration = mergedPayload
+                    ? mergedPayload.duration
+                    : (op.duration || (op.keyframes?.length ? Math.max(...op.keyframes.map(k => k.time)) : 5));
+                const kfLoop = mergedPayload ? mergedPayload.loop : (op.loop ?? false);
                 return `
 const targetId = ${kfItemRef};
 app.addAnimation(targetId, ${kfJson}, { duration: ${kfDuration}, loop: ${kfLoop} });
@@ -1883,16 +2066,14 @@ return { itemId: targetId, duration: ${kfDuration}, loop: ${kfLoop} };
                     ? `itemIds[${op.itemId.substring(1)}]`
                     : `'${op.itemId}'`;
                 const maskOpts = JSON.stringify(op.maskOptions || {});
+                const preset = op.maskPreset || op.maskType || 'wipeLeft';
                 return `
 const targetId = ${maskItemRef};
-if (!app.maskSystem) throw new Error('Mask system not available');
-const result = app.maskSystem.applyAnimatedMask(targetId, {
-  preset: ${op.maskPreset ? `'${op.maskPreset}'` : 'null'},
-  maskType: ${op.maskType ? `'${op.maskType}'` : 'null'},
-  options: ${maskOpts},
-  maskOptions: ${maskOpts}
-});
-return result;
+const item = app.getItemById(targetId);
+if (!item) throw new Error('Item not found: ' + targetId);
+if (!app.applyAnimatedMask) throw new Error('Mask system not available');
+const maskedGroup = app.applyAnimatedMask(item, '${preset}', ${maskOpts});
+return { success: !!maskedGroup, itemId: targetId, preset: '${preset}' };
 `;
             }
             case 'apply_effect': {
@@ -1914,7 +2095,7 @@ return { itemId: targetId, effectType: '${op.effectType || 'sparkle'}' };
                 const ptLoop = op.loop ?? false;
                 if (ptAction === 'play') {
                     return `
-app.playKeyframeTimeline(${ptDuration}, ${ptLoop});
+app.playKeyframeTimeline(${ptDuration}, ${ptLoop}, { timeUnits: 'seconds' });
 return { success: true, action: 'play', duration: ${ptDuration}, loop: ${ptLoop} };
 `;
                 }
@@ -1940,8 +2121,9 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
      */
     generateAgentExport(input) {
         const validated = AgentExportInputSchema.parse(input);
-        const { platform, format, quality, framing } = validated;
+        const { platform, format, quality, framing, duration } = validated;
         const qualityLevel = quality || 'standard';
+        const videoDuration = duration ?? 5;
         // Quality settings (bitrate in bps for VideoEncoder)
         const qualitySettings = {
             draft: { compression: 0.6, fps: 15, dpi: 72, bitrate: 2_000_000 },
@@ -2055,7 +2237,7 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
         // ExportEngine._quickExportVideo overrides quality with undefined for
         // mp4/webm, _calculateBitrate yields NaN, and VideoEncoder.configure
         // rejects with 'malformed bitrate value'.
-        const baseVideoSettings = { format, fps: settings.fps, quality: settings.compression, duration: 5 };
+        const baseVideoSettings = { format, fps: settings.fps, quality: settings.compression, duration: ${videoDuration} };
         const blobToDataUrl = (b) => new Promise(resolve => {
           const r = new FileReader();
           r.onloadend = () => resolve(r.result);
@@ -2178,14 +2360,7 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
     if (item.shadowColor || item.shadowBlur) hasShadow = true;
   });
 
-  // Check animation manager for registered animations
-  if (app.animationManager) {
-    const animations = app.animationManager.getAll ? app.animationManager.getAll() : (app.animationManager.animations || []);
-    if (animations.length > 0) {
-      analysis.hasAnimations = true;
-      animationSet.add('managed');
-    }
-  }
+  // 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)) {
     analysis.hasAnimations = true;
@@ -2249,257 +2424,6 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
     suggestedPlatforms
   };
 })();
-`.trim();
-    }
-    // ===========================================================================
-    // INTERACTIVE TRIGGER CODE GENERATORS
-    // ===========================================================================
-    /**
-     * Generate code for adding a trigger
-     */
-    generateAddTrigger(input) {
-        const validated = AddTriggerInputSchema.parse(input);
-        const { itemId, event, actions, condition, timelineOffset } = validated;
-        const actionsStr = JSON.stringify(actions);
-        const conditionStr = condition ? `'${condition.replace(/'/g, "\\'")}'` : 'null';
-        const offsetStr = timelineOffset !== undefined ? timelineOffset : 'null';
-        return `
-// Add trigger to ${itemId}
-const item = app.getItemById('${itemId}');
-if (!item) throw new Error('Item not found: ${itemId}');
-
-const trigger = {
-  event: '${event}',
-  actions: ${actionsStr},
-  condition: ${conditionStr},
-  timelineOffset: ${offsetStr}
-};
-
-// Initialize triggers array if needed
-if (!item.data) item.data = {};
-if (!item.data.triggers) item.data.triggers = [];
-
-// Add trigger
-item.data.triggers.push(trigger);
-
-// Register event handler
-if (app.triggerManager) {
-  app.triggerManager.registerTrigger(item, trigger);
-}
-
-app.historyManager.saveState();
-({ success: true, itemId: '${itemId}', event: '${event}', triggerId: item.data.triggers.length - 1 });
-`.trim();
-    }
-    /**
-     * Generate code for removing a trigger
-     */
-    generateRemoveTrigger(input) {
-        const validated = RemoveTriggerInputSchema.parse(input);
-        const { itemId, event, removeAll } = validated;
-        if (removeAll) {
-            return `
-// Remove all triggers from ${itemId}
-const item = app.getItemById('${itemId}');
-if (!item) throw new Error('Item not found: ${itemId}');
-
-const removedCount = item.data?.triggers?.length || 0;
-if (item.data) item.data.triggers = [];
-
-if (app.triggerManager) {
-  app.triggerManager.unregisterAll(item);
-}
-
-app.historyManager.saveState();
-({ success: true, itemId: '${itemId}', removedCount, removeAll: true });
-`.trim();
-        }
-        return `
-// Remove ${event} trigger from ${itemId}
-const item = app.getItemById('${itemId}');
-if (!item) throw new Error('Item not found: ${itemId}');
-
-let removedCount = 0;
-if (item.data?.triggers) {
-  const before = item.data.triggers.length;
-  item.data.triggers = item.data.triggers.filter(t => t.event !== '${event}');
-  removedCount = before - item.data.triggers.length;
-}
-
-if (app.triggerManager) {
-  app.triggerManager.unregisterEvent(item, '${event}');
-}
-
-app.historyManager.saveState();
-({ success: true, itemId: '${itemId}', event: '${event}', removedCount });
-`.trim();
-    }
-    /**
-     * Generate code for querying triggers
-     */
-    generateQueryTriggers(input) {
-        const validated = QueryTriggersInputSchema.parse(input);
-        const { itemId, event } = validated;
-        if (itemId) {
-            return `
-// Query triggers for ${itemId}
-const item = app.getItemById('${itemId}');
-if (!item) throw new Error('Item not found: ${itemId}');
-
-let triggers = item.data?.triggers || [];
-${event ? `triggers = triggers.filter(t => t.event === '${event}');` : ''}
-
-({ success: true, itemId: '${itemId}', triggers, count: triggers.length });
-`.trim();
-        }
-        return `
-// Query all triggers
-const allTriggers = [];
-const items = app.itemRegistry ? app.itemRegistry.getAll() : [];
-
-items.forEach(entry => {
-  const item = entry.item;
-  if (item.data?.triggers?.length > 0) {
-    let triggers = item.data.triggers;
-    ${event ? `triggers = triggers.filter(t => t.event === '${event}');` : ''}
-    triggers.forEach((trigger, idx) => {
-      allTriggers.push({
-        itemId: entry.id,
-        triggerId: idx,
-        ...trigger
-      });
-    });
-  }
-});
-
-({ success: true, triggers: allTriggers, count: allTriggers.length${event ? `, event: '${event}'` : ''} });
-`.trim();
-    }
-    // ===========================================================================
-    // QUIZ CODE GENERATORS
-    // ===========================================================================
-    /**
-     * Generate code for creating a quiz
-     */
-    generateCreateQuiz(input) {
-        const validated = CreateQuizInputSchema.parse(input);
-        const { title, questions, passingScore, showScore, allowRetry, shuffleQuestions, shuffleOptions } = validated;
-        const quizConfig = JSON.stringify({
-            title: title || 'Untitled Quiz',
-            questions,
-            passingScore: passingScore || 70,
-            showScore: showScore !== false,
-            allowRetry: allowRetry !== false,
-            shuffleQuestions: shuffleQuestions || false,
-            shuffleOptions: shuffleOptions || false,
-        }, null, 2);
-        return `
-// Create quiz
-const quizConfig = ${quizConfig};
-
-// Initialize quiz manager if needed
-if (!app.quizManager) {
-  app.quizManager = {
-    quizzes: [],
-    activeQuiz: null,
-    createQuiz: function(config) {
-      const quiz = {
-        id: 'quiz_' + Date.now(),
-        ...config,
-        state: {
-          currentQuestion: 0,
-          answers: [],
-          score: 0,
-          maxScore: config.questions.reduce((sum, q) => sum + q.points, 0),
-          complete: false
-        }
-      };
-      this.quizzes.push(quiz);
-      this.activeQuiz = quiz;
-      return quiz;
-    }
-  };
-}
-
-const quiz = app.quizManager.createQuiz(quizConfig);
-app.historyManager.saveState();
-
-({
-  success: true,
-  quizId: quiz.id,
-  title: quiz.title,
-  questionCount: quiz.questions.length,
-  maxScore: quiz.state.maxScore,
-  passingScore: quiz.passingScore
-});
-`.trim();
-    }
-    /**
-     * Generate code for getting quiz state
-     */
-    generateGetQuizState(input) {
-        const validated = GetQuizStateInputSchema.parse(input);
-        const { quizId } = validated;
-        const quizRef = quizId
-            ? `app.quizManager.quizzes.find(q => q.id === '${quizId}')`
-            : 'app.quizManager?.activeQuiz';
-        return `
-// Get quiz state
-if (!app.quizManager) {
-  return { success: false, error: 'No quiz manager initialized' };
-}
-
-const quiz = ${quizRef};
-if (!quiz) {
-  return { success: false, error: 'Quiz not found' };
-}
-
-({
-  success: true,
-  quizId: quiz.id,
-  title: quiz.title,
-  currentQuestion: quiz.state.currentQuestion,
-  totalQuestions: quiz.questions.length,
-  score: quiz.state.score,
-  maxScore: quiz.state.maxScore,
-  answers: quiz.state.answers,
-  complete: quiz.state.complete,
-  passed: quiz.state.complete ? (quiz.state.score / quiz.state.maxScore * 100) >= quiz.passingScore : null
-});
-`.trim();
-    }
-    /**
-     * Generate code for resetting a quiz
-     */
-    generateResetQuiz(input) {
-        const validated = ResetQuizInputSchema.parse(input);
-        const { quizId } = validated;
-        const quizRef = quizId
-            ? `app.quizManager.quizzes.find(q => q.id === '${quizId}')`
-            : 'app.quizManager?.activeQuiz';
-        return `
-// Reset quiz
-if (!app.quizManager) {
-  return { success: false, error: 'No quiz manager initialized' };
-}
-
-const quiz = ${quizRef};
-if (!quiz) {
-  return { success: false, error: 'Quiz not found' };
-}
-
-// Reset state
-quiz.state = {
-  currentQuestion: 0,
-  answers: [],
-  score: 0,
-  maxScore: quiz.questions.reduce((sum, q) => sum + q.points, 0),
-  complete: false
-};
-
-app.historyManager.saveState();
-
-({ success: true, quizId: quiz.id, reset: true });
 `.trim();
     }
     // ===========================================================================
@@ -2510,7 +2434,7 @@ app.historyManager.saveState();
      */
     generateCreateLetterCollage(input) {
         const validated = CreateLetterCollageInputSchema.parse(input);
-        const { text, style = 'tile', palette, position, fontSize = 48, fontFamily = 'Inter, sans-serif', spacing = 1.1, gradientPalette, gradientDirection = 'vertical', cornerRadius = 4, shadowEnabled = true, } = validated;
+        const { text, style = 'tile', palette, position, fontSize = 48, fontFamily = 'Inter, sans-serif', spacing = 1.1, gradientPalette, gradientDirection = 'vertical', cornerRadius = 4, shadowEnabled = true, particleSpacing, particleDotSize, } = validated;
         // Build options object
         const options = {
             style,
@@ -2528,6 +2452,10 @@ app.historyManager.saveState();
             options.gradientPalette = gradientPalette;
         if (gradientDirection)
             options.gradientDirection = gradientDirection;
+        if (particleSpacing !== undefined)
+            options.particleSpacing = particleSpacing;
+        if (particleDotSize !== undefined)
+            options.particleDotSize = particleDotSize;
         return `
 // Create letter collage
 (function() {
@@ -2588,80 +2516,6 @@ app.historyManager.saveState();
 
   return result;
 })();
-`.trim();
-    }
-    /**
-     * Generate code to get letter collage options
-     */
-    generateGetLetterCollageOptions() {
-        return `
-// Get letter collage options
-(function() {
-  if (!app.getLetterCollageOptions) {
-    // Return static options if function not available
-    return {
-      success: true,
-      styles: ['tile', 'magazine', 'paperCut', 'fold', 'gradient', 'image'],
-      tilePalettes: {
-        game: ['wordle', 'scrabble'],
-        vibrant: ['candy', 'neon', 'rainbow'],
-        soft: ['pastel', 'cotton'],
-        natural: ['earth', 'ocean', 'forest', 'sunset'],
-        professional: ['corporate', 'minimal', 'slate'],
-        seasonal: ['christmas', 'halloween', 'spring'],
-        magazine: ['magazine', 'newspaper', 'vintage'],
-        paperCraft: ['paperCraft', 'origami', 'craftPaper']
-      },
-      gradientPalettes: ['rainbow', 'sunset', 'ocean', 'fire', 'gold', 'rose', 'ice', 'cyberpunk', 'neonGlow', 'purplePink'],
-      gradientDirections: ['vertical', 'horizontal', 'diagonal', 'radial']
-    };
-  }
-
-  return app.getLetterCollageOptions();
-})();
-`.trim();
-    }
-    // ===========================================================================
-    // CANVAS PRESETS CODE GENERATORS
-    // ===========================================================================
-    /**
-     * Generate code to get canvas presets
-     */
-    generateGetCanvasPresets() {
-        return `
-// Get canvas presets
-(function() {
-  if (app.getCanvasPresets) {
-    return app.getCanvasPresets();
-  }
-
-  // Return static presets if function not available
-  return {
-    success: true,
-    presets: [
-      { key: 'youtube-thumbnail', name: 'YouTube Thumbnail', width: 1280, height: 720, aspectRatio: '16:9', category: 'video' },
-      { key: 'youtube-short', name: 'YouTube Shorts', width: 1080, height: 1920, aspectRatio: '9:16', category: 'video' },
-      { key: 'tiktok', name: 'TikTok', width: 1080, height: 1920, aspectRatio: '9:16', category: 'video' },
-      { key: 'instagram-story', name: 'Instagram Story', width: 1080, height: 1920, aspectRatio: '9:16', category: 'social' },
-      { key: 'instagram-post', name: 'Instagram Post (Square)', width: 1080, height: 1080, aspectRatio: '1:1', category: 'social' },
-      { key: 'instagram-landscape', name: 'Instagram Landscape', width: 1080, height: 566, aspectRatio: '1.91:1', category: 'social' },
-      { key: 'instagram-portrait', name: 'Instagram Portrait', width: 1080, height: 1350, aspectRatio: '4:5', category: 'social' },
-      { key: 'facebook-post', name: 'Facebook Post', width: 1200, height: 630, aspectRatio: '1.91:1', category: 'social' },
-      { key: 'facebook-cover', name: 'Facebook Cover', width: 820, height: 312, aspectRatio: '2.63:1', category: 'social' },
-      { key: 'facebook-story', name: 'Facebook Story', width: 1080, height: 1920, aspectRatio: '9:16', category: 'social' },
-      { key: 'twitter-post', name: 'Twitter/X Post', width: 1200, height: 675, aspectRatio: '16:9', category: 'social' },
-      { key: 'twitter-header', name: 'Twitter/X Header', width: 1500, height: 500, aspectRatio: '3:1', category: 'social' },
-      { key: 'linkedin-post', name: 'LinkedIn Post', width: 1200, height: 627, aspectRatio: '1.91:1', category: 'social' },
-      { key: 'linkedin-banner', name: 'LinkedIn Banner', width: 1584, height: 396, aspectRatio: '4:1', category: 'social' },
-      { key: 'pinterest-pin', name: 'Pinterest Pin', width: 1000, height: 1500, aspectRatio: '2:3', category: 'social' },
-      { key: 'presentation-16x9', name: 'Presentation 16:9', width: 1920, height: 1080, aspectRatio: '16:9', category: 'presentation' },
-      { key: 'presentation-4x3', name: 'Presentation 4:3', width: 1024, height: 768, aspectRatio: '4:3', category: 'presentation' },
-      { key: 'hd-720p', name: 'HD 720p', width: 1280, height: 720, aspectRatio: '16:9', category: 'video' },
-      { key: 'full-hd-1080p', name: 'Full HD 1080p', width: 1920, height: 1080, aspectRatio: '16:9', category: 'video' },
-      { key: 'default', name: 'Default', width: 800, height: 600, aspectRatio: '4:3', category: 'general' }
-    ]
-  };
-})();
 `.trim();
     }
     // ===========================================================================
@@ -3185,54 +3039,246 @@ app.historyManager.saveState();
 })();
 `.trim();
     }
+    // -------------------------------------------------------------------------
+    // Globe + World Tour
+    // -------------------------------------------------------------------------
     /**
-     * Generate code to export the complete scene state
+     * Generate code to enable globe (orthographic) mode
      */
-    generateExportScene() {
+    generateGlobeEnable(input) {
+        const validated = GlobeEnableInputSchema.parse(input);
+        const optionsStr = JSON.stringify(validated);
         return `
-// Export complete scene state
+// Enable globe mode
 (function() {
-  try {
-    const items = [];
-    const relations = [];
-    const decorative = [];
-
-    // Collect items from registry
-    if (app.itemRegistry) {
-      for (const [id, item] of app.itemRegistry.entries()) {
-        const itemData = {
-          id: id,
-          type: item.data?.type || item.className?.toLowerCase() || 'unknown',
-          position: item.position ? { x: item.position.x, y: item.position.y } : null,
-          bounds: item.bounds ? {
-            x: item.bounds.x,
-            y: item.bounds.y,
-            width: item.bounds.width,
-            height: item.bounds.height
-          } : null,
-          properties: {}
-        };
-
-        // Collect common properties
-        if (item.fillColor) itemData.properties.fillColor = item.fillColor.toCSS ? item.fillColor.toCSS() : item.fillColor;
-        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;
-        if (item.data?.content) itemData.properties.content = item.data.content;
+  if (!app.mapSystem) {
+    return { success: false, error: 'Map system not available' };
+  }
+  if (typeof app.mapSystem.enableGlobeMode !== 'function') {
+    return { success: false, error: 'enableGlobeMode unavailable on this build (update the canvas)' };
+  }
 
-        if (item.data?.isDecorative) {
-          decorative.push(itemData);
-        } else {
-          items.push(itemData);
-        }
-      }
+  try {
+    app.mapSystem.enableGlobeMode(${optionsStr});
+    return { success: true };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+})();
+`.trim();
     }
-
-    // Collect relations
-    if (app.getRelations) {
-      const activeRelations = app.getRelations();
-      for (const rel of activeRelations) {
+    /**
+     * Generate code to rotate the globe to a coordinate (versor slerp)
+     */
+    generateGlobeRotateTo(input) {
+        const validated = GlobeRotateToInputSchema.parse(input);
+        const durationArg = validated.duration !== undefined ? `, ${validated.duration}` : '';
+        return `
+// Rotate globe to coordinate
+(function() {
+  if (!app.mapSystem) {
+    return { success: false, error: 'Map system not available' };
+  }
+  if (typeof app.mapSystem.rotateGlobeTo !== 'function') {
+    return { success: false, error: 'rotateGlobeTo unavailable on this build (update the canvas)' };
+  }
+
+  try {
+    app.mapSystem.rotateGlobeTo(${validated.lon}, ${validated.lat}${durationArg});
+    return { success: true, rotateTo: [${validated.lon}, ${validated.lat}] };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+})();
+`.trim();
+    }
+    /**
+     * Generate code to continuously spin the globe
+     */
+    generateGlobeSpin(input) {
+        const validated = GlobeSpinInputSchema.parse(input);
+        const optionsStr = JSON.stringify(validated);
+        return `
+// Spin globe continuously
+(function() {
+  if (!app.mapSystem) {
+    return { success: false, error: 'Map system not available' };
+  }
+  if (typeof app.mapSystem.animateGlobeRotation !== 'function') {
+    return { success: false, error: 'animateGlobeRotation unavailable on this build (update the canvas)' };
+  }
+
+  try {
+    const callbackId = app.mapSystem.animateGlobeRotation(${optionsStr});
+    return { success: true, callbackId: callbackId || null };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+})();
+`.trim();
+    }
+    /**
+     * Generate code to run a world tour across regions or coordinates
+     */
+    generateWorldTour(input) {
+        const validated = WorldTourInputSchema.parse(input);
+        const optionsStr = JSON.stringify(validated);
+        return `
+// World tour across regions / coordinates
+(function() {
+  if (!app.mapSystem) {
+    return { success: false, error: 'Map system not available' };
+  }
+  if (typeof app.mapSystem.worldTour !== 'function') {
+    return { success: false, error: 'worldTour unavailable on this build (update the canvas)' };
+  }
+
+  try {
+    const tourId = app.mapSystem.worldTour(${optionsStr});
+    return { success: true, tourId: tourId || null };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+})();
+`.trim();
+    }
+    /**
+     * Generate code to stop a running world tour
+     */
+    generateStopWorldTour(input) {
+        const validated = StopWorldTourInputSchema.parse(input);
+        const idArg = validated.id !== undefined ? JSON.stringify(validated.id) : '';
+        return `
+// Stop world tour
+(function() {
+  if (!app.mapSystem) {
+    return { success: false, error: 'Map system not available' };
+  }
+  if (typeof app.mapSystem.stopWorldTour !== 'function') {
+    return { success: false, error: 'stopWorldTour unavailable on this build (update the canvas)' };
+  }
+
+  try {
+    app.mapSystem.stopWorldTour(${idArg});
+    return { success: true };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+})();
+`.trim();
+    }
+    /**
+     * Generate code to pin a canvas item to a globe surface coordinate
+     */
+    generatePinToGlobe(input) {
+        const validated = PinToGlobeInputSchema.parse(input);
+        const itemId = validated.itemId;
+        const opts = JSON.stringify({ hideOnFarSide: validated.hideOnFarSide });
+        return `
+// Pin item to globe coordinate
+(function() {
+  if (!app.mapSystem) {
+    return { success: false, error: 'Map system not available' };
+  }
+  if (typeof app.mapSystem.pinItemToGlobe !== 'function') {
+    return { success: false, error: 'pinItemToGlobe unavailable on this build (update the canvas)' };
+  }
+
+  const item = (app.getItemById && app.getItemById(${JSON.stringify(itemId)})) || (app.itemRegistry && app.itemRegistry.get && app.itemRegistry.get(${JSON.stringify(itemId)}) && (app.itemRegistry.get(${JSON.stringify(itemId)}).item || app.itemRegistry.get(${JSON.stringify(itemId)})));
+  if (!item) {
+    return { success: false, error: 'Item ${itemId} not found' };
+  }
+
+  try {
+    const pinned = app.mapSystem.pinItemToGlobe(item, ${validated.lon}, ${validated.lat}, ${opts});
+    return { success: !!pinned, pinned: !!pinned };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+})();
+`.trim();
+    }
+    /**
+     * Generate code to tour a canvas item along regions or coordinates
+     */
+    generateTourItem(input) {
+        const validated = TourItemInputSchema.parse(input);
+        const itemId = validated.itemId;
+        const { itemId: _omit, regions, coords, ...rest } = validated;
+        const optsStr = JSON.stringify(rest);
+        return `
+// Tour item along regions / coordinates
+(function() {
+  if (!app.mapSystem) {
+    return { success: false, error: 'Map system not available' };
+  }
+
+  const item = (app.getItemById && app.getItemById(${JSON.stringify(itemId)})) || (app.itemRegistry && app.itemRegistry.get && app.itemRegistry.get(${JSON.stringify(itemId)}) && (app.itemRegistry.get(${JSON.stringify(itemId)}).item || app.itemRegistry.get(${JSON.stringify(itemId)})));
+  if (!item) {
+    return { success: false, error: 'Item ${itemId} not found' };
+  }
+
+  try {
+    ${regions
+            ? `if (typeof app.mapSystem.tourRegions !== 'function') { return { success: false, error: 'tourRegions unavailable on this build (update the canvas)' }; }
+    const tourId = app.mapSystem.tourRegions(item, ${JSON.stringify(regions)}, ${optsStr});`
+            : `if (typeof app.mapSystem.tourItemAlongCoords !== 'function') { return { success: false, error: 'tourItemAlongCoords unavailable on this build (update the canvas)' }; }
+    const tourId = app.mapSystem.tourItemAlongCoords(item, ${JSON.stringify(coords || [])}, ${optsStr});`}
+    return { success: true, tourId: tourId || null };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+})();
+`.trim();
+    }
+    /**
+     * Generate code to export the complete scene state
+     */
+    generateExportScene() {
+        return `
+// Export complete scene state
+(function() {
+  try {
+    const items = [];
+    const relations = [];
+    const decorative = [];
+
+    // Collect items from registry
+    if (app.itemRegistry) {
+      for (const [id, item] of app.itemRegistry.entries()) {
+        const itemData = {
+          id: id,
+          type: item.data?.type || item.className?.toLowerCase() || 'unknown',
+          position: item.position ? { x: item.position.x, y: item.position.y } : null,
+          bounds: item.bounds ? {
+            x: item.bounds.x,
+            y: item.bounds.y,
+            width: item.bounds.width,
+            height: item.bounds.height
+          } : null,
+          properties: {}
+        };
+
+        // Collect common properties
+        if (item.fillColor) itemData.properties.fillColor = item.fillColor.toCSS ? item.fillColor.toCSS() : item.fillColor;
+        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;
+        if (item.data?.content) itemData.properties.content = item.data.content;
+
+        if (item.data?.isDecorative) {
+          decorative.push(itemData);
+        } else {
+          items.push(itemData);
+        }
+      }
+    }
+
+    // Collect relations
+    if (app.getRelations) {
+      const activeRelations = app.getRelations();
+      for (const rel of activeRelations) {
         relations.push({
           sourceId: rel.sourceId,
           targetId: rel.targetId,
@@ -3446,22 +3492,27 @@ app.historyManager.saveState();
         const optionsStr = validated.options ? JSON.stringify(validated.options) : '{}';
         const keyframesStr = validated.keyframes ? JSON.stringify(validated.keyframes) : 'null';
         const maskOptionsStr = validated.maskOptions ? JSON.stringify(validated.maskOptions) : '{}';
+        const preset = validated.preset || validated.maskType || 'wipeLeft';
+        // Per-preset options. Custom keyframes are an animated-mask extension —
+        // when supplied, fall through to maskingSystem.applyCustomMask instead.
         return `
 // Apply animated mask to ${validated.itemId}
 (function() {
-  if (!app.maskSystem) {
+  if (!app.applyAnimatedMask) {
     return { success: false, error: 'Mask system not available' };
   }
+  const item = app.getItemById('${validated.itemId}');
+  if (!item) return { success: false, error: 'Item not found: ${validated.itemId}' };
 
   try {
-    const result = app.maskSystem.applyAnimatedMask('${validated.itemId}', {
-      preset: ${validated.preset ? `'${validated.preset}'` : 'null'},
-      maskType: ${validated.maskType ? `'${validated.maskType}'` : 'null'},
-      keyframes: ${keyframesStr},
-      options: ${optionsStr},
-      maskOptions: ${maskOptionsStr}
-    });
-    return result;
+    const mergedOpts = Object.assign({}, ${optionsStr}, ${maskOptionsStr});
+    let maskedGroup;
+    if (${keyframesStr} && app.maskingSystem && app.maskingSystem.applyCustomMask) {
+      maskedGroup = app.maskingSystem.applyCustomMask(item, '${preset}', ${keyframesStr}, mergedOpts);
+    } else {
+      maskedGroup = app.applyAnimatedMask(item, '${preset}', mergedOpts);
+    }
+    return { success: !!maskedGroup, itemId: '${validated.itemId}', preset: '${preset}' };
   } catch (error) {
     return { success: false, error: error.message };
   }
@@ -3475,17 +3526,15 @@ app.historyManager.saveState();
         return `
 // Apply custom mask to ${validated.itemId}
 (function() {
-  if (!app.maskSystem) {
+  if (!app.maskingSystem || !app.maskingSystem.applyCustomMask) {
     return { success: false, error: 'Mask system not available' };
   }
+  const item = app.getItemById('${validated.itemId}');
+  if (!item) return { success: false, error: 'Item not found: ${validated.itemId}' };
 
   try {
-    const result = app.maskSystem.applyCustomMask('${validated.itemId}', {
-      maskType: '${validated.maskType}',
-      keyframes: ${keyframesStr},
-      maskOptions: ${maskOptionsStr}
-    });
-    return result;
+    const maskedGroup = app.maskingSystem.applyCustomMask(item, '${validated.maskType}', ${keyframesStr}, ${maskOptionsStr});
+    return { success: !!maskedGroup, itemId: '${validated.itemId}', maskType: '${validated.maskType}' };
   } catch (error) {
     return { success: false, error: error.message };
   }
@@ -3497,12 +3546,17 @@ app.historyManager.saveState();
         return `
 // Remove mask from ${validated.itemId}
 (function() {
-  if (!app.maskSystem) {
+  if (!app.removeMask) {
     return { success: false, error: 'Mask system not available' };
   }
+  // The item id may point at either the masked group OR the original item;
+  // app.removeMask expects the masked group, so resolve and walk up if needed.
+  const item = app.getItemById('${validated.itemId}');
+  if (!item) return { success: false, error: 'Item not found: ${validated.itemId}' };
+  const maskedGroup = (item.data && item.data.isMaskedGroup) ? item : (item.parent && item.parent.data && item.parent.data.isMaskedGroup ? item.parent : item);
 
   try {
-    const result = app.maskSystem.removeMask('${validated.itemId}');
+    app.removeMask(maskedGroup);
     return { success: true, itemId: '${validated.itemId}', message: 'Mask removed' };
   } catch (error) {
     return { success: false, error: error.message };
@@ -3596,10 +3650,12 @@ app.historyManager.saveState();
 })();
 `.trim();
     }
+    // =============================================================================
+    // TEMPLATE
+    // =============================================================================
     generateApplyTemplate(input) {
         const { templateId, category, listOnly } = input;
         if (listOnly || !templateId) {
-            // List mode: return available templates, optionally filtered by category
             const categoryFilter = category ? `'${category}'` : 'null';
             return `
 // List available templates
@@ -3625,7 +3681,6 @@ app.historyManager.saveState();
 })();
 `.trim();
         }
-        // Load mode: apply a specific template
         return `
 // Apply template: ${templateId}
 (async function() {
@@ -3901,7 +3956,7 @@ ${mask ? `    app.imageTools.applyMask(raster, '${mask}');\n` : ''}    const ite
 // Select all items
 (function() {
   app.selectAll();
-  const items = app.getSelection().map(i => i.data?.itemId || i.name || i.id);
+  const items = app.getSelectedItems().map(i => i.data?.itemId || i.name || i.id);
   return { success: true, action: 'select_all', count: items.length, items };
 })();`.trim();
             case 'deselect_all':
@@ -3915,7 +3970,7 @@ ${mask ? `    app.imageTools.applyMask(raster, '${mask}');\n` : ''}    const ite
                 return `
 // Get current selection
 (function() {
-  const items = app.getSelection().map(i => ({
+  const items = app.getSelectedItems().map(i => ({
     itemId: i.data?.itemId || i.name || i.id,
     type: i.data?.itemType || i.className,
     bounds: i.bounds ? { x: i.bounds.x, y: i.bounds.y, width: i.bounds.width, height: i.bounds.height } : null
@@ -3926,7 +3981,7 @@ ${mask ? `    app.imageTools.applyMask(raster, '${mask}');\n` : ''}    const ite
                 return `
 // Delete selected items
 (function() {
-  const selection = app.getSelection();
+  const selection = app.getSelectedItems();
   const deleted = selection.map(i => i.data?.itemId || i.name || i.id);
   app.deleteSelected();
   return { success: true, action: 'delete_selected', deleted, count: deleted.length };
@@ -4031,15 +4086,23 @@ ${mask ? `    app.imageTools.applyMask(raster, '${mask}');\n` : ''}    const ite
     // IMAGE PROCESSING
     // ===========================================================================
     generateImageFilter(input) {
-        const guard = `if (!app.imageTools) return { error: 'ImageTools not available' };`;
+        // Resolve the raster from the registry id (unwrapping groups when the
+        // build has the _resolveRaster helper), then use the real GPU-filter
+        // facades. The previous emitter called app.imageTools.applyFilter, a
+        // method that never existed — the tool errored on every use.
+        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' };`;
         switch (input.action) {
             case 'apply':
                 return `
 // Apply image filter
 (async function() {
-  ${guard}
+${resolve}
   try {
-    const result = await app.imageTools.applyFilter(${JSON.stringify(input.itemId)}, ${JSON.stringify(input.filterName || '')}, ${JSON.stringify(input.params || {})});
+    await app.applyImageFilter(item, ${JSON.stringify(input.filterName || '')}, ${JSON.stringify(input.params || {})});
     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 };
@@ -4049,10 +4112,10 @@ ${mask ? `    app.imageTools.applyMask(raster, '${mask}');\n` : ''}    const ite
                 return `
 // Apply filter chain
 (async function() {
-  ${guard}
+${resolve}
   try {
     const filters = ${JSON.stringify(input.filters || [])};
-    const result = await app.imageTools.applyFilterChain(${JSON.stringify(input.itemId)}, filters);
+    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 };
@@ -4160,29 +4223,6 @@ ${mask ? `    app.imageTools.applyMask(raster, '${mask}');\n` : ''}    const ite
                 return `(function() { return { error: 'Unknown precomp action: ${input.action}' }; })();`;
         }
     }
-    generateView(input) {
-        switch (input.action) {
-            case 'fit': {
-                const mode = input.mode || 'content';
-                const padding = input.padding ?? 20;
-                return `
-// Fit view to ${mode}
-(function() {
-  app.fitView('${mode}', ${padding});
-  return { success: true, action: 'fit', mode: '${mode}', padding: ${padding} };
-})();`.trim();
-            }
-            case 'get_state':
-                return `
-// Get current view state
-(function() {
-  const state = app.getViewState();
-  return { success: true, action: 'get_state', ...state };
-})();`.trim();
-            default:
-                return `(function() { return { error: 'Unknown view action: ${input.action}' }; })();`;
-        }
-    }
     generateBackground(input) {
         switch (input.action) {
             case 'set': {
@@ -4226,8 +4266,9 @@ ${mask ? `    app.imageTools.applyMask(raster, '${mask}');\n` : ''}    const ite
                 return `
 // Get background info
 (function() {
-  const bg = app.getBackground();
-  return { success: true, action: 'get', ...bg };
+  // FxTool exposes getBackgroundMode() returning the mode string only.
+  const mode = app.getBackgroundMode ? app.getBackgroundMode() : null;
+  return { success: true, action: 'get', mode };
 })();`.trim();
             default:
                 return `(function() { return { error: 'Unknown background action: ${input.action}' }; })();`;
@@ -4435,61 +4476,6 @@ ${mask ? `    app.imageTools.applyMask(raster, '${mask}');\n` : ''}    const ite
         }
     }
     // ===========================================================================
-    // STORAGE
-    // ===========================================================================
-    generateStorage(input) {
-        const guard = `if (!app.storageManager) return { error: 'StorageManager not available' };`;
-        switch (input.action) {
-            case 'save': {
-                const name = input.name ? JSON.stringify(input.name) : "'Untitled Project'";
-                const thumbnailCode = input.thumbnail
-                    ? `const thumbnail = app.exportThumbnail ? app.exportThumbnail() : null;\n  if (thumbnail) project.thumbnail = thumbnail;`
-                    : '';
-                return `
-// Save project
-(async function() {
-  ${guard}
-  const project = { name: ${name}, data: app.serialize() };
-  ${thumbnailCode}
-  const projectId = await app.storageManager.saveProject(project);
-  return { success: true, action: 'save', projectId, name: ${name} };
-})();`.trim();
-            }
-            case 'load': {
-                const projId = JSON.stringify(input.projectId || '');
-                return `
-// Load project
-(async function() {
-  ${guard}
-  const project = await app.storageManager.loadProject(${projId});
-  if (!project) return { error: 'Project not found: ' + ${projId} };
-  app.deserialize(project.data);
-  return { success: true, action: 'load', projectId: ${projId}, name: project.name };
-})();`.trim();
-            }
-            case 'list':
-                return `
-// List saved projects
-(async function() {
-  ${guard}
-  const projects = await app.storageManager.listProjects();
-  return { success: true, action: 'list', projects: projects.map(p => ({ id: p.id, name: p.name, updatedAt: p.updatedAt })), count: projects.length };
-})();`.trim();
-            case 'delete': {
-                const projId = JSON.stringify(input.projectId || '');
-                return `
-// Delete project
-(async function() {
-  ${guard}
-  await app.storageManager.deleteProject(${projId});
-  return { success: true, action: 'delete', projectId: ${projId} };
-})();`.trim();
-            }
-            default:
-                return `(function() { return { error: 'Unknown storage action: ${input.action}' }; })();`;
-        }
-    }
-    // ===========================================================================
     // INTERACTION
     // ===========================================================================
     generateInteraction(input) {
@@ -4559,8 +4545,8 @@ ${mask ? `    app.imageTools.applyMask(raster, '${mask}');\n` : ''}    const ite
         return `
 // Export widget (pp:PinePaper ontology JSON)
 (async function() {
-  if (!app.exportWidget) return { error: 'Widget export not available' };
-  const result = await app.exportWidget(${JSON.stringify(opts)});
+  if (!app.exportEngine || !app.exportEngine.exportWidget) return { error: 'Widget export not available' };
+  const result = await app.exportEngine.exportWidget(${JSON.stringify(opts)});
   return { success: true, json: result.json, filename: result.filename, embedCode: result.embedCode, metadata: result.data?.metadata };
 })();`.trim();
     }
@@ -4573,8 +4559,8 @@ ${mask ? `    app.imageTools.applyMask(raster, '${mask}');\n` : ''}    const ite
         return `
 // Export widget as self-contained HTML
 (async function() {
-  if (!app.exportWidgetHTML) return { error: 'Widget HTML export not available' };
-  const result = await app.exportWidgetHTML(${JSON.stringify(opts)});
+  if (!app.exportEngine || !app.exportEngine.exportWidgetHTML) return { error: 'Widget HTML export not available' };
+  const result = await app.exportEngine.exportWidgetHTML(${JSON.stringify(opts)});
   return { success: true, html: result.html, estimatedSize: result.estimatedSize, analysis: { itemTypes: [...result.analysis.itemTypes], relationTypes: [...result.analysis.relationTypes], hasSimpleAnimations: result.analysis.hasSimpleAnimations, hasKeyframeAnimations: result.analysis.hasKeyframeAnimations, hasMasks: result.analysis.hasMasks } };
 })();`.trim();
     }
@@ -4882,6 +4868,665 @@ ${mask ? `    app.imageTools.applyMask(raster, '${mask}');\n` : ''}    const ite
                 return `(function() { return { error: 'Unknown measurement action: ${input.action}' }; })();`;
         }
     }
+    /**
+     * Z-order: select the item, then call the matching app stacking method
+     * (bringToFront / sendToBack / bringForward / sendBackward).
+     */
+    generateArrange(input) {
+        const method = {
+            front: 'bringToFront',
+            back: 'sendToBack',
+            forward: 'bringForward',
+            backward: 'sendBackward',
+        }[input.action];
+        const id = JSON.stringify(input.itemId);
+        return `
+// Arrange ${input.itemId} → ${input.action}
+(function() {
+  const item = app.getItemById(${id});
+  if (!item) return { success: false, error: 'Item not found: ' + ${id} };
+  if (typeof app.${method} !== 'function') return { success: false, error: 'app.${method} unavailable — update FxTool' };
+  app.select(${id});
+  app.${method}();
+  return { success: true, itemId: ${id}, action: '${input.action}' };
+})();`.trim();
+    }
+    /**
+     * On-device object detection (FxTool ImageWorkflow). Finds objects in an image;
+     * with asNodes promotes each detection to a typed, image-anchored design node
+     * (pp:Detected*) instead of a labeled box. Async (runs an on-device ML model).
+     */
+    generateDetectObjects(input) {
+        const args = JSON.stringify({
+            ...(input.itemId !== undefined ? { itemId: input.itemId } : {}),
+            ...(input.threshold !== undefined ? { threshold: input.threshold } : {}),
+            ...(input.asNodes !== undefined ? { asNodes: input.asNodes } : {}),
+            ...(input.queries !== undefined ? { queries: input.queries } : {}),
+        });
+        return `
+// Detect objects${input.queries !== undefined ? ' (open-vocabulary / OWL-ViT)' : ''}${input.asNodes ? ' (asNodes — relational compositing)' : ''}
+(async function() {
+  if (typeof app.detectObjects !== 'function') {
+    return { success: false, error: 'app.detectObjects unavailable — update FxTool to a build that exposes on-device object detection on app' };
+  }
+  try {
+    const res = await app.detectObjects(${args});
+    return Object.assign({ success: !!(res && res.ok) }, res || {});
+  } catch (e) { return { success: false, error: String((e && e.message) || e) }; }
+})();`.trim();
+    }
+    /**
+     * Extract the best-matching detected region from an image as a NEW item (FxTool
+     * ImageWorkflow.extractObject). Async (runs detection first).
+     */
+    generateExtractObject(input) {
+        const args = JSON.stringify({
+            ...(input.label !== undefined ? { label: input.label } : {}),
+            ...(input.itemId !== undefined ? { itemId: input.itemId } : {}),
+            ...(input.x !== undefined ? { x: input.x } : {}),
+            ...(input.y !== undefined ? { y: input.y } : {}),
+            ...(input.threshold !== undefined ? { threshold: input.threshold } : {}),
+        });
+        return `
+// Extract object${input.label ? ` "${input.label}"` : ''} from the image
+(async function() {
+  if (typeof app.extractObject !== 'function') {
+    return { success: false, error: 'app.extractObject unavailable — update FxTool to a build that exposes on-device object detection on app' };
+  }
+  try {
+    const res = await app.extractObject(${args});
+    return Object.assign({ success: !!(res && res.ok) }, res || {});
+  } catch (e) { return { success: false, error: String((e && e.message) || e) }; }
+})();`.trim();
+    }
+    /**
+     * Camera director (FxTool DirectorCompiler): compile a shot list into ONE
+     * camera_animates walkthrough. 'auto' derives a shot per item; 'shots' applies
+     * an explicit list. WYSIWYG between editor and any export size (one camera).
+     */
+    generateCameraDirector(input) {
+        if (input.action === 'shots') {
+            const shotsJson = JSON.stringify(input.shots ?? []);
+            const opts = JSON.stringify({ loop: !!input.loop });
+            return `
+// Camera director — apply explicit shot list
+(function() {
+  if (typeof app.applyDirectorShots !== 'function') {
+    return { success: false, error: 'app.applyDirectorShots unavailable — update FxTool to a build with the camera director' };
+  }
+  const shots = ${shotsJson};
+  const ok = app.applyDirectorShots(shots, ${opts});
+  return { success: !!ok, mode: 'shots', shotCount: shots.length, loop: ${!!input.loop} };
+})();`.trim();
+        }
+        const opts = JSON.stringify({
+            ...(input.order !== undefined ? { order: input.order } : {}),
+            ...(input.hold !== undefined ? { hold: input.hold } : {}),
+            ...(input.establishing !== undefined ? { establishing: input.establishing } : {}),
+            loop: !!input.loop,
+        });
+        return `
+// Camera director — auto-direct a walkthrough of the scene
+(function() {
+  if (typeof app.autoDirectStory !== 'function') {
+    return { success: false, error: 'app.autoDirectStory unavailable — update FxTool to a build with the camera director' };
+  }
+  const shots = app.autoDirectStory(${opts});
+  if (!shots) return { success: false, mode: 'auto', error: 'No items to direct — add content first' };
+  return { success: true, mode: 'auto', shotCount: shots.length, shots: shots };
+})();`.trim();
+    }
+    /**
+     * Inner JS that groups resolved item ids into ONE draggable entity via the
+     * GroupManager (createGroup → addItemsToGroup). idsArrayExpr is a JS expression
+     * evaluating to an array of id strings; nameExpr is a JS string expression or 'undefined'.
+     * Shared by the standalone pinepaper_group tool and the batch "group" operation.
+     */
+    groupCodeBody(idsArrayExpr, nameExpr) {
+        return `
+  if (!app.groupManager) return { success: false, error: 'GroupManager not available — update FxTool' };
+  const ids = (${idsArrayExpr}).filter(function(x) { return x != null; });
+  const items = ids.map(function(id) { return app.getItemById(id); }).filter(Boolean);
+  if (!items.length) return { success: false, error: 'No valid items to group (check the ids / $N refs)' };
+  const group = app.groupManager.createGroup(${nameExpr});
+  if (!group) return { success: false, error: 'Failed to create group' };
+  app.groupManager.addItemsToGroup(items, group);
+  if (app.historyManager) app.historyManager.saveState();
+  const groupId = (group.data && (group.data.registryId || group.data.groupId)) || null;
+  return { success: true, groupId: groupId, groupName: group.data && group.data.groupName, itemCount: items.length };`;
+    }
+    /**
+     * Group a set of items into one draggable entity, or ungroup one back into loose
+     * items. Grouping is non-destructive — ungroup restores the individual items.
+     */
+    generateGroup(input) {
+        if (input.action === 'break_apart') {
+            const idExpr = JSON.stringify(input.itemId || '');
+            return `
+// Break apart ${input.itemId || ''} into movable parts
+(function() {
+  if (typeof app.breakApart !== 'function') return { success: false, error: 'app.breakApart unavailable — update FxTool to a build with SVG/group segmentation' };
+  const target = app.getItemById(${idExpr});
+  if (!target) return { success: false, error: 'Item not found: ' + ${idExpr} };
+  const result = app.breakApart(target);
+  if (!result || !result.parts || !result.parts.length) return { success: false, error: 'Nothing to break apart (no sub-parts found)' };
+  const partIds = result.parts.map(function(p) { return p && p.data && (p.data.registryId || p.data.id); }).filter(Boolean);
+  const groupId = (result.group && result.group.data && (result.group.data.registryId || result.group.data.groupId)) || null;
+  return { success: true, action: 'break_apart', groupId: groupId, partIds: partIds, partCount: partIds.length };
+})();`.trim();
+        }
+        if (input.action === 'ungroup') {
+            const idExpr = JSON.stringify(input.groupId || '');
+            return `
+// Ungroup ${input.groupId || ''}
+(function() {
+  if (!app.groupManager) return { success: false, error: 'GroupManager not available — update FxTool' };
+  const gid = ${idExpr};
+  const group = app.getItemById(gid) || (app.groupManager.getGroupById ? app.groupManager.getGroupById(gid) : null);
+  if (!group) return { success: false, error: 'Group not found: ' + gid };
+  app.groupManager.ungroupAll(group);
+  if (app.historyManager) app.historyManager.saveState();
+  return { success: true, ungrouped: true, groupId: gid };
+})();`.trim();
+        }
+        const idsArrayExpr = JSON.stringify(input.itemIds ?? []);
+        const nameExpr = input.groupName !== undefined ? JSON.stringify(input.groupName) : 'undefined';
+        return `
+// Group ${(input.itemIds || []).length} items${input.groupName ? ` as "${input.groupName}"` : ''}
+(function() {${this.groupCodeBody(idsArrayExpr, nameExpr)}
+})();`.trim();
+    }
+    /**
+     * Audit the live scene (or pre-validate a batch of proposed ops) with FxTool's
+     * OntologyValidator — structured { ok, diagnostics } feedback instead of console warnings.
+     */
+    generateValidateScene(input) {
+        const guard = `const v = app.sceneValidator;
+  if (!v) return { success: false, error: 'app.sceneValidator unavailable — update FxTool to a build with the OntologyValidator' };`;
+        if (input.ops) {
+            const opsJson = JSON.stringify(input.ops);
+            return `
+// Pre-validate proposed ops against the live scene
+(function() {
+  ${guard}
+  if (typeof v.validateOps !== 'function') return { success: false, error: 'validateOps unavailable in this FxTool build' };
+  const r = v.validateOps(${opsJson});
+  return { success: true, mode: 'ops', ok: r.ok, diagnosticCount: r.diagnostics.length, diagnostics: r.diagnostics };
+})();`.trim();
+        }
+        return `
+// Audit the current scene
+(function() {
+  ${guard}
+  const r = v.validateScene();
+  return { success: true, mode: 'scene', ok: r.ok, diagnosticCount: r.diagnostics.length, diagnostics: r.diagnostics };
+})();`.trim();
+    }
+    /**
+     * Deterministic headless frame capture (S3): app.captureFramesAt(times, { seed })
+     * seeds Math.random once around the sequence and evaluates the scene at each time via
+     * sceneAt(t). Returns a cheap per-frame hash by default (token-light) so an agent can
+     * verify determinism (re-run → identical hashes) and whether frames actually change.
+     */
+    generateCaptureFrames(input) {
+        const timesJson = JSON.stringify(input.times);
+        const seed = input.seed !== undefined ? input.seed : 0;
+        const includeDataUrls = !!input.includeDataUrls;
+        return `
+// Deterministic frame capture
+(function() {
+  if (typeof app.captureFramesAt !== 'function') {
+    return { success: false, error: 'app.captureFramesAt unavailable — update FxTool to a build with the deterministic capture entrypoint' };
+  }
+  const includeDataUrls = ${includeDataUrls};
+  const hashStr = function(s) { let h = 5381; for (let i = 0; i < s.length; i++) { h = (((h << 5) + h) ^ s.charCodeAt(i)) >>> 0; } return h.toString(16); };
+  const frames = app.captureFramesAt(${timesJson}, {
+    seed: ${seed},
+    capture: function(c, t, i) {
+      // Prefer app.captureFrameDataURL(): it renders only the used region, so an
+      // unbounded canvas's fill-workspace margin is never baked into the frame.
+      // Fall back to the raw canvas toDataURL on pre-capture-region FxTool builds.
+      const url = (typeof app.captureFrameDataURL === 'function')
+        ? app.captureFrameDataURL()
+        : ((c && c.toDataURL) ? c.toDataURL() : '');
+      const f = { index: i, time: t, hash: hashStr(url), bytes: url.length };
+      if (includeDataUrls) f.dataUrl = url;
+      return f;
+    }
+  });
+  const uniqueHashes = new Set(frames.map(function(f) { return f.hash; })).size;
+  return { success: true, seed: ${seed}, frameCount: frames.length, uniqueHashes: uniqueHashes, allIdentical: uniqueHashes <= 1, frames: frames };
+})();`.trim();
+    }
+    /**
+     * Ontology→scene compiler (S12-E3). Compiles the JSON-LD design graph SERVER-SIDE
+     * (deterministic, unit-tested) into create/addRelation ops, then emits code that
+     * applies them. Only root nodes carry coordinates; structural relations place the
+     * rest at runtime. Compile diagnostics are baked into the emitted result.
+     */
+    generateInstantiateOntology(input) {
+        const { ops, diagnostics } = new OntologyCompiler({
+            canvas: input.canvas,
+            defaultGeometry: input.defaultGeometry,
+        }).compile(input.doc);
+        const opsJson = JSON.stringify(ops, null, 2);
+        const diagJson = JSON.stringify(diagnostics);
+        return `
+// Instantiate ontology → scene (${ops.filter((o) => o.op === 'create').length} items, ${ops.filter((o) => o.op === 'addRelation').length} relations)
+(function() {
+  if (typeof app.create !== 'function' || typeof app.addRelation !== 'function') {
+    return { success: false, error: 'app.create / app.addRelation unavailable' };
+  }
+  const ops = ${opsJson};
+  const diagnostics = ${diagJson};
+  const itemIds = [];
+  const errors = [];
+  for (const op of ops) {
+    try {
+      if (op.op === 'create') {
+        app.create(op.type, { id: op.id, x: op.x, y: op.y, width: op.width, height: op.height });
+        itemIds.push(op.id);
+      } else if (op.op === 'addRelation') {
+        app.addRelation(op.from, op.to, op.relation, op.params || {});
+      }
+    } catch (e) {
+      errors.push({ op: op.op, id: op.id || (op.from + '->' + op.to), error: e && e.message });
+    }
+  }
+  if (app.historyManager) app.historyManager.saveState();
+  return { success: errors.length === 0, itemIds: itemIds, itemCount: itemIds.length, diagnostics: diagnostics, errors: errors };
+})();`.trim();
+    }
+    /**
+     * Relational-density lint of the live scene (S12-E2) via app.lintScene(). Reports
+     * relationalDensity + edge/component counts and suggests structural relations for
+     * unrelated item pairs already in a structural configuration. Read-only/advisory.
+     */
+    generateLintScene(input) {
+        const optsJson = JSON.stringify({
+            ...(input.eps !== undefined ? { eps: input.eps } : {}),
+            ...(input.cap !== undefined ? { cap: input.cap } : {}),
+        });
+        return `
+// Relational-density lint (advisory)
+(function() {
+  if (typeof app.lintScene !== 'function') {
+    return { success: false, error: 'app.lintScene unavailable — update FxTool to a build with the relational linter (S12-E2)' };
+  }
+  const result = app.lintScene(${optsJson});
+  return { success: true, density: result.density, suggestions: result.suggestions };
+})();`.trim();
+    }
+    /**
+     * Media (video/audio) via window.PinePaperAgent. Upload is URL-based (the agent
+     * hands a URL, FxTool fetches → File). Async IIFE so uploads resolve before the
+     * value is returned (the governor awaits it).
+     */
+    generateMedia(input) {
+        const guard = `  const A = (typeof window !== 'undefined') && window.PinePaperAgent;
+  if (!A || typeof A.uploadVideo !== 'function') { return { success: false, error: 'window.PinePaperAgent media API unavailable — update FxTool to a media-capable build' }; }`;
+        switch (input.action) {
+            case 'upload_video': {
+                const opts = JSON.stringify({
+                    ...(input.position ? { position: input.position } : {}),
+                    ...(input.scale !== undefined ? { scale: input.scale } : {}),
+                    ...(input.timeOffset !== undefined ? { timeOffset: input.timeOffset } : {}),
+                    ...(input.clipInPoint !== undefined ? { clipInPoint: input.clipInPoint } : {}),
+                    ...(input.clipOutPoint !== undefined ? { clipOutPoint: input.clipOutPoint } : {}),
+                });
+                return `
+// Upload video from URL
+(async function() {
+${guard}
+  const info = await A.uploadVideo(${JSON.stringify(input.url)}, ${opts});
+  return { success: true, action: 'upload_video', media: info };
+})();`.trim();
+            }
+            case 'upload_audio': {
+                const opts = JSON.stringify({
+                    ...(input.volume !== undefined ? { volume: input.volume } : {}),
+                    ...(input.loop !== undefined ? { loop: input.loop } : {}),
+                    ...(input.muted !== undefined ? { muted: input.muted } : {}),
+                    ...(input.timeOffset !== undefined ? { timeOffset: input.timeOffset } : {}),
+                });
+                return `
+// Upload audio from URL
+(async function() {
+${guard}
+  const info = await A.uploadAudio(${JSON.stringify(input.url)}, ${opts});
+  return { success: true, action: 'upload_audio', media: info };
+})();`.trim();
+            }
+            case 'list':
+                return `
+// List media
+(function() {
+${guard}
+  return { success: true, action: 'list', media: A.listMedia() };
+})();`.trim();
+            case 'remove':
+                return `
+// Remove media
+(function() {
+${guard}
+  const removed = A.removeMedia(${JSON.stringify(input.id)});
+  return { success: removed, action: 'remove', id: ${JSON.stringify(input.id)}, removed: removed };
+})();`.trim();
+            case 'set_playback_rate':
+                return `
+// Set media playback rate
+(function() {
+${guard}
+  const ok = A.setMediaPlaybackRate(${JSON.stringify(input.id)}, ${input.rate});
+  return { success: ok, action: 'set_playback_rate', id: ${JSON.stringify(input.id)}, rate: ${input.rate} };
+})();`.trim();
+            case 'set_clip':
+                return `
+// Re-trim an existing media clip (media-time seconds)
+(function() {
+${guard}
+  if (typeof A.setMediaClip !== 'function') { return { success: false, error: 'setMediaClip unavailable — update FxTool' }; }
+  const ok = A.setMediaClip(${JSON.stringify(input.id)}, ${input.inPoint}, ${input.outPoint});
+  return { success: ok, action: 'set_clip', id: ${JSON.stringify(input.id)}, inPoint: ${input.inPoint}, outPoint: ${input.outPoint} };
+})();`.trim();
+        }
+    }
+    /**
+     * One-shot image crop via the PinePaper.cropImage facade (Track A parity).
+     * The replacement raster keeps the item's registry id.
+     */
+    generateCropImage(input) {
+        const opts = input.aspectRatio ? JSON.stringify({ aspectRatio: input.aspectRatio }) : '{}';
+        return `
+// Crop image ${input.itemId}
+(async function() {
+  if (typeof app.cropImage !== 'function') { return { success: false, error: 'app.cropImage unavailable — update FxTool to a build with one-shot image ops' }; }
+  const result = await app.cropImage(${JSON.stringify(input.itemId)}, ${JSON.stringify(input.rect)}, ${opts});
+  if (!result) { return { success: false, error: 'crop failed — item is not a raster or rect does not intersect it' }; }
+  return { success: true, itemId: result.data.id, width: Math.round(result.width), height: Math.round(result.height) };
+})();`.trim();
+    }
+    /**
+     * One-shot chroma key (background removal) via PinePaper.applyChromaKey.
+     * Threshold/smoothing auto-estimate when omitted.
+     */
+    generateChromaKey(input) {
+        const opts = JSON.stringify({
+            ...(input.color !== undefined ? { color: input.color } : {}),
+            ...(input.threshold !== undefined ? { threshold: input.threshold } : {}),
+            ...(input.smoothing !== undefined ? { smoothing: input.smoothing } : {}),
+        });
+        return `
+// Chroma-key image ${input.itemId}
+(async function() {
+  if (typeof app.applyChromaKey !== 'function') { return { success: false, error: 'app.applyChromaKey unavailable — update FxTool to a build with one-shot image ops' }; }
+  const result = await app.applyChromaKey(${JSON.stringify(input.itemId)}, ${opts});
+  if (!result) { return { success: false, error: 'chroma key failed — item is not a raster or the color is invalid' }; }
+  return { success: true, itemId: result.data.id, params: result.data.chromaKeyParams };
+})();`.trim();
+    }
+    /**
+     * Rigging (skeletons/bones/IK/breakdown-pose keyframes) via app.riggingSystem.
+     * One consolidated emitter; each action maps 1:1 to a riggingSystem method with
+     * FxTool's exact param contract. Guarded on app.riggingSystem.
+     */
+    generateRigging(input) {
+        const g = `  const R = app.riggingSystem;
+  if (!R) { return { success: false, error: 'app.riggingSystem unavailable — update FxTool to a rigging-capable build' }; }`;
+        const wrap = (comment, body) => `\n// ${comment}\n(function() {\n${g}\n${body}\n})();`.trim();
+        const S = (v) => JSON.stringify(v);
+        switch (input.action) {
+            case 'create_skeleton': {
+                const root = input.rootPosition ? S(input.rootPosition) : S({ x: 400, y: 300 });
+                return wrap('Rigging: create skeleton', `  const skeletonId = R.createSkeleton(${S(input.name ?? null)}, ${root});
+  if (app.historyManager) app.historyManager.saveState();
+  return { success: !!skeletonId, action: 'create_skeleton', skeletonId: skeletonId };`);
+            }
+            case 'add_bone': {
+                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.flexibility !== undefined ? { flexibility: input.flexibility } : {}),
+                    ...(input.segments !== undefined ? { segments: input.segments } : {}),
+                });
+                return wrap('Rigging: add bone', `  const boneId = R.addBone(${S(input.skeletonId)}, ${config});
+  if (app.historyManager) app.historyManager.saveState();
+  return { success: !!boneId, action: 'add_bone', boneId: boneId };`);
+            }
+            case 'attach_item': {
+                const opts = S(input.attachPoint !== undefined ? { attachPoint: input.attachPoint } : {});
+                return wrap('Rigging: attach item to bone', `  const ok = R.attachItem(${S(input.skeletonId)}, ${S(input.boneId)}, ${S(input.itemId)}, ${opts});
+  if (app.historyManager) app.historyManager.saveState();
+  return { success: !!ok, action: 'attach_item', itemId: ${S(input.itemId)}, boneId: ${S(input.boneId)} };`);
+            }
+            case 'create_ik_chain': {
+                const config = S({
+                    boneIds: input.boneIds,
+                    ...(input.name !== undefined ? { name: input.name } : {}),
+                    ...(input.solverType !== undefined ? { solverType: input.solverType } : {}),
+                    ...(input.iterations !== undefined ? { iterations: input.iterations } : {}),
+                    ...(input.tolerance !== undefined ? { tolerance: input.tolerance } : {}),
+                    ...(input.strength !== undefined ? { strength: input.strength } : {}),
+                    ...(input.poleVector !== undefined ? { poleVector: input.poleVector } : {}),
+                });
+                return wrap('Rigging: create IK chain', `  const chainId = R.createIKChain(${S(input.skeletonId)}, ${config});
+  if (app.historyManager) app.historyManager.saveState();
+  return { success: !!chainId, action: 'create_ik_chain', chainId: chainId };`);
+            }
+            case 'add_pose_keyframe': {
+                const opts = S({
+                    ...(input.favor !== undefined ? { favor: input.favor } : {}),
+                    ...(input.breakdown !== undefined ? { breakdown: input.breakdown } : {}),
+                    ...(input.curve !== undefined ? { curve: input.curve } : {}),
+                    ...(input.boneOffsets !== undefined ? { boneOffsets: input.boneOffsets } : {}),
+                    ...(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});
+  if (app.historyManager) app.historyManager.saveState();
+  return { success: !!ok, action: 'add_pose_keyframe', time: ${input.time} };`);
+            }
+            case 'set_target_path': {
+                const opts = S({
+                    ...(input.duration !== undefined ? { duration: input.duration } : {}),
+                    ...(input.loop !== undefined ? { loop: input.loop } : {}),
+                });
+                return wrap('Rigging: set IK target path', `  const ok = R.setTargetPath(${S(input.skeletonId)}, ${S(input.chainId)}, ${S(input.waypoints)}, ${opts});
+  if (app.historyManager) app.historyManager.saveState();
+  return { success: !!ok, action: 'set_target_path', chainId: ${S(input.chainId)} };`);
+            }
+            case 'save_pose':
+                return wrap('Rigging: save pose', `  const poseId = R.savePose(${S(input.skeletonId)}, ${S(input.name ?? null)});
+  if (app.historyManager) app.historyManager.saveState();
+  return { success: !!poseId, action: 'save_pose', poseId: poseId };`);
+            case 'save_shape_key':
+                return wrap('Rigging: save shape key', `  const shapeKeyId = R.saveShapeKey(${S(input.skeletonId)}, ${S(input.name ?? null)});
+  if (app.historyManager) app.historyManager.saveState();
+  return { success: !!shapeKeyId, action: 'save_shape_key', shapeKeyId: shapeKeyId };`);
+        }
+    }
+    /**
+     * Drive app.constructionSequence (Layer 3): build a step-by-step reveal of a
+     * figure, play it on the timeline, clear it, or list sequences. Item refs are
+     * registryId strings — build resolves them via app.getItemById.
+     */
+    generateConstructionSequence(input) {
+        const guard = `const cs = app.constructionSequence;
+  if (!cs) return { success: false, error: 'app.constructionSequence unavailable — update FxTool to a build with the construction-sequence library' };`;
+        switch (input.action) {
+            case 'build': {
+                const stepsJson = JSON.stringify(input.steps ?? []);
+                const opts = JSON.stringify({
+                    ...(input.stepDuration !== undefined ? { stepDuration: input.stepDuration } : {}),
+                    ...(input.fadeIn !== undefined ? { fadeIn: input.fadeIn } : {}),
+                });
+                return `
+// Build construction sequence
+(function() {
+  ${guard}
+  const rec = cs.build(${stepsJson}, ${opts});
+  return {
+    success: true,
+    action: 'build',
+    sequenceId: rec.id,
+    stepCount: rec.steps.length,
+    stepDuration: rec.stepDuration,
+    fadeIn: rec.fadeIn,
+    totalDuration: rec.totalDuration,
+  };
+})();`.trim();
+            }
+            case 'play': {
+                const seqArg = input.sequenceId ? JSON.stringify(input.sequenceId) : 'null';
+                const opts = JSON.stringify({
+                    loop: !!input.loop,
+                    ...(input.duration !== undefined ? { duration: input.duration } : {}),
+                });
+                return `
+// Play construction sequence
+(function() {
+  ${guard}
+  let seqId = ${seqArg};
+  if (!seqId) { const all = cs.list(); seqId = all.length ? all[all.length - 1].id : null; }
+  if (!seqId) return { success: false, error: 'No sequence to play — build one first' };
+  const duration = cs.play(seqId, ${opts});
+  return { success: true, action: 'play', sequenceId: seqId, duration: duration, loop: ${!!input.loop} };
+})();`.trim();
+            }
+            case 'clear': {
+                const seqArg = input.sequenceId ? JSON.stringify(input.sequenceId) : 'null';
+                return `
+// Clear construction sequence
+(function() {
+  ${guard}
+  let seqId = ${seqArg};
+  if (!seqId) { const all = cs.list(); seqId = all.length ? all[all.length - 1].id : null; }
+  if (!seqId) return { success: false, error: 'No sequence to clear' };
+  const ok = cs.clear(seqId);
+  return { success: ok, action: 'clear', sequenceId: seqId };
+})();`.trim();
+            }
+            case 'list':
+            default:
+                return `
+// List construction sequences
+(function() {
+  ${guard}
+  const sequences = cs.list().map(function(r) {
+    return { id: r.id, stepCount: r.steps.length, stepDuration: r.stepDuration, totalDuration: r.totalDuration };
+  });
+  return { success: true, action: 'list', sequences: sequences };
+})();`.trim();
+        }
+    }
+    /**
+     * Run an app.geometry.* construction helper (Layer 1) and, when createAs is
+     * given, build a canvas item from the result. The op name is whitelisted by the
+     * Zod enum, so it is safe to index app.geometry[op] directly. Mirrors FxTool's
+     * documented composition: app.create('polygon', { points: app.geometry.regularPolygon(...) }).
+     */
+    generateGeometry(input) {
+        const op = JSON.stringify(input.operation);
+        const argsJson = JSON.stringify(input.args ?? []);
+        const createAsJson = input.createAs ? JSON.stringify(input.createAs) : 'null';
+        return `
+// Geometry construction: ${input.operation}
+(function() {
+  const g = app.geometry;
+  if (!g || typeof g[${op}] !== 'function') {
+    return { success: false, error: 'app.geometry.' + ${op} + ' unavailable — update FxTool to a build with the geometry construction library' };
+  }
+  const result = g[${op}](...${argsJson});
+  if (result == null) {
+    return { success: false, operation: ${op}, result: null, error: 'Degenerate construction (parallel lines, collinear points, or a point inside the circle) — returned null' };
+  }
+
+  let itemId = null;
+  const createAs = ${createAsJson};
+  if (createAs) {
+    const { itemType, radius, ...style } = createAs;
+    let item = null;
+    if (Array.isArray(result)) {
+      // Vertex list (regularPolygon / star / polygonFromVertices / tangent points)
+      item = app.create('polygon', { points: result, ...style });
+    } else if (result.center && typeof result.radius === 'number') {
+      // Circle / circumcircle
+      item = app.create('circle', { x: result.center.x, y: result.center.y, radius: result.radius, ...style });
+    } else if (typeof result.x === 'number' && typeof result.y === 'number') {
+      // Point → small marker
+      item = app.create(itemType || 'circle', { x: result.x, y: result.y, radius: (radius != null ? radius : 6), ...style });
+    } else {
+      return { success: true, operation: ${op}, result, itemId: null, note: 'Result is not directly creatable (line/scalar) — use the returned geometry as input to other tools' };
+    }
+    if (item) {
+      if (item.bringToFront) item.bringToFront();
+      itemId = item.data && item.data.registryId;
+      if (app.historyManager) app.historyManager.saveState();
+    }
+  }
+
+  return { success: true, operation: ${op}, result, itemId };
+})();`.trim();
+    }
+    /**
+     * Generate code for an equation-driven path (Expression IR — S10 B5).
+     * Emits app.createEquationPath(opts); the whole validated input IS the opts
+     * object. Guards on the app method so old FxTool builds degrade gracefully.
+     */
+    generateEquationPath(input) {
+        const optsJson = JSON.stringify(input);
+        const kindJson = JSON.stringify(input.kind);
+        return `
+// Equation-driven path: ${input.kind}${input.preset ? ' ' + input.preset : ''}
+(function() {
+  if (typeof app.createEquationPath !== 'function') {
+    return { success: false, error: 'app.createEquationPath unavailable — update FxTool to a build with the Expression IR equation-path API (S10 B5)' };
+  }
+  const path = app.createEquationPath(${optsJson});
+  if (!path) {
+    return { success: false, error: 'Equation path produced no points — check expr/xExpr/yExpr, the sample range, or the preset name' };
+  }
+  const itemId = path.data && path.data.registryId;
+  if (app.historyManager) app.historyManager.saveState();
+  return { success: true, kind: ${kindJson}, itemId };
+})();`.trim();
+    }
+    /**
+     * Generate code for the pp:event channel (S11 event-driven scene chains).
+     * create → app.createEvent(name, opts) → eventId; pulse → app.pulseEvent.
+     * Guards on the app methods so old FxTool builds degrade gracefully.
+     */
+    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 });
+            return `
+// Create event: ${input.name}
+(function() {
+  if (typeof app.createEvent !== 'function') {
+    return { success: false, error: 'app.createEvent unavailable — update FxTool to a build with the event system (S11)' };
+  }
+  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 };
+})();`.trim();
+        }
+        // pulse — a runtime fire, not a scene edit (no history save)
+        const eventIdJson = JSON.stringify(input.eventId);
+        const payloadJson = JSON.stringify(input.payload ?? null);
+        return `
+// Pulse event: ${input.eventId}
+(function() {
+  if (typeof app.pulseEvent !== 'function') {
+    return { success: false, error: 'app.pulseEvent unavailable — update FxTool to a build with the event system (S11)' };
+  }
+  app.pulseEvent(${eventIdJson}, ${payloadJson});
+  return { success: true, action: 'pulse', eventId: ${eventIdJson} };
+})();`.trim();
+    }
 }
 // Export singleton instance
 export const codeGenerator = new PinePaperCodeGenerator();