@pinepaper.studio/mcp-server 1.4.3 → 1.5.0

package/dist/tools/handlers.js

@@ -8,11 +8,35 @@
 import { codeGenerator } from '../types/code-generator.js';
 import { CreateItemInputSchema, ModifyItemInputSchema, DeleteItemInputSchema, AddRelationInputSchema, RemoveRelationInputSchema, QueryRelationsInputSchema, AnimateItemInputSchema, KeyframeAnimateInputSchema, ExecuteGeneratorInputSchema, ApplyEffectInputSchema, GetItemsInputSchema, PlayTimelineInputSchema, SetBackgroundColorInputSchema, SetCanvasSizeInputSchema, ExportTrainingDataInputSchema, ImportSVGInputSchema, AddFilterInputSchema, CreateGlossySphereInputSchema, CreateDiagonalStripesInputSchema, BatchCreateInputSchema, BatchModifyInputSchema, CreateGridInputSchema, CreateSceneInputSchema, GetPerformanceMetricsInputSchema, SearchAssetsInputSchema, ImportAssetInputSchema, P5DrawInputSchema, 
 // Diagram schemas
-CreateDiagramShapeInputSchema, ConnectInputSchema, ConnectPortsInputSchema, AddPortsInputSchema, AutoLayoutInputSchema, GetDiagramShapesInputSchema, UpdateConnectorInputSchema, RemoveConnectorInputSchema, DiagramModeInputSchema, ErrorCodes, } from '../types/schemas.js';
+CreateDiagramShapeInputSchema, ConnectInputSchema, ConnectPortsInputSchema, AddPortsInputSchema, AutoLayoutInputSchema, GetDiagramShapesInputSchema, UpdateConnectorInputSchema, RemoveConnectorInputSchema, DiagramModeInputSchema, 
+// Agent flow mode schemas
+AgentStartJobInputSchema, AgentEndJobInputSchema, AgentResetInputSchema, AgentBatchExecuteInputSchema, AgentExportInputSchema, AgentAnalyzeInputSchema, 
+// Interactive/Trigger schemas
+AddTriggerInputSchema, RemoveTriggerInputSchema, QueryTriggersInputSchema, 
+// Quiz schemas
+CreateQuizInputSchema, GetQuizStateInputSchema, ResetQuizInputSchema, 
+// Letter collage schemas
+CreateLetterCollageInputSchema, AnimateLetterCollageInputSchema, 
+// Map schemas
+LoadMapInputSchema, HighlightRegionsInputSchema, UnhighlightRegionsInputSchema, ApplyDataColorsInputSchema, AddMarkerInputSchema, AddMapLabelsInputSchema, PanMapInputSchema, ZoomMapInputSchema, ImportCustomMapInputSchema, GetRegionAtPointInputSchema, 
+// Map animation/CSV schemas
+AnimateMapRegionsInputSchema, AnimateMapWaveInputSchema, StopMapAnimationsInputSchema, ExportMapRegionCSVInputSchema, ImportMapRegionCSVInputSchema, SelectMapRegionsInputSchema, DeselectMapRegionsInputSchema, 
+// Custom relation/code schemas
+RegisterCustomRelationInputSchema, ExecuteCustomCodeInputSchema, 
+// Mask schemas
+ApplyAnimatedMaskInputSchema, ApplyCustomMaskInputSchema, RemoveMaskInputSchema, 
+// Template schemas
+ApplyTemplateInputSchema, 
+// Image import schemas
+ImportImageInputSchema, ErrorCodes, } from '../types/schemas.js';
 import { ZodError } from 'zod';
+import { writeFile, mkdir } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import { getBrowserController, } from '../browser/puppeteer-controller.js';
 import { getPerformanceTracker } from '../metrics/index.js';
 import { formatErrorContext, captureCanvasState } from '../execution/index.js';
+import { getSessionManager } from '../agent/session-manager.js';
 /**
  * Get screenshot mode from environment variable.
  * Defaults to 'on_request' for optimal performance.
@@ -25,6 +49,37 @@ export function getScreenshotMode() {
     // Default to 'on_request' for better performance (best practice)
     return 'on_request';
 }
+// =============================================================================
+// EXPORT FILE SAVE HELPERS
+// =============================================================================
+function getExportDir() {
+    return process.env.PINEPAPER_EXPORT_DIR || join(tmpdir(), 'pinepaper-exports');
+}
+const ALWAYS_SAVE_FORMATS = new Set(['mp4', 'webm', 'gif', 'pdf']);
+const SAVE_THRESHOLD_BYTES = 500_000; // ~500KB base64 ≈ 375KB decoded
+function getFileExtension(format) {
+    const extMap = { mp4: 'mp4', webm: 'webm', gif: 'gif', pdf: 'pdf', png: 'png', svg: 'svg' };
+    return extMap[format] || format;
+}
+async function saveExportToFile(data, format, platform) {
+    const exportDir = getExportDir();
+    await mkdir(exportDir, { recursive: true });
+    const ext = getFileExtension(format);
+    const timestamp = Date.now();
+    const fileName = `pinepaper_${platform}_${timestamp}.${ext}`;
+    const filePath = join(exportDir, fileName);
+    if (data.startsWith('data:')) {
+        const base64Data = data.split(',')[1];
+        const buffer = Buffer.from(base64Data, 'base64');
+        await writeFile(filePath, buffer);
+        return { filePath, fileSize: buffer.length };
+    }
+    else {
+        // Plain text (SVG)
+        await writeFile(filePath, data, 'utf-8');
+        return { filePath, fileSize: Buffer.byteLength(data, 'utf-8') };
+    }
+}
 /**
  * Get execution mode from environment variable.
  * Defaults to 'puppeteer' for live execution.
@@ -153,7 +208,32 @@ async function executeOrGenerate(code, description, options, toolName) {
             success: true,
             metadata: { executionMode: 'code' },
         });
-        return successResult(code, `${description}\n\n📋 **Code Generation Mode**: Copy the code above and paste it into the PinePaper Studio console to execute.`);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `✅ **Code Generated Successfully**
+
+**Tool:** ${toolName}
+**Action:** ${description}
+
+## Generated Code
+
+\`\`\`javascript
+${code}
+\`\`\`
+
+## How to Execute
+
+1. Open **PinePaper Studio**: https://pinepaper.studio/editor?agent=1&mode=agent
+2. Click the **Code Console** button (</> icon) in the toolbar
+3. Paste the code above into the console
+4. Click **Run** to execute
+
+The code is ready to use. Each subsequent tool call will also generate code you can paste.`,
+                },
+            ],
+        };
     }
     if (!executeInBrowser) {
         const totalDuration = tracker.endTimer(`${timerId}_total`);
@@ -167,17 +247,72 @@ async function executeOrGenerate(code, description, options, toolName) {
         return successResult(code, description);
     }
     const controller = browserController || getBrowserController();
+    // Auto-connect in agent mode if not connected
     if (!controller.connected) {
-        const totalDuration = tracker.endTimer(`${timerId}_total`);
-        tracker.recordMetric({
-            toolName,
-            phase: 'total',
-            duration: totalDuration,
-            timestamp: Date.now(),
-            success: true,
-            metadata: { browserConnected: false },
+        console.error('[PinePaper] Auto-connecting browser in agent mode...');
+        try {
+            await controller.connect(); // Will use connectAgent() due to enforced agentMode
+            console.error('[PinePaper] Browser auto-connected successfully');
+        }
+        catch (connectError) {
+            const totalDuration = tracker.endTimer(`${timerId}_total`);
+            tracker.recordMetric({
+                toolName,
+                phase: 'total',
+                duration: totalDuration,
+                timestamp: Date.now(),
+                success: false,
+                metadata: { browserConnected: false, autoConnectFailed: true, fallbackToCode: true },
+            });
+            // FALLBACK: Return code for manual paste instead of failing
+            const errorMessage = connectError instanceof Error ? connectError.message : 'Unknown error';
+            console.error(`[PinePaper] Browser connection failed: ${errorMessage}. Falling back to code-only mode.`);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `⚠️ **Browser Connection Failed** - Falling back to code mode
+
+**Error:** ${errorMessage}
+
+**Don't worry!** You can still use PinePaper by copying the code below and pasting it into the PinePaper Code Console.
+
+## How to use the code manually:
+
+1. Open **PinePaper Studio**: https://pinepaper.studio/editor?agent=1&mode=agent
+2. Click the **Code Console** button (</> icon) in the toolbar
+3. Paste the code below into the console
+4. Click **Run** to execute
+
+---
+
+## Generated Code for: ${toolName}
+
+\`\`\`javascript
+${code}
+\`\`\`
+
+---
+
+**${description}**
+
+💡 **Tip:** If browser connection keeps failing, check:
+- Is Chrome/Chromium installed?
+- Are there firewall restrictions?
+- Try setting \`headless: false\` in browser_connect to see the browser window`,
+                    },
+                ],
+            };
+        }
+    }
+    // Auto-start agent session if not already active (enforced agent mode)
+    const sessionManager = getSessionManager();
+    if (!sessionManager.hasActiveJob()) {
+        sessionManager.startJob({
+            name: 'auto_session',
+            screenshotPolicy: 'on_complete',
         });
-        return successResult(code, `${description}\n\n⚠️ Browser not connected. Call pinepaper_browser_connect first to execute code live.`);
+        console.error('[PinePaper] Auto-started agent session for enforced agent mode');
     }
     // Track browser execution time
     tracker.startTimer(`${timerId}_browser_execution`);
@@ -318,6 +453,14 @@ export async function handleToolCall(toolName, args, options = {}) {
             }
             case 'pinepaper_modify_item': {
                 const input = ModifyItemInputSchema.parse(args);
+                // Guard: reject animation properties — they don't work via modify
+                const animProps = ['animationType', 'animationSpeed', 'keyframes', 'animation'];
+                const passedAnimProps = animProps.filter(p => p in (input.properties || {}));
+                if (passedAnimProps.length > 0) {
+                    return errorResult('INVALID_PROPERTIES', `Animation properties (${passedAnimProps.join(', ')}) cannot be set via pinepaper_modify_item — they will be silently ignored. ` +
+                        `Use pinepaper_animate for loop animations (pulse, rotate, bounce, fade, wobble, slide) ` +
+                        `or pinepaper_keyframe_animate for timed/sequenced animations with precise control.`);
+                }
                 const code = codeGenerator.generateModifyItem(input);
                 const description = getLocalizedSuccessMessage(i18n, 'itemModified', {
                     itemId: input.itemId,
@@ -386,7 +529,7 @@ export async function handleToolCall(toolName, args, options = {}) {
                 const description = getLocalizedSuccessMessage(i18n, 'relationAdded', {
                     relationType: input.relationType,
                     sourceId: input.sourceId,
-                    targetId: input.targetId,
+                    targetId: input.targetId || 'self',
                 });
                 return executeOrGenerate(code, description, options, 'pinepaper_add_relation');
             }
@@ -404,6 +547,16 @@ export async function handleToolCall(toolName, args, options = {}) {
                 const code = codeGenerator.generateQueryRelations(input.itemId, input.relationType, input.direction);
                 return executeOrGenerate(code, `Queries ${input.direction || 'all'} relations for ${input.itemId}`, options, 'pinepaper_query_relations');
             }
+            case 'pinepaper_register_custom_relation': {
+                const input = RegisterCustomRelationInputSchema.parse(args);
+                const code = codeGenerator.generateRegisterCustomRelation(input);
+                return executeOrGenerate(code, `Registers custom relation type: ${input.name}`, options, 'pinepaper_register_custom_relation');
+            }
+            case 'pinepaper_execute_custom_code': {
+                const input = ExecuteCustomCodeInputSchema.parse(args);
+                const code = codeGenerator.generateExecuteCustomCode(input);
+                return executeOrGenerate(code, input.description || 'Executes custom JavaScript code', options, 'pinepaper_execute_custom_code');
+            }
             // -----------------------------------------------------------------------
             // ANIMATION TOOLS
             // -----------------------------------------------------------------------
@@ -454,6 +607,204 @@ export async function handleToolCall(toolName, args, options = {}) {
                 return executeOrGenerate(code, description, options, 'pinepaper_apply_effect');
             }
             // -----------------------------------------------------------------------
+            // MASK TOOLS
+            // -----------------------------------------------------------------------
+            case 'pinepaper_apply_animated_mask': {
+                const input = ApplyAnimatedMaskInputSchema.parse(args);
+                const code = codeGenerator.generateApplyAnimatedMask(input);
+                const mode = input.preset && input.keyframes ? 'hybrid' : input.preset ? 'preset' : 'custom';
+                return executeOrGenerate(code, `Applies ${mode} animated mask to ${input.itemId}`, options, 'pinepaper_apply_animated_mask');
+            }
+            case 'pinepaper_apply_custom_mask': {
+                const input = ApplyCustomMaskInputSchema.parse(args);
+                const code = codeGenerator.generateApplyCustomMask(input);
+                return executeOrGenerate(code, `Applies custom ${input.maskType} mask with ${input.keyframes.length} keyframes to ${input.itemId}`, options, 'pinepaper_apply_custom_mask');
+            }
+            case 'pinepaper_remove_mask': {
+                const input = RemoveMaskInputSchema.parse(args);
+                const code = codeGenerator.generateRemoveMask(input);
+                return executeOrGenerate(code, `Removes mask from ${input.itemId}`, options, 'pinepaper_remove_mask');
+            }
+            case 'pinepaper_get_animatable_properties': {
+                const code = codeGenerator.generateGetAnimatableProperties();
+                return executeOrGenerate(code, 'Gets animatable properties for mask types', options, 'pinepaper_get_animatable_properties');
+            }
+            case 'pinepaper_get_available_easings': {
+                const code = codeGenerator.generateGetAvailableEasings();
+                return executeOrGenerate(code, 'Gets available easing functions', options, 'pinepaper_get_available_easings');
+            }
+            case 'pinepaper_get_mask_types': {
+                const code = codeGenerator.generateGetMaskTypes();
+                return executeOrGenerate(code, 'Gets available mask types', options, 'pinepaper_get_mask_types');
+            }
+            case 'pinepaper_get_mask_animations': {
+                const code = codeGenerator.generateGetMaskAnimations();
+                return executeOrGenerate(code, 'Gets available mask animation presets', options, 'pinepaper_get_mask_animations');
+            }
+            // -----------------------------------------------------------------------
+            // CAMERA TOOLS
+            // -----------------------------------------------------------------------
+            case 'pinepaper_camera_animate': {
+                const keyframes = args.keyframes;
+                const duration = args.duration;
+                const loop = args.loop ?? false;
+                const delay = args.delay ?? 0;
+                const keyframesStr = JSON.stringify(keyframes);
+                const code = `app.camera && app.camera.animate ? app.camera.animate(${keyframesStr}, ${duration}, ${loop}, ${delay}) : app.addRelation('camera', 'camera', 'camera_animates', { keyframes: ${keyframesStr}, duration: ${duration}, loop: ${loop}, delay: ${delay} });`;
+                return executeOrGenerate(code, `Animates camera with ${keyframes.length} keyframes over ${duration}s`, options, 'pinepaper_camera_animate');
+            }
+            case 'pinepaper_camera_zoom': {
+                const direction = args.direction;
+                const level = args.level ?? (direction === 'in' ? 2 : 0.5);
+                const duration = args.duration ?? 0.5;
+                const method = direction === 'in' ? 'zoomIn' : 'zoomOut';
+                const code = `app.camera && app.camera.${method} ? app.camera.${method}(${level}, ${duration}) : null;`;
+                return executeOrGenerate(code, `Camera zoom ${direction} to ${level}x`, options, 'pinepaper_camera_zoom');
+            }
+            case 'pinepaper_camera_pan': {
+                const direction = args.direction;
+                const amount = args.amount ?? 100;
+                const x = args.x;
+                const y = args.y;
+                const duration = args.duration ?? 0.5;
+                let code;
+                let description;
+                if (x !== undefined && y !== undefined) {
+                    code = `app.camera && app.camera.panTo ? app.camera.panTo(${x}, ${y}, ${duration}) : null;`;
+                    description = `Camera pan to (${x}, ${y})`;
+                }
+                else if (direction) {
+                    const methodMap = { left: 'panLeft', right: 'panRight', up: 'panUp', down: 'panDown' };
+                    const method = methodMap[direction];
+                    code = `app.camera && app.camera.${method} ? app.camera.${method}(${amount}, ${duration}) : null;`;
+                    description = `Camera pan ${direction} by ${amount}px`;
+                }
+                else {
+                    code = `// No direction or coordinates specified`;
+                    description = 'Camera pan (no parameters)';
+                }
+                return executeOrGenerate(code, description, options, 'pinepaper_camera_pan');
+            }
+            case 'pinepaper_camera_move_to': {
+                const x = args.x;
+                const y = args.y;
+                const zoom = args.zoom;
+                const duration = args.duration ?? 0.5;
+                const code = `app.camera && app.camera.moveTo ? app.camera.moveTo(${x}, ${y}, ${zoom}, ${duration}) : null;`;
+                return executeOrGenerate(code, `Camera move to (${x}, ${y}) at ${zoom}x zoom`, options, 'pinepaper_camera_move_to');
+            }
+            case 'pinepaper_camera_reset': {
+                const duration = args.duration ?? 0.5;
+                const code = `app.camera && app.camera.reset ? app.camera.reset(${duration}) : null;`;
+                return executeOrGenerate(code, 'Reset camera to default state', options, 'pinepaper_camera_reset');
+            }
+            case 'pinepaper_camera_stop': {
+                const code = `app.camera && app.camera.stop ? app.camera.stop() : null;`;
+                return executeOrGenerate(code, 'Stop camera animation', options, 'pinepaper_camera_stop');
+            }
+            case 'pinepaper_camera_state': {
+                const code = `app.camera && app.camera.getState ? app.camera.getState() : { zoom: 1, center: [400, 300], isAnimating: false };`;
+                return executeOrGenerate(code, 'Get current camera state', options, 'pinepaper_camera_state');
+            }
+            // -----------------------------------------------------------------------
+            // FONT TOOLS
+            // -----------------------------------------------------------------------
+            case 'pinepaper_font_show_studio': {
+                const code = `app.fontStudio && app.fontStudio.show ? app.fontStudio.show() : null;`;
+                return executeOrGenerate(code, 'Opens Font Studio UI', options, 'pinepaper_font_show_studio');
+            }
+            case 'pinepaper_font_set_name': {
+                const { name } = args;
+                const code = `app.fontStudio.setName(${JSON.stringify(name)});`;
+                return executeOrGenerate(code, `Set font name to "${name}"`, options, 'pinepaper_font_set_name');
+            }
+            case 'pinepaper_font_get_required_chars': {
+                const { set } = args;
+                const setArg = set ? JSON.stringify(set) : '"minimum"';
+                const code = `app.fontStudio.getRequiredChars(${setArg});`;
+                return executeOrGenerate(code, `Get required characters (${set || 'minimum'} set)`, options, 'pinepaper_font_get_required_chars');
+            }
+            case 'pinepaper_font_get_status': {
+                const code = `app.fontStudio.getStatus();`;
+                return executeOrGenerate(code, 'Get font completion status', options, 'pinepaper_font_get_status');
+            }
+            case 'pinepaper_font_create_glyph': {
+                const { character, pathId } = args;
+                const code = `app.fontStudio.createGlyph(${JSON.stringify(character)}, ${JSON.stringify(pathId)});`;
+                return executeOrGenerate(code, `Create glyph for "${character}" from path ${pathId}`, options, 'pinepaper_font_create_glyph');
+            }
+            case 'pinepaper_font_create_space': {
+                const { width } = args;
+                const code = width !== undefined
+                    ? `app.fontStudio.createSpace(${width});`
+                    : `app.fontStudio.createSpace();`;
+                return executeOrGenerate(code, `Create space glyph${width ? ` (width: ${width})` : ''}`, options, 'pinepaper_font_create_space');
+            }
+            case 'pinepaper_font_remove_glyph': {
+                const { character } = args;
+                const code = `app.fontStudio.removeGlyph(${JSON.stringify(character)});`;
+                return executeOrGenerate(code, `Remove glyph for "${character}"`, options, 'pinepaper_font_remove_glyph');
+            }
+            case 'pinepaper_font_set_metrics': {
+                const metrics = args;
+                const code = `app.fontStudio.setMetrics(${JSON.stringify(metrics)});`;
+                return executeOrGenerate(code, 'Set font metrics', options, 'pinepaper_font_set_metrics');
+            }
+            case 'pinepaper_font_export': {
+                const { download } = args;
+                const code = download === false
+                    ? `app.fontStudio.export({ download: false });`
+                    : `app.fontStudio.export();`;
+                return executeOrGenerate(code, 'Export font as OTF', options, 'pinepaper_font_export');
+            }
+            case 'pinepaper_font_load_into_document': {
+                const code = `app.fontStudio.loadIntoDocument();`;
+                return executeOrGenerate(code, 'Load font into document', options, 'pinepaper_font_load_into_document');
+            }
+            case 'pinepaper_font_export_data': {
+                const { download } = args;
+                const code = download === false
+                    ? `app.fontStudio.exportData({ download: false });`
+                    : `app.fontStudio.exportData();`;
+                return executeOrGenerate(code, 'Export font data as JSON', options, 'pinepaper_font_export_data');
+            }
+            case 'pinepaper_font_import_data': {
+                const { data } = args;
+                const code = `app.fontStudio.importData(${JSON.stringify(data)});`;
+                return executeOrGenerate(code, 'Import font data from JSON', options, 'pinepaper_font_import_data');
+            }
+            case 'pinepaper_font_clear': {
+                const code = `app.fontStudio.clear();`;
+                return executeOrGenerate(code, 'Clear all glyphs and reset font', options, 'pinepaper_font_clear');
+            }
+            case 'pinepaper_font_remove_overlap': {
+                const { pathId } = args;
+                const code = `app.fontStudio.removeOverlap(${JSON.stringify(pathId)});`;
+                return executeOrGenerate(code, `Remove overlaps from path ${pathId}`, options, 'pinepaper_font_remove_overlap');
+            }
+            case 'pinepaper_font_correct_direction': {
+                const { pathId } = args;
+                const code = `app.fontStudio.correctDirection(${JSON.stringify(pathId)});`;
+                return executeOrGenerate(code, `Correct path direction for ${pathId}`, options, 'pinepaper_font_correct_direction');
+            }
+            case 'pinepaper_font_cleanup_path': {
+                const { pathId, removeOverlap, correctDirection, smooth, smoothTolerance } = args;
+                const optsObj = {};
+                if (removeOverlap !== undefined)
+                    optsObj.removeOverlap = removeOverlap;
+                if (correctDirection !== undefined)
+                    optsObj.correctDirection = correctDirection;
+                if (smooth !== undefined)
+                    optsObj.smooth = smooth;
+                if (smoothTolerance !== undefined)
+                    optsObj.smoothTolerance = smoothTolerance;
+                const hasOpts = Object.keys(optsObj).length > 0;
+                const code = hasOpts
+                    ? `app.fontStudio.cleanupPath(${JSON.stringify(pathId)}, ${JSON.stringify(optsObj)});`
+                    : `app.fontStudio.cleanupPath(${JSON.stringify(pathId)});`;
+                return executeOrGenerate(code, `Cleanup path ${pathId}`, options, 'pinepaper_font_cleanup_path');
+            }
+            // -----------------------------------------------------------------------
             // QUERY TOOLS
             // -----------------------------------------------------------------------
             case 'pinepaper_get_items': {
@@ -565,19 +916,24 @@ You can now start creating new items on a clean canvas.`,
                 });
                 return executeOrGenerate(code, description, options, 'pinepaper_export_training_data');
             }
+            case 'pinepaper_export_scene': {
+                const code = codeGenerator.generateExportScene();
+                return executeOrGenerate(code, 'Exports complete scene state', options, 'pinepaper_export_scene');
+            }
             // -----------------------------------------------------------------------
             // BROWSER CONTROL TOOLS
             // -----------------------------------------------------------------------
             case 'pinepaper_browser_connect': {
                 const url = args.url || 'https://pinepaper.studio';
-                const headless = args.headless ?? false;
+                // Default to headless: true for enforced agent mode
+                const headless = args.headless ?? true;
                 const controller = getBrowserController({ studioUrl: url, headless });
                 if (controller.connected) {
                     return {
                         content: [
                             {
                                 type: 'text',
-                                text: `Already connected to PinePaper Studio at ${controller.studioUrl}`,
+                                text: `Already connected to PinePaper Studio at ${controller.actualUrl}. Do NOT call this tool again — proceed directly with pinepaper_agent_start_job.`,
                             },
                         ],
                     };
@@ -593,8 +949,9 @@ You can now start creating new items on a clean canvas.`,
                     const content = [
                         {
                             type: 'text',
-                            text: `✅ Connected to PinePaper Studio at ${url}
+                            text: `✅ Connected to PinePaper Studio at ${controller.actualUrl}
 
+**Agent mode enabled** (agent=1&mode=agent parameters added automatically)
 **Current canvas size: ${canvasSize.width}x${canvasSize.height}**
 
 ⚠️ IMPORTANT NOTES:
@@ -615,7 +972,39 @@ Browser is ready. You can now use other pinepaper tools to create and animate gr
                     return { content };
                 }
                 catch (error) {
-                    return errorResult('BROWSER_CONNECTION_ERROR', error instanceof Error ? error.message : 'Failed to connect to browser', { url });
+                    const errorMessage = error instanceof Error ? error.message : 'Failed to connect to browser';
+                    // Provide helpful fallback instructions instead of just failing
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `⚠️ **Browser Connection Failed**
+
+**Error:** ${errorMessage}
+
+## Don't worry! You can still use PinePaper manually:
+
+### Option 1: Manual Browser Mode
+1. Open **PinePaper Studio** in your browser: https://pinepaper.studio/editor?agent=1&mode=agent
+2. Continue using PinePaper tools - the MCP server will generate code for each action
+3. Copy the generated code and paste it into the **Code Console** (</> icon in toolbar)
+
+### Option 2: Troubleshoot Browser Connection
+- **Check Chrome/Chromium**: Puppeteer requires Chrome or Chromium installed
+- **Try headless: false**: Call \`pinepaper_browser_connect\` with \`headless: false\` to see the browser window
+- **Check permissions**: Ensure the process has permission to launch browsers
+- **Firewall**: Check if firewall is blocking browser launch
+
+### What happens now?
+All PinePaper tools will work in **code-only mode**:
+- Each tool generates JavaScript code
+- You copy the code and paste it in PinePaper's Code Console
+- The code executes and creates your graphics
+
+**The MCP server is fully functional** - just without automatic browser control.`,
+                            },
+                        ],
+                    };
                 }
             }
             case 'pinepaper_browser_disconnect': {
@@ -664,7 +1053,8 @@ Browser is ready. You can now use other pinepaper tools to create and animate gr
                             type: 'text',
                             text: JSON.stringify({
                                 connected: controller.connected,
-                                studioUrl: controller.studioUrl,
+                                studioUrl: controller.actualUrl,
+                                agentMode: controller.agentMode,
                             }, null, 2),
                         },
                     ],
@@ -894,6 +1284,426 @@ Browser is ready. You can now use other pinepaper tools to create and animate gr
                 return executeOrGenerate(code, description, options, 'pinepaper_diagram_mode');
             }
             // -----------------------------------------------------------------------
+            // AGENT FLOW MODE TOOLS
+            // -----------------------------------------------------------------------
+            case 'pinepaper_agent_start_job': {
+                const input = AgentStartJobInputSchema.parse(args);
+                // Guard against pipeline restarts — warn loudly if a job is already active
+                const session = getSessionManager();
+                if (session.hasActiveJob()) {
+                    const currentJob = session.getCurrentJob();
+                    const itemCount = currentJob?.itemsCreated.length ?? 0;
+                    if (itemCount > 0) {
+                        // Job has items — this is almost certainly a pipeline restart bug
+                        console.error(`[PinePaper] WARNING: Starting new job while ${itemCount} items exist from active job ${currentJob?.jobId}`);
+                        const code = codeGenerator.generateAgentStartJob(input);
+                        const result = await executeOrGenerate(code, `Restarted job (previous had ${itemCount} items)`, options, 'pinepaper_agent_start_job');
+                        // Prepend a strong warning to the result text
+                        if (result.content && result.content.length > 0 && result.content[0].type === 'text') {
+                            result.content[0].text = `⚠️ WARNING: A job was already active with ${itemCount} items created. Starting a new job will create DUPLICATE items on the canvas. If you already created items, do NOT recreate them — continue from where you left off or call pinepaper_agent_end_job instead.\n\n${result.content[0].text}`;
+                        }
+                        return result;
+                    }
+                }
+                const code = codeGenerator.generateAgentStartJob(input);
+                const description = `Started agent job${input.name ? ` "${input.name}"` : ''} with ${input.screenshotPolicy || 'on_complete'} screenshot policy`;
+                return executeOrGenerate(code, description, options, 'pinepaper_agent_start_job');
+            }
+            case 'pinepaper_agent_end_job': {
+                const input = AgentEndJobInputSchema.parse(args);
+                const code = codeGenerator.generateAgentEndJob(input);
+                const description = 'Ended agent job with summary and recommendations';
+                // In code mode or non-browser mode, return as usual
+                const endJobExecMode = options.executionMode ?? getExecutionMode();
+                if (endJobExecMode === 'code' || !options.executeInBrowser) {
+                    return executeOrGenerate(code, description, options, 'pinepaper_agent_end_job');
+                }
+                // Execute in browser and intercept result to save large screenshots to disk
+                const endJobController = options.browserController || getBrowserController();
+                if (!endJobController.connected) {
+                    return executeOrGenerate(code, description, options, 'pinepaper_agent_end_job');
+                }
+                // Auto-start agent session if not active
+                const endJobSessionMgr = getSessionManager();
+                if (!endJobSessionMgr.hasActiveJob()) {
+                    endJobSessionMgr.startJob({ name: 'auto_session', screenshotPolicy: 'on_complete' });
+                }
+                const endJobBrowserResult = await endJobController.executeCode(code, false);
+                if (!endJobBrowserResult.success) {
+                    const canvasState = await captureCanvasState(endJobController);
+                    return errorResult(ErrorCodes.EXECUTION_ERROR, endJobBrowserResult.error || 'End job failed', { code }, { toolName: 'pinepaper_agent_end_job', canvasState: canvasState || undefined });
+                }
+                const endJobResult = endJobBrowserResult.result;
+                // Check if result contains a large screenshot data URL
+                if (endJobResult?.screenshot && typeof endJobResult.screenshot === 'string' && endJobResult.screenshot.length > SAVE_THRESHOLD_BYTES) {
+                    try {
+                        const { filePath, fileSize } = await saveExportToFile(endJobResult.screenshot, 'png', 'screenshot');
+                        const cleanResult = { ...endJobResult, screenshot: undefined, screenshotPath: filePath, screenshotSize: fileSize };
+                        // Take a smaller Puppeteer viewport screenshot to show the user inline
+                        const previewScreenshot = await endJobController.takeScreenshot();
+                        const content = [{
+                                type: 'text',
+                                text: `Executed PinePaper code:\n\n\`\`\`javascript\n${code}\n\`\`\`\n\nFull screenshot saved to: ${filePath} (${(fileSize / 1024).toFixed(1)} KB)\n\nResult: ${JSON.stringify(cleanResult, null, 2)}`,
+                            }];
+                        if (previewScreenshot) {
+                            content.push({
+                                type: 'image',
+                                data: previewScreenshot,
+                                mimeType: 'image/png',
+                            });
+                        }
+                        return { content };
+                    }
+                    catch (saveError) {
+                        console.error('[PinePaper] Failed to save end_job screenshot to file:', saveError);
+                        // Fall through to inline result but strip the screenshot to avoid oversized response
+                        const strippedResult = { ...endJobResult, screenshot: '[screenshot too large for inline — save failed]' };
+                        return executedResult(code, strippedResult, undefined, description);
+                    }
+                }
+                return executedResult(code, endJobResult, endJobBrowserResult.screenshot, description);
+            }
+            case 'pinepaper_agent_reset': {
+                const input = AgentResetInputSchema.parse(args);
+                const code = codeGenerator.generateAgentReset(input);
+                const description = `Fast canvas reset${input.canvasPreset ? ` to ${input.canvasPreset} preset` : ''}`;
+                return executeOrGenerate(code, description, options, 'pinepaper_agent_reset');
+            }
+            case 'pinepaper_agent_batch_execute': {
+                const input = AgentBatchExecuteInputSchema.parse(args);
+                const code = codeGenerator.generateAgentBatchExecute(input);
+                const description = `Batch executed ${input.operations.length} operations${input.atomic !== false ? ' (atomic)' : ''}`;
+                // Check for out-of-bounds items before execution
+                let boundsWarning = '';
+                const sizeOp = input.operations.find((op) => op.type === 'set_canvas_size');
+                if (sizeOp) {
+                    const cw = sizeOp.width || 1920;
+                    const ch = sizeOp.height || 1080;
+                    const oobItems = [];
+                    input.operations.forEach((op, idx) => {
+                        if (op.type === 'create' && op.position) {
+                            const { x, y } = op.position;
+                            if (x < 0 || y < 0 || x > cw || y > ch) {
+                                oobItems.push(`op[${idx}] ${op.itemType || 'item'} at (${x},${y})`);
+                            }
+                        }
+                    });
+                    if (oobItems.length > 0) {
+                        boundsWarning = `\n\nWARNING: ${oobItems.length} item(s) positioned outside canvas bounds (${cw}x${ch}): ${oobItems.join(', ')}. Items may be clipped or invisible.`;
+                    }
+                }
+                const batchResult = await executeOrGenerate(code, description, options, 'pinepaper_agent_batch_execute');
+                // Append bounds warning if any
+                if (boundsWarning && batchResult.content && batchResult.content.length > 0) {
+                    const firstContent = batchResult.content[0];
+                    if (firstContent.type === 'text') {
+                        firstContent.text += boundsWarning;
+                    }
+                }
+                return batchResult;
+            }
+            case 'pinepaper_agent_export': {
+                const input = AgentExportInputSchema.parse(args);
+                const code = codeGenerator.generateAgentExport(input);
+                const description = `Smart export for ${input.platform} as ${input.format || 'auto'}`;
+                // In code mode, return generated code as usual
+                const effectiveExecMode = options.executionMode ?? getExecutionMode();
+                if (effectiveExecMode === 'code' || !options.executeInBrowser) {
+                    return executeOrGenerate(code, description, options, 'pinepaper_agent_export');
+                }
+                // Execute in browser and intercept result for file saving
+                const controller = options.browserController || getBrowserController();
+                // Auto-connect if needed
+                if (!controller.connected) {
+                    console.error('[PinePaper] Auto-connecting browser for export...');
+                    try {
+                        await controller.connect();
+                    }
+                    catch (connectError) {
+                        // Fall back to executeOrGenerate which handles the fallback gracefully
+                        return executeOrGenerate(code, description, options, 'pinepaper_agent_export');
+                    }
+                }
+                // Auto-start agent session if not active
+                const exportSessionManager = getSessionManager();
+                if (!exportSessionManager.hasActiveJob()) {
+                    exportSessionManager.startJob({ name: 'auto_session', screenshotPolicy: 'on_complete' });
+                }
+                const exportBrowserResult = await controller.executeCode(code, false);
+                if (!exportBrowserResult.success) {
+                    const canvasState = await captureCanvasState(controller);
+                    return errorResult(ErrorCodes.EXECUTION_ERROR, exportBrowserResult.error || 'Export failed', { code }, { toolName: 'pinepaper_agent_export', canvasState: canvasState || undefined });
+                }
+                const exportResult = exportBrowserResult.result;
+                const format = exportResult?.format || input.format || 'png';
+                const data = exportResult?.data;
+                const shouldSaveToFile = data && typeof data === 'string' && (ALWAYS_SAVE_FORMATS.has(format) ||
+                    data.length > SAVE_THRESHOLD_BYTES);
+                if (shouldSaveToFile) {
+                    try {
+                        const { filePath, fileSize } = await saveExportToFile(data, format, input.platform || 'auto');
+                        const cleanResult = { ...exportResult, data: undefined, filePath, fileSize };
+                        return {
+                            content: [{
+                                    type: 'text',
+                                    text: `Export saved to file:\n\nFile: ${filePath}\nFormat: ${format}\nSize: ${(fileSize / 1024).toFixed(1)} KB\nPlatform: ${input.platform}\n\nResult: ${JSON.stringify(cleanResult, null, 2)}`,
+                                }],
+                        };
+                    }
+                    catch (saveError) {
+                        console.error('[PinePaper] Failed to save export to file:', saveError);
+                        // Strip the massive data to prevent oversized response
+                        const strippedResult = { ...exportResult, data: `[${format} export data — file save failed: ${saveError instanceof Error ? saveError.message : 'unknown error'}]` };
+                        return executedResult(code, strippedResult, exportBrowserResult.screenshot, description);
+                    }
+                }
+                // Small export — return inline (existing behavior)
+                return executedResult(code, exportResult, exportBrowserResult.screenshot, description);
+            }
+            case 'pinepaper_agent_analyze': {
+                const input = AgentAnalyzeInputSchema.parse(args);
+                const code = codeGenerator.generateAgentAnalyze(input);
+                const description = 'Analyzed canvas content for export recommendations';
+                return executeOrGenerate(code, description, options, 'pinepaper_agent_analyze');
+            }
+            // -----------------------------------------------------------------------
+            // INTERACTIVE TRIGGER TOOLS
+            // -----------------------------------------------------------------------
+            case 'pinepaper_add_trigger': {
+                const input = AddTriggerInputSchema.parse(args);
+                const code = codeGenerator.generateAddTrigger(input);
+                const description = `Added ${input.event} trigger to ${input.itemId} with ${input.actions.length} actions`;
+                return executeOrGenerate(code, description, options, 'pinepaper_add_trigger');
+            }
+            case 'pinepaper_remove_trigger': {
+                const input = RemoveTriggerInputSchema.parse(args);
+                const code = codeGenerator.generateRemoveTrigger(input);
+                const description = input.removeAll
+                    ? `Removed all triggers from ${input.itemId}`
+                    : `Removed ${input.event} trigger from ${input.itemId}`;
+                return executeOrGenerate(code, description, options, 'pinepaper_remove_trigger');
+            }
+            case 'pinepaper_query_triggers': {
+                const input = QueryTriggersInputSchema.parse(args);
+                const code = codeGenerator.generateQueryTriggers(input);
+                const description = input.itemId
+                    ? `Queried triggers for ${input.itemId}`
+                    : 'Queried all triggers on canvas';
+                return executeOrGenerate(code, description, options, 'pinepaper_query_triggers');
+            }
+            // -----------------------------------------------------------------------
+            // QUIZ/LMS TOOLS
+            // -----------------------------------------------------------------------
+            case 'pinepaper_create_quiz': {
+                const input = CreateQuizInputSchema.parse(args);
+                const code = codeGenerator.generateCreateQuiz(input);
+                const description = `Created quiz${input.title ? ` "${input.title}"` : ''} with ${input.questions.length} questions`;
+                return executeOrGenerate(code, description, options, 'pinepaper_create_quiz');
+            }
+            case 'pinepaper_get_quiz_state': {
+                const input = GetQuizStateInputSchema.parse(args);
+                const code = codeGenerator.generateGetQuizState(input);
+                const description = input.quizId
+                    ? `Got state for quiz ${input.quizId}`
+                    : 'Got state for active quiz';
+                return executeOrGenerate(code, description, options, 'pinepaper_get_quiz_state');
+            }
+            case 'pinepaper_reset_quiz': {
+                const input = ResetQuizInputSchema.parse(args);
+                const code = codeGenerator.generateResetQuiz(input);
+                const description = input.quizId
+                    ? `Reset quiz ${input.quizId}`
+                    : 'Reset active quiz';
+                return executeOrGenerate(code, description, options, 'pinepaper_reset_quiz');
+            }
+            // -----------------------------------------------------------------------
+            // LETTER COLLAGE TOOLS
+            // -----------------------------------------------------------------------
+            case 'pinepaper_create_letter_collage': {
+                const input = CreateLetterCollageInputSchema.parse(args);
+                const code = codeGenerator.generateCreateLetterCollage(input);
+                const description = `Created ${input.style || 'tile'} letter collage: "${input.text}"`;
+                return executeOrGenerate(code, description, options, 'pinepaper_create_letter_collage');
+            }
+            case 'pinepaper_animate_letter_collage': {
+                const input = AnimateLetterCollageInputSchema.parse(args);
+                const code = codeGenerator.generateAnimateLetterCollage(input);
+                const description = `Animated collage ${input.collageId} with ${input.animationType}`;
+                return executeOrGenerate(code, description, options, 'pinepaper_animate_letter_collage');
+            }
+            case 'pinepaper_get_letter_collage_options': {
+                const code = codeGenerator.generateGetLetterCollageOptions();
+                return executeOrGenerate(code, 'Gets available letter collage styles and palettes', options, 'pinepaper_get_letter_collage_options');
+            }
+            // -----------------------------------------------------------------------
+            // CANVAS PRESETS TOOLS
+            // -----------------------------------------------------------------------
+            case 'pinepaper_get_canvas_presets': {
+                const code = codeGenerator.generateGetCanvasPresets();
+                return executeOrGenerate(code, 'Gets all available canvas presets', options, 'pinepaper_get_canvas_presets');
+            }
+            // -----------------------------------------------------------------------
+            // MAP TOOLS
+            // -----------------------------------------------------------------------
+            case 'pinepaper_load_map': {
+                const input = LoadMapInputSchema.parse(args);
+                const code = codeGenerator.generateLoadMap(input);
+                const description = `Loads ${input.mapId} map with ${input.projection || 'default'} projection`;
+                return executeOrGenerate(code, description, options, 'pinepaper_load_map');
+            }
+            case 'pinepaper_highlight_regions': {
+                const input = HighlightRegionsInputSchema.parse(args);
+                const code = codeGenerator.generateHighlightRegions(input);
+                const description = `Highlights ${input.regionIds.length} region(s) on the map`;
+                return executeOrGenerate(code, description, options, 'pinepaper_highlight_regions');
+            }
+            case 'pinepaper_unhighlight_regions': {
+                const input = UnhighlightRegionsInputSchema.parse(args);
+                const code = codeGenerator.generateUnhighlightRegions(input);
+                return executeOrGenerate(code, 'Removes region highlights', options, 'pinepaper_unhighlight_regions');
+            }
+            case 'pinepaper_apply_data_colors': {
+                const input = ApplyDataColorsInputSchema.parse(args);
+                const code = codeGenerator.generateApplyDataColors(input);
+                const regionCount = Object.keys(input.data).length;
+                const description = `Applies choropleth coloring to ${regionCount} region(s)`;
+                return executeOrGenerate(code, description, options, 'pinepaper_apply_data_colors');
+            }
+            case 'pinepaper_add_marker': {
+                const input = AddMarkerInputSchema.parse(args);
+                const code = codeGenerator.generateAddMarker(input);
+                const description = `Adds marker at [${input.lat}, ${input.lon}]${input.label ? `: ${input.label}` : ''}`;
+                return executeOrGenerate(code, description, options, 'pinepaper_add_marker');
+            }
+            case 'pinepaper_add_map_labels': {
+                const input = AddMapLabelsInputSchema.parse(args);
+                const code = codeGenerator.generateAddMapLabels(input);
+                return executeOrGenerate(code, 'Adds labels to map regions', options, 'pinepaper_add_map_labels');
+            }
+            case 'pinepaper_pan_map': {
+                const input = PanMapInputSchema.parse(args);
+                const code = codeGenerator.generatePanMap(input);
+                const description = `Pans map to [${input.lat}, ${input.lon}]`;
+                return executeOrGenerate(code, description, options, 'pinepaper_pan_map');
+            }
+            case 'pinepaper_zoom_map': {
+                const input = ZoomMapInputSchema.parse(args);
+                const code = codeGenerator.generateZoomMap(input);
+                const description = `Sets map zoom level to ${input.level}`;
+                return executeOrGenerate(code, description, options, 'pinepaper_zoom_map');
+            }
+            case 'pinepaper_export_map': {
+                const code = codeGenerator.generateExportMap();
+                return executeOrGenerate(code, 'Exports map configuration', options, 'pinepaper_export_map');
+            }
+            case 'pinepaper_import_custom_map': {
+                const input = ImportCustomMapInputSchema.parse(args);
+                const code = codeGenerator.generateImportCustomMap(input);
+                const description = input.url ? `Imports custom map from URL` : 'Imports custom GeoJSON map';
+                return executeOrGenerate(code, description, options, 'pinepaper_import_custom_map');
+            }
+            case 'pinepaper_get_region_at_point': {
+                const input = GetRegionAtPointInputSchema.parse(args);
+                const code = codeGenerator.generateGetRegionAtPoint(input);
+                const description = `Gets region at point [${input.x}, ${input.y}]`;
+                return executeOrGenerate(code, description, options, 'pinepaper_get_region_at_point');
+            }
+            // -----------------------------------------------------------------------
+            // MAP ANIMATION/CSV TOOLS
+            // -----------------------------------------------------------------------
+            case 'pinepaper_animate_map_regions': {
+                const input = AnimateMapRegionsInputSchema.parse(args);
+                const code = codeGenerator.generateAnimateMapRegions(input);
+                const regionCount = Object.keys(input.regions).length;
+                const description = `Animates ${regionCount} map region(s) over ${input.duration || 5}s`;
+                return executeOrGenerate(code, description, options, 'pinepaper_animate_map_regions');
+            }
+            case 'pinepaper_animate_map_wave': {
+                const input = AnimateMapWaveInputSchema.parse(args);
+                const code = codeGenerator.generateAnimateMapWave(input);
+                const description = `Creates ${input.waveDirection || 'horizontal'} wave animation`;
+                return executeOrGenerate(code, description, options, 'pinepaper_animate_map_wave');
+            }
+            case 'pinepaper_stop_map_animations': {
+                const input = StopMapAnimationsInputSchema.parse(args);
+                const code = codeGenerator.generateStopMapAnimations(input);
+                return executeOrGenerate(code, 'Stops map region animations', options, 'pinepaper_stop_map_animations');
+            }
+            case 'pinepaper_get_animated_map_regions': {
+                const code = codeGenerator.generateGetAnimatedMapRegions();
+                return executeOrGenerate(code, 'Gets list of animated map regions', options, 'pinepaper_get_animated_map_regions');
+            }
+            case 'pinepaper_export_map_region_csv': {
+                const input = ExportMapRegionCSVInputSchema.parse(args);
+                const code = codeGenerator.generateExportMapRegionCSV(input);
+                return executeOrGenerate(code, 'Exports map region data as CSV', options, 'pinepaper_export_map_region_csv');
+            }
+            case 'pinepaper_import_map_region_csv': {
+                const input = ImportMapRegionCSVInputSchema.parse(args);
+                const code = codeGenerator.generateImportMapRegionCSV(input);
+                return executeOrGenerate(code, 'Imports CSV data to update map regions', options, 'pinepaper_import_map_region_csv');
+            }
+            case 'pinepaper_select_map_regions': {
+                const input = SelectMapRegionsInputSchema.parse(args);
+                const code = codeGenerator.generateSelectMapRegions(input);
+                const description = `Selects ${input.regionIds.length} map region(s)`;
+                return executeOrGenerate(code, description, options, 'pinepaper_select_map_regions');
+            }
+            case 'pinepaper_deselect_map_regions': {
+                const input = DeselectMapRegionsInputSchema.parse(args);
+                const code = codeGenerator.generateDeselectMapRegions(input);
+                return executeOrGenerate(code, 'Deselects map regions', options, 'pinepaper_deselect_map_regions');
+            }
+            case 'pinepaper_get_highlighted_map_regions': {
+                const code = codeGenerator.generateGetHighlightedMapRegions();
+                return executeOrGenerate(code, 'Gets list of highlighted map regions', options, 'pinepaper_get_highlighted_map_regions');
+            }
+            case 'pinepaper_export_map_geojson': {
+                const code = codeGenerator.generateExportMapGeoJson({
+                    includeStyles: args.includeStyles,
+                    includeMetadata: args.includeMetadata,
+                    selectedOnly: args.selectedOnly,
+                    download: args.download,
+                    filename: args.filename,
+                });
+                return executeOrGenerate(code, 'Exports map as GeoJSON', options, 'pinepaper_export_map_geojson');
+            }
+            case 'pinepaper_export_original_map_geojson': {
+                const code = codeGenerator.generateExportOriginalMapGeoJson({
+                    download: args.download,
+                    filename: args.filename,
+                });
+                return executeOrGenerate(code, 'Exports original map GeoJSON', options, 'pinepaper_export_original_map_geojson');
+            }
+            case 'pinepaper_get_map_source_info': {
+                const code = codeGenerator.generateGetMapSourceInfo();
+                return executeOrGenerate(code, 'Gets map source information', options, 'pinepaper_get_map_source_info');
+            }
+            case 'pinepaper_register_item': {
+                const code = codeGenerator.generateRegisterItem({
+                    itemJson: args.itemJson,
+                    itemType: args.itemType,
+                    properties: args.properties,
+                });
+                return executeOrGenerate(code, 'Registers Paper.js item', options, 'pinepaper_register_item');
+            }
+            // -----------------------------------------------------------------------
+            // TEMPLATE TOOLS
+            // -----------------------------------------------------------------------
+            case 'pinepaper_apply_template': {
+                const parsed = ApplyTemplateInputSchema.parse(args);
+                const code = codeGenerator.generateApplyTemplate(parsed);
+                return executeOrGenerate(code, 'Applies template', options, 'pinepaper_apply_template');
+            }
+            // -----------------------------------------------------------------------
+            // IMAGE IMPORT TOOLS
+            // -----------------------------------------------------------------------
+            case 'pinepaper_import_image': {
+                const parsed = ImportImageInputSchema.parse(args);
+                const code = codeGenerator.generateImportImage(parsed);
+                return executeOrGenerate(code, 'Imports image', options, 'pinepaper_import_image');
+            }
+            // -----------------------------------------------------------------------
             // UNKNOWN TOOL
             // -----------------------------------------------------------------------
             default: {
@@ -913,12 +1723,28 @@ Browser is ready. You can now use other pinepaper tools to create and animate gr
                         'pinepaper_add_relation',
                         'pinepaper_remove_relation',
                         'pinepaper_query_relations',
+                        'pinepaper_register_custom_relation',
+                        'pinepaper_execute_custom_code',
                         'pinepaper_animate',
                         'pinepaper_keyframe_animate',
                         'pinepaper_play_timeline',
                         'pinepaper_execute_generator',
                         'pinepaper_list_generators',
                         'pinepaper_apply_effect',
+                        'pinepaper_apply_animated_mask',
+                        'pinepaper_apply_custom_mask',
+                        'pinepaper_remove_mask',
+                        'pinepaper_get_animatable_properties',
+                        'pinepaper_get_available_easings',
+                        'pinepaper_get_mask_types',
+                        'pinepaper_get_mask_animations',
+                        'pinepaper_camera_animate',
+                        'pinepaper_camera_zoom',
+                        'pinepaper_camera_pan',
+                        'pinepaper_camera_move_to',
+                        'pinepaper_camera_reset',
+                        'pinepaper_camera_stop',
+                        'pinepaper_camera_state',
                         'pinepaper_get_items',
                         'pinepaper_get_relation_stats',
                         'pinepaper_set_background_color',
@@ -930,6 +1756,7 @@ Browser is ready. You can now use other pinepaper tools to create and animate gr
                         'pinepaper_add_filter',
                         'pinepaper_export_svg',
                         'pinepaper_export_training_data',
+                        'pinepaper_export_scene',
                         'pinepaper_browser_connect',
                         'pinepaper_browser_disconnect',
                         'pinepaper_browser_screenshot',
@@ -948,6 +1775,77 @@ Browser is ready. You can now use other pinepaper tools to create and animate gr
                         'pinepaper_update_connector',
                         'pinepaper_remove_connector',
                         'pinepaper_diagram_mode',
+                        // Scene tools
+                        'pinepaper_create_scene',
+                        // Agent flow mode tools
+                        'pinepaper_agent_start_job',
+                        'pinepaper_agent_end_job',
+                        'pinepaper_agent_reset',
+                        'pinepaper_agent_batch_execute',
+                        'pinepaper_agent_export',
+                        'pinepaper_agent_analyze',
+                        // Interactive trigger tools
+                        'pinepaper_add_trigger',
+                        'pinepaper_remove_trigger',
+                        'pinepaper_query_triggers',
+                        // Quiz/LMS tools
+                        'pinepaper_create_quiz',
+                        'pinepaper_get_quiz_state',
+                        'pinepaper_reset_quiz',
+                        // Letter collage tools
+                        'pinepaper_create_letter_collage',
+                        'pinepaper_animate_letter_collage',
+                        'pinepaper_get_letter_collage_options',
+                        // Canvas presets tools
+                        'pinepaper_get_canvas_presets',
+                        // Map tools
+                        'pinepaper_load_map',
+                        'pinepaper_highlight_regions',
+                        'pinepaper_unhighlight_regions',
+                        'pinepaper_apply_data_colors',
+                        'pinepaper_add_marker',
+                        'pinepaper_add_map_labels',
+                        'pinepaper_pan_map',
+                        'pinepaper_zoom_map',
+                        'pinepaper_export_map',
+                        'pinepaper_import_custom_map',
+                        'pinepaper_get_region_at_point',
+                        // Map animation/CSV tools
+                        'pinepaper_animate_map_regions',
+                        'pinepaper_animate_map_wave',
+                        'pinepaper_stop_map_animations',
+                        'pinepaper_get_animated_map_regions',
+                        'pinepaper_export_map_region_csv',
+                        'pinepaper_import_map_region_csv',
+                        'pinepaper_select_map_regions',
+                        'pinepaper_deselect_map_regions',
+                        'pinepaper_get_highlighted_map_regions',
+                        'pinepaper_export_map_geojson',
+                        'pinepaper_export_original_map_geojson',
+                        'pinepaper_get_map_source_info',
+                        // Font tools
+                        'pinepaper_font_show_studio',
+                        'pinepaper_font_set_name',
+                        'pinepaper_font_get_required_chars',
+                        'pinepaper_font_get_status',
+                        'pinepaper_font_create_glyph',
+                        'pinepaper_font_create_space',
+                        'pinepaper_font_remove_glyph',
+                        'pinepaper_font_set_metrics',
+                        'pinepaper_font_export',
+                        'pinepaper_font_load_into_document',
+                        'pinepaper_font_export_data',
+                        'pinepaper_font_import_data',
+                        'pinepaper_font_clear',
+                        'pinepaper_font_remove_overlap',
+                        'pinepaper_font_correct_direction',
+                        'pinepaper_font_cleanup_path',
+                        // Template tools
+                        'pinepaper_apply_template',
+                        // Image import tools
+                        'pinepaper_import_image',
+                        // Paper.js direct access tools
+                        'pinepaper_register_item',
                     ],
                 });
             }