@pinepaper.studio/mcp-server 1.5.5 → 1.6.0

package/dist/types/code-generator.js

@@ -16,10 +16,13 @@ CreateLetterCollageInputSchema, AnimateLetterCollageInputSchema,
 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
 // =============================================================================
@@ -273,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}');
@@ -282,7 +287,7 @@ if (!item) {
 }
 app.animate(item, {
   animationType: '${animationType}',
-  animationSpeed: ${speed}
+  animationSpeed: ${speed}${extra}
 });
 
 ({ success: true, itemId: '${itemId}', animationType: '${animationType}' });
@@ -307,7 +312,7 @@ function normalizeKeyframePositions(keyframes) {
 /**
  * Template for keyframe animation
  */
-function generateKeyframeAnimateCode(itemId, keyframes, duration, loop = false, timeOffset, clipInPoint, clipOutPoint) {
+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 };
@@ -317,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)});
@@ -327,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();
 }
@@ -401,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':
@@ -422,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});
@@ -555,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
  */
@@ -638,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);
@@ -679,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
@@ -711,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
@@ -870,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();
     }
     /**
@@ -1728,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() {
@@ -1738,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 {
@@ -1746,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;'}
@@ -1772,7 +1909,7 @@ 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': {
                 const pos = op.position || { x: 400, y: 300 };
@@ -1790,6 +1927,19 @@ const itemId = item.data && item.data.id ? item.data.id : app.registerItem(item,
                 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();
@@ -1850,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 `
@@ -1859,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;
@@ -1874,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(normalizeKeyframePositions(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} });
@@ -1920,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} };
 `;
                 }
@@ -2259,7 +2434,7 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
      */
     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,
@@ -2277,6 +2452,10 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
             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() {
@@ -2858,6 +3037,198 @@ return { success: true, action: 'seek', time: ${op.time || 0} };
     return { success: false, error: error.message };
   }
 })();
+`.trim();
+    }
+    // -------------------------------------------------------------------------
+    // Globe + World Tour
+    // -------------------------------------------------------------------------
+    /**
+     * Generate code to enable globe (orthographic) mode
+     */
+    generateGlobeEnable(input) {
+        const validated = GlobeEnableInputSchema.parse(input);
+        const optionsStr = JSON.stringify(validated);
+        return `
+// Enable globe mode
+(function() {
+  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)' };
+  }
+
+  try {
+    app.mapSystem.enableGlobeMode(${optionsStr});
+    return { success: true };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+})();
+`.trim();
+    }
+    /**
+     * 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();
     }
     /**
@@ -3715,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 };
@@ -3733,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 };
@@ -4489,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();