@pinepaper.studio/mcp-server 1.5.3 → 1.5.5

package/dist/tools/handlers.js

@@ -6,45 +6,52 @@
  * 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
 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, 
+CreateLetterCollageInputSchema, AnimateLetterCollageInputSchema, ApplyTemplateInputSchema, 
 // Custom relation/code schemas
 RegisterCustomRelationInputSchema, ExecuteCustomCodeInputSchema, 
 // Mask schemas
 ApplyAnimatedMaskInputSchema, ApplyCustomMaskInputSchema, RemoveMaskInputSchema, 
-// Template schemas
-ApplyTemplateInputSchema, 
 // Image import schemas
 ImportImageInputSchema, 
-// Tool guide schema
-ToolGuideInputSchema, 
-// Ontology schemas
-AnalyzeDesignInputSchema, ValidateDesignInputSchema, QueryOntologyInputSchema, 
 // Scene management schemas
 ManageScenesInputSchema, ScenePlaybackInputSchema, 
 // New consolidated tool schemas
-SelectionInputSchema, TransformInputSchema, HistoryInputSchema, ImageFilterInputSchema, LassoInputSchema, CutoutStyleInputSchema, PrecompInputSchema, ViewInputSchema, BackgroundInputSchema, QueryInputSchema, ErrorCodes, } from '../types/schemas.js';
+SelectionInputSchema, TransformInputSchema, HistoryInputSchema, ImageFilterInputSchema, LassoInputSchema, CutoutStyleInputSchema, PrecompInputSchema, BackgroundInputSchema, QueryInputSchema, DeformInputSchema, SpriteSheetInputSchema, 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, 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.
@@ -146,7 +153,7 @@ function screenshotResult(screenshot) {
         ],
     };
 }
-function errorResult(code, message, details, context) {
+export function errorResult(code, message, details, context) {
     // Build error object
     const errorObj = {
         success: false,
@@ -173,10 +180,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.
@@ -192,7 +207,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();
@@ -369,7 +384,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);
@@ -453,6 +468,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
@@ -493,7 +516,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.`);
                 }
@@ -589,11 +612,6 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
                 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);
@@ -608,6 +626,57 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
                 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_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
             // -----------------------------------------------------------------------
             case 'pinepaper_batch_create': {
@@ -750,168 +819,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
             // -----------------------------------------------------------------------
@@ -956,7 +868,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
@@ -985,7 +897,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');
                 }
             }
             // -----------------------------------------------------------------------
@@ -997,6 +909,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
             // -----------------------------------------------------------------------
@@ -1007,46 +928,53 @@ 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': {
                 // Default to headless: false — if you explicitly call browser_connect, you likely want to see it
                 const headless = args.headless ?? false;
-                const controller = getBrowserController({ headless });
-                // Already connected with same headless mode → nothing to do
-                if (controller.connected && controller.isHeadless === headless) {
+                // 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 };
+                let controller = getBrowserController(cfg);
+                // NOT gated on controller.connected. getBrowserController() ignores cfg
+                // once the singleton exists, AND the singleton survives disconnect()
+                // (pinepaper_browser_disconnect doesn't null it) carrying its old
+                // studioUrl. So a stale/disconnected controller pointing at the prod
+                // default — which any prior browser_status() or connect() creates —
+                // would otherwise silently swallow an explicit url= (e.g. localhost for
+                // a dev build). Treat a different requested target as a change even when
+                // not currently connected.
+                const urlChanged = !!studioUrl &&
+                    !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 (headless: ${headless}).` }],
+                        content: [{ type: 'text', text: `Already connected to PinePaper Studio (${controller.studioUrl || 'default'}, headless: ${headless}).` }],
                     };
                 }
-                // Already connected but different headless mode → reconnect
-                if (controller.connected && controller.isHeadless !== headless) {
+                // Headless mode or target URL differs from the existing singleton → tear
+                // it down so the new config takes effect. Runs even when disconnected,
+                // because getBrowserController() reuses the stale singleton (and its old
+                // config) on the next call otherwise.
+                if (urlChanged || (controller.connected && controller.isHeadless !== headless)) {
                     await resetBrowserController();
+                    controller = getBrowserController(cfg);
                 }
                 try {
-                    const newController = controller.connected ? controller : getBrowserController({ headless });
+                    const newController = controller;
                     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);
@@ -1054,7 +982,7 @@ You can now start creating new items on a clean canvas.`,
                         ? canvasSizeResult.result
                         : { width: 800, height: 600 };
                     return {
-                        content: [{ type: 'text', text: `Connected to PinePaper Studio (headless: ${headless}, canvas: ${canvasSize.width}x${canvasSize.height}).` }],
+                        content: [{ type: 'text', text: `Connected to PinePaper Studio (${newController.studioUrl || 'default'}, headless: ${headless}, canvas: ${canvasSize.width}x${canvasSize.height}).` }],
                     };
                 }
                 catch (error) {
@@ -1089,13 +1017,13 @@ You can now start creating new items on a clean canvas.`,
             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,
                     });
@@ -1160,8 +1088,9 @@ You can now start creating new items on a clean canvas.`,
                 const metricsLimit = input.metricsLimit ?? 100;
                 // --- Server info ---
                 const { detectToolkitFromEnvironment: detectToolkit, detectVerbosityFromEnvironment: detectVerbosity } = await import('./toolkits.js');
+                const { SERVER_VERSION } = await import('../version.js');
                 const serverSection = {
-                    version: '1.5.1',
+                    version: SERVER_VERSION,
                     toolkit: detectToolkit(),
                     verbosity: detectVerbosity(),
                     locale: process.env.PINEPAPER_LOCALE || 'en',
@@ -1382,54 +1311,8 @@ You can now start creating new items on a clean canvas.`,
                 };
             }
             // -----------------------------------------------------------------------
-            // 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
             // -----------------------------------------------------------------------
@@ -1713,6 +1596,37 @@ You can now start creating new items on a clean canvas.`,
             }
             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
@@ -1809,56 +1723,6 @@ You can now start creating new items on a clean canvas.`,
                 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': {
@@ -1873,154 +1737,9 @@ You can now start creating new items on a clean canvas.`,
                 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');
-            }
+            // -----------------------------------------------------------------------
+            // MAP TOOLS — extracted to src/tools/handlers/maps.ts
+            // -----------------------------------------------------------------------
             case 'pinepaper_register_item': {
                 const code = codeGenerator.generateRegisterItem({
                     itemJson: args.itemJson,
@@ -2030,7 +1749,7 @@ You can now start creating new items on a clean canvas.`,
                 return executeOrGenerate(code, 'Registers Paper.js item', options, 'pinepaper_register_item');
             }
             // -----------------------------------------------------------------------
-            // TEMPLATE TOOLS
+            // TEMPLATE TOOL
             // -----------------------------------------------------------------------
             case 'pinepaper_apply_template': {
                 const parsed = ApplyTemplateInputSchema.parse(args);
@@ -2046,169 +1765,8 @@ You can now start creating new items on a clean canvas.`,
                 return executeOrGenerate(code, 'Imports image', options, 'pinepaper_import_image');
             }
             // -----------------------------------------------------------------------
-            // ONTOLOGY TOOLS
+            // ONTOLOGY TOOLS — extracted to src/tools/handlers/ontology.ts
             // -----------------------------------------------------------------------
-            case 'pinepaper_analyze_design': {
-                const input = AnalyzeDesignInputSchema.parse(args);
-                const { DesignGraph } = await import('../ontology/index.js');
-                const dg = new DesignGraph();
-                const graph = dg.extractFromDefinition(input.definition);
-                const jsonLd = dg.toJsonLd(graph);
-                return {
-                    content: [{
-                            type: 'text',
-                            text: JSON.stringify({
-                                templateId: graph.templateId,
-                                templateName: graph.templateName,
-                                category: graph.category,
-                                dimensions: graph.dimensions,
-                                duration: graph.duration,
-                                nodeCount: graph.nodes.length,
-                                edgeCount: graph.edges.length,
-                                nodeTypes: Object.fromEntries(Object.entries(graph.fingerprint?.nodeTypeCounts || {}).sort((a, b) => b[1] - a[1])),
-                                edgeTypes: Object.fromEntries(Object.entries(graph.fingerprint?.edgeTypeCounts || {}).sort((a, b) => b[1] - a[1])),
-                                patterns: graph.patterns,
-                                mathFunctions: graph.mathFunctions,
-                                generator: graph.generator,
-                                semantics: graph.semantics,
-                                fingerprint: graph.fingerprint,
-                                jsonLd,
-                            }, null, 2),
-                        }],
-                };
-            }
-            case 'pinepaper_validate_design': {
-                const input = ValidateDesignInputSchema.parse(args);
-                const { DesignGraph, KnowledgeGraphValidator } = await import('../ontology/index.js');
-                const dg = new DesignGraph();
-                const validator = new KnowledgeGraphValidator();
-                const definition = input.definition;
-                const validation = validator.validateTemplate(definition);
-                let quality = null;
-                if (validation.valid) {
-                    const graph = dg.extractFromDefinition(definition);
-                    quality = validator.scoreQuality(definition, graph);
-                }
-                return {
-                    content: [{
-                            type: 'text',
-                            text: JSON.stringify({
-                                validation,
-                                quality,
-                            }, null, 2),
-                        }],
-                };
-            }
-            // -----------------------------------------------------------------------
-            // ONTOLOGY QUERY (read-only graph navigation)
-            // -----------------------------------------------------------------------
-            case 'pinepaper_query_ontology': {
-                const input = QueryOntologyInputSchema.parse(args);
-                const { PP_VOCABULARY, ITEM_TYPE_MAP, RELATION_TYPE_MAP } = await import('../ontology/vocabulary.js');
-                const { DesignGraph } = await import('../ontology/design-graph.js');
-                const dg = new DesignGraph();
-                let result;
-                switch (input.query) {
-                    case 'list_types': {
-                        const entries = Object.entries(PP_VOCABULARY.types);
-                        const filtered = entries.filter(([key, def]) => {
-                            if (input.category && def.category !== input.category)
-                                return false;
-                            if (!input.includeAbstract && def.abstract)
-                                return false;
-                            return true;
-                        });
-                        result = Object.fromEntries(filtered);
-                        break;
-                    }
-                    case 'list_edges': {
-                        const entries = Object.entries(PP_VOCABULARY.edges);
-                        const filtered = input.category
-                            ? entries.filter(([, def]) => def.category === input.category)
-                            : entries;
-                        result = Object.fromEntries(filtered);
-                        break;
-                    }
-                    case 'list_generators': {
-                        const entries = Object.entries(PP_VOCABULARY.generators);
-                        const filtered = input.category
-                            ? entries.filter(([, def]) => def.category === input.category)
-                            : entries;
-                        result = Object.fromEntries(filtered);
-                        break;
-                    }
-                    case 'list_effects': {
-                        result = ['sparkle', 'blast', 'smoke', 'fire', 'rain', 'snow', 'confetti', 'ripple', 'glow', 'electric'];
-                        break;
-                    }
-                    case 'list_patterns': {
-                        result = PP_VOCABULARY.patterns;
-                        break;
-                    }
-                    case 'list_math_functions': {
-                        result = PP_VOCABULARY.mathFunctions;
-                        break;
-                    }
-                    case 'type_hierarchy': {
-                        if (!input.ppType)
-                            return errorResult('INVALID_INPUT', 'ppType is required for type_hierarchy');
-                        result = dg.getTypeHierarchy(input.ppType);
-                        break;
-                    }
-                    case 'type_children': {
-                        if (!input.ppType)
-                            return errorResult('INVALID_INPUT', 'ppType is required for type_children');
-                        result = dg.getTypeChildren(input.ppType);
-                        break;
-                    }
-                    case 'type_properties': {
-                        if (!input.ppType)
-                            return errorResult('INVALID_INPUT', 'ppType is required for type_properties');
-                        result = dg.getPropertiesFor(input.ppType);
-                        break;
-                    }
-                    case 'animatable_properties': {
-                        if (!input.ppType)
-                            return errorResult('INVALID_INPUT', 'ppType is required for animatable_properties');
-                        result = dg.getAnimatableProperties(input.ppType);
-                        break;
-                    }
-                    case 'is_subtype': {
-                        if (!input.typeA || !input.typeB)
-                            return errorResult('INVALID_INPUT', 'typeA and typeB are required for is_subtype');
-                        result = { isSubtype: dg.isSubtypeOf(input.typeA, input.typeB) };
-                        break;
-                    }
-                    case 'edge_info': {
-                        const edgeName = input.relationName || input.ppType;
-                        if (!edgeName)
-                            return errorResult('INVALID_INPUT', 'relationName or ppType is required for edge_info');
-                        const ppEdge = PP_VOCABULARY.edges[edgeName] || PP_VOCABULARY.edges[RELATION_TYPE_MAP[edgeName] || ''];
-                        result = ppEdge || { error: `Unknown edge: ${edgeName}` };
-                        break;
-                    }
-                    case 'node_type': {
-                        if (!input.itemType)
-                            return errorResult('INVALID_INPUT', 'itemType is required for node_type');
-                        result = { ppType: dg.getNodeType(input.itemType) };
-                        break;
-                    }
-                    case 'edge_type': {
-                        if (!input.relationName)
-                            return errorResult('INVALID_INPUT', 'relationName is required for edge_type');
-                        result = { ppEdge: dg.getEdgeType(input.relationName) };
-                        break;
-                    }
-                    default:
-                        return errorResult('INVALID_INPUT', `Unknown query: ${input.query}`);
-                }
-                return {
-                    content: [{
-                            type: 'text',
-                            text: JSON.stringify(result, null, 2),
-                        }],
-                };
-            }
             // -----------------------------------------------------------------------
             // UNKNOWN TOOL
             // -----------------------------------------------------------------------
@@ -2216,7 +1774,7 @@ You can now start creating new items on a clean canvas.`,
                 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',
@@ -2245,12 +1803,7 @@ You can now start creating new items on a clean canvas.`,
                         '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',
@@ -2259,6 +1812,7 @@ You can now start creating new items on a clean canvas.`,
                         'pinepaper_clear_canvas',
                         'pinepaper_refresh_page',
                         'pinepaper_import_svg',
+                        'pinepaper_import_mermaid',
                         'pinepaper_add_filter',
                         'pinepaper_export_svg',
                         'pinepaper_export_training_data',
@@ -2293,64 +1847,16 @@ You can now start creating new items on a clean canvas.`,
                         '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',
+                        // 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',
-                        // Template tools
-                        'pinepaper_apply_template',
+                        'pinepaper_font',
                         // Image import tools
                         'pinepaper_import_image',
                         // Paper.js direct access tools
@@ -2359,6 +1865,7 @@ You can now start creating new items on a clean canvas.`,
                         'pinepaper_tool_guide',
                         'pinepaper_set_toolkit',
                         // Ontology tools
+                        'pinepaper_get_canvas_ontology',
                         'pinepaper_analyze_design',
                         'pinepaper_validate_design',
                         'pinepaper_query_ontology',
@@ -2372,10 +1879,21 @@ You can now start creating new items on a clean canvas.`,
                         'pinepaper_cutout_style',
                         // Composition & view tools
                         'pinepaper_precomp',
-                        'pinepaper_view',
                         'pinepaper_background',
                         // Canvas query tools
                         'pinepaper_query',
+                        // Deformation, sprite sheets, interaction
+                        'pinepaper_deform',
+                        'pinepaper_sprite_sheet',
+                        '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',
                     ],
                 });
             }