@pinepaper.studio/mcp-server 1.5.1 → 1.5.4

package/dist/tools/handlers.js

@@ -6,7 +6,7 @@
  * Supports browser execution via Puppeteer.
  */
 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, DiagnosticReportInputSchema, SearchAssetsInputSchema, ImportAssetInputSchema, P5DrawInputSchema, 
+import { CreateItemInputSchema, ModifyItemInputSchema, DeleteItemInputSchema, AddRelationInputSchema, RemoveRelationInputSchema, QueryRelationsInputSchema, AnimateItemInputSchema, KeyframeAnimateInputSchema, ExecuteGeneratorInputSchema, ApplyEffectInputSchema, GetItemsInputSchema, PlayTimelineInputSchema, SetBackgroundColorInputSchema, SetCanvasSizeInputSchema, ImportSVGInputSchema, ImportMermaidInputSchema, AddFilterInputSchema, CreateGlossySphereInputSchema, CreateDiagonalStripesInputSchema, BatchCreateInputSchema, BatchModifyInputSchema, CreateGridInputSchema, CreateSceneInputSchema, GetPerformanceMetricsInputSchema, DiagnosticReportInputSchema, SearchAssetsInputSchema, ImportAssetInputSchema, P5DrawInputSchema, 
 // Diagram schemas
 CreateDiagramShapeInputSchema, ConnectInputSchema, ConnectPortsInputSchema, AddPortsInputSchema, AutoLayoutInputSchema, GetDiagramShapesInputSchema, UpdateConnectorInputSchema, RemoveConnectorInputSchema, DiagramModeInputSchema, 
 // Agent flow mode schemas
@@ -17,10 +17,6 @@ AddTriggerInputSchema, RemoveTriggerInputSchema, QueryTriggersInputSchema,
 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
@@ -29,16 +25,39 @@ ApplyAnimatedMaskInputSchema, ApplyCustomMaskInputSchema, RemoveMaskInputSchema,
 ApplyTemplateInputSchema, 
 // Image import schemas
 ImportImageInputSchema, 
-// Tool guide schema
-ToolGuideInputSchema, ErrorCodes, } from '../types/schemas.js';
+// Scene management schemas
+ManageScenesInputSchema, ScenePlaybackInputSchema, 
+// New consolidated tool schemas
+SelectionInputSchema, TransformInputSchema, HistoryInputSchema, ImageFilterInputSchema, LassoInputSchema, CutoutStyleInputSchema, PrecompInputSchema, ViewInputSchema, BackgroundInputSchema, QueryInputSchema, DeformInputSchema, SpriteSheetInputSchema, StorageInputSchema, InteractionInputSchema, ExportWidgetInputSchema, ExportWidgetHtmlInputSchema, CreateChartInputSchema, MagicInputSchema, PhysicsInputSchema, MeasurementInputSchema, 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 { getBrowserController, resetBrowserController, } from '../browser/puppeteer-controller.js';
+import { sameStudioTarget, validateStudioUrl } from '../browser/url-target.js';
 import { getPerformanceTracker } from '../metrics/index.js';
 import { formatErrorContext, captureCanvasState } from '../execution/index.js';
 import { getSessionManager } from '../agent/session-manager.js';
+import { vocabularyHintForPath, validateBatchVocabulary, detectBatchPropertyTypos } from '../ontology/hints.js';
+import { cameraHandlers } from './handlers/camera.js';
+import { fontHandlers } from './handlers/font.js';
+import { toolGuideHandlers } from './handlers/tool-guide.js';
+import { mapHandlers } from './handlers/maps.js';
+import { ontologyHandlers } from './handlers/ontology.js';
+import { exportHandlers } from './handlers/export.js';
+/**
+ * Registry of per-domain handler maps. Tools listed here short-circuit the
+ * main switch at dispatch time (see handleToolCallInner). New domains are
+ * folded in incrementally as they are migrated out of the monolithic switch.
+ */
+const DOMAIN_HANDLERS = [
+    cameraHandlers,
+    fontHandlers,
+    toolGuideHandlers,
+    mapHandlers,
+    ontologyHandlers,
+    exportHandlers,
+];
 /**
  * Get screenshot mode from environment variable.
  * Defaults to 'on_request' for optimal performance.
@@ -52,43 +71,6 @@ export function getScreenshotMode() {
     return 'on_request';
 }
 // =============================================================================
-// SMART DESIGN GUIDANCE — detect if user prompt has specific design direction
-// =============================================================================
-const COLOR_KEYWORDS = /(?:#[0-9a-f]{3,8}|rgb\(|hsl\(|\b(?:red|blue|green|purple|pink|gold|silver|orange|yellow|cyan|magenta|indigo|teal|coral|crimson|navy|maroon|turquoise|violet|amber|emerald|scarlet)\b)/i;
-const STYLE_KEYWORDS = /\b(?:gradient|bokeh|geometric|circuit|wave|sunset|sunrise|minimal|modern|retro|vintage|elegant|playful|abstract|organic|neon|pastel|watercolor|grunge|futuristic|cosmic|dreamy|glossy)\b/i;
-const LAYOUT_KEYWORDS = /\b(?:centered|left-aligned|right-aligned|grid|stacked|scattered|radial|circular|diagonal|symmetrical|horizontal|vertical)\b/i;
-const ANIMATION_KEYWORDS = /\b(?:orbit|follow|pulse|bounce|fade|rotate|wobble|slide|wipe|reveal|parallax|wave|morph|float|glow|sparkle|burst|spiral)\b/i;
-/**
- * Detect if a prompt has enough design specificity to skip guidance injection.
- * Returns true if the prompt is design-specific (skip guidance).
- * Returns false if vague (inject guidance).
- */
-function detectDesignSpecificity(prompt) {
-    if (!prompt || prompt.trim().length === 0)
-        return false;
-    let specificityScore = 0;
-    // Color mentions: strong signal of specificity
-    if (COLOR_KEYWORDS.test(prompt))
-        specificityScore += 2;
-    // Style/mood keywords
-    if (STYLE_KEYWORDS.test(prompt))
-        specificityScore += 2;
-    // Layout direction
-    if (LAYOUT_KEYWORDS.test(prompt))
-        specificityScore += 1;
-    // Animation specifics
-    if (ANIMATION_KEYWORDS.test(prompt))
-        specificityScore += 1;
-    // Word count: detailed prompts tend to be longer
-    const wordCount = prompt.trim().split(/\s+/).length;
-    if (wordCount >= 20)
-        specificityScore += 1;
-    if (wordCount >= 35)
-        specificityScore += 1;
-    // Threshold: 3+ = specific enough, skip guidance
-    return specificityScore >= 3;
-}
-// =============================================================================
 // EXPORT FILE SAVE HELPERS
 // =============================================================================
 function getExportDir() {
@@ -150,18 +132,13 @@ function successResult(code, description) {
     return { content };
 }
 function executedResult(code, result, screenshot, description) {
+    const resultObj = { success: true, result };
+    if (description)
+        resultObj.description = description;
     const content = [
-        {
-            type: 'text',
-            text: `Executed PinePaper code:\n\n\`\`\`javascript\n${code}\n\`\`\`\n\nResult: ${JSON.stringify(result, null, 2)}`,
-        },
+        { type: 'text', text: JSON.stringify(resultObj, null, 2) },
+        { type: 'text', text: `Generated code:\n\`\`\`javascript\n${code}\n\`\`\`` },
     ];
-    if (description) {
-        content.push({
-            type: 'text',
-            text: `\n${description}`,
-        });
-    }
     if (screenshot) {
         content.push({
             type: 'image',
@@ -182,7 +159,7 @@ function screenshotResult(screenshot) {
         ],
     };
 }
-function errorResult(code, message, details, context) {
+export function errorResult(code, message, details, context) {
     // Build error object
     const errorObj = {
         success: false,
@@ -209,10 +186,18 @@ function handleValidationError(error, i18n) {
     const message = i18n
         ? i18n.getError('validationError', { message: 'Invalid input parameters' })
         : 'Invalid input parameters';
-    return errorResult(ErrorCodes.VALIDATION_ERROR, message, error.errors.map((e) => ({
-        path: e.path.join('.'),
-        message: e.message,
-    })));
+    const details = error.errors.map((e) => {
+        const path = e.path.join('.');
+        const detail = { path, message: e.message };
+        if (e.code === 'invalid_enum_value') {
+            const received = e.received;
+            const hint = vocabularyHintForPath(path, received);
+            if (hint)
+                detail.vocabulary = hint;
+        }
+        return detail;
+    });
+    return errorResult(ErrorCodes.VALIDATION_ERROR, message, details);
 }
 /**
  * Execute code in browser if connected, otherwise return generated code.
@@ -228,7 +213,7 @@ function handleValidationError(error, i18n) {
  *
  * Default is 'on_request' for optimal performance per best practices.
  */
-async function executeOrGenerate(code, description, options, toolName) {
+export async function executeOrGenerate(code, description, options, toolName) {
     const { executeInBrowser, browserController, screenshotMode, executionMode } = options;
     const effectiveExecutionMode = executionMode ?? getExecutionMode();
     const effectiveScreenshotMode = screenshotMode ?? getScreenshotMode();
@@ -405,7 +390,7 @@ ${code}
 // =============================================================================
 // I18N HELPER FUNCTIONS
 // =============================================================================
-function getLocalizedSuccessMessage(i18n, key, params) {
+export function getLocalizedSuccessMessage(i18n, key, params) {
     if (!i18n) {
         // Fallback to English template
         return Object.entries(params).reduce((msg, [k, v]) => msg.replace(`{{${k}}}`, String(v)), key);
@@ -489,6 +474,14 @@ export async function handleToolCall(toolName, args, options = {}) {
 async function handleToolCallInner(toolName, args, options, tracker, baseTimerId) {
     const { i18n } = options;
     try {
+        // Domain-module dispatch: tools migrated to per-domain handler files
+        // short-circuit before the main switch. See DOMAIN_HANDLERS for the
+        // current registry.
+        for (const domainMap of DOMAIN_HANDLERS) {
+            const handler = domainMap[toolName];
+            if (handler)
+                return await handler(args, options);
+        }
         switch (toolName) {
             // -----------------------------------------------------------------------
             // ITEM TOOLS
@@ -529,7 +522,7 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
                 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. ` +
+                    return errorResult(ErrorCodes.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.`);
                 }
@@ -571,6 +564,134 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
                 const description = `Creates complete scene with ${itemCount} items, ${relationCount} relations, ${animationCount} animations`;
                 return executeOrGenerate(code, description, options, 'pinepaper_create_scene');
             }
+            case 'pinepaper_manage_scenes': {
+                const input = ManageScenesInputSchema.parse(args);
+                const code = codeGenerator.generateManageScenes(input);
+                return executeOrGenerate(code, `Scene: ${input.action}`, options, 'pinepaper_manage_scenes');
+            }
+            case 'pinepaper_scene_playback': {
+                const input = ScenePlaybackInputSchema.parse(args);
+                const code = codeGenerator.generateScenePlayback(input);
+                return executeOrGenerate(code, `Scene playback: ${input.action}`, options, 'pinepaper_scene_playback');
+            }
+            // -----------------------------------------------------------------------
+            // SELECTION, TRANSFORM & HISTORY TOOLS
+            // -----------------------------------------------------------------------
+            case 'pinepaper_selection': {
+                const input = SelectionInputSchema.parse(args);
+                const code = codeGenerator.generateSelection(input);
+                return executeOrGenerate(code, `Selection: ${input.action}`, options, 'pinepaper_selection');
+            }
+            case 'pinepaper_transform': {
+                const input = TransformInputSchema.parse(args);
+                const code = codeGenerator.generateTransform(input);
+                return executeOrGenerate(code, `Transform: ${input.action}`, options, 'pinepaper_transform');
+            }
+            case 'pinepaper_history': {
+                const input = HistoryInputSchema.parse(args);
+                const code = codeGenerator.generateHistory(input);
+                return executeOrGenerate(code, `History: ${input.action}`, options, 'pinepaper_history');
+            }
+            // -----------------------------------------------------------------------
+            // IMAGE PROCESSING TOOLS
+            // -----------------------------------------------------------------------
+            case 'pinepaper_image_filter': {
+                const input = ImageFilterInputSchema.parse(args);
+                const code = codeGenerator.generateImageFilter(input);
+                return executeOrGenerate(code, `Image filter: ${input.action}`, options, 'pinepaper_image_filter');
+            }
+            case 'pinepaper_lasso': {
+                const input = LassoInputSchema.parse(args);
+                const code = codeGenerator.generateLasso(input);
+                return executeOrGenerate(code, `Lasso: ${input.action}`, options, 'pinepaper_lasso');
+            }
+            case 'pinepaper_cutout_style': {
+                const input = CutoutStyleInputSchema.parse(args);
+                const code = codeGenerator.generateCutoutStyle(input);
+                return executeOrGenerate(code, `Cutout style: ${input.action}`, options, 'pinepaper_cutout_style');
+            }
+            // -----------------------------------------------------------------------
+            // COMPOSITION & VIEW TOOLS
+            // -----------------------------------------------------------------------
+            case 'pinepaper_precomp': {
+                const input = PrecompInputSchema.parse(args);
+                const code = codeGenerator.generatePrecomp(input);
+                return executeOrGenerate(code, `Precomp: ${input.action}`, options, 'pinepaper_precomp');
+            }
+            case 'pinepaper_view': {
+                const input = ViewInputSchema.parse(args);
+                const code = codeGenerator.generateView(input);
+                return executeOrGenerate(code, `View: ${input.action}`, options, 'pinepaper_view');
+            }
+            case 'pinepaper_background': {
+                const input = BackgroundInputSchema.parse(args);
+                const code = codeGenerator.generateBackground(input);
+                return executeOrGenerate(code, `Background: ${input.action}`, options, 'pinepaper_background');
+            }
+            // -----------------------------------------------------------------------
+            // CANVAS QUERY TOOLS
+            // -----------------------------------------------------------------------
+            case 'pinepaper_query': {
+                const input = QueryInputSchema.parse(args);
+                const code = codeGenerator.generateQuery(input);
+                return executeOrGenerate(code, `Query: ${input.action}`, options, 'pinepaper_query');
+            }
+            // -----------------------------------------------------------------------
+            // DEFORMATION, SPRITE SHEETS, STORAGE, INTERACTION
+            // -----------------------------------------------------------------------
+            case 'pinepaper_deform': {
+                const input = DeformInputSchema.parse(args);
+                const code = codeGenerator.generateDeform(input);
+                return executeOrGenerate(code, `Deform: ${input.action}`, options, 'pinepaper_deform');
+            }
+            case 'pinepaper_sprite_sheet': {
+                const input = SpriteSheetInputSchema.parse(args);
+                const code = codeGenerator.generateSpriteSheet(input);
+                return executeOrGenerate(code, `Sprite sheet: ${input.action}`, options, 'pinepaper_sprite_sheet');
+            }
+            case 'pinepaper_storage': {
+                const input = StorageInputSchema.parse(args);
+                const code = codeGenerator.generateStorage(input);
+                return executeOrGenerate(code, `Storage: ${input.action}`, options, 'pinepaper_storage');
+            }
+            case 'pinepaper_interaction': {
+                const input = InteractionInputSchema.parse(args);
+                const code = codeGenerator.generateInteraction(input);
+                return executeOrGenerate(code, `Interaction: ${input.action}`, options, 'pinepaper_interaction');
+            }
+            case 'pinepaper_export_widget': {
+                const input = ExportWidgetInputSchema.parse(args);
+                const code = codeGenerator.generateExportWidget(input);
+                return executeOrGenerate(code, 'Export widget JSON', options, 'pinepaper_export_widget');
+            }
+            case 'pinepaper_export_widget_html': {
+                const input = ExportWidgetHtmlInputSchema.parse(args);
+                const code = codeGenerator.generateExportWidgetHtml(input);
+                return executeOrGenerate(code, 'Export widget HTML', options, 'pinepaper_export_widget_html');
+            }
+            // -----------------------------------------------------------------------
+            // DATA VISUALIZATION, MAGIC, PHYSICS, MEASUREMENT
+            // -----------------------------------------------------------------------
+            case 'pinepaper_create_chart': {
+                const input = CreateChartInputSchema.parse(args);
+                const code = codeGenerator.generateChart(input);
+                return executeOrGenerate(code, `Chart: ${input.action}`, options, 'pinepaper_create_chart');
+            }
+            case 'pinepaper_magic': {
+                const input = MagicInputSchema.parse(args);
+                const code = codeGenerator.generateMagic(input);
+                return executeOrGenerate(code, `Magic: ${input.action}`, options, 'pinepaper_magic');
+            }
+            case 'pinepaper_physics': {
+                const input = PhysicsInputSchema.parse(args);
+                const code = codeGenerator.generatePhysics(input);
+                return executeOrGenerate(code, `Physics: ${input.action}`, options, 'pinepaper_physics');
+            }
+            case 'pinepaper_measurement': {
+                const input = MeasurementInputSchema.parse(args);
+                const code = codeGenerator.generateMeasurement(input);
+                return executeOrGenerate(code, `Measurement: ${input.action}`, options, 'pinepaper_measurement');
+            }
             // -----------------------------------------------------------------------
             // BATCH OPERATION TOOLS
             // -----------------------------------------------------------------------
@@ -714,168 +835,11 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
                 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');
-            }
+            // CAMERA TOOLS — extracted to src/tools/handlers/camera.ts
+            // -----------------------------------------------------------------------
+            // -----------------------------------------------------------------------
+            // FONT TOOLS — extracted to src/tools/handlers/font.ts
+            // -----------------------------------------------------------------------
             // -----------------------------------------------------------------------
             // QUERY TOOLS
             // -----------------------------------------------------------------------
@@ -920,7 +884,7 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
             case 'pinepaper_refresh_page': {
                 const controller = options.browserController || getBrowserController();
                 if (!controller.connected) {
-                    return errorResult('BROWSER_NOT_CONNECTED', 'Not connected to PinePaper Studio. Call pinepaper_browser_connect first.');
+                    return errorResult(ErrorCodes.BROWSER_NOT_CONNECTED, 'Not connected to PinePaper Studio. Call pinepaper_browser_connect first.');
                 }
                 try {
                     // Refresh the page
@@ -949,7 +913,7 @@ You can now start creating new items on a clean canvas.`,
                     return { content };
                 }
                 catch (error) {
-                    return errorResult('REFRESH_FAILED', error instanceof Error ? error.message : 'Failed to refresh page');
+                    return errorResult(ErrorCodes.REFRESH_FAILED, error instanceof Error ? error.message : 'Failed to refresh page');
                 }
             }
             // -----------------------------------------------------------------------
@@ -961,6 +925,15 @@ You can now start creating new items on a clean canvas.`,
                 const description = 'Imports SVG onto the canvas';
                 return executeOrGenerate(code, description, options, 'pinepaper_import_svg');
             }
+            case 'pinepaper_import_mermaid': {
+                const input = ImportMermaidInputSchema.parse(args);
+                const code = codeGenerator.generateImportMermaid(input.mermaidText, {
+                    autoLayout: input.autoLayout,
+                    clearExisting: input.clearExisting,
+                });
+                const description = 'Imports a Mermaid diagram onto the canvas';
+                return executeOrGenerate(code, description, options, 'pinepaper_import_mermaid');
+            }
             // -----------------------------------------------------------------------
             // FILTER TOOLS
             // -----------------------------------------------------------------------
@@ -971,111 +944,57 @@ You can now start creating new items on a clean canvas.`,
                 return executeOrGenerate(code, description, options, 'pinepaper_add_filter');
             }
             // -----------------------------------------------------------------------
-            // EXPORT TOOLS
+            // EXPORT TOOLS — extracted to src/tools/handlers/export.ts
             // -----------------------------------------------------------------------
-            case 'pinepaper_export_svg': {
-                const code = codeGenerator.generateExportSVG();
-                const description = getLocalizedSuccessMessage(i18n, 'exported', {
-                    format: 'SVG',
-                });
-                return executeOrGenerate(code, description, options, 'pinepaper_export_svg');
-            }
-            case 'pinepaper_export_training_data': {
-                const input = ExportTrainingDataInputSchema.parse(args);
-                const code = codeGenerator.generateExportTrainingData(input.format, input.includeMetadata);
-                const description = getLocalizedSuccessMessage(i18n, 'exported', {
-                    format: input.format?.toUpperCase() || 'JSON',
-                });
-                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';
-                // Default to headless: true for enforced agent mode
-                const headless = args.headless ?? true;
-                const controller = getBrowserController({ studioUrl: url, headless });
-                if (controller.connected) {
+                // Default to headless: false — if you explicitly call browser_connect, you likely want to see it
+                const headless = args.headless ?? false;
+                // Target a custom Studio instance (e.g. local dev at http://localhost:3000).
+                // Falls back to the PINEPAPER_STUDIO_URL env var, else PuppeteerController's
+                // built-in prod default. "/editor" + agent params are appended by the controller.
+                const rawUrl = typeof args.url === 'string' ? args.url.trim() : '';
+                const studioUrl = (rawUrl || (process.env.PINEPAPER_STUDIO_URL || '').trim()) || undefined;
+                // Only http(s) is supported — reject file://, data://, javascript:, etc.
+                if (studioUrl) {
+                    const v = validateStudioUrl(studioUrl);
+                    if (!v.ok)
+                        return errorResult(ErrorCodes.INVALID_INPUT, v.error);
+                }
+                const cfg = studioUrl ? { headless, studioUrl } : { headless };
+                const controller = getBrowserController(cfg);
+                const urlChanged = !!studioUrl && controller.connected &&
+                    !sameStudioTarget(controller.studioUrl, studioUrl);
+                // Already connected, same headless mode, same URL → nothing to do
+                if (controller.connected && controller.isHeadless === headless && !urlChanged) {
                     return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: `Already connected to PinePaper Studio at ${controller.actualUrl}. Do NOT call this tool again — proceed directly with pinepaper_agent_start_job.`,
-                            },
-                        ],
+                        content: [{ type: 'text', text: `Already connected to PinePaper Studio (${controller.studioUrl || 'default'}, headless: ${headless}).` }],
                     };
                 }
+                // Connected but headless mode OR target URL changed → tear down so the
+                // new config takes effect (getBrowserController ignores config once the
+                // singleton exists).
+                if (controller.connected && (controller.isHeadless !== headless || urlChanged)) {
+                    await resetBrowserController();
+                }
                 try {
-                    await controller.connect();
-                    // Get canvas size info to help agent understand the workspace
-                    const canvasSizeResult = await controller.executeCode(`const size = app.getCanvasSize ? app.getCanvasSize() : { width: 800, height: 600 }; ({ width: size.width || 800, height: size.height || 600 });`, false);
+                    const newController = controller.connected ? controller : getBrowserController(cfg);
+                    if (!newController.connected)
+                        await newController.connect();
+                    const canvasSizeResult = await newController.executeCode(`const size = app.getCanvasSize ? app.getCanvasSize() : { width: 800, height: 600 }; ({ width: size.width || 800, height: size.height || 600 });`, false);
                     const canvasSize = canvasSizeResult.success
                         ? canvasSizeResult.result
                         : { width: 800, height: 600 };
-                    const screenshot = await controller.takeScreenshot();
-                    const content = [
-                        {
-                            type: 'text',
-                            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:
-1. **Welcome Template**: First-time visitors see a welcome template with example items. Use \`pinepaper_clear_canvas\` or \`pinepaper_refresh_page\` to start with an empty canvas.
-2. **Canvas Size**: For complex designs (cards, invitations, detailed graphics), call \`pinepaper_set_canvas_size\` FIRST to set an appropriate size like 1080x1080 or larger. The default 800x600 may be too small.
-3. **Verify with Screenshots**: After making changes, use \`pinepaper_browser_screenshot\` to confirm your work.
-
-Browser is ready. You can now use other pinepaper tools to create and animate graphics.`,
-                        },
-                    ];
-                    if (screenshot) {
-                        content.push({
-                            type: 'image',
-                            data: screenshot,
-                            mimeType: 'image/png',
-                        });
-                    }
-                    return { content };
+                    return {
+                        content: [{ type: 'text', text: `Connected to PinePaper Studio (${newController.studioUrl || 'default'}, headless: ${headless}, canvas: ${canvasSize.width}x${canvasSize.height}).` }],
+                    };
                 }
                 catch (error) {
-                    const errorMessage = error instanceof Error ? error.message : 'Failed to connect to browser';
-                    // Provide helpful fallback instructions instead of just failing
+                    const errorMessage = error instanceof Error ? error.message : 'Failed to connect';
                     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.`,
-                            },
-                        ],
+                        content: [{ type: 'text', text: `Browser connection failed: ${errorMessage}` }],
                     };
                 }
             }
@@ -1104,13 +1023,13 @@ All PinePaper tools will work in **code-only mode**:
             case 'pinepaper_browser_screenshot': {
                 const controller = getBrowserController();
                 if (!controller.connected) {
-                    return errorResult('BROWSER_NOT_CONNECTED', 'Not connected to PinePaper Studio. Call pinepaper_browser_connect first.');
+                    return errorResult(ErrorCodes.BROWSER_NOT_CONNECTED, 'Not connected to PinePaper Studio. Call pinepaper_browser_connect first.');
                 }
                 const screenshot = await controller.takeScreenshot();
                 if (!screenshot) {
                     // Capture canvas state for debugging
                     const canvasState = await captureCanvasState(controller);
-                    return errorResult('SCREENSHOT_FAILED', 'Failed to capture screenshot', undefined, {
+                    return errorResult(ErrorCodes.SCREENSHOT_FAILED, 'Failed to capture screenshot', undefined, {
                         toolName: 'pinepaper_browser_screenshot',
                         canvasState: canvasState || undefined,
                     });
@@ -1397,54 +1316,8 @@ All PinePaper tools will work in **code-only mode**:
                 };
             }
             // -----------------------------------------------------------------------
-            // TOOL GUIDE (on-demand documentation)
+            // TOOL GUIDE — extracted to src/tools/handlers/tool-guide.ts
             // -----------------------------------------------------------------------
-            case 'pinepaper_tool_guide': {
-                const input = ToolGuideInputSchema.parse(args);
-                const { PINEPAPER_TOOLS, AI_AGENT_GUIDE } = await import('./definitions.js');
-                const { TOOL_TAGS } = await import('./toolkits.js');
-                // No args → full AI Agent Guide
-                if (!input.tool && !input.category) {
-                    return {
-                        content: [{ type: 'text', text: AI_AGENT_GUIDE }],
-                    };
-                }
-                // Specific tool → full verbose description
-                if (input.tool) {
-                    const tool = PINEPAPER_TOOLS.find((t) => t.name === input.tool);
-                    if (!tool) {
-                        return {
-                            content: [{ type: 'text', text: `Unknown tool: ${input.tool}. Use pinepaper_tool_guide with no args to see the AI Agent Guide.` }],
-                            isError: true,
-                        };
-                    }
-                    return {
-                        content: [{ type: 'text', text: `# ${tool.name}\n\n${tool.description}` }],
-                    };
-                }
-                // Category → all tools in that tag with descriptions
-                if (input.category) {
-                    const toolNames = TOOL_TAGS[input.category];
-                    if (!toolNames) {
-                        const available = Object.keys(TOOL_TAGS).join(', ');
-                        return {
-                            content: [{ type: 'text', text: `Unknown category: ${input.category}. Available: ${available}` }],
-                            isError: true,
-                        };
-                    }
-                    const lines = [`# Category: ${input.category}\n`];
-                    for (const name of toolNames) {
-                        const tool = PINEPAPER_TOOLS.find((t) => t.name === name);
-                        if (tool) {
-                            lines.push(`## ${tool.name}\n${tool.description}\n`);
-                        }
-                    }
-                    return {
-                        content: [{ type: 'text', text: lines.join('\n') }],
-                    };
-                }
-                return { content: [{ type: 'text', text: AI_AGENT_GUIDE }] };
-            }
             // -----------------------------------------------------------------------
             // ASSET TOOLS
             // -----------------------------------------------------------------------
@@ -1660,33 +1533,9 @@ All PinePaper tools will work in **code-only mode**:
                 const code = codeGenerator.generateAgentStartJob(input);
                 const descriptionText = `Started agent job${input.name ? ` "${input.name}"` : ''} with ${input.screenshotPolicy || 'on_complete'} screenshot policy`;
                 const result = await executeOrGenerate(code, descriptionText, options, 'pinepaper_agent_start_job');
-                // --- Smart design guidance injection ---
+                // Append a 1-line workflow hint
                 if (result.content && result.content.length > 0 && result.content[0].type === 'text') {
-                    const prompt = (input.description || input.name || '').toLowerCase();
-                    const isDesignSpecific = detectDesignSpecificity(prompt);
-                    // Always include workflow hint
-                    let guidance = `\n\nNEXT: Call pinepaper_agent_batch_execute with ALL operations in one call:` +
-                        `\n  1. set_canvas_size / set_background / execute_generator (canvas setup)` +
-                        `\n  2. create (items — text, shapes, etc.)` +
-                        `\n  3. animate / keyframe_animate / relation (REQUIRED for animation — add for EACH item)` +
-                        `\n  4. play_timeline (REQUIRED — starts playback)` +
-                        `\nThen: pinepaper_agent_end_job (returns screenshot for validation)`;
-                    // Inject design inspiration when the prompt is vague
-                    if (!isDesignSpecific) {
-                        guidance += `\n\n─── DESIGN INSPIRATION (your prompt is open-ended — use these for creative direction) ───` +
-                            `\nBACKGROUND: Use execute_generator for rich visuals:` +
-                            `\n  Dreamy/soft: drawBokeh, drawGradientMesh, drawOrganicFlow` +
-                            `\n  Energetic: drawSunburst, drawSunsetScene, drawGeometricAbstract` +
-                            `\n  Tech/modern: drawCircuit, drawGrid, drawWindField` +
-                            `\n  Calm/organic: drawWaves, drawFluidFlow, drawNoiseTexture` +
-                            `\nCOLORS: dark bg (#0f172a, #1a1a2e) + bright accents (#f472b6 pink, #818cf8 purple, #fbbf24 gold, #34d399 green)` +
-                            `\nCOMPOSITION: generator bg → large decorative shapes (low opacity 0.3-0.5) → main text → small accents on top` +
-                            `\nANIMATION: Use "relation" ops for dynamic motion:` +
-                            `\n  orbits (items circle around center), follows (items trail each other), wave_through (ripple effect)` +
-                            `\n  Plus: keyframe_animate for timed reveals (fade in, scale up), animate for loops (pulse, rotate, bounce)` +
-                            `\n5s TIMING: bg 0s → shapes fade-in 0.5-1.5s → main text 2-3s → accents 3-4s → play_timeline`;
-                    }
-                    result.content[0].text += guidance;
+                    result.content[0].text += `\n\nNEXT: Call batch_execute with all operations, then end_job.`;
                 }
                 return result;
             }
@@ -1752,6 +1601,37 @@ All PinePaper tools will work in **code-only mode**:
             }
             case 'pinepaper_agent_batch_execute': {
                 const input = AgentBatchExecuteInputSchema.parse(args);
+                // Ontology preflight — catch typos in itemType/relationType/
+                // effectType/generatorName before generating JS, so the LLM gets a
+                // structured hint instead of a silent failure inside the browser.
+                // Opt-out via skipValidation: true when the caller knows what they're
+                // doing (e.g. experimental vocabulary).
+                if (!input.skipValidation) {
+                    const ops = input.operations;
+                    const violations = validateBatchVocabulary(ops);
+                    if (violations.length > 0) {
+                        return errorResult(ErrorCodes.VALIDATION_ERROR, `Batch preflight rejected ${violations.length} operation${violations.length > 1 ? 's' : ''} with unknown vocabulary value${violations.length > 1 ? 's' : ''}. Fix the offending fields and retry, or pass skipValidation: true to bypass.`, violations.map((v) => ({
+                            path: `operations[${v.opIndex}].${v.field}`,
+                            opType: v.opType,
+                            vocabulary: v.hint,
+                        })));
+                    }
+                    // Property-key typo detection — narrow scope (Levenshtein ≤2) so
+                    // legitimate extras like `gradient` pass through. Catches the
+                    // common typo class (radiues vs radius, fontSiz vs fontSize)
+                    // before browser execution silently drops them.
+                    const typos = detectBatchPropertyTypos(ops);
+                    if (typos.length > 0) {
+                        return errorResult(ErrorCodes.VALIDATION_ERROR, `Batch preflight detected ${typos.length} likely property-key typo${typos.length > 1 ? 's' : ''}. Each suggestion is a Levenshtein-≤2 match against the schema for that itemType — fix and retry, or pass skipValidation: true to bypass.`, typos.map((t) => ({
+                            path: `operations[${t.opIndex}].properties.${t.property}`,
+                            opType: t.opType,
+                            itemType: t.itemType,
+                            received: t.property,
+                            suggestion: t.suggestion,
+                            validKeys: t.validKeys,
+                        })));
+                    }
+                }
                 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
@@ -1926,140 +1806,9 @@ All PinePaper tools will work in **code-only mode**:
             // -----------------------------------------------------------------------
             // 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');
-            }
+            // -----------------------------------------------------------------------
+            // MAP TOOLS — extracted to src/tools/handlers/maps.ts
+            // -----------------------------------------------------------------------
             case 'pinepaper_register_item': {
                 const code = codeGenerator.generateRegisterItem({
                     itemJson: args.itemJson,
@@ -2085,13 +1834,16 @@ All PinePaper tools will work in **code-only mode**:
                 return executeOrGenerate(code, 'Imports image', options, 'pinepaper_import_image');
             }
             // -----------------------------------------------------------------------
+            // ONTOLOGY TOOLS — extracted to src/tools/handlers/ontology.ts
+            // -----------------------------------------------------------------------
+            // -----------------------------------------------------------------------
             // UNKNOWN TOOL
             // -----------------------------------------------------------------------
             default: {
                 const message = i18n
                     ? i18n.getError('unknownTool', { toolName })
                     : `Unknown tool: ${toolName}`;
-                return errorResult('UNKNOWN_TOOL', message, {
+                return errorResult(ErrorCodes.UNKNOWN_TOOL, message, {
                     availableTools: [
                         'pinepaper_create_item',
                         'pinepaper_modify_item',
@@ -2120,12 +1872,7 @@ All PinePaper tools will work in **code-only mode**:
                         '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_camera',
                         'pinepaper_get_items',
                         'pinepaper_get_relation_stats',
                         'pinepaper_set_background_color',
@@ -2134,6 +1881,7 @@ All PinePaper tools will work in **code-only mode**:
                         'pinepaper_clear_canvas',
                         'pinepaper_refresh_page',
                         'pinepaper_import_svg',
+                        'pinepaper_import_mermaid',
                         'pinepaper_add_filter',
                         'pinepaper_export_svg',
                         'pinepaper_export_training_data',
@@ -2159,6 +1907,8 @@ All PinePaper tools will work in **code-only mode**:
                         'pinepaper_diagram_mode',
                         // Scene tools
                         'pinepaper_create_scene',
+                        'pinepaper_manage_scenes',
+                        'pinepaper_scene_playback',
                         // Agent flow mode tools
                         'pinepaper_agent_start_job',
                         'pinepaper_agent_end_job',
@@ -2180,48 +1930,13 @@ All PinePaper tools will work in **code-only mode**:
                         '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',
+                        // Map tools (4 action-dispatched)
+                        'pinepaper_map',
+                        'pinepaper_map_regions',
+                        'pinepaper_map_animation',
+                        'pinepaper_map_data',
                         // 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',
+                        'pinepaper_font',
                         // Template tools
                         'pinepaper_apply_template',
                         // Image import tools
@@ -2231,6 +1946,38 @@ All PinePaper tools will work in **code-only mode**:
                         // On-demand guide & runtime config
                         'pinepaper_tool_guide',
                         'pinepaper_set_toolkit',
+                        // Ontology tools
+                        'pinepaper_get_canvas_ontology',
+                        'pinepaper_analyze_design',
+                        'pinepaper_validate_design',
+                        'pinepaper_query_ontology',
+                        // Selection, transform & history tools
+                        'pinepaper_selection',
+                        'pinepaper_transform',
+                        'pinepaper_history',
+                        // Image processing tools
+                        'pinepaper_image_filter',
+                        'pinepaper_lasso',
+                        'pinepaper_cutout_style',
+                        // Composition & view tools
+                        'pinepaper_precomp',
+                        'pinepaper_view',
+                        'pinepaper_background',
+                        // Canvas query tools
+                        'pinepaper_query',
+                        // Deformation, sprite sheets, storage, interaction
+                        'pinepaper_deform',
+                        'pinepaper_sprite_sheet',
+                        'pinepaper_storage',
+                        'pinepaper_interaction',
+                        // Widget export
+                        'pinepaper_export_widget',
+                        'pinepaper_export_widget_html',
+                        // Data visualization, magic, physics, measurement
+                        'pinepaper_create_chart',
+                        'pinepaper_magic',
+                        'pinepaper_physics',
+                        'pinepaper_measurement',
                     ],
                 });
             }