@pinepaper.studio/mcp-server 1.5.3 → 1.5.5

package/dist/tools/definitions.js

@@ -9,6 +9,16 @@
  */
 import { COMPACT_DESCRIPTIONS } from './compact-descriptions.js';
 import { MINIMAL_DESCRIPTIONS } from './minimal-descriptions.js';
+import { EffectTypeSchema, SimpleAnimationTypeSchema, } from '../types/schemas.js';
+/**
+ * Vocabulary lists derived from Zod schemas so tool descriptions stay in
+ * sync automatically. The description-schema-parity test
+ * (src/__tests__/unit/description-schema-parity.test.ts) fails CI if any
+ * tool description that names a vocabulary slot drops or invents values
+ * relative to the source-of-truth schema.
+ */
+const EFFECT_TYPES_LIST = EffectTypeSchema.options.join(', ');
+const SIMPLE_ANIMATION_TYPES_LIST = SimpleAnimationTypeSchema.options.join(', ');
 // =============================================================================
 // AI AGENT GUIDE (exported for pinepaper_tool_guide)
 // =============================================================================
@@ -47,7 +57,7 @@ RULES:
 CANVAS:  set_canvas_size (width/height or preset) → set_background (color) → execute_generator (procedural art)
 ITEMS:   create (itemType, position, properties) → modify (itemId, properties) → delete (itemId)
 ANIMATE: animate (loop presets) → keyframe_animate (timed reveals) → relation (behavioral links)
-EFFECTS: apply_mask (reveal animations) → apply_effect (sparkle/blast)
+EFFECTS: apply_mask (reveal animations) → apply_effect (sparkle/blast/bubbles/fireflies/trail...)
 PLAY:    play_timeline (start playback)
 
 ─── GENERATORS (prefer these for backgrounds) ───
@@ -64,6 +74,7 @@ Choose based on mood:
 
 Shapes: circle, rectangle, star, ellipse, triangle, polygon, line, arc, path
 Text: text (content, fontSize, fontFamily, color, fontWeight)
+  Dynamic text: set contentType on text items → clock (live time), timer (elapsed), countdown (from N seconds), stopwatch (pauseable)
 All items: opacity, shadowColor, shadowBlur, blendMode, strokeColor, strokeWidth
 
 SVG imports for recognizable objects (planes, cars, animals, buildings):
@@ -73,7 +84,7 @@ SVG imports for recognizable objects (planes, cars, animals, buildings):
 
 Loop presets (animate): pulse, rotate, bounce, fade, wobble, slide, typewriter
 Keyframe (keyframe_animate): [{time, properties, easing}] → opacity, scale, scaleX, scaleY, x, y, rotation, fillColor, strokeColor, fontSize
-Relations (relation): orbits, follows, attached_to, points_at, mirrors, parallax, wave_through, morphs_to (+ 9 more in batch_execute schema)
+Relations (relation): orbits, follows, attached_to, points_at, mirrors, parallax, wave_through, morphs_to, group_morphs_to, moves_along_path (+ 9 more in batch_execute schema)
 Masks (apply_mask): wipeLeft, wipeRight, wipeUp, wipeDown, iris, irisOut, star, heart, curtainHorizontal, curtainVertical, cinematic, diagonalWipe, revealUp, revealDown
 Effects (apply_effect): sparkle, blast
 
@@ -111,10 +122,35 @@ Shapes: process (rect), decision (diamond), terminal (rounded), data, document,
 Workflow: create shapes with positions → connect with arrows → optional auto_layout
 See pinepaper://docs/diagrams for full examples.
 
+─── STANDALONE TOOLS (not batch — call directly) ───
+
+Deformation: pinepaper_deform — vertex-level presets (fold, squeeze, twist, ripple, wave, breathe, wobble...)
+  Phase-driven animation: sin, blink, pingpong, elastic, heartbeat, stepped
+  Use for organic motion that keyframes can't achieve.
+
+Sprite Sheets: pinepaper_sprite_sheet — generate from skeleton poses, play, export (PNG + atlas)
+  For character animation and game sprite pipelines.
+
+Interaction: pinepaper_interaction — continuous physics behaviors (repel, attract, follow, orbit, slingshot)
+  For interactive storytelling, quizzes, games. trigger_action for state changes (incrementScore, navigate, showFeedback).
+
+Data Viz: pinepaper_create_chart — create/update/reconfigure/remove charts (bar, line, scatter, area)
+  Pass data as array of objects + options. Auto-animated with expression-driven oscillation.
+
+Magic: pinepaper_magic — ontology-aware auto-animation + style remix
+  One-click animate (mood: calm/professional/energetic/dramatic/whimsical) or remix (cycle colors/fonts).
+
+Physics: pinepaper_physics — rigid body simulation (init, add_body, apply_force, create_joint)
+  For interactive simulations, gravity, collisions. Based on Box2D/Planck.js.
+
+Measurement: pinepaper_measurement — rulers, grid, snap-to-grid, get item dimensions
+  For precise layouts and alignment.
+
 ─── CANVAS & EXPORT ───
 
 Presets: instagram (1080x1080), youtube (1920x1080), tiktok (1080x1920), twitter (1200x675)
-Export: pinepaper_agent_export (SVG/PNG/GIF/MP4/WebM/PDF), pinepaper_export_svg`;
+Export: pinepaper_agent_export (SVG/PNG/GIF/MP4/WebM/PDF), pinepaper_export_svg
+Widget: pinepaper_export_widget (pp:PinePaper ontology JSON), pinepaper_export_widget_html (self-contained HTML with tree-shaken runtime)`;
 /*
  * The AI_AGENT_GUIDE constant above is included as a comment in verbose/compact modes
  * and served on-demand via pinepaper_tool_guide in minimal mode.
@@ -290,7 +326,7 @@ USE WHEN:
 IMPORTANT:
 - Save the returned itemId! You need it for pinepaper_add_relation, pinepaper_modify_item, pinepaper_delete_item, etc.
 - If there's a welcome template on the canvas, use pinepaper_clear_canvas first
-- Position defaults to canvas center (400, 300). Use position: {x, y} to place elsewhere.
+- Position defaults to canvas center (400, 300). Use position: {x, y} or [x, y] (both forms accepted) to place elsewhere.
 - DO NOT take screenshots after every create operation. Trust the API response - if it returns success, the item was created. Take ONE screenshot at the end to verify the final result.
 
 ⚠️ COMPLEX CHARACTERS/ILLUSTRATIONS:
@@ -352,12 +388,23 @@ For glossy 3D spheres, use pinepaper_create_glossy_sphere instead. For diagonal
                     description: 'Type of item to create',
                 },
                 position: {
-                    type: 'object',
-                    properties: {
-                        x: { type: 'number', description: 'X coordinate (default: 400)' },
-                        y: { type: 'number', description: 'Y coordinate (default: 300)' },
-                    },
-                    description: 'Position on canvas',
+                    oneOf: [
+                        {
+                            type: 'object',
+                            properties: {
+                                x: { type: 'number', description: 'X coordinate (default: 400)' },
+                                y: { type: 'number', description: 'Y coordinate (default: 300)' },
+                            },
+                        },
+                        {
+                            type: 'array',
+                            items: { type: 'number' },
+                            minItems: 2,
+                            maxItems: 2,
+                            description: '[x, y] tuple — array shorthand for position',
+                        },
+                    ],
+                    description: 'Position on canvas. Either {x, y} object or [x, y] array.',
                 },
                 properties: {
                     type: 'object',
@@ -435,7 +482,15 @@ MODIFIABLE PROPERTIES:
 - blendMode: Blend mode (normal, multiply, screen, overlay, etc.)
 
 GRADIENT OBJECT FORMAT:
-{type: "linear"|"radial", stops: [{color: "#fff", offset: 0}, {color: "#000", offset: 1}], origin: [x,y], destination: [x,y]}`,
+{type: "linear"|"radial", stops: [{color: "#fff", offset: 0}, {color: "#000", offset: 1}], origin: [x,y], destination: [x,y]}
+
+LETTER-COLLAGE PROPS (non-destructive — registry ids, animations, relations, effects, deformations all preserved):
+- palette (collage group): Swap palette name in-place. e.g. "wordle", "spring", "sunset", "magazine". Walks existing letters, rewrites tile + text fills. No geometry change.
+- collageStyle (collage group): Swap visual style — "tile" | "magazine" | "paperCut" | "fold" | "gradient" | "image". Geometry rebuilds; every registryId is preserved via graft.
+- palette + collageStyle (collage group): Combine in one call to apply both atomically.
+- bgColor (single letter group, child of a collage): Tile/background fill for that one letter.
+- textColor (single letter group): PointText fill for that one letter.
+Use the collage group's id for palette/collageStyle; use a child letter's id for bgColor/textColor. Prefer this over destructive recreation.`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -445,7 +500,7 @@ GRADIENT OBJECT FORMAT:
                 },
                 properties: {
                     type: 'object',
-                    description: 'Properties to update: x, y, width, height, scale, scaleX, scaleY, rotation, opacity, color, strokeColor, strokeWidth, fontSize, content. DO NOT pass animationType here — use pinepaper_animate or pinepaper_keyframe_animate instead.',
+                    description: 'Properties to update: x, y, width, height, scale, scaleX, scaleY, rotation, opacity, color, strokeColor, strokeWidth, fontSize, content. Letter-collage non-destructive props (preserve ids/animations/relations): palette, collageStyle (collage group); bgColor, textColor (single letter). DO NOT pass animationType here — use pinepaper_animate or pinepaper_keyframe_animate instead.',
                     additionalProperties: true,
                 },
                 data: {
@@ -707,6 +762,65 @@ Returns the itemId of the imported SVG group, which can be used with pinepaper_a
             },
         },
     },
+    {
+        name: 'pinepaper_import_mermaid',
+        annotations: {
+            title: 'Import Mermaid Diagram',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: `Import a Mermaid diagram source string and render it onto the canvas as native diagram shapes + connectors. Faster than building a flowchart shape-by-shape with pinepaper_create_diagram_shape + pinepaper_connect.
+
+USE WHEN:
+- User asks for a flowchart, sequence diagram, ER diagram, class diagram, or state machine
+- You have Mermaid source from another tool / docs / the user's clipboard
+- You want to author multi-node diagrams in one call instead of N create+connect operations
+
+SUPPORTED DIAGRAM TYPES (auto-detected from the first non-blank line):
+- flowchart / graph: shapes + edges + subgraphs + chained edges (TD, LR, RL, BT directions)
+- stateDiagram(-v2): states, transitions, [*] start/end, stereotypes, nested states
+- sequenceDiagram: participants, messages, activations / lifelines
+- erDiagram: entities + relationships + attributes
+- classDiagram: classes, fields, methods, visibility, inheritance / association
+
+OPTIONS:
+- autoLayout (default true): run hierarchical/force layout after import. Set false to keep coordinates exactly as parsed.
+- clearExisting (default false): remove existing canvas items first. Default is additive — diagram is appended.
+
+EXAMPLE (flowchart):
+{
+  "mermaidText": "flowchart TD\\n  A[Start] --> B{Decision}\\n  B -->|Yes| C[Action]\\n  B -->|No| D[End]"
+}
+
+EXAMPLE (sequenceDiagram):
+{
+  "mermaidText": "sequenceDiagram\\n  Alice->>Bob: Hello\\n  Bob-->>Alice: Hi back\\n  Note right of Bob: Thinking..."
+}
+
+Returns { success, nodeCount, edgeCount, nodes, edges, errors }. The created shapes participate in the relation/animation systems just like natively created items — you can grab their ids from \`nodes\` and feed them into pinepaper_add_relation, pinepaper_animate, etc.
+
+NOTE: Import-only — there is no MCP equivalent of FxTool's exportMermaid. Mermaid lacks animation primitives, so a round-trip would silently drop animations.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                mermaidText: {
+                    type: 'string',
+                    description: 'Mermaid diagram source. First line picks the type (flowchart, stateDiagram, sequenceDiagram, erDiagram, classDiagram).',
+                },
+                autoLayout: {
+                    type: 'boolean',
+                    description: 'Run auto-layout after import (default: true).',
+                },
+                clearExisting: {
+                    type: 'boolean',
+                    description: 'Clear existing canvas items first (default: false).',
+                },
+            },
+            required: ['mermaidText'],
+        },
+    },
     {
         name: 'pinepaper_import_image',
         annotations: {
@@ -1151,6 +1265,8 @@ RELATION COMPATIBILITY:
   Circle→Circle: radius interpolation
   Text→Text: font blend
   Cross-type: particle denoising transition
+- group_morphs_to: pair-by-index morph between two paper.Groups (any two — graph vertices+edges, letter collages, dashboard clusters). Path.Line children deform via endpoints; other children translate; excess children fade. Params: duration, hold, loop, easing (linear|easeIn|easeOut|easeInOut), deformLines.
+- moves_along_path: self-relation (targetId=null); item is driven along a custom-drawn path stored in params.path (array of {x,y} or [x,y]). Params: path, speed, closed, phase, easing (linear|easeIn|easeOut|easeInOut|sine|bounce|pingpong).
 
 VERIFYING ANIMATION WORKS:
 After adding a relation, verify the animation is running:
@@ -1172,7 +1288,7 @@ Relations are COMPOSITIONAL - an item can have multiple relations that work toge
                 },
                 relationType: {
                     type: 'string',
-                    enum: ['orbits', 'follows', 'attached_to', 'maintains_distance', 'points_at', 'mirrors', 'parallax', 'bounds_to', 'animates', 'grows_from', 'staggered_with', 'indicates', 'circumscribes', 'wave_through', 'camera_follows', 'camera_animates', 'morphs_to'],
+                    enum: ['orbits', 'follows', 'attached_to', 'maintains_distance', 'points_at', 'mirrors', 'parallax', 'bounds_to', 'animates', 'grows_from', 'staggered_with', 'indicates', 'circumscribes', 'wave_through', 'camera_follows', 'camera_animates', 'morphs_to', 'group_morphs_to', 'moves_along_path'],
                     description: 'Type of relationship',
                 },
                 params: {
@@ -1206,7 +1322,7 @@ USE WHEN:
                 targetId: { type: 'string', description: 'Target item ID' },
                 relationType: {
                     type: 'string',
-                    enum: ['orbits', 'follows', 'attached_to', 'maintains_distance', 'points_at', 'mirrors', 'parallax', 'bounds_to', 'animates', 'grows_from', 'staggered_with', 'indicates', 'circumscribes', 'wave_through', 'camera_follows', 'camera_animates', 'morphs_to'],
+                    enum: ['orbits', 'follows', 'attached_to', 'maintains_distance', 'points_at', 'mirrors', 'parallax', 'bounds_to', 'animates', 'grows_from', 'staggered_with', 'indicates', 'circumscribes', 'wave_through', 'camera_follows', 'camera_animates', 'morphs_to', 'group_morphs_to', 'moves_along_path'],
                     description: 'Specific relation type to remove (optional - removes all if not specified)',
                 },
             },
@@ -1234,7 +1350,7 @@ USE WHEN:
                 itemId: { type: 'string', description: 'Item to query relations for' },
                 relationType: {
                     type: 'string',
-                    enum: ['orbits', 'follows', 'attached_to', 'maintains_distance', 'points_at', 'mirrors', 'parallax', 'bounds_to', 'animates', 'grows_from', 'staggered_with', 'indicates', 'circumscribes', 'wave_through', 'camera_follows', 'camera_animates', 'morphs_to'],
+                    enum: ['orbits', 'follows', 'attached_to', 'maintains_distance', 'points_at', 'mirrors', 'parallax', 'bounds_to', 'animates', 'grows_from', 'staggered_with', 'indicates', 'circumscribes', 'wave_through', 'camera_follows', 'camera_animates', 'morphs_to', 'group_morphs_to', 'moves_along_path'],
                     description: 'Filter by relation type (optional)',
                 },
                 direction: {
@@ -1437,7 +1553,7 @@ USE WHEN:
 - Any animation with specific timing or sequential stages
 
 ANIMATABLE PROPERTIES:
-- position: [x, y] array
+- position: [x, y] array (a { x, y } object is also accepted and normalized)
 - x, y: Individual coordinates
 - scale: Uniform scale
 - scaleX, scaleY: Axis scaling
@@ -1453,7 +1569,17 @@ EASING OPTIONS:
 - easeOut: Slow end
 - easeInOut: Slow start and end
 - bounce: Bounce effect
-- elastic: Elastic overshoot`,
+- elastic: Elastic overshoot
+
+CLIP WINDOW (optional — Premiere/Canva-style clip behavior):
+- timeOffset: Shift the whole clip in canvas time (seconds). The animation only runs while canvas time is in [timeOffset, timeOffset + (clipOutPoint - clipInPoint)].
+- clipInPoint: Skip the first N seconds of keyframe data (head trim).
+- clipOutPoint: Stop at N seconds into the keyframe data (tail trim). Default: lastKeyframeTime.
+Outside the clip window the item is hidden via item.visible=false (opacity is left alone, so opacity-keyframes still work inside the window).
+
+EXAMPLE — Reveal at 2s, skip first second of keyframe data, end at 4s of keyframe data:
+{ itemId, timeOffset: 2, clipInPoint: 1, clipOutPoint: 4, keyframes: [...] }
+// Item visible during canvas time 2..5s; keyframes shifted so kf time=1 plays at canvas 2s.`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -1486,6 +1612,18 @@ EASING OPTIONS:
                     type: 'boolean',
                     description: 'Whether to loop the animation',
                 },
+                timeOffset: {
+                    type: 'number',
+                    description: 'Shift the whole clip in canvas time (seconds). Item is hidden outside [timeOffset, timeOffset+window].',
+                },
+                clipInPoint: {
+                    type: 'number',
+                    description: 'Skip the first N seconds of keyframe data (head trim).',
+                },
+                clipOutPoint: {
+                    type: 'number',
+                    description: 'Stop at N seconds into the keyframe data (tail trim). Default: lastKeyframeTime.',
+                },
             },
             required: ['itemId', 'keyframes'],
         },
@@ -1754,29 +1892,60 @@ Requires maskType and keyframes array.`,
             idempotentHint: false,
             openWorldHint: false,
         },
-        description: `Animate camera with keyframe-based zoom and pan sequence for cinematic effects.
+        description: `Animate camera with keyframe-based zoom, pan, and 3D tilt sequence for cinematic effects.
 
 USE WHEN:
 - Creating cinematic camera movements
 - Building presentation zoom sequences
 - Making dramatic reveals with camera motion
 - Tour animations showing different parts of canvas
+- 3D perspective effects (pitch/yaw tilt via equirectangular projection)
+
+The camera follows a keyframe sequence. For an orbit-style camera (revolving
+around a subject), add 4-8 keyframes around the pivot using pathMode: "arc"
+with pivot + arcDirection on each segment. There is no separate "orbit" mode
+— it is expressible as keyframes + arc paths.
 
 KEYFRAME PROPERTIES:
 - time: Time in seconds
 - zoom: Zoom level (1=normal, 2=2x zoom in, 0.5=zoom out)
-- center: View center [x, y]
+- focus: Camera target, resolved live against the scene graph. Accepts:
+    [x, y]                         literal position
+    'item-id'                      itemRegistry lookup → item bounds center (tracks the item as it moves)
+    { item: 'id', offset: [dx, dy] } item center + offset
+- center: [x, y] — legacy alias, honored only when focus is absent
+- pitch: 3D tilt in degrees (0=flat, positive=tilt forward). Uses equirectangular projection
+- yaw: 3D rotation in degrees. Uses equirectangular projection
 - easing: Timing function (linear, easeIn, easeOut, easeInOut, bounce, elastic)
 
-EXAMPLE:
+CURVED INTER-KEYFRAME PATHS (optional; default is linear):
+- pathOut: [dx, dy] — bezier tangent handle when LEAVING this keyframe
+- pathIn:  [dx, dy] — bezier tangent handle when ARRIVING at this keyframe
+    Either handle alone promotes the segment to a cubic bezier.
+- pathMode: 'arc' — arc around a pivot. Requires pivot: [x, y]; optional arcDirection: 'ccw'|'cw'
+- pathMode: 'custom' + path: 'M x y C ...' — sample any SVG path string (falls back to linear when Paper.js is unavailable)
+Endpoints always match the resolved focus of each keyframe — handles only shape the curve between them.
+
+EXAMPLE (with 3D tilt):
 {
   "duration": 6,
   "loop": true,
+  "fov": 60,
+  "keyframes": [
+    { "time": 0, "zoom": 1, "focus": [400, 300], "pitch": 0, "yaw": 0 },
+    { "time": 2, "zoom": 2, "focus": "hero-character", "pitch": 12, "yaw": -5, "easing": "easeInOut" },
+    { "time": 4, "zoom": 2, "focus": { "item": "villain", "offset": [0, -40] }, "pitch": 8, "yaw": 3, "easing": "easeOut" },
+    { "time": 6, "zoom": 1, "focus": [400, 300], "pitch": 0, "yaw": 0, "easing": "easeInOut" }
+  ]
+}
+
+EXAMPLE (curved arc between waypoints):
+{
+  "duration": 4,
   "keyframes": [
-    { "time": 0, "zoom": 1, "center": [400, 300] },
-    { "time": 2, "zoom": 2, "center": [400, 300], "easing": "easeInOut" },
-    { "time": 4, "zoom": 2, "center": [600, 300], "easing": "easeOut" },
-    { "time": 6, "zoom": 1, "center": [400, 300], "easing": "easeInOut" }
+    { "time": 0, "zoom": 1, "focus": [200, 300], "pathOut": [120, -60] },
+    { "time": 2, "zoom": 1.5, "focus": [800, 300], "pathIn": [-120, -60], "pathMode": "arc", "pivot": [500, 450], "arcDirection": "ccw" },
+    { "time": 4, "zoom": 1, "focus": [200, 300] }
   ]
 }`,
         inputSchema: {
@@ -1790,183 +1959,113 @@ EXAMPLE:
                         properties: {
                             time: { type: 'number', description: 'Time in seconds' },
                             zoom: { type: 'number', description: 'Zoom level (1=normal, 2=2x zoom in)' },
+                            focus: {
+                                description: 'Camera target, resolved live against the scene graph. Accepts [x, y], an item id string, or { item: "id", offset: [dx, dy] }. Takes precedence over center.',
+                            },
                             center: {
                                 type: 'array',
                                 items: { type: 'number' },
-                                description: 'View center [x, y]',
+                                description: 'Legacy view center [x, y] — honored only when focus is absent',
                             },
+                            pitch: { type: 'number', description: '3D tilt in degrees (0=flat, positive=forward tilt)' },
+                            yaw: { type: 'number', description: '3D rotation in degrees' },
                             easing: {
                                 type: 'string',
                                 enum: ['linear', 'easeIn', 'easeOut', 'easeInOut', 'bounce', 'elastic'],
                             },
+                            pathOut: {
+                                type: 'array',
+                                items: { type: 'number' },
+                                description: 'Bezier tangent handle [dx, dy] when leaving this keyframe. Promotes segment to cubic bezier.',
+                            },
+                            pathIn: {
+                                type: 'array',
+                                items: { type: 'number' },
+                                description: 'Bezier tangent handle [dx, dy] when arriving at this keyframe. Promotes segment to cubic bezier.',
+                            },
+                            pathMode: {
+                                type: 'string',
+                                enum: ['arc', 'custom'],
+                                description: 'arc: curve around pivot (requires pivot). custom: sample an SVG path (requires path).',
+                            },
+                            pivot: {
+                                type: 'array',
+                                items: { type: 'number' },
+                                description: 'Arc center [x, y] when pathMode is "arc"',
+                            },
+                            arcDirection: {
+                                type: 'string',
+                                enum: ['ccw', 'cw'],
+                                description: 'Arc sweep direction when pathMode is "arc" (default: ccw)',
+                            },
+                            path: {
+                                type: 'string',
+                                description: 'SVG path string (e.g. "M 100 200 C 150 100 350 100 400 200") when pathMode is "custom"',
+                            },
                         },
                     },
                 },
                 duration: { type: 'number', description: 'Total animation duration in seconds' },
                 loop: { type: 'boolean', description: 'Loop the animation' },
                 delay: { type: 'number', description: 'Delay before animation starts' },
+                fov: { type: 'number', description: 'Field of view in degrees for 3D perspective (default: 60)' },
             },
             required: ['keyframes', 'duration'],
         },
     },
     {
-        name: 'pinepaper_camera_zoom',
-        annotations: {
-            title: 'Camera Zoom',
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-        description: `Simple camera zoom animation.
-
-USE WHEN:
-- Quick zoom in to focus on something
-- Zoom out to show full canvas
-- Simple zoom effects without complex keyframes`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                direction: {
-                    type: 'string',
-                    enum: ['in', 'out'],
-                    description: 'Zoom direction',
-                },
-                level: {
-                    type: 'number',
-                    description: 'Target zoom level (default: 2 for in, 0.5 for out)',
-                },
-                duration: {
-                    type: 'number',
-                    description: 'Animation duration in seconds (default: 0.5)',
-                },
-            },
-            required: ['direction'],
-        },
-    },
-    {
-        name: 'pinepaper_camera_pan',
+        name: 'pinepaper_camera',
         annotations: {
-            title: 'Camera Pan',
+            title: 'Camera Control',
             readOnlyHint: false,
             destructiveHint: false,
             idempotentHint: false,
             openWorldHint: false,
         },
-        description: `Pan camera in a direction or to specific coordinates.
+        description: `Camera control: zoom, pan, move, reset, stop, get state. Single action-dispatched tool replaces six thin wrappers. For keyframe walkthroughs / 3D pitch+yaw / curved paths, use pinepaper_camera_animate (a separate, richer tool).
 
-USE WHEN:
-- Moving view to different part of canvas
-- Directional panning (left, right, up, down)
-- Centering on specific coordinates
+ACTIONS:
+- zoom    — { direction: "in"|"out", level?: number, duration?: number }
+            level defaults to 2 (in) or 0.5 (out). duration default 0.5s.
+- pan     — { direction?: "left"|"right"|"up"|"down", amount?: number, x?: number, y?: number, duration?: number }
+            Either direction+amount (default 100px) OR x+y for panTo.
+- move_to — { x, y, zoom, duration?: number }
+            Combined zoom + pan in one motion.
+- reset   — { duration?: number }
+            Back to center + zoom 1.
+- stop    — {}
+            Cancel any active animation.
+- state   — {}
+            Returns { zoom, center, isAnimating }.
+- fit_view — {}
+            Fit canvas content to the viewport (calls app.fitView()).
 
 EXAMPLES:
-// Pan left 200 pixels
-{ "direction": "left", "amount": 200 }
-
-// Pan to specific coordinates
-{ "x": 200, "y": 200, "duration": 1 }`,
+{ action: "zoom", direction: "in", level: 2.5 }
+{ action: "pan", x: 200, y: 200, duration: 1 }
+{ action: "move_to", x: 600, y: 400, zoom: 2 }
+{ action: "reset" }
+{ action: "state" }`,
         inputSchema: {
             type: 'object',
             properties: {
-                direction: {
+                action: {
                     type: 'string',
-                    enum: ['left', 'right', 'up', 'down'],
-                    description: 'Pan direction (use with amount)',
-                },
-                amount: {
-                    type: 'number',
-                    description: 'Pixels to pan (default: 100)',
-                },
-                x: {
-                    type: 'number',
-                    description: 'Target X coordinate (use with y for panTo)',
+                    enum: ['zoom', 'pan', 'move_to', 'reset', 'stop', 'state', 'fit_view'],
+                    description: 'Camera action to perform',
                 },
-                y: {
-                    type: 'number',
-                    description: 'Target Y coordinate (use with x for panTo)',
-                },
-                duration: {
-                    type: 'number',
-                    description: 'Animation duration in seconds (default: 0.5)',
+                direction: {
+                    type: 'string',
+                    description: 'For zoom: "in"|"out". For pan: "left"|"right"|"up"|"down".',
                 },
+                level: { type: 'number', description: 'Zoom level (zoom action; default 2 for in, 0.5 for out)' },
+                amount: { type: 'number', description: 'Pixels to pan (pan action with direction; default 100)' },
+                x: { type: 'number', description: 'Target X coordinate (pan with x+y, or move_to)' },
+                y: { type: 'number', description: 'Target Y coordinate (pan with x+y, or move_to)' },
+                zoom: { type: 'number', description: 'Target zoom level (move_to)' },
+                duration: { type: 'number', description: 'Animation duration in seconds (default 0.5)' },
             },
-        },
-    },
-    {
-        name: 'pinepaper_camera_move_to',
-        annotations: {
-            title: 'Camera Move To',
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-        description: `Combined camera zoom and pan to a specific location.
-
-USE WHEN:
-- Moving to and zooming on a specific point in one motion
-- Focusing on an item with appropriate zoom level`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                x: { type: 'number', description: 'Target X coordinate' },
-                y: { type: 'number', description: 'Target Y coordinate' },
-                zoom: { type: 'number', description: 'Target zoom level' },
-                duration: { type: 'number', description: 'Animation duration in seconds (default: 0.5)' },
-            },
-            required: ['x', 'y', 'zoom'],
-        },
-    },
-    {
-        name: 'pinepaper_camera_reset',
-        annotations: {
-            title: 'Camera Reset',
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-        description: `Reset camera to default state (center of canvas, zoom 1).
-
-USE WHEN:
-- Returning to default view after camera movements
-- Resetting before starting new sequence`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                duration: { type: 'number', description: 'Animation duration in seconds (default: 0.5)' },
-            },
-        },
-    },
-    {
-        name: 'pinepaper_camera_stop',
-        annotations: {
-            title: 'Camera Stop',
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-        description: `Stop current camera animation.`,
-        inputSchema: {
-            type: 'object',
-            properties: {},
-        },
-    },
-    {
-        name: 'pinepaper_camera_state',
-        annotations: {
-            title: 'Camera State',
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-        description: `Get current camera state (zoom level, center position, animation status).`,
-        inputSchema: {
-            type: 'object',
-            properties: {},
+            required: ['action'],
         },
     },
     // ---------------------------------------------------------------------------
@@ -2034,7 +2133,7 @@ EXAMPLE - Bouncing Balls:
 }
 
 SUPPORTED ITEM TYPES: text, circle, star, rectangle, triangle, polygon, ellipse, path, line, arc
-SUPPORTED RELATIONS: orbits, follows, attached_to, maintains_distance, points_at, mirrors, parallax, bounds_to, animates, grows_from, staggered_with, indicates, circumscribes, wave_through, camera_follows, camera_animates, morphs_to
+SUPPORTED RELATIONS: orbits, follows, attached_to, maintains_distance, points_at, mirrors, parallax, bounds_to, animates, grows_from, staggered_with, indicates, circumscribes, wave_through, camera_follows, camera_animates, morphs_to, group_morphs_to, moves_along_path
 SUPPORTED ANIMATIONS: pulse, rotate, bounce, fade, wobble, slide, typewriter`,
         inputSchema: {
             type: 'object',
@@ -2080,7 +2179,7 @@ SUPPORTED ANIMATIONS: pulse, rotate, bounce, fade, wobble, slide, typewriter`,
                             target: { type: 'string', description: 'Name of target item' },
                             type: {
                                 type: 'string',
-                                enum: ['orbits', 'follows', 'attached_to', 'maintains_distance', 'points_at', 'mirrors', 'parallax', 'bounds_to', 'animates', 'grows_from', 'staggered_with', 'indicates', 'circumscribes', 'wave_through', 'camera_follows', 'camera_animates', 'morphs_to'],
+                                enum: ['orbits', 'follows', 'attached_to', 'maintains_distance', 'points_at', 'mirrors', 'parallax', 'bounds_to', 'animates', 'grows_from', 'staggered_with', 'indicates', 'circumscribes', 'wave_through', 'camera_follows', 'camera_animates', 'morphs_to', 'group_morphs_to', 'moves_along_path'],
                             },
                             params: {
                                 type: 'object',
@@ -2492,38 +2591,6 @@ ACTIONS:
             required: ['action'],
         },
     },
-    {
-        name: 'pinepaper_view',
-        annotations: {
-            title: 'View',
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-        description: `View control — fit view to content or get current view state.
-
-ACTIONS:
-- fit: Fit view to content or canvas bounds. Params: mode (content|canvas), padding (number)
-- get_state: Get current view state (zoom, center, bounds)`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                action: {
-                    type: 'string',
-                    enum: ['fit', 'get_state'],
-                    description: 'View action',
-                },
-                mode: {
-                    type: 'string',
-                    enum: ['content', 'canvas'],
-                    description: 'Fit mode (for fit action)',
-                },
-                padding: { type: 'number', description: 'Padding around content in pixels (default: 20)' },
-            },
-            required: ['action'],
-        },
-    },
     {
         name: 'pinepaper_background',
         annotations: {
@@ -2596,94 +2663,291 @@ ACTIONS:
         },
     },
     // ---------------------------------------------------------------------------
-    // LAYER 5 — BLUEPRINTS: TEMPLATE TOOLS
+    // DEFORMATION, SPRITE SHEETS, INTERACTION
     // ---------------------------------------------------------------------------
     {
-        name: 'pinepaper_apply_template',
+        name: 'pinepaper_deform',
         annotations: {
-            title: 'Apply Template',
+            title: 'Deformation',
             readOnlyHint: false,
-            destructiveHint: true,
+            destructiveHint: false,
             idempotentHint: false,
             openWorldHint: false,
         },
-        description: `Load a pre-built template design onto the canvas, or list available templates.
+        description: `Apply vertex deformation presets to items for organic motion effects.
 
-USE WHEN:
-- User wants to start from a pre-made design
-- User asks for a template, preset, or starter layout
-- User wants to see what templates are available
-- Need a quick starting point for social media, presentations, etc.
-
-⚠️ DESTRUCTIVE: Loading a template replaces the current canvas content.
-
-MODES:
-1. LIST MODE: Set listOnly: true (or omit templateId) to browse available templates
-   - Optionally filter by category
-2. LOAD MODE: Provide a templateId to apply that template
+ACTIONS:
+- apply: Apply looping deformation. Params: itemId, preset, frequency, amplitude (0-1), phase, loop, axis, turns, waves, maxDisplacement, speed, steps
+- trigger: One-shot deformation (auto-removes). Params: itemId, preset, amplitude, speed
+- remove: Restore original geometry. Params: itemId
 
-TEMPLATE CATEGORIES (13):
-- social-media: Social media post/story layouts
-- meme: Meme templates and formats
-- business: Business cards, letterheads, presentations
-- education: Educational diagrams, worksheets
-- creative: Artistic and creative compositions
-- tech: Technology-themed designs
-- global: International and multicultural designs
-- indigenous: Indigenous art-inspired patterns
-- seasonal: Holiday and seasonal themes
-- masking: Mask reveal effect demonstrations
-- scenes: Pre-built animated scenes
-- diagrams: Flowchart and diagram starters
-- maps: Geographic visualization templates
+PRESETS: fold, squeeze, squash, pinch, bulge, twist, ripple, wave, breathe, melt, shear, inflate, wobble
 
-EXAMPLES:
-- List all templates: { "listOnly": true }
-- List by category: { "category": "social-media", "listOnly": true }
-- Load template: { "templateId": "solar-system" }`,
+PHASES: sin, blink, linear, pingpong, once, elastic, heartbeat, stepped`,
         inputSchema: {
             type: 'object',
             properties: {
-                templateId: {
+                action: {
                     type: 'string',
-                    description: 'Template ID to load (omit to list templates)',
+                    enum: ['apply', 'trigger', 'remove'],
+                    description: 'Deformation action',
                 },
-                category: {
+                itemId: { type: 'string', description: 'Target item ID' },
+                preset: {
                     type: 'string',
-                    enum: ['social-media', 'meme', 'business', 'education', 'creative', 'tech', 'global', 'indigenous', 'seasonal', 'masking', 'scenes', 'diagrams', 'maps'],
-                    description: 'Filter templates by category',
+                    enum: ['fold', 'squeeze', 'squash', 'pinch', 'bulge', 'twist', 'ripple', 'wave', 'breathe', 'melt', 'shear', 'inflate', 'wobble'],
+                    description: 'Deformation preset name',
                 },
-                listOnly: {
-                    type: 'boolean',
-                    description: 'If true, only list available templates without loading (default: false)',
+                frequency: { type: 'number', description: 'Oscillation speed (default: 1)' },
+                amplitude: { type: 'number', description: 'Deformation strength 0-1 (default: 1)' },
+                phase: {
+                    type: 'string',
+                    enum: ['sin', 'blink', 'linear', 'pingpong', 'once', 'elastic', 'heartbeat', 'stepped'],
+                    description: 'Phase driver for animation timing',
                 },
+                loop: { type: 'boolean', description: 'Loop the deformation (default: true)' },
+                axis: { type: 'string', enum: ['horizontal', 'vertical'], description: 'Axis for fold/wave presets' },
+                turns: { type: 'number', description: 'Rotation amount for twist preset' },
+                waves: { type: 'number', description: 'Wave count for ripple/wave presets' },
+                maxDisplacement: { type: 'number', description: 'Maximum displacement in pixels' },
+                speed: { type: 'number', description: 'Animation speed multiplier' },
+                steps: { type: 'number', description: 'Quantization levels for stepped phase' },
             },
+            required: ['action'],
         },
     },
-    // ---------------------------------------------------------------------------
-    // DOMAIN: DIAGRAM TOOLS
-    // ---------------------------------------------------------------------------
     {
-        name: 'pinepaper_create_diagram_shape',
+        name: 'pinepaper_sprite_sheet',
         annotations: {
-            title: 'Create Diagram Shape',
+            title: 'Sprite Sheet',
             readOnlyHint: false,
             destructiveHint: false,
             idempotentHint: false,
             openWorldHint: false,
         },
-        description: `Create a diagram shape on the canvas. Diagram shapes are specialized shapes for flowcharts, UML diagrams, network diagrams, and similar technical drawings.
-
-USE WHEN:
-- Creating flowcharts, process diagrams, or workflows
-- Building UML class diagrams, use case diagrams, or sequence diagrams
-- Designing network topology diagrams
-- Making organizational charts or decision trees
-- Any technical or architectural diagram
-
-SHAPE TYPES:
+        description: `Generate, play, and export sprite sheets from skeleton poses.
 
-Flowchart shapes:
+ACTIONS:
+- generate: Create sprite sheet from skeleton. Params: skeletonId, poses, transition, bakedAnimation, animations, padding, name
+- play: Play sprite animation on canvas. Params: spriteSheetId, x, y, animation, fps, scale
+- export: Export sprite sheet as image + metadata. Params: spriteSheetId, format (png|webp)`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['generate', 'play', 'export'],
+                    description: 'Sprite sheet action',
+                },
+                skeletonId: { type: 'string', description: 'Skeleton ID (for generate)' },
+                spriteSheetId: { type: 'string', description: 'Sprite sheet ID (for play/export)' },
+                name: { type: 'string', description: 'Sheet name' },
+                poses: {
+                    type: 'array',
+                    items: { type: 'object', properties: { name: { type: 'string' }, poseId: { type: 'string' } }, required: ['name', 'poseId'] },
+                    description: 'Explicit pose list',
+                },
+                transition: {
+                    type: 'object',
+                    properties: { poseIdA: { type: 'string' }, poseIdB: { type: 'string' }, frameCount: { type: 'number' }, name: { type: 'string' } },
+                    description: 'Interpolate between two poses',
+                },
+                bakedAnimation: {
+                    type: 'object',
+                    properties: { duration: { type: 'number' }, fps: { type: 'number' }, name: { type: 'string' } },
+                    description: 'Bake timeline animation into frames',
+                },
+                animations: {
+                    type: 'object',
+                    additionalProperties: { type: 'object', properties: { frames: { type: 'array', items: { type: 'string' } }, fps: { type: 'number' }, loop: { type: 'boolean' } } },
+                    description: 'Animation definitions mapping name to frame sequences',
+                },
+                padding: { type: 'number', description: 'Padding between frames (default: 1)' },
+                x: { type: 'number', description: 'X position for playback' },
+                y: { type: 'number', description: 'Y position for playback' },
+                animation: { type: 'string', description: 'Animation name to play' },
+                fps: { type: 'number', description: 'Frame rate (default: 12)' },
+                scale: { type: 'number', description: 'Scale factor (default: 1)' },
+                format: { type: 'string', enum: ['png', 'webp'], description: 'Export format (default: png)' },
+            },
+            required: ['action'],
+        },
+    },
+    {
+        name: 'pinepaper_interaction',
+        annotations: {
+            title: 'Interaction',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: `Add continuous physics behaviors and trigger interaction actions.
+
+ACTIONS:
+- add_behavior: Attach a continuous behavior. Params: itemId, behaviorType, params
+- remove_behavior: Remove a behavior. Params: itemId, behaviorId
+- trigger_action: Fire an interaction action. Params: actionType, params
+- get_state: Get interaction state (score, progress, step)
+
+BEHAVIOR TYPES: repel, attract, follow, orbit, slingshot, physics_body, draggable_constrained
+
+ACTION TYPES: navigate, show, hide, animate, stopAnimation, setState, incrementScore, playTimeline, pauseTimeline, seekTimeline, showFeedback, complete`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['add_behavior', 'remove_behavior', 'trigger_action', 'get_state'],
+                    description: 'Interaction action',
+                },
+                itemId: { type: 'string', description: 'Target item ID' },
+                behaviorType: {
+                    type: 'string',
+                    enum: ['repel', 'attract', 'follow', 'orbit', 'slingshot', 'physics_body', 'draggable_constrained'],
+                    description: 'Continuous behavior type',
+                },
+                behaviorId: { type: 'string', description: 'Behavior ID (for remove_behavior)' },
+                actionType: {
+                    type: 'string',
+                    enum: ['navigate', 'show', 'hide', 'animate', 'stopAnimation', 'setState', 'incrementScore', 'playTimeline', 'pauseTimeline', 'seekTimeline', 'showFeedback', 'complete'],
+                    description: 'Interaction action type (for trigger_action)',
+                },
+                params: {
+                    type: 'object',
+                    description: 'Action-specific or behavior-specific parameters',
+                },
+            },
+            required: ['action'],
+        },
+    },
+    // ---------------------------------------------------------------------------
+    // WIDGET EXPORT
+    // ---------------------------------------------------------------------------
+    {
+        name: 'pinepaper_export_widget',
+        annotations: {
+            title: 'Export Widget',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        description: `Export current scene as a PineWidget (pp:PinePaper ontology JSON v0.4.3).
+
+Returns portable scene data with items, relations, animations, masks, and interactions serialized in the pp:PinePaper semantic format. Includes embed code snippet for external sites.
+
+Params: download (bool), filename, includeInteractions (bool, default true), minify (bool)`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                download: { type: 'boolean', description: 'Trigger browser download (default: false)' },
+                filename: { type: 'string', description: 'Output filename (default: widget-scene.json)' },
+                includeInteractions: { type: 'boolean', description: 'Include interaction triggers (default: true)' },
+                minify: { type: 'boolean', description: 'Minify JSON output (default: false)' },
+            },
+        },
+    },
+    {
+        name: 'pinepaper_export_widget_html',
+        annotations: {
+            title: 'Export Widget HTML',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        description: `Export current scene as a self-contained HTML page with tree-shaken PineWidget runtime.
+
+Generates a single HTML file (<20KB typical) with inline scene data and only the JavaScript code needed for the specific items, relations, and features used. No external dependencies.
+
+Params: title (page title), download (bool)`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                title: { type: 'string', description: 'HTML page title (default: PinePaper Widget)' },
+                download: { type: 'boolean', description: 'Trigger browser download (default: false)' },
+            },
+        },
+    },
+    // ---------------------------------------------------------------------------
+    // DOMAIN: TEMPLATE TOOL
+    // ---------------------------------------------------------------------------
+    {
+        name: 'pinepaper_apply_template',
+        annotations: {
+            title: 'Apply Template',
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: `Load a pre-built template design onto the canvas, or list available templates.
+
+USE WHEN:
+- User wants to start from a pre-made design
+- User asks for a template, preset, or starter layout
+- User wants to see what templates are available
+- Need a quick starting point for social media, presentations, etc.
+
+⚠️ DESTRUCTIVE: Loading a template replaces the current canvas content.
+
+MODES:
+1. LIST MODE: Set listOnly: true (or omit templateId) to browse available templates
+   - Optionally filter by category
+2. LOAD MODE: Provide a templateId to apply that template
+
+TEMPLATE CATEGORIES (13):
+- social-media, meme, business, education, creative, tech, global,
+  indigenous, seasonal, masking, scenes, diagrams, maps
+
+EXAMPLES:
+- List all templates: { "listOnly": true }
+- List by category: { "category": "social-media", "listOnly": true }
+- Load template: { "templateId": "solar-system" }`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                templateId: {
+                    type: 'string',
+                    description: 'Template ID to load (omit to list templates)',
+                },
+                category: {
+                    type: 'string',
+                    enum: ['social-media', 'meme', 'business', 'education', 'creative', 'tech', 'global', 'indigenous', 'seasonal', 'masking', 'scenes', 'diagrams', 'maps'],
+                    description: 'Filter templates by category',
+                },
+                listOnly: {
+                    type: 'boolean',
+                    description: 'If true, only list available templates without loading (default: false)',
+                },
+            },
+        },
+    },
+    // ---------------------------------------------------------------------------
+    // DOMAIN: DIAGRAM TOOLS
+    // ---------------------------------------------------------------------------
+    {
+        name: 'pinepaper_create_diagram_shape',
+        annotations: {
+            title: 'Create Diagram Shape',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: `Create a diagram shape on the canvas. Diagram shapes are specialized shapes for flowcharts, UML diagrams, network diagrams, and similar technical drawings.
+
+USE WHEN:
+- Creating flowcharts, process diagrams, or workflows
+- Building UML class diagrams, use case diagrams, or sequence diagrams
+- Designing network topology diagrams
+- Making organizational charts or decision trees
+- Any technical or architectural diagram
+
+SHAPE TYPES:
+
+Flowchart shapes:
 - process: Rectangle for process steps (default: 120x60)
 - decision: Diamond for yes/no decisions (default: 100x100)
 - terminal: Rounded rectangle for start/end (default: 120x40)
@@ -3340,2209 +3604,614 @@ EXAMPLES:
         },
     },
     // ---------------------------------------------------------------------------
-    // DOMAIN: MAP TOOLS
+    // DOMAIN: MAP TOOLS — four action-dispatched tools replace 23 wrappers
     // ---------------------------------------------------------------------------
     {
-        name: 'pinepaper_load_map',
+        name: 'pinepaper_map',
         annotations: {
-            title: 'Load Map',
+            title: 'Map: Load + Viewport',
             readOnlyHint: false,
             destructiveHint: false,
             idempotentHint: false,
             openWorldHint: false,
         },
-        description: `Load a geographic map onto the canvas with specified projection and styling.
+        description: `Load a map and control its viewport. Call action: "load" first to set up; subsequent calls control pan / zoom / config import-export.
 
-USE WHEN:
-- Creating world maps or country visualizations
-- Building choropleth data visualizations
-- Making infographics with geographic data
-- Creating animated map reveals
-
-AVAILABLE MAPS:
-- world: World countries (110m resolution, faster)
-- worldHighRes: World countries (50m resolution, more detailed)
-- usa: US states map
-
-PROJECTIONS:
-- naturalEarth: Natural Earth projection (recommended for world maps)
-- mercator: Standard web mercator
-- equalEarth: Equal-area projection
-- orthographic: Globe/3D sphere view
-- albers: Conic projection (good for USA)
-- stereographic: Stereographic projection
-
-QUALITY SETTINGS:
-- fast: Aggressive simplification (prototyping)
-- balanced: Moderate detail (most uses)
-- professional: No simplification (publications)
-
-EXAMPLES:
-- World map: {mapId: "world", projection: "naturalEarth", quality: "balanced"}
-- USA map: {mapId: "usa", projection: "albers", quality: "professional"}
-- Globe view: {mapId: "worldHighRes", projection: "orthographic", rotate: [0, -30, 0]}
+ACTIONS:
+- load           — { mapId: "usa"|"world"|"worldHighRes"|<custom>, projection?, options? }
+- pan            — { lat, lon, duration? }
+- zoom           — { level, duration? }
+- export_config  — {}
+- import_custom  — { url? | geojson?, projection? }
 
-RETURNS:
-- mapId: Reference ID for the loaded map
-- group: Paper.js group containing all regions
-- regions: Array of region info
-- bounds: Map bounding box`,
+For region styling/selection use pinepaper_map_regions; for animations use pinepaper_map_animation; for CSV/GeoJSON/source-info use pinepaper_map_data.`,
         inputSchema: {
             type: 'object',
             properties: {
-                mapId: {
-                    type: 'string',
-                    enum: ['world', 'worldHighRes', 'usa'],
-                    description: 'Map to load (world=110m, worldHighRes=50m professional quality, usa=US states)',
-                },
-                projection: {
-                    type: 'string',
-                    enum: ['mercator', 'equalEarth', 'naturalEarth', 'orthographic', 'albers', 'stereographic'],
-                    description: 'Map projection type',
-                },
-                quality: {
-                    type: 'string',
-                    enum: ['fast', 'balanced', 'professional'],
-                    description: 'Rendering quality (professional=no simplification)',
-                },
-                fillColor: { type: 'string', description: 'Default fill color for regions' },
-                strokeColor: { type: 'string', description: 'Border/stroke color' },
-                strokeWidth: { type: 'number', description: 'Border width in pixels' },
-                scale: { type: 'number', description: 'Scale multiplier' },
-                center: {
-                    type: 'array',
-                    items: { type: 'number' },
-                    description: 'Center coordinates [longitude, latitude]',
-                },
-                rotate: {
-                    type: 'array',
-                    items: { type: 'number' },
-                    description: 'Rotation angles [x, y, z]',
-                },
-                enableHover: { type: 'boolean', description: 'Enable hover effects on regions' },
-                enableClick: { type: 'boolean', description: 'Enable click events on regions' },
-                hoverFill: { type: 'string', description: 'Fill color on hover' },
-                hoverStroke: { type: 'string', description: 'Stroke color on hover' },
+                action: { type: 'string', enum: ['load', 'pan', 'zoom', 'export_config', 'import_custom'], description: 'Map action' },
+                mapId: { type: 'string', description: 'Map identifier (load)' },
+                projection: { type: 'string', description: 'Projection (load / import_custom)' },
+                options: { type: 'object', description: 'Map options (load)', additionalProperties: true },
+                lat: { type: 'number', description: 'Latitude (pan)' },
+                lon: { type: 'number', description: 'Longitude (pan)' },
+                level: { type: 'number', description: 'Zoom level (zoom)' },
+                duration: { type: 'number', description: 'Animation duration (pan, zoom; default 0.5)' },
+                url: { type: 'string', description: 'GeoJSON/TopoJSON URL (import_custom)' },
+                geojson: { type: 'object', description: 'Inline GeoJSON (import_custom)' },
             },
-            required: ['mapId'],
+            required: ['action'],
         },
     },
     {
-        name: 'pinepaper_highlight_regions',
+        name: 'pinepaper_map_regions',
         annotations: {
-            title: 'Highlight Regions',
+            title: 'Map: Region Styling + Selection',
             readOnlyHint: false,
             destructiveHint: false,
-            idempotentHint: true,
+            idempotentHint: false,
             openWorldHint: false,
         },
-        description: `Highlight specific regions on a loaded map with custom styling.
-
-USE WHEN:
-- Emphasizing specific countries or states
-- Creating interactive map highlights
-- Building step-by-step map reveals
-- Showing geographic data points
+        description: `Highlight, color, label, and select map regions. Requires a map loaded via pinepaper_map { action: "load" } first.
 
-REGION ID FORMATS:
-- World maps: Full country names ("United States of America", "France", "Japan")
-- USA map: State codes ("CA", "TX", "NY", "FL")
-
-STYLING OPTIONS:
-- fillColor: Highlight fill color
-- strokeColor: Highlight stroke color
-- strokeWidth: Border width for highlighted regions
-- animate: Whether to animate the highlight transition
-
-EXAMPLES:
-- Highlight countries: {regionIds: ["United States of America", "Canada", "Mexico"], options: {fillColor: "#3b82f6"}}
-- Highlight US states: {regionIds: ["CA", "TX", "NY"], options: {fillColor: "#22c55e", animate: true}}
-- Custom styling: {regionIds: ["Japan"], options: {fillColor: "#ef4444", strokeColor: "#dc2626", strokeWidth: 2}}`,
+ACTIONS:
+- highlight        — { regionIds: string[], color?, opacity? }
+- unhighlight      — { regionIds?: string[] }              omit to clear all
+- apply_colors     — { data: Record<regionId, value>, options? }   choropleth coloring
+- add_marker       — { lat, lon, label?, color?, size? }
+- add_labels       — { regions?: string[], style?, formatter? }
+- get_at_point     — { x, y }                              region at canvas coords
+- select           — { regionIds: string[] }
+- deselect         — { regionIds?: string[] }              omit to deselect all
+- get_highlighted  — {}`,
         inputSchema: {
             type: 'object',
             properties: {
-                regionIds: {
-                    type: 'array',
-                    items: { type: 'string' },
-                    description: 'Array of region IDs to highlight (country names or state codes)',
-                },
-                options: {
-                    type: 'object',
-                    properties: {
-                        fillColor: { type: 'string', description: 'Highlight fill color' },
-                        strokeColor: { type: 'string', description: 'Highlight stroke color' },
-                        strokeWidth: { type: 'number', description: 'Highlight stroke width' },
-                        animate: { type: 'boolean', description: 'Animate the highlight transition' },
-                    },
-                    description: 'Highlight styling options',
-                },
+                action: { type: 'string', enum: ['highlight', 'unhighlight', 'apply_colors', 'add_marker', 'add_labels', 'get_at_point', 'select', 'deselect', 'get_highlighted'], description: 'Region action' },
+                regionIds: { type: 'array', items: { type: 'string' } },
+                color: { type: 'string' },
+                opacity: { type: 'number' },
+                data: { type: 'object', description: 'Region → value (apply_colors)', additionalProperties: true },
+                options: { type: 'object', additionalProperties: true },
+                lat: { type: 'number' },
+                lon: { type: 'number' },
+                label: { type: 'string' },
+                size: { type: 'number' },
+                regions: { type: 'array', items: { type: 'string' } },
+                style: { type: 'object', additionalProperties: true },
+                formatter: { type: 'string' },
+                x: { type: 'number' },
+                y: { type: 'number' },
             },
-            required: ['regionIds'],
+            required: ['action'],
         },
     },
     {
-        name: 'pinepaper_unhighlight_regions',
+        name: 'pinepaper_map_animation',
         annotations: {
-            title: 'Unhighlight Regions',
+            title: 'Map: Region Animations',
             readOnlyHint: false,
             destructiveHint: false,
-            idempotentHint: true,
+            idempotentHint: false,
             openWorldHint: false,
         },
-        description: `Remove highlights from specific regions or all regions on the map.
-
-USE WHEN:
-- Resetting map to original state
-- Removing specific region highlights
-- Cycling through different highlight states
+        description: `Animate map regions with keyframes or wave effects.
 
-EXAMPLES:
-- Remove all highlights: {regionIds: "all"}
-- Remove specific: {regionIds: ["CA", "TX"]}`,
+ACTIONS:
+- animate_regions  — { regions: Record<regionId, keyframes[]>, duration?, loop? }
+- animate_wave     — { regions?: string[], waveDirection?, speed?, color?, duration?, loop? }
+- stop             — { regionIds?: string[] }
+- get_animated     — {}`,
         inputSchema: {
             type: 'object',
             properties: {
-                regionIds: {
-                    oneOf: [
-                        { type: 'array', items: { type: 'string' } },
-                        { type: 'string', enum: ['all'] },
-                    ],
-                    description: 'Region IDs to unhighlight, or "all" for all regions',
-                },
+                action: { type: 'string', enum: ['animate_regions', 'animate_wave', 'stop', 'get_animated'], description: 'Animation action' },
+                regions: { type: 'object', description: 'Keyframes per region (animate_regions) or list (animate_wave)', additionalProperties: true },
+                regionIds: { type: 'array', items: { type: 'string' } },
+                waveDirection: { type: 'string', enum: ['horizontal', 'vertical', 'radial'] },
+                speed: { type: 'number' },
+                color: { type: 'string' },
+                duration: { type: 'number' },
+                loop: { type: 'boolean' },
             },
-            required: ['regionIds'],
+            required: ['action'],
         },
     },
     {
-        name: 'pinepaper_apply_data_colors',
+        name: 'pinepaper_map_data',
         annotations: {
-            title: 'Apply Data Colors',
+            title: 'Map: Data Import + Export',
             readOnlyHint: false,
             destructiveHint: false,
             idempotentHint: true,
             openWorldHint: false,
         },
-        description: `Apply data-driven coloring to map regions (choropleth visualization).
-
-USE WHEN:
-- Visualizing statistics by region (population, GDP, etc.)
-- Creating heat maps
-- Showing data distribution across geography
-- Building infographics with data overlays
-
-COLOR SCALES:
-- blues: Light to dark blue gradient
-- greens: Light to dark green gradient
-- reds: Light to dark red gradient
-- oranges: Light to dark orange gradient
-- purples: Light to dark purple gradient
-- heat: Yellow to red heat map gradient
-
-DATA FORMAT:
-Keys must match region IDs exactly (country names for world maps, state codes for USA).
+        description: `CSV / GeoJSON import-export and source-info introspection.
 
-EXAMPLES:
-- Population data: {data: {"California": 39538223, "Texas": 29145505, "New York": 20201249}, options: {colorScale: "blues", showLegend: true}}
-- GDP heat map: {data: {"United States of America": 21000, "China": 15000, "Japan": 5000}, options: {colorScale: "heat"}}
-- Custom range: {data: {"CA": 85, "TX": 72}, options: {colorScale: "greens", minValue: 0, maxValue: 100}}`,
+ACTIONS:
+- export_csv               — { regionIds?, columns?, download?, filename? }
+- import_csv               — { csv: string, mapping?: { region?, value?, color? } }
+- export_geojson           — { includeStyles?, includeMetadata?, selectedOnly?, download?, filename? }
+- export_original_geojson  — { download?, filename? }   source GeoJSON before styling
+- source_info              — {}                          { source, projection, quality, regionCount, hasOriginalGeoJSON, isCustomImport }`,
         inputSchema: {
             type: 'object',
             properties: {
-                data: {
-                    type: 'object',
-                    additionalProperties: { type: 'number' },
-                    description: 'Object mapping region IDs to numeric values',
-                },
-                options: {
-                    type: 'object',
-                    properties: {
-                        colorScale: {
-                            type: 'string',
-                            enum: ['blues', 'greens', 'reds', 'oranges', 'purples', 'heat'],
-                            description: 'Color scale to use',
-                        },
-                        minValue: { type: 'number', description: 'Minimum value for scale' },
-                        maxValue: { type: 'number', description: 'Maximum value for scale' },
-                        showLegend: { type: 'boolean', description: 'Display color legend' },
-                        legendPosition: {
-                            type: 'string',
-                            enum: ['top-left', 'top-right', 'bottom-left', 'bottom-right'],
-                            description: 'Legend position',
-                        },
-                        legendTitle: { type: 'string', description: 'Title for the legend' },
-                    },
-                    description: 'Choropleth styling options',
-                },
+                action: { type: 'string', enum: ['export_csv', 'import_csv', 'export_geojson', 'export_original_geojson', 'source_info'], description: 'Data action' },
+                regionIds: { type: 'array', items: { type: 'string' } },
+                columns: { type: 'array', items: { type: 'string' } },
+                csv: { type: 'string' },
+                mapping: { type: 'object', additionalProperties: true },
+                includeStyles: { type: 'boolean' },
+                includeMetadata: { type: 'boolean' },
+                selectedOnly: { type: 'boolean' },
+                download: { type: 'boolean' },
+                filename: { type: 'string' },
             },
-            required: ['data'],
+            required: ['action'],
         },
     },
+    // ---------------------------------------------------------------------------
+    // DOMAIN: FONT TOOLS — single action-dispatched tool replaces 16 wrappers
+    // ---------------------------------------------------------------------------
     {
-        name: 'pinepaper_add_marker',
+        name: 'pinepaper_font',
         annotations: {
-            title: 'Add Map Marker',
+            title: 'Font Studio',
             readOnlyHint: false,
             destructiveHint: false,
             idempotentHint: false,
             openWorldHint: false,
         },
-        description: `Add a marker to the map at specified coordinates.
-
-USE WHEN:
-- Marking cities or points of interest
-- Creating location-based visualizations
-- Adding data points with geographic coordinates
-- Building interactive map annotations
-
-MARKER OPTIONS:
-- lat, lon: Geographic coordinates (required)
-- label: Text label for the marker
-- color: Marker color
-- size: Marker size in pixels
-- pulse: Enable animated pulse effect
-- shape: Marker shape (circle, pin, star)
+        description: `Font Studio control — single action-dispatched tool covering the full Studio API. Sixteen previous thin wrappers collapse into this one entry to reduce the tool list footprint without losing capability.
 
-EXAMPLES:
-- City marker: {lat: 37.7749, lon: -122.4194, label: "San Francisco", color: "#ef4444", pulse: true}
-- Simple point: {lat: 40.7128, lon: -74.0060, size: 8, color: "#3b82f6"}
-- Pin marker: {lat: 51.5074, lon: -0.1278, label: "London", shape: "pin"}`,
+ACTIONS:
+- show_studio          — {}                          open the Font Studio UI
+- set_name             — { name }                    name the in-progress font
+- get_required_chars   — { set?: string }            list chars to draw (default: minimum)
+- get_status           — {}                          completion status
+- create_glyph         — { character, pathId }       attach a path as a glyph
+- create_space         — { width? }                  create a space glyph
+- remove_glyph         — { character }
+- set_metrics          — { metrics: { unitsPerEm?, ascender?, descender?, xHeight?, capHeight? } } (or top-level keys)
+- export               — { download?: boolean }      export as OTF
+- load_into_document   — {}                          load the font for use in this canvas
+- export_data          — { download?: boolean }      export as JSON
+- import_data          — { data: object }            import from JSON
+- clear                — {}                          reset everything
+- remove_overlap       — { pathId }                  path cleanup
+- correct_direction    — { pathId }                  path cleanup
+- cleanup_path         — { pathId, removeOverlap?, correctDirection?, smooth?, smoothTolerance? }`,
         inputSchema: {
             type: 'object',
             properties: {
-                lat: { type: 'number', description: 'Latitude' },
-                lon: { type: 'number', description: 'Longitude' },
-                label: { type: 'string', description: 'Marker label text' },
-                color: { type: 'string', description: 'Marker color' },
-                size: { type: 'number', description: 'Marker size in pixels' },
-                pulse: { type: 'boolean', description: 'Enable pulse animation' },
-                shape: {
+                action: {
                     type: 'string',
-                    enum: ['circle', 'pin', 'star'],
-                    description: 'Marker shape',
+                    enum: [
+                        'show_studio', 'set_name', 'get_required_chars', 'get_status',
+                        'create_glyph', 'create_space', 'remove_glyph', 'set_metrics',
+                        'export', 'load_into_document', 'export_data', 'import_data',
+                        'clear', 'remove_overlap', 'correct_direction', 'cleanup_path',
+                    ],
+                    description: 'Font Studio action',
+                },
+                name: { type: 'string', description: 'Font name (set_name)' },
+                set: { type: 'string', description: 'Character set name (get_required_chars; default "minimum")' },
+                character: { type: 'string', description: 'Single-character glyph identifier (create_glyph, remove_glyph)' },
+                pathId: { type: 'string', description: 'Item id of the path source (create_glyph, remove_overlap, correct_direction, cleanup_path)' },
+                width: { type: 'number', description: 'Space-glyph width (create_space)' },
+                download: { type: 'boolean', description: 'Trigger browser download (export, export_data); default true' },
+                metrics: {
+                    type: 'object',
+                    description: 'Font metrics (set_metrics)',
+                    properties: {
+                        unitsPerEm: { type: 'number' },
+                        ascender: { type: 'number' },
+                        descender: { type: 'number' },
+                        xHeight: { type: 'number' },
+                        capHeight: { type: 'number' },
+                    },
                 },
+                data: { type: 'object', description: 'Font JSON payload (import_data)' },
+                removeOverlap: { type: 'boolean', description: 'cleanup_path option' },
+                correctDirection: { type: 'boolean', description: 'cleanup_path option' },
+                smooth: { type: 'boolean', description: 'cleanup_path option (default true)' },
+                smoothTolerance: { type: 'number', description: 'cleanup_path tolerance (default 2.5)' },
             },
-            required: ['lat', 'lon'],
+            required: ['action'],
         },
     },
+    // ---------------------------------------------------------------------------
+    // DOMAIN: LETTER COLLAGE TOOLS (Text Design)
+    // ---------------------------------------------------------------------------
     {
-        name: 'pinepaper_add_map_labels',
+        name: 'pinepaper_create_letter_collage',
         annotations: {
-            title: 'Add Map Labels',
+            title: 'Create Letter Collage',
             readOnlyHint: false,
             destructiveHint: false,
-            idempotentHint: true,
+            idempotentHint: false,
             openWorldHint: false,
         },
-        description: `Add text labels to map regions.
+        description: `Create stylized text with per-letter customization. Perfect for word games, ransom notes, gradient text, and creative typography.
 
 USE WHEN:
-- Labeling countries or states
-- Adding region names to visualizations
-- Creating annotated maps
-- Showing data values on regions
+- Creating Wordle-style word displays
+- Making magazine cutout/ransom note text
+- Designing gradient-filled text
+- Building creative typography effects
+- Creating paper craft style lettering
 
-LABEL TYPES:
-- name: Full region name
-- code: Region code (e.g., "CA" for California)
-- value: Data value (if applyDataColors was used)
+STYLE TYPES:
+- tile: Wordle/Scrabble colored backgrounds (use with tile palettes)
+- magazine: Mixed fonts/colors like cutouts
+- paperCut: Shadow/depth like cut paper
+- fold: Origami-style folded letters
+- gradient: Each letter with gradient fill (use with gradient palettes)
+- image: Letters filled with image
 
-EXAMPLES:
-- Label all visible: {options: {fontSize: 10, fontColor: "#374151"}}
-- Label specific regions: {regions: ["California", "Texas"], options: {labelType: "code"}}
-- Show data values: {options: {labelType: "value", fontSize: 12}}`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                regions: {
-                    type: 'array',
-                    items: { type: 'string' },
-                    description: 'Specific regions to label (null for all visible)',
-                },
-                options: {
-                    type: 'object',
-                    properties: {
-                        fontSize: { type: 'number', description: 'Label font size' },
-                        fontColor: { type: 'string', description: 'Label text color' },
-                        labelType: {
-                            type: 'string',
-                            enum: ['name', 'code', 'value'],
-                            description: 'Type of label content',
-                        },
-                        backgroundColor: { type: 'string', description: 'Label background color' },
-                    },
-                    description: 'Label styling options',
-                },
-            },
-        },
-    },
-    {
-        name: 'pinepaper_pan_map',
-        annotations: {
-            title: 'Pan Map',
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-        description: `Pan the map view to center on specific coordinates.
-
-USE WHEN:
-- Navigating to a specific location
-- Creating animated map transitions
-- Focusing on a region of interest
-
-EXAMPLES:
-- Pan to New York: {lat: 40.7128, lon: -74.0060}
-- Pan to Europe: {lat: 50, lon: 10}`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                lat: { type: 'number', description: 'Target latitude' },
-                lon: { type: 'number', description: 'Target longitude' },
-                animate: { type: 'boolean', description: 'Animate the pan transition' },
-                duration: { type: 'number', description: 'Animation duration in seconds' },
-            },
-            required: ['lat', 'lon'],
-        },
-    },
-    {
-        name: 'pinepaper_zoom_map',
-        annotations: {
-            title: 'Zoom Map',
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-        description: `Set the map zoom level.
-
-USE WHEN:
-- Zooming in on specific areas
-- Creating zoom animations
-- Adjusting map scale
-
-ZOOM LEVELS:
-- 1: Full view (default)
-- 2-5: Moderate zoom
-- 5+: Close-up view
-
-EXAMPLES:
-- Zoom in: {level: 2}
-- Animated zoom: {level: 3, animate: true, duration: 1}`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                level: { type: 'number', description: 'Zoom level (1 = full view)' },
-                animate: { type: 'boolean', description: 'Animate the zoom transition' },
-                duration: { type: 'number', description: 'Animation duration in seconds' },
-            },
-            required: ['level'],
-        },
-    },
-    {
-        name: 'pinepaper_export_map',
-        annotations: {
-            title: 'Export Map',
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-        description: `Export the current map configuration and state.
-
-USE WHEN:
-- Saving map state for later restoration
-- Exporting map data for external use
-- Creating shareable map configurations
-
-RETURNS:
-- mapId: Current map identifier
-- projection: Active projection
-- regions: Region states and highlights
-- markers: All added markers
-- dataColors: Applied data coloring configuration`,
-        inputSchema: {
-            type: 'object',
-            properties: {},
-        },
-    },
-    {
-        name: 'pinepaper_import_custom_map',
-        annotations: {
-            title: 'Import Custom Map',
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: true,
-        },
-        description: `Import a custom GeoJSON or TopoJSON map.
-
-USE WHEN:
-- Loading custom geographic boundaries
-- Using detailed country/region maps from GADM
-- Importing custom shapes or territories
-- Working with non-standard geographic data
-
-SUPPORTED FORMATS:
-- GeoJSON: Standard geographic JSON format
-- TopoJSON: Compressed topology format
-
-SOURCES:
-- GADM: Detailed country subdivisions (gadm.org)
-- Natural Earth: Public domain maps (naturalearthdata.com)
-- Census: Official boundary files
-- Custom: Your own GeoJSON files
-
-EXAMPLES:
-- Import from URL: {url: "https://example.com/custom.geojson", options: {projection: "mercator"}}
-- Import GeoJSON object: {geoJson: {...}, options: {projection: "naturalEarth"}}`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                url: { type: 'string', description: 'URL to GeoJSON/TopoJSON file' },
-                geoJson: {
-                    type: 'object',
-                    description: 'GeoJSON object to import directly',
-                },
-                options: {
-                    type: 'object',
-                    properties: {
-                        projection: {
-                            type: 'string',
-                            enum: ['mercator', 'equalEarth', 'naturalEarth', 'orthographic', 'albers', 'stereographic'],
-                            description: 'Projection to use for rendering',
-                        },
-                        fillColor: { type: 'string' },
-                        strokeColor: { type: 'string' },
-                        strokeWidth: { type: 'number' },
-                    },
-                    description: 'Import options',
-                },
-            },
-        },
-    },
-    {
-        name: 'pinepaper_get_region_at_point',
-        annotations: {
-            title: 'Get Region at Point',
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-        description: `[Utility] Get the region at a specific canvas point (hit testing).
-
-USE WHEN:
-- Implementing click interactions
-- Finding which region is at a coordinate
-- Building interactive map features
-
-EXAMPLES:
-- Check point: {x: 400, y: 300}
-
-RETURNS:
-- regionId: ID of the region at point (or null)
-- regionName: Display name
-- properties: Region properties from GeoJSON`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                x: { type: 'number', description: 'Canvas X coordinate' },
-                y: { type: 'number', description: 'Canvas Y coordinate' },
-            },
-            required: ['x', 'y'],
-        },
-    },
-    {
-        name: 'pinepaper_animate_map_regions',
-        annotations: {
-            title: 'Animate Map Regions',
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-        description: `Animate specific map regions with timeline-integrated keyframe color animations.
-
-USE WHEN:
-- Creating animated choropleth transitions
-- Showing data changes over time
-- Building story-based map visualizations
-- Adding visual emphasis to regions
-
-KEYFRAME PROPERTIES:
-- time: Time in seconds for this keyframe
-- fillColor: Fill color at this keyframe (required)
-- strokeColor: Optional stroke color
-- opacity: Optional opacity (0-1)
-
-EXAMPLES:
-- Simple color transition: {duration: 5, loop: true, regions: {"USA": [{"time": 0, "fillColor": "#ef4444"}, {"time": 5, "fillColor": "#22c55e"}]}}
-- Multi-region animation: {duration: 8, regions: {"USA": [...], "France": [...], "Japan": [...]}}`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                duration: {
-                    type: 'number',
-                    description: 'Total animation duration in seconds (default: 5)',
-                },
-                loop: {
-                    type: 'boolean',
-                    description: 'Loop the animation (default: true)',
-                },
-                regions: {
-                    type: 'object',
-                    additionalProperties: {
-                        type: 'array',
-                        items: {
-                            type: 'object',
-                            properties: {
-                                time: { type: 'number', description: 'Time in seconds' },
-                                fillColor: { type: 'string', description: 'Fill color at this keyframe' },
-                                strokeColor: { type: 'string', description: 'Stroke color (optional)' },
-                                opacity: { type: 'number', description: 'Opacity 0-1 (optional)' },
-                            },
-                            required: ['time', 'fillColor'],
-                        },
-                    },
-                    description: 'Object mapping region IDs to arrays of keyframes',
-                },
-            },
-            required: ['regions'],
-        },
-    },
-    {
-        name: 'pinepaper_animate_map_wave',
-        annotations: {
-            title: 'Animate Map Wave',
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-        description: `Create a wave animation across all map regions based on geographic position.
-
-USE WHEN:
-- Creating dramatic visual effects
-- Showing global spread patterns
-- Adding ambient map animations
-- Building attention-grabbing transitions
-
-WAVE DIRECTIONS:
-- horizontal: Wave sweeps left to right
-- vertical: Wave sweeps top to bottom
-- radial: Wave radiates from center outward
-
-EXAMPLES:
-- Rainbow wave: {duration: 10, colors: ["#ef4444", "#fbbf24", "#22c55e", "#3b82f6"], waveDirection: "horizontal"}
-- Fast radial pulse: {duration: 3, colors: ["#ffffff", "#3b82f6"], waveDirection: "radial", loop: true}`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                duration: {
-                    type: 'number',
-                    description: 'Total wave duration in seconds (default: 10)',
-                },
-                loop: {
-                    type: 'boolean',
-                    description: 'Loop the animation (default: true)',
-                },
-                colors: {
-                    type: 'array',
-                    items: { type: 'string' },
-                    description: 'Array of colors for the wave (default: red, yellow, green, blue)',
-                },
-                waveDirection: {
-                    type: 'string',
-                    enum: ['horizontal', 'vertical', 'radial'],
-                    description: 'Direction of the wave effect (default: horizontal)',
-                },
-            },
-        },
-    },
-    {
-        name: 'pinepaper_stop_map_animations',
-        annotations: {
-            title: 'Stop Map Animations',
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-        description: `Stop all or specific map region animations.
-
-USE WHEN:
-- Ending animated sequences
-- Resetting map to static state
-- Pausing for user interaction
-- Transitioning to different visualization
-
-EXAMPLES:
-- Stop all: {}
-- Stop specific regions: {regions: ["USA", "France"]}
-- Stop and reset colors: {resetColors: true}`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                regions: {
-                    type: 'array',
-                    items: { type: 'string' },
-                    description: 'Specific region IDs to stop (omit for all)',
-                },
-                resetColors: {
-                    type: 'boolean',
-                    description: 'Reset regions to default colors (default: true)',
-                },
-            },
-        },
-    },
-    {
-        name: 'pinepaper_get_animated_map_regions',
-        annotations: {
-            title: 'Get Animated Map Regions',
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-        description: `[Utility] Get list of currently animated map regions with their animation data.
-
-USE WHEN:
-- Debugging animations
-- Checking animation state
-- Building animation controls
-- Inspecting current timeline
-
-RETURNS:
-- animatedRegions: Array of region animation info
-- count: Total number of animated regions`,
-        inputSchema: {
-            type: 'object',
-            properties: {},
-        },
-    },
-    {
-        name: 'pinepaper_export_map_region_csv',
-        annotations: {
-            title: 'Export Map Region CSV',
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-        description: `Export map region data as CSV including colors, highlight, and selection status.
-
-USE WHEN:
-- Saving map state for later
-- Creating data-driven workflows
-- Integrating with spreadsheet tools
-- Building export features
-
-CSV COLUMNS:
-- regionId: Region identifier
-- name: Display name
-- highlighted: 1 or 0
-- selected: 1 or 0
-- fillColor: Current fill color
-- strokeColor: Current stroke color
-
-EXAMPLES:
-- Full export: {}
-- Colors only: {includeHighlighted: false, includeSelected: false}
-- Auto-download: {download: true, filename: "map-export.csv"}`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                includeHighlighted: {
-                    type: 'boolean',
-                    description: 'Include highlight status column (default: true)',
-                },
-                includeSelected: {
-                    type: 'boolean',
-                    description: 'Include selection status column (default: true)',
-                },
-                includeColors: {
-                    type: 'boolean',
-                    description: 'Include fill/stroke color columns (default: true)',
-                },
-                download: {
-                    type: 'boolean',
-                    description: 'Auto-download the CSV file (default: false)',
-                },
-                filename: {
-                    type: 'string',
-                    description: 'Filename for download (default: map-regions.csv)',
-                },
-            },
-        },
-    },
-    {
-        name: 'pinepaper_import_map_region_csv',
-        annotations: {
-            title: 'Import Map Region CSV',
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-        description: `Import CSV data to update map region states (colors, highlight, selection).
-
-USE WHEN:
-- Restoring saved map state
-- Applying data from spreadsheets
-- Batch updating region properties
-- Building data-driven visualizations
-
-CSV FORMAT:
-Must have 'regionId' column. Optional columns:
-- fillColor: Hex color for fill
-- strokeColor: Hex color for stroke
-- highlighted: 1 or 0
-- selected: 1 or 0
-
-EXAMPLES:
-- Import full CSV: {csvText: "regionId,fillColor,highlighted\\nUSA,#22c55e,1\\nFrance,#3b82f6,0"}
-- Colors only: {csvText: "...", applyHighlight: false, applySelection: false}`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                csvText: {
-                    type: 'string',
-                    description: 'CSV text content to import',
-                },
-                applyColors: {
-                    type: 'boolean',
-                    description: 'Apply fill/stroke colors from CSV (default: true)',
-                },
-                applyHighlight: {
-                    type: 'boolean',
-                    description: 'Update highlight status from CSV (default: true)',
-                },
-                applySelection: {
-                    type: 'boolean',
-                    description: 'Update selection status from CSV (default: true)',
-                },
-            },
-            required: ['csvText'],
-        },
-    },
-    {
-        name: 'pinepaper_select_map_regions',
-        annotations: {
-            title: 'Select Map Regions',
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-        description: `Programmatically select map regions.
-
-USE WHEN:
-- Building interactive map features
-- Responding to user input
-- Creating selection-based workflows
-- Highlighting user choices
-
-EXAMPLES:
-- Select countries: {regionIds: ["USA", "Canada", "Mexico"]}
-- Select US states: {regionIds: ["CA", "TX", "NY"]}`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                regionIds: {
-                    type: 'array',
-                    items: { type: 'string' },
-                    description: 'Array of region IDs to select',
-                },
-            },
-            required: ['regionIds'],
-        },
-    },
-    {
-        name: 'pinepaper_deselect_map_regions',
-        annotations: {
-            title: 'Deselect Map Regions',
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-        description: `Programmatically deselect map regions.
-
-USE WHEN:
-- Clearing user selections
-- Resetting map state
-- Implementing toggle behavior
-- Building selection management
-
-EXAMPLES:
-- Deselect specific: {regionIds: ["USA", "France"]}
-- Deselect all: {} (omit regionIds)`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                regionIds: {
-                    type: 'array',
-                    items: { type: 'string' },
-                    description: 'Array of region IDs to deselect (omit for all)',
-                },
-            },
-        },
-    },
-    {
-        name: 'pinepaper_get_highlighted_map_regions',
-        annotations: {
-            title: 'Get Highlighted Map Regions',
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-        description: `[Utility] Get list of currently highlighted map regions.
-
-USE WHEN:
-- Checking current highlight state
-- Building conditional logic
-- Creating highlight summaries
-- Debugging map state
-
-RETURNS:
-- highlighted: Array of highlighted region IDs
-- count: Total number of highlighted regions`,
-        inputSchema: {
-            type: 'object',
-            properties: {},
-        },
-    },
-    {
-        name: 'pinepaper_export_map_geojson',
-        annotations: {
-            title: 'Export Map GeoJSON',
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-        description: `Export the current map as GeoJSON (with current colors/modifications).
-
-USE WHEN:
-- Saving map state with custom styling
-- Exporting for use in other mapping tools
-- Creating styled GeoJSON for external applications
-- Archiving map customizations
-
-EXAMPLES:
-- Export with styles: {includeStyles: true}
-- Selected regions only: {selectedOnly: true}
-- Auto-download: {download: true, filename: "my-map.geojson"}`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                includeStyles: {
-                    type: 'boolean',
-                    description: 'Include fill/stroke colors as properties (default: true)',
-                },
-                includeMetadata: {
-                    type: 'boolean',
-                    description: 'Include region names and IDs (default: true)',
-                },
-                selectedOnly: {
-                    type: 'boolean',
-                    description: 'Only export selected regions (default: false)',
-                },
-                download: {
-                    type: 'boolean',
-                    description: 'Auto-download the file (default: false)',
-                },
-                filename: {
-                    type: 'string',
-                    description: 'Filename for download (default: "map-export.geojson")',
-                },
-            },
-        },
-    },
-    {
-        name: 'pinepaper_export_original_map_geojson',
-        annotations: {
-            title: 'Export Original Map GeoJSON',
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-        description: `Export the original source GeoJSON (unmodified boundaries). Returns the exact data used to load the map, allowing users to edit boundaries externally and re-import.
-
-USE WHEN:
-- Extracting original map data for external editing
-- Getting clean boundaries without customizations
-- Creating a baseline for map modifications
-- Re-importing after external boundary edits
-
-EXAMPLES:
-- Get original data: {}
-- Auto-download: {download: true, filename: "map-source.geojson"}`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                download: {
-                    type: 'boolean',
-                    description: 'Auto-download the file (default: false)',
-                },
-                filename: {
-                    type: 'string',
-                    description: 'Filename for download (default: "map-source.geojson")',
-                },
-            },
-        },
-    },
-    {
-        name: 'pinepaper_get_map_source_info',
-        annotations: {
-            title: 'Get Map Source Info',
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-        description: `[Utility] Get information about the currently loaded map source.
-
-USE WHEN:
-- Checking what map is currently loaded
-- Debugging map loading issues
-- Getting map metadata
-- Verifying map configuration
-
-RETURNS:
-- source: Map source identifier (e.g., "world", "worldHighRes", "usa", or custom)
-- projection: Current projection type
-- quality: Rendering quality setting
-- regionCount: Total number of regions
-- hasOriginalGeoJSON: Whether original GeoJSON is available
-- isCustomImport: Whether this is a custom imported map`,
-        inputSchema: {
-            type: 'object',
-            properties: {},
-        },
-    },
-    // ---------------------------------------------------------------------------
-    // DOMAIN: FONT TOOLS
-    // ---------------------------------------------------------------------------
-    {
-        name: 'pinepaper_font_show_studio',
-        annotations: {
-            title: 'Font Show Studio',
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-        description: `Open the Font Studio UI for interactive font creation.
-
-USE WHEN:
-- Starting a custom font creation workflow
-- Need the interactive Font Studio interface with guide lines
-- Want to create a hand-drawn font from scratch
-
-WORKFLOW:
-1. Open Font Studio → pinepaper_font_show_studio
-2. Set font name → pinepaper_font_set_name
-3. Check required chars → pinepaper_font_get_required_chars
-4. For each character: draw path, cleanup, create glyph
-5. Check progress → pinepaper_font_get_status
-6. Export when complete → pinepaper_font_export`,
-        inputSchema: {
-            type: 'object',
-            properties: {},
-        },
-    },
-    {
-        name: 'pinepaper_font_set_name',
-        annotations: {
-            title: 'Font Set Name',
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-        description: `Set the font family name for the current font being created.`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                name: {
-                    type: 'string',
-                    description: "Font family name (e.g., 'MyHandwriting')",
-                },
-            },
-            required: ['name'],
-        },
-    },
-    {
-        name: 'pinepaper_font_get_required_chars',
-        annotations: {
-            title: 'Font Get Required Chars',
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-        description: `Get the list of characters needed for a complete font.
-
-CHARACTER SETS:
-- minimum: A-Z, a-z, 0-9, space (63 chars) - enough for basic text
-- standard: adds punctuation and symbols (90+ chars) - full typography`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                set: {
-                    type: 'string',
-                    enum: ['minimum', 'standard'],
-                    description: 'minimum: A-Z, a-z, 0-9, space (63 chars). standard: adds punctuation (90+ chars)',
-                },
-            },
-        },
-    },
-    {
-        name: 'pinepaper_font_get_status',
-        annotations: {
-            title: 'Font Get Status',
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-        description: `Get font completion status including progress percentage, completed/pending characters.
-
-USE WHEN:
-- Checking progress during font creation
-- Determining which characters still need to be drawn
-- Verifying font is complete before export`,
-        inputSchema: {
-            type: 'object',
-            properties: {},
-        },
-    },
-    {
-        name: 'pinepaper_font_create_glyph',
-        annotations: {
-            title: 'Font Create Glyph',
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-        description: `Create a glyph from a Paper.js path. Converts a drawn path into an OpenType glyph with calculated advance width.
-
-USE WHEN:
-- Converting a drawn character path to a font glyph
-- Adding a new character to the font
-
-WORKFLOW:
-1. Draw the character as a Paper.js path on the canvas
-2. Optionally clean up the path (pinepaper_font_cleanup_path)
-3. Use the path's registry ID to create the glyph`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                character: {
-                    type: 'string',
-                    description: "Single character (e.g., 'A', 'a', '1', ' ')",
-                },
-                pathId: {
-                    type: 'string',
-                    description: 'Registry ID of the Paper.js path to use as glyph shape',
-                },
-            },
-            required: ['character', 'pathId'],
-        },
-    },
-    {
-        name: 'pinepaper_font_create_space',
-        annotations: {
-            title: 'Font Create Space',
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-        description: `Create the space glyph (no visible shape, just advance width).
-
-USE WHEN:
-- Adding the space character to the font
-- Space needs no drawn path, only a width value`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                width: {
-                    type: 'number',
-                    description: 'Space width in font units (default: 250)',
-                },
-            },
-        },
-    },
-    {
-        name: 'pinepaper_font_remove_glyph',
-        annotations: {
-            title: 'Font Remove Glyph',
-            readOnlyHint: false,
-            destructiveHint: true,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-        description: `Remove a glyph from the font. Use when a character needs to be redrawn.`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                character: {
-                    type: 'string',
-                    description: 'Character to remove',
-                },
-            },
-            required: ['character'],
-        },
-    },
-    {
-        name: 'pinepaper_font_set_metrics',
-        annotations: {
-            title: 'Font Set Metrics',
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-        description: `Set font metrics (advanced). Controls the coordinate grid and vertical measurements.
-
-METRICS:
-- unitsPerEm: Coordinate grid size (default: 1000)
-- ascender: Height above baseline (default: 800)
-- descender: Depth below baseline, negative (default: -200)
-- xHeight: Lowercase letter height (default: 500)
-- capHeight: Capital letter height (default: 700)`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                unitsPerEm: {
-                    type: 'number',
-                    description: 'Coordinate grid size (default: 1000)',
-                },
-                ascender: {
-                    type: 'number',
-                    description: 'Height above baseline (default: 800)',
-                },
-                descender: {
-                    type: 'number',
-                    description: 'Depth below baseline, negative (default: -200)',
-                },
-                xHeight: {
-                    type: 'number',
-                    description: 'Lowercase letter height (default: 500)',
-                },
-                capHeight: {
-                    type: 'number',
-                    description: 'Capital letter height (default: 700)',
-                },
-            },
-        },
-    },
-    {
-        name: 'pinepaper_font_export',
-        annotations: {
-            title: 'Font Export',
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-        description: `Export the font as an OTF file. Triggers browser download of the completed font.
-
-USE WHEN:
-- Font is complete and ready for download
-- User wants to save the font as a file`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                download: {
-                    type: 'boolean',
-                    description: 'Trigger browser download (default: true)',
-                },
-            },
-        },
-    },
-    {
-        name: 'pinepaper_font_load_into_document',
-        annotations: {
-            title: 'Font Load Into Document',
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-        description: `Load the custom font into the document for immediate use in PinePaper text items.
-
-USE WHEN:
-- Want to use the created font immediately in the current document
-- Testing how the font looks in actual text items`,
-        inputSchema: {
-            type: 'object',
-            properties: {},
-        },
-    },
-    {
-        name: 'pinepaper_font_export_data',
-        annotations: {
-            title: 'Font Export Data',
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-        description: `Export font data as JSON for saving progress. Use to save work-in-progress fonts.
-
-USE WHEN:
-- Saving font progress for later continuation
-- Backing up font data`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                download: {
-                    type: 'boolean',
-                    description: 'Trigger browser download (default: true)',
-                },
-            },
-        },
-    },
-    {
-        name: 'pinepaper_font_import_data',
-        annotations: {
-            title: 'Font Import Data',
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-        description: `Import font data from previously saved JSON. Restores a font from exported data.
-
-USE WHEN:
-- Resuming work on a previously saved font
-- Loading font data exported with pinepaper_font_export_data`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                data: {
-                    type: 'object',
-                    description: 'Font data object from pinepaper_font_export_data',
-                },
-            },
-            required: ['data'],
-        },
-    },
-    {
-        name: 'pinepaper_font_clear',
-        annotations: {
-            title: 'Font Clear',
-            readOnlyHint: false,
-            destructiveHint: true,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-        description: `Clear all glyphs and reset the font. Removes all drawn characters.
-
-WARNING: This is destructive - all glyph progress will be lost.`,
-        inputSchema: {
-            type: 'object',
-            properties: {},
-        },
-    },
-    {
-        name: 'pinepaper_font_remove_overlap',
-        annotations: {
-            title: 'Font Remove Overlap',
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-        description: `Remove overlapping areas from a path (like FontForge's RemoveOverlap). Merges multiple overlapping paths into a single clean outline.
-
-USE WHEN:
-- Path has overlapping strokes that need merging
-- Preparing a glyph path for clean font output`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                pathId: {
-                    type: 'string',
-                    description: 'Registry ID of the Paper.js path to process',
-                },
-            },
-            required: ['pathId'],
-        },
-    },
-    {
-        name: 'pinepaper_font_correct_direction',
-        annotations: {
-            title: 'Font Correct Direction',
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-        description: `Correct path winding direction for proper fill rendering (like FontForge's CorrectDirection). Ensures outer contours are clockwise and inner holes are counter-clockwise.
-
-USE WHEN:
-- Glyph fills are rendering incorrectly (holes appear filled)
-- Preparing paths for font export`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                pathId: {
-                    type: 'string',
-                    description: 'Registry ID of the Paper.js path to process',
-                },
-            },
-            required: ['pathId'],
-        },
-    },
-    {
-        name: 'pinepaper_font_cleanup_path',
-        annotations: {
-            title: 'Font Cleanup Path',
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-        description: `Apply all path cleanup operations in the correct order: removeOverlap -> correctDirection -> smooth. Convenience tool that combines all path preparation steps.
-
-USE WHEN:
-- Preparing a drawn path before creating a glyph
-- Quick one-step path cleanup instead of calling individual operations`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                pathId: {
-                    type: 'string',
-                    description: 'Registry ID of the Paper.js path to process',
-                },
-                removeOverlap: {
-                    type: 'boolean',
-                    description: 'Merge overlapping strokes (default: true)',
-                },
-                correctDirection: {
-                    type: 'boolean',
-                    description: 'Fix winding direction for fills (default: true)',
-                },
-                smooth: {
-                    type: 'boolean',
-                    description: 'Apply path smoothing (default: true)',
-                },
-                smoothTolerance: {
-                    type: 'number',
-                    description: 'Smoothing tolerance - higher = more simplification (default: 2.5)',
-                },
-            },
-            required: ['pathId'],
-        },
-    },
-    // ---------------------------------------------------------------------------
-    // DOMAIN: LETTER COLLAGE TOOLS (Text Design)
-    // ---------------------------------------------------------------------------
-    {
-        name: 'pinepaper_create_letter_collage',
-        annotations: {
-            title: 'Create Letter Collage',
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-        description: `Create stylized text with per-letter customization. Perfect for word games, ransom notes, gradient text, and creative typography.
-
-USE WHEN:
-- Creating Wordle-style word displays
-- Making magazine cutout/ransom note text
-- Designing gradient-filled text
-- Building creative typography effects
-- Creating paper craft style lettering
-
-STYLE TYPES:
-- tile: Wordle/Scrabble colored backgrounds (use with tile palettes)
-- magazine: Mixed fonts/colors like cutouts
-- paperCut: Shadow/depth like cut paper
-- fold: Origami-style folded letters
-- gradient: Each letter with gradient fill (use with gradient palettes)
-- image: Letters filled with image
-
-TILE PALETTES:
-- Game: wordle, scrabble
-- Vibrant: candy, neon, rainbow
-- Soft: pastel, cotton
-- Natural: earth, ocean, forest, sunset
-- Professional: corporate, minimal, slate
-- Seasonal: christmas, halloween, spring
-- Magazine: magazine, newspaper, vintage
-- Paper Craft: paperCraft, origami, craftPaper
-
-GRADIENT PALETTES:
-rainbow, sunset, ocean, fire, gold, rose, ice, cyberpunk, neonGlow, purplePink
-
-EXAMPLES:
-- Wordle style: {text: "HELLO", style: "tile", palette: "wordle"}
-- Ransom note: {text: "SECRET", style: "magazine", palette: "newspaper"}
-- Gradient text: {text: "RAINBOW", style: "gradient", gradientPalette: "rainbow"}
-- Neon style: {text: "GLOW", style: "tile", palette: "neon"}`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                text: {
-                    type: 'string',
-                    description: 'The text to stylize',
-                },
-                style: {
-                    type: 'string',
-                    enum: ['tile', 'magazine', 'paperCut', 'fold', 'gradient', 'image'],
-                    description: 'Style type (default: tile)',
-                },
-                palette: {
-                    type: 'string',
-                    enum: [
-                        'wordle', 'scrabble',
-                        'candy', 'neon', 'rainbow',
-                        'pastel', 'cotton',
-                        'earth', 'ocean', 'forest', 'sunset',
-                        'corporate', 'minimal', 'slate',
-                        'christmas', 'halloween', 'spring',
-                        'magazine', 'newspaper', 'vintage',
-                        'paperCraft', 'origami', 'craftPaper',
-                    ],
-                    description: 'Color palette for tile/magazine styles',
-                },
-                position: {
-                    type: 'object',
-                    properties: {
-                        x: { type: 'number' },
-                        y: { type: 'number' },
-                    },
-                    description: 'Position on canvas (defaults to center)',
-                },
-                fontSize: {
-                    type: 'number',
-                    description: 'Base font size in pixels (default: 48)',
-                },
-                fontFamily: {
-                    type: 'string',
-                    description: 'Font family (default: Inter, sans-serif)',
-                },
-                spacing: {
-                    type: 'number',
-                    description: 'Letter spacing multiplier (default: 1.1)',
-                },
-                gradientPalette: {
-                    type: 'string',
-                    enum: ['rainbow', 'sunset', 'ocean', 'fire', 'gold', 'rose', 'ice', 'cyberpunk', 'neonGlow', 'purplePink'],
-                    description: 'Gradient palette (for style="gradient")',
-                },
-                gradientDirection: {
-                    type: 'string',
-                    enum: ['vertical', 'horizontal', 'diagonal', 'radial'],
-                    description: 'Gradient direction (default: vertical)',
-                },
-                cornerRadius: {
-                    type: 'number',
-                    description: 'Corner radius for tile backgrounds (default: 4)',
-                },
-                shadowEnabled: {
-                    type: 'boolean',
-                    description: 'Enable drop shadows (default: true)',
-                },
-            },
-            required: ['text'],
-        },
-    },
-    {
-        name: 'pinepaper_animate_letter_collage',
-        annotations: {
-            title: 'Animate Letter Collage',
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-        description: `Apply animation to all letters in a collage with staggered timing.
-
-USE WHEN:
-- Adding entrance animations to text
-- Creating typewriter-style reveals
-- Making text bounce or pulse
-- Adding dynamic effects to lettering
-
-ANIMATION TYPES:
-- pulse: Scale up and down rhythmically
-- bounce: Bouncing motion
-- fade: Fade in/out
-- wobble: Side-to-side wobble
-- rotate: Spinning rotation
-
-STAGGER EFFECT:
-Use staggerDelay to create wave-like animations where each letter starts slightly after the previous one. 0.1s is a good default for smooth wave effects.
-
-EXAMPLES:
-- Wave entrance: {collageId: "collage_1", animationType: "bounce", staggerDelay: 0.1}
-- Pulsing text: {collageId: "collage_1", animationType: "pulse", staggerDelay: 0.05}
-- Fast typewriter: {collageId: "collage_1", animationType: "fade", staggerDelay: 0.15}`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                collageId: {
-                    type: 'string',
-                    description: 'Collage ID from create_letter_collage',
-                },
-                animationType: {
-                    type: 'string',
-                    enum: ['pulse', 'bounce', 'fade', 'wobble', 'rotate'],
-                    description: 'Animation type to apply',
-                },
-                staggerDelay: {
-                    type: 'number',
-                    description: 'Delay between each letter animation start in seconds (default: 0.1)',
-                },
-                animationSpeed: {
-                    type: 'number',
-                    description: 'Animation speed multiplier (default: 1)',
-                },
-            },
-            required: ['collageId', 'animationType'],
-        },
-    },
-    {
-        name: 'pinepaper_get_letter_collage_options',
-        annotations: {
-            title: 'Get Letter Collage Options',
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-        description: `[Utility] Get available styles, palettes, and gradient options for letter collages.
-
-USE WHEN:
-- Learning available letter collage styles
-- Discovering palette options
-- Exploring gradient possibilities
-- Building UI for collage creation
-
-RETURNS:
-- styles: All available style types
-- tilePalettes: Grouped by category (game, vibrant, soft, natural, etc.)
-- gradientPalettes: Available gradient color schemes
-- gradientDirections: Direction options for gradients`,
-        inputSchema: {
-            type: 'object',
-            properties: {},
-        },
-    },
-    // ---------------------------------------------------------------------------
-    // DOMAIN: GENERATOR TOOLS
-    // ---------------------------------------------------------------------------
-    {
-        name: 'pinepaper_execute_generator',
-        annotations: {
-            title: 'Execute Generator',
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-        description: `Execute a background generator to create procedural patterns.
-
-USE WHEN:
-- "add a sunburst background", "bokeh effect", "gradient mesh"
-- "create wave pattern", "wind field", "fluid flow"
-- "grid background", "geometric abstract", "noise texture"
-- Creating dynamic procedural backgrounds
-
-GENERATORS (15 total):
-
-Classic:
-- drawSunburst: Radial rays from center (rayCount, colors, bgColor, opacity, rayGap, gradientRays)
-- drawSunsetScene: Animated sunset with clouds (sunColor, skyColors, cloudCount, skyOpacity, starCount, starColor, reflectionEnabled, reflectionOpacity)
-- drawGrid: Lines/dots/squares (gridType, spacing, lineColor, opacity, gap, randomRotation, colorMode: checkerboard|gradient|random|rows|columns, strokeColor, strokeWidth)
-- drawStackedCircles: Overlapping circles (count, colors, distribution: random|poisson|golden, opacityMin, opacityMax, blendMode, strokeWidth, strokeColor, sizeGradient, animationType: pulse|float|none)
-- drawCircuit: Tech circuit board (lineColor, nodeColor, density, traceOpacity, nodeOpacity, diagonalPaths, chipDensity: auto|none|low|medium|high)
-- drawWaves: Layered wave pattern (waveCount, colors, amplitude, frequency, opacity, fill, fillOpacity, amplitudeVariation, blendMode)
-- drawPattern: Geometric shapes in orbit (patternType, size, color, opacity, blendMode, layers: 1-5, layerScaleDecay)
-
-New — Effects:
-- drawBokeh: Soft-focus circles (count, colors, minRadius, maxRadius, shadowBlur, distribution: random|poisson, driftAnimation)
-
-New — Organic:
-- drawGradientMesh: Radial gradient blobs with screen blending (colors, blobCount, blendMode, drift)
-- drawFluidFlow: Sinusoidal stream paths with depth (streamCount, colors, depthLayers, speed)
-- drawOrganicFlow: Aurora/silk layers with fill-to-bottom (layerCount, colors, blendMode, fillToBottom)
-
-New — Geometric:
-- drawGeometricAbstract: Mixed translucent shapes (colors, shapeCount, blendMode, rotation)
-
-New — Particles:
-- drawWindField: Directional wind particles with noise turbulence (particleCount, colors, direction, turbulence, trailLength, speed)
-
-New — Textures:
-- drawNoiseTexture: Perlin/grain/stipple noise (noiseType: perlin|grain|stipple, colors, scale, density, animated)
-
-New — Tech:
-- drawGlobeWireframe: Vercel-style wireframe globe (bgColor, wireColor, glowColor, highlightColor, meridianCount, latitudeCount, globeRadius, nodeCount, nodeSize, animationEnabled, animationSpeed, strokeWidth, gridOpacity)`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                generatorName: {
-                    type: 'string',
-                    enum: [
-                        'drawSunburst', 'drawSunsetScene', 'drawGrid', 'drawStackedCircles',
-                        'drawCircuit', 'drawWaves', 'drawPattern',
-                        'drawBokeh', 'drawGradientMesh', 'drawGeometricAbstract', 'drawWindField',
-                        'drawFluidFlow', 'drawOrganicFlow', 'drawNoiseTexture',
-                        'drawGlobeWireframe',
-                    ],
-                    description: 'Generator name',
-                },
-                params: {
-                    type: 'object',
-                    description: 'Generator-specific parameters',
-                    additionalProperties: true,
-                },
-            },
-            required: ['generatorName'],
-        },
-    },
-    {
-        name: 'pinepaper_list_generators',
-        annotations: {
-            title: 'List Generators',
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-        description: `[Utility] Get a list of all available background generators with their parameters.
-
-USE WHEN:
-- User asks "what backgrounds are available?"
-- Need to show generator options
-- Discovering generator capabilities`,
-        inputSchema: {
-            type: 'object',
-            properties: {},
-        },
-    },
-    // ---------------------------------------------------------------------------
-    // DOMAIN: EFFECT TOOLS
-    // ---------------------------------------------------------------------------
-    {
-        name: 'pinepaper_apply_effect',
-        annotations: {
-            title: 'Apply Effect',
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-        description: `Apply a visual effect to an item.
-
-USE WHEN:
-- Adding sparkle/glitter effects
-- Creating burst/explosion, fire, smoke effects
-- Weather effects (rain, snow)
-- Celebration effects (confetti)
-- Enhancing visual impact (ripple, glow, electric)
-
-EFFECTS (10 total):
-- sparkle: Glitter/sparkle particles (color, speed, size)
-- blast: Explosion burst effect (color, radius, count)
-- smoke: Rising smoke plumes (color, speed, size, drift, height, growthRate)
-- fire: Animated fire/flames (color, colors, speed, size, height, turbulence)
-- rain: Falling rain drops (color, count, speed, angle, spread)
-- snow: Falling snowflakes (color, count, speed, spread, particleLife)
-- confetti: Celebration confetti (colors, count, radius, gravity, size, spread, interval, repeat)
-- ripple: Expanding ring ripples (color, speed, maxRadius, ringCount, strokeWidth)
-- glow: Pulsing glow aura (color, speed, intensity, size)
-- electric: Lightning bolts (color, speed, boltCount, length, flickerRate)`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                itemId: { type: 'string', description: 'Registry ID of the item' },
-                effectType: {
-                    type: 'string',
-                    enum: ['sparkle', 'blast', 'smoke', 'fire', 'rain', 'snow', 'confetti', 'ripple', 'glow', 'electric'],
-                    description: 'Type of effect',
-                },
-                params: {
-                    type: 'object',
-                    description: 'Effect parameters',
-                    additionalProperties: true,
-                },
-            },
-            required: ['itemId', 'effectType'],
-        },
-    },
-    // ---------------------------------------------------------------------------
-    // DOMAIN: FILTER TOOLS
-    // ---------------------------------------------------------------------------
-    {
-        name: 'pinepaper_add_filter',
-        annotations: {
-            title: 'Add Filter',
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-        description: `Add a visual filter effect to the canvas. Filters are scene-wide effects that can be stacked.
-
-USE WHEN:
-- User wants visual effects like blur, grayscale, vintage look
-- Creating mood or atmosphere (cinematic, dreamy, noir)
-- Post-processing the entire scene
-- User says "make it look vintage", "add blur", "black and white"
-
-AVAILABLE FILTERS:
-- grayscale: Convert to black and white (params: intensity 0-1)
-- sepia: Warm vintage brownish tone (params: intensity 0-1)
-- blur: Gaussian blur effect (params: radius 0-20)
-- brightness: Adjust brightness (params: value -100 to 100)
-- contrast: Adjust contrast (params: value -100 to 100)
-- saturate: Adjust color saturation (params: value -100 to 100)
-- invert: Invert colors (params: intensity 0-1)
-- noise: Add film grain (params: intensity 0-100, monochrome: true/false)
-- vignette: Darken edges (params: intensity 0-1, radius 0-1)
-- vintage: Preset combining sepia, vignette, noise
-- colorOverlay: Add color tint (params: color, intensity, blendMode)
-- sharpen: Increase sharpness (params: intensity 0-100)
-- posterize: Reduce color levels (params: levels 2-32)
-
-EXAMPLES:
-- "Make it black and white" → filterType: "grayscale"
-- "Add vintage look" → filterType: "vintage", params: {intensity: 0.8}
-- "Blur the background" → filterType: "blur", params: {radius: 5}
-- "Increase contrast" → filterType: "contrast", params: {value: 30}
-
-Filters can be stacked - call multiple times to combine effects.`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                filterType: {
-                    type: 'string',
-                    enum: ['grayscale', 'sepia', 'blur', 'brightness', 'contrast', 'saturate', 'invert', 'noise', 'vignette', 'vintage', 'colorOverlay', 'sharpen', 'posterize'],
-                    description: 'Type of filter to apply',
-                },
-                params: {
-                    type: 'object',
-                    description: 'Filter-specific parameters',
-                    additionalProperties: true,
-                },
-            },
-            required: ['filterType'],
-        },
-    },
-    // ---------------------------------------------------------------------------
-    // DOMAIN: INTERACTIVE TRIGGER TOOLS
-    // ---------------------------------------------------------------------------
-    {
-        name: 'pinepaper_add_trigger',
-        annotations: {
-            title: 'Add Trigger',
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-        description: `Add an interactive trigger to an item. Triggers execute actions when events occur.
+TILE PALETTES:
+- Game: wordle, scrabble
+- Vibrant: candy, neon, rainbow
+- Soft: pastel, cotton
+- Natural: earth, ocean, forest, sunset
+- Professional: corporate, minimal, slate
+- Seasonal: christmas, halloween, spring
+- Magazine: magazine, newspaper, vintage
+- Paper Craft: paperCraft, origami, craftPaper
 
-USE WHEN:
-- Making items clickable
-- Adding hover effects
-- Creating drag interactions
-- Building interactive tutorials/quizzes
-- Timeline-based triggers
-
-TRIGGER EVENTS:
-- click: When item is clicked
-- hover_enter: When mouse enters item
-- hover_exit: When mouse leaves item
-- drag_start: When item drag begins
-- drag_move: While item is being dragged
-- drag_end: When item drag ends
-- timeline: At specific time in animation
-- scene_enter: When scene becomes active
-- scene_exit: When scene deactivates
-- animation_end: When item's animation completes
-- quiz_answer: When quiz answer is submitted
-
-ACTION TYPES:
-- show: Make target item visible
-- hide: Hide target item
-- toggle_visibility: Toggle target visibility
-- play_animation: Start animation on target
-- stop_animation: Stop animation on target
-- navigate: Navigate to scene or URL
-- update_property: Change item property
-- set_variable: Set a scene variable
-- submit_answer: Submit quiz answer
-- increment_score: Add to quiz score
-- reset_quiz: Reset quiz state
+GRADIENT PALETTES:
+rainbow, sunset, ocean, fire, gold, rose, ice, cyberpunk, neonGlow, purplePink
 
 EXAMPLES:
-- Click to show: {itemId: "button_1", event: "click", actions: [{type: "show", targetItemId: "panel_1"}]}
-- Hover to animate: {itemId: "star_1", event: "hover_enter", actions: [{type: "play_animation", targetItemId: "star_1", animationType: "pulse"}]}
-- Click to navigate: {itemId: "next_btn", event: "click", actions: [{type: "navigate", url: "#scene2"}]}`,
+- Wordle style: {text: "HELLO", style: "tile", palette: "wordle"}
+- Ransom note: {text: "SECRET", style: "magazine", palette: "newspaper"}
+- Gradient text: {text: "RAINBOW", style: "gradient", gradientPalette: "rainbow"}
+- Neon style: {text: "GLOW", style: "tile", palette: "neon"}`,
         inputSchema: {
             type: 'object',
             properties: {
-                itemId: {
+                text: {
                     type: 'string',
-                    description: 'Item to attach trigger to',
+                    description: 'The text to stylize',
                 },
-                event: {
+                style: {
                     type: 'string',
-                    enum: ['click', 'hover_enter', 'hover_exit', 'drag_start', 'drag_move', 'drag_end', 'timeline', 'scene_enter', 'scene_exit', 'animation_end', 'quiz_answer'],
-                    description: 'Event that fires the trigger',
+                    enum: ['tile', 'magazine', 'paperCut', 'fold', 'gradient', 'image'],
+                    description: 'Style type (default: tile)',
                 },
-                actions: {
-                    type: 'array',
-                    items: {
-                        type: 'object',
-                        properties: {
-                            type: {
-                                type: 'string',
-                                enum: ['show', 'hide', 'toggle_visibility', 'play_animation', 'stop_animation', 'navigate', 'update_property', 'set_variable', 'submit_answer', 'increment_score', 'reset_quiz'],
-                                description: 'Action type',
-                            },
-                            targetItemId: {
-                                type: 'string',
-                                description: 'Target item for the action',
-                            },
-                            animationType: {
-                                type: 'string',
-                                description: 'Animation type for play_animation',
-                            },
-                            property: {
-                                type: 'string',
-                                description: 'Property name for update_property',
-                            },
-                            value: {
-                                description: 'Value for update_property or set_variable',
-                            },
-                            variableName: {
-                                type: 'string',
-                                description: 'Variable name for set_variable',
-                            },
-                            url: {
-                                type: 'string',
-                                description: 'URL or scene ID for navigate',
-                            },
-                            points: {
-                                type: 'number',
-                                description: 'Points for increment_score',
-                            },
-                        },
-                        required: ['type'],
+                palette: {
+                    type: 'string',
+                    enum: [
+                        'wordle', 'scrabble',
+                        'candy', 'neon', 'rainbow',
+                        'pastel', 'cotton',
+                        'earth', 'ocean', 'forest', 'sunset',
+                        'corporate', 'minimal', 'slate',
+                        'christmas', 'halloween', 'spring',
+                        'magazine', 'newspaper', 'vintage',
+                        'paperCraft', 'origami', 'craftPaper',
+                    ],
+                    description: 'Color palette for tile/magazine styles',
+                },
+                position: {
+                    type: 'object',
+                    properties: {
+                        x: { type: 'number' },
+                        y: { type: 'number' },
                     },
-                    description: 'Actions to execute when triggered',
+                    description: 'Position on canvas (defaults to center)',
+                },
+                fontSize: {
+                    type: 'number',
+                    description: 'Base font size in pixels (default: 48)',
                 },
-                condition: {
+                fontFamily: {
                     type: 'string',
-                    description: 'Optional condition expression (e.g., "$score > 10")',
+                    description: 'Font family (default: Inter, sans-serif)',
                 },
-                timelineOffset: {
+                spacing: {
                     type: 'number',
-                    description: 'Time offset in ms for timeline triggers',
+                    description: 'Letter spacing multiplier (default: 1.1)',
                 },
-            },
-            required: ['itemId', 'event', 'actions'],
-        },
-    },
-    {
-        name: 'pinepaper_remove_trigger',
-        annotations: {
-            title: 'Remove Trigger',
-            readOnlyHint: false,
-            destructiveHint: true,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-        description: `Remove triggers from an item.
-
-USE WHEN:
-- Disabling interactivity on an item
-- Cleaning up triggers before adding new ones
-- Removing specific event handlers
-
-OPTIONS:
-- Remove specific event: {itemId: "button_1", event: "click"}
-- Remove all triggers: {itemId: "button_1", removeAll: true}`,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                itemId: {
+                gradientPalette: {
                     type: 'string',
-                    description: 'Item to remove triggers from',
+                    enum: ['rainbow', 'sunset', 'ocean', 'fire', 'gold', 'rose', 'ice', 'cyberpunk', 'neonGlow', 'purplePink'],
+                    description: 'Gradient palette (for style="gradient")',
                 },
-                event: {
+                gradientDirection: {
                     type: 'string',
-                    enum: ['click', 'hover_enter', 'hover_exit', 'drag_start', 'drag_move', 'drag_end', 'timeline', 'scene_enter', 'scene_exit', 'animation_end', 'quiz_answer'],
-                    description: 'Specific event to remove (optional)',
+                    enum: ['vertical', 'horizontal', 'diagonal', 'radial'],
+                    description: 'Gradient direction (default: vertical)',
+                },
+                cornerRadius: {
+                    type: 'number',
+                    description: 'Corner radius for tile backgrounds (default: 4)',
                 },
-                removeAll: {
+                shadowEnabled: {
                     type: 'boolean',
-                    description: 'Remove all triggers from item',
+                    description: 'Enable drop shadows (default: true)',
                 },
             },
-            required: ['itemId'],
+            required: ['text'],
         },
     },
     {
-        name: 'pinepaper_query_triggers',
+        name: 'pinepaper_animate_letter_collage',
         annotations: {
-            title: 'Query Triggers',
-            readOnlyHint: true,
+            title: 'Animate Letter Collage',
+            readOnlyHint: false,
             destructiveHint: false,
             idempotentHint: true,
             openWorldHint: false,
         },
-        description: `[Utility] List all triggers on the canvas or for a specific item.
+        description: `Apply animation to all letters in a collage with staggered timing.
 
 USE WHEN:
-- Inspecting existing interactivity
-- Debugging trigger behavior
-- Understanding scene's interactive elements
+- Adding entrance animations to text
+- Creating typewriter-style reveals
+- Making text bounce or pulse
+- Adding dynamic effects to lettering
+
+ANIMATION TYPES:
+- pulse: Scale up and down rhythmically
+- bounce: Bouncing motion
+- fade: Fade in/out
+- wobble: Side-to-side wobble
+- rotate: Spinning rotation
+
+STAGGER EFFECT:
+Use staggerDelay to create wave-like animations where each letter starts slightly after the previous one. 0.1s is a good default for smooth wave effects.
 
 EXAMPLES:
-- All triggers: {}
-- Triggers on specific item: {itemId: "button_1"}
-- Filter by event type: {event: "click"}`,
+- Wave entrance: {collageId: "collage_1", animationType: "bounce", staggerDelay: 0.1}
+- Pulsing text: {collageId: "collage_1", animationType: "pulse", staggerDelay: 0.05}
+- Fast typewriter: {collageId: "collage_1", animationType: "fade", staggerDelay: 0.15}`,
         inputSchema: {
             type: 'object',
             properties: {
-                itemId: {
+                collageId: {
                     type: 'string',
-                    description: 'Filter triggers by item ID',
+                    description: 'Collage ID from create_letter_collage',
                 },
-                event: {
+                animationType: {
                     type: 'string',
-                    enum: ['click', 'hover_enter', 'hover_exit', 'drag_start', 'drag_move', 'drag_end', 'timeline', 'scene_enter', 'scene_exit', 'animation_end', 'quiz_answer'],
-                    description: 'Filter by event type',
+                    enum: ['pulse', 'bounce', 'fade', 'wobble', 'rotate'],
+                    description: 'Animation type to apply',
+                },
+                staggerDelay: {
+                    type: 'number',
+                    description: 'Delay between each letter animation start in seconds (default: 0.1)',
+                },
+                animationSpeed: {
+                    type: 'number',
+                    description: 'Animation speed multiplier (default: 1)',
                 },
             },
+            required: ['collageId', 'animationType'],
         },
     },
     // ---------------------------------------------------------------------------
-    // DOMAIN: QUIZ/LMS TOOLS
+    // DOMAIN: GENERATOR TOOLS
     // ---------------------------------------------------------------------------
     {
-        name: 'pinepaper_create_quiz',
+        name: 'pinepaper_execute_generator',
         annotations: {
-            title: 'Create Quiz',
+            title: 'Execute Generator',
             readOnlyHint: false,
             destructiveHint: false,
             idempotentHint: false,
             openWorldHint: false,
         },
-        description: `Create an interactive quiz with questions, answers, and scoring.
+        description: `Execute a background generator to create procedural patterns.
 
 USE WHEN:
-- Building educational content
-- Creating assessments
-- Adding gamification elements
-- Making interactive learning modules
-
-QUESTION TYPES:
-- multiple-choice: Single correct answer from options
-- multiple-select: Multiple correct answers
-- drag-drop: Drag items to correct zones
-- matching: Match pairs of items
-- sequencing: Put items in correct order
-- hotspot: Click correct area on image
-- true-false: True or false question
-
-FEEDBACK:
-Each question can have:
-- correctFeedback: Message shown on correct answer
-- incorrectFeedback: Message shown on wrong answer
-- partialFeedback: Message for partially correct (multi-select)
-
-SCORING:
-- Each question has a points value
-- passingScore: Minimum score to pass
-- showScore: Display score during quiz
-- allowRetry: Allow retrying incorrect answers
+- "add a sunburst background", "bokeh effect", "gradient mesh"
+- "create wave pattern", "wind field", "fluid flow"
+- "grid background", "geometric abstract", "noise texture"
+- Creating dynamic procedural backgrounds
 
-EXAMPLE:
-{
-  "title": "Geography Quiz",
-  "questions": [
-    {
-      "type": "multiple-choice",
-      "prompt": "What is the capital of France?",
-      "options": [
-        {"id": "a", "label": "London"},
-        {"id": "b", "label": "Paris", "isCorrect": true},
-        {"id": "c", "label": "Berlin"}
-      ],
-      "points": 10,
-      "correctFeedback": "Correct! Paris is the capital.",
-      "incorrectFeedback": "Sorry, the correct answer is Paris."
-    }
-  ],
-  "passingScore": 70,
-  "showScore": true
-}`,
+GENERATORS (15 total):
+
+Classic:
+- drawSunburst: Radial rays from center (rayCount, colors, bgColor, opacity, rayGap, gradientRays)
+- drawSunsetScene: Animated sunset with clouds (sunColor, skyColors, cloudCount, skyOpacity, starCount, starColor, reflectionEnabled, reflectionOpacity)
+- drawGrid: Lines/dots/squares (gridType, spacing, lineColor, opacity, gap, randomRotation, colorMode: checkerboard|gradient|random|rows|columns, strokeColor, strokeWidth)
+- drawStackedCircles: Overlapping circles (count, colors, distribution: random|poisson|golden, opacityMin, opacityMax, blendMode, strokeWidth, strokeColor, sizeGradient, animationType: pulse|float|none)
+- drawCircuit: Tech circuit board (lineColor, nodeColor, density, traceOpacity, nodeOpacity, diagonalPaths, chipDensity: auto|none|low|medium|high)
+- drawWaves: Layered wave pattern (waveCount, colors, amplitude, frequency, opacity, fill, fillOpacity, amplitudeVariation, blendMode)
+- drawPattern: Geometric shapes in orbit (patternType, size, color, opacity, blendMode, layers: 1-5, layerScaleDecay)
+
+New — Effects:
+- drawBokeh: Soft-focus circles (count, colors, minRadius, maxRadius, shadowBlur, distribution: random|poisson, driftAnimation)
+
+New — Organic:
+- drawGradientMesh: Radial gradient blobs with screen blending (colors, blobCount, blendMode, drift)
+- drawFluidFlow: Sinusoidal stream paths with depth (streamCount, colors, depthLayers, speed)
+- drawOrganicFlow: Aurora/silk layers with fill-to-bottom (layerCount, colors, blendMode, fillToBottom)
+
+New — Geometric:
+- drawGeometricAbstract: Mixed translucent shapes (colors, shapeCount, blendMode, rotation)
+
+New — Particles:
+- drawWindField: Directional wind particles with noise turbulence (particleCount, colors, direction, turbulence, trailLength, speed)
+
+New — Textures:
+- drawNoiseTexture: Perlin/grain/stipple noise (noiseType: perlin|grain|stipple, colors, scale, density, animated)
+
+New — Tech:
+- drawGlobeWireframe: Vercel-style wireframe globe (bgColor, wireColor, glowColor, highlightColor, meridianCount, latitudeCount, globeRadius, nodeCount, nodeSize, animationEnabled, animationSpeed, strokeWidth, gridOpacity)
+
+PineMath — Math/Science:
+- drawFunctionPlot: Plot y=f(x) (expression, xMin, xMax, yMin, yMax, color, lineWidth, showAxes, showGrid, steps, animate: none|scroll-right|scroll-left|oscillate|bounce|wipe|custom)
+- drawParametricCurve: Plot (x(t),y(t)) Lissajous/spirals/roses (xExpression, yExpression, tMin, tMax, color, steps, scale, animate: none|linear|slow|fast|wave|bounce, trailFade)
+- drawSimulation: Dynamic systems with ODE solvers (preset: pendulum|springMass|lorenz|doublePendulum|vanderpol, solver: euler|rk4|rk45, timeScale, showTrail, trailLength, trailColor, objectColor)
+- drawSpectrumAnalyzer: FFT signal visualization (waveform: sine|square|sawtooth|triangle|noise|composite, frequency, amplitude, sampleRate, window: none|hann|hamming|blackman, waveColor, spectrumColor)
+- draw3DSurface: 3D surfaces from equations (preset: torus|sphere|wave|klein|mobius|custom, xExpr, yExpr, zExpr, uSteps, vSteps, scale, rotateSpeed)
+
+COMMON PARAMS (all generators):
+- bgColor: Background color ("none"/"transparent" for no background)
+- interactive: Make generated items selectable/draggable (default false)
+- clipToCanvas: Clip output to canvas bounds (default true, set false for overflow)`,
         inputSchema: {
             type: 'object',
             properties: {
-                title: {
+                generatorName: {
                     type: 'string',
-                    description: 'Quiz title',
-                },
-                questions: {
-                    type: 'array',
-                    items: {
-                        type: 'object',
-                        properties: {
-                            type: {
-                                type: 'string',
-                                enum: ['multiple-choice', 'multiple-select', 'drag-drop', 'matching', 'sequencing', 'hotspot', 'true-false'],
-                                description: 'Question type',
-                            },
-                            prompt: {
-                                type: 'string',
-                                description: 'Question text',
-                            },
-                            options: {
-                                type: 'array',
-                                items: {
-                                    type: 'object',
-                                    properties: {
-                                        id: { type: 'string' },
-                                        label: { type: 'string' },
-                                        isCorrect: { type: 'boolean' },
-                                    },
-                                },
-                                description: 'Answer options',
-                            },
-                            points: {
-                                type: 'number',
-                                description: 'Points for correct answer',
-                            },
-                            correctFeedback: {
-                                type: 'string',
-                                description: 'Feedback for correct answer',
-                            },
-                            incorrectFeedback: {
-                                type: 'string',
-                                description: 'Feedback for incorrect answer',
-                            },
-                            draggableItems: {
-                                type: 'array',
-                                items: { type: 'string' },
-                                description: 'Item IDs that can be dragged (for drag-drop)',
-                            },
-                            dropZones: {
-                                type: 'array',
-                                items: {
-                                    type: 'object',
-                                    properties: {
-                                        id: { type: 'string' },
-                                        correctItems: { type: 'array', items: { type: 'string' } },
-                                    },
-                                },
-                                description: 'Drop zones with correct items (for drag-drop)',
-                            },
-                        },
-                        required: ['type', 'prompt', 'points'],
-                    },
-                    description: 'Quiz questions',
-                },
-                passingScore: {
-                    type: 'number',
-                    description: 'Minimum percentage to pass (0-100)',
-                },
-                showScore: {
-                    type: 'boolean',
-                    description: 'Display score during quiz',
-                },
-                allowRetry: {
-                    type: 'boolean',
-                    description: 'Allow retrying incorrect answers',
-                },
-                shuffleQuestions: {
-                    type: 'boolean',
-                    description: 'Randomize question order',
+                    enum: [
+                        'drawSunburst', 'drawSunsetScene', 'drawGrid', 'drawStackedCircles',
+                        'drawCircuit', 'drawWaves', 'drawPattern',
+                        'drawBokeh', 'drawGradientMesh', 'drawGeometricAbstract', 'drawWindField',
+                        'drawFluidFlow', 'drawOrganicFlow', 'drawNoiseTexture',
+                        'drawGlobeWireframe',
+                        'drawFunctionPlot', 'drawParametricCurve', 'drawSimulation',
+                        'drawSpectrumAnalyzer', 'draw3DSurface',
+                    ],
+                    description: 'Generator name',
                 },
-                shuffleOptions: {
-                    type: 'boolean',
-                    description: 'Randomize answer options',
+                params: {
+                    type: 'object',
+                    description: 'Generator-specific parameters',
+                    additionalProperties: true,
                 },
             },
-            required: ['questions'],
+            required: ['generatorName'],
+        },
+    },
+    {
+        name: 'pinepaper_list_generators',
+        annotations: {
+            title: 'List Generators',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        description: `[Utility] Get a list of all available background generators with their parameters.
+
+USE WHEN:
+- User asks "what backgrounds are available?"
+- Need to show generator options
+- Discovering generator capabilities`,
+        inputSchema: {
+            type: 'object',
+            properties: {},
         },
     },
+    // ---------------------------------------------------------------------------
+    // DOMAIN: EFFECT TOOLS
+    // ---------------------------------------------------------------------------
     {
-        name: 'pinepaper_get_quiz_state',
+        name: 'pinepaper_apply_effect',
         annotations: {
-            title: 'Get Quiz State',
-            readOnlyHint: true,
+            title: 'Apply Effect',
+            readOnlyHint: false,
             destructiveHint: false,
-            idempotentHint: true,
+            idempotentHint: false,
             openWorldHint: false,
         },
-        description: `[Utility] Get the current state of an active quiz.
+        description: `Apply a visual effect to an item.
 
 USE WHEN:
-- Checking quiz progress
-- Getting current score
-- Reviewing answered questions
-- Debugging quiz behavior
+- Adding sparkle/glitter effects
+- Creating burst/explosion, fire, smoke effects
+- Weather effects (rain, snow)
+- Celebration effects (confetti)
+- Enhancing visual impact (ripple, glow, electric)
 
-RETURNS:
-- quizId: Quiz identifier
-- currentQuestion: Current question index
-- totalQuestions: Total number of questions
-- score: Current score
-- maxScore: Maximum possible score
-- answers: Array of submitted answers
-- passed: Whether passing score achieved (if complete)
-- complete: Whether quiz is finished`,
+EFFECTS (15 total):
+- sparkle: Glitter/sparkle particles (color, speed, size)
+- blast: Explosion burst effect (color, radius, count)
+- smoke: Rising smoke plumes (color, speed, size, drift, height, growthRate)
+- fire: Animated fire/flames (color, colors, speed, size, height, turbulence)
+- rain: Falling rain drops (color, count, speed, angle, spread)
+- snow: Falling snowflakes (color, count, speed, spread, particleLife)
+- confetti: Celebration confetti (colors, count, radius, gravity, size, spread, interval, repeat)
+- ripple: Expanding ring ripples (color, speed, maxRadius, ringCount, strokeWidth)
+- glow: Pulsing glow aura (color drives the shadow halo; speed, intensity, size; optional fill — interior tint decoupled from color; fillOpacity 0..1 multiplies intensity opacity)
+- electric: Lightning bolts (color, speed, boltCount, length, flickerRate)
+- bubbles: Rising transparent bubbles (color drives the rim; count, speed, size, spread; optional fill — interior tint, default null = outlined-only; fillOpacity 0..1, default 0.25 when fill is set)
+- dust: Ambient drifting motes (color, count, speed, size, spread)
+- fireflies: Glowing wandering dots (color, count, speed, size, spread)
+- shockwave: Expanding concentric rings — burst type (speed, maxRadius, count, thickness)
+- trail: Fading afterimages following movement (speed, count, size, fadeRate)
+
+EXAMPLE — bubbles with magenta interior over a blue rim:
+{ effectType: "bubbles", params: { color: "#93c5fd", fill: "#ff00aa", fillOpacity: 0.4 } }`,
         inputSchema: {
             type: 'object',
             properties: {
-                quizId: {
+                itemId: { type: 'string', description: 'Registry ID of the item' },
+                effectType: {
                     type: 'string',
-                    description: 'Quiz ID (optional, uses active quiz if not specified)',
+                    enum: ['sparkle', 'blast', 'smoke', 'fire', 'rain', 'snow', 'confetti', 'ripple', 'glow', 'electric', 'bubbles', 'dust', 'fireflies', 'shockwave', 'trail'],
+                    description: 'Type of effect',
+                },
+                params: {
+                    type: 'object',
+                    description: 'Effect parameters',
+                    additionalProperties: true,
                 },
             },
+            required: ['itemId', 'effectType'],
         },
     },
+    // ---------------------------------------------------------------------------
+    // DOMAIN: FILTER TOOLS
+    // ---------------------------------------------------------------------------
     {
-        name: 'pinepaper_reset_quiz',
+        name: 'pinepaper_add_filter',
         annotations: {
-            title: 'Reset Quiz',
+            title: 'Add Filter',
             readOnlyHint: false,
-            destructiveHint: true,
-            idempotentHint: true,
+            destructiveHint: false,
+            idempotentHint: false,
             openWorldHint: false,
         },
-        description: `Reset a quiz to its initial state.
+        description: `Add a visual filter effect to the canvas. Filters are scene-wide effects that can be stacked.
 
 USE WHEN:
-- Restarting a quiz
-- Clearing quiz progress
-- Allowing user to retake quiz`,
+- User wants visual effects like blur, grayscale, vintage look
+- Creating mood or atmosphere (cinematic, dreamy, noir)
+- Post-processing the entire scene
+- User says "make it look vintage", "add blur", "black and white"
+
+AVAILABLE FILTERS:
+- grayscale: Convert to black and white (params: intensity 0-1)
+- sepia: Warm vintage brownish tone (params: intensity 0-1)
+- blur: Gaussian blur effect (params: radius 0-20)
+- brightness: Adjust brightness (params: value -100 to 100)
+- contrast: Adjust contrast (params: value -100 to 100)
+- saturate: Adjust color saturation (params: value -100 to 100)
+- invert: Invert colors (params: intensity 0-1)
+- noise: Add film grain (params: intensity 0-100, monochrome: true/false)
+- vignette: Darken edges (params: intensity 0-1, radius 0-1)
+- vintage: Preset combining sepia, vignette, noise
+- colorOverlay: Add color tint (params: color, intensity, blendMode)
+- sharpen: Increase sharpness (params: intensity 0-100)
+- posterize: Reduce color levels (params: levels 2-32)
+
+EXAMPLES:
+- "Make it black and white" → filterType: "grayscale"
+- "Add vintage look" → filterType: "vintage", params: {intensity: 0.8}
+- "Blur the background" → filterType: "blur", params: {radius: 5}
+- "Increase contrast" → filterType: "contrast", params: {value: 30}
+
+Filters can be stacked - call multiple times to combine effects.`,
         inputSchema: {
             type: 'object',
             properties: {
-                quizId: {
+                filterType: {
                     type: 'string',
-                    description: 'Quiz ID (optional, uses active quiz if not specified)',
+                    enum: ['grayscale', 'sepia', 'blur', 'brightness', 'contrast', 'saturate', 'invert', 'noise', 'vignette', 'vintage', 'colorOverlay', 'sharpen', 'posterize'],
+                    description: 'Type of filter to apply',
+                },
+                params: {
+                    type: 'object',
+                    description: 'Filter-specific parameters',
+                    additionalProperties: true,
                 },
             },
+            required: ['filterType'],
         },
     },
     // ---------------------------------------------------------------------------
@@ -5723,6 +4392,10 @@ RETURNS:
                     type: 'boolean',
                     description: 'Run in headless mode (default: false when explicitly called)',
                 },
+                url: {
+                    type: 'string',
+                    description: 'Studio URL to connect to (e.g. "http://localhost:3000" for local dev). Must be http:// or https:// — file:/data:/javascript: are rejected. Overrides the PINEPAPER_STUDIO_URL env var and the prod default. "/editor" and agent-mode params are added automatically. Passing a URL with a different origin/pathname reconnects.',
+                },
             },
         },
     },
@@ -5957,7 +4630,7 @@ PRIVACY: No screenshots, no tool call arguments, no user content — only struct
 
 WORKFLOW: start_job → batch_execute (everything in ONE call) → end_job (screenshot) → show user → iterate if needed.
 
-RETURNS: canvasSize {width, height} — use this to position items within bounds.
+RETURNS: canvasSize {width, height} — use this to position items within bounds. Also returns ontology: a pp: triples + item summary snapshot of the (typically empty) canvas. Reuse this baseline across the same agent turn instead of calling pinepaper_get_canvas_ontology unless you've mutated the canvas. When clearCanvas is false, the ontology captures whatever's already on the canvas.
 
 CANVAS PRESETS: instagram (1080x1080), instagram-story (1080x1920), tiktok (1080x1920), youtube (1920x1080), youtube-thumbnail (1280x720), twitter (1200x675), linkedin (1200x627), web, print-a4, print-letter`,
         inputSchema: {
@@ -5985,6 +4658,10 @@ CANVAS PRESETS: instagram (1080x1080), instagram-story (1080x1920), tiktok (1080
                     type: 'boolean',
                     description: 'Clear canvas when starting job (default: true)',
                 },
+                includeOntology: {
+                    type: 'boolean',
+                    description: 'Include canvas ontology snapshot in the result (default: true). Pre-bundles a pp: triples baseline so the agent can reason about composition without a follow-up pinepaper_get_canvas_ontology call.',
+                },
             },
         },
     },
@@ -6112,6 +4789,8 @@ NOTE: For diagrams (flowcharts, UML), use pinepaper_create_diagram_shape + pinep
 
 ⚠️ SIZING: All positions/sizes MUST fit within the canvas. start_job returns canvasSize. Keep items within 5%-95% of canvas width/height. Max canvas: 4096x4096.
 
+ONTOLOGY PREFLIGHT: Before code generation, this tool validates itemType, relationType, effectType, and generatorName against the canonical PinePaper vocabulary. A typo (e.g. "circel") returns a structured VALIDATION_ERROR with the operation index, the offending field, the canonical valid list, and a suggested fix — fix and retry rather than guessing. Pass skipValidation: true to bypass when intentionally using experimental vocabulary.
+
 WORKFLOW:
 1. pinepaper_agent_start_job → 2. pinepaper_agent_batch_execute (everything) → 3. pinepaper_agent_end_job (screenshot for validation)
 After validation: user reviews screenshot → feedback → modify/recreate as needed.
@@ -6122,7 +4801,8 @@ CANVAS SETUP:
   set_canvas_size — {width, height} or {preset: "instagram"|"youtube"|"tiktok"|...}
   set_background — {backgroundColor: "#hex"}
   execute_generator — {generatorName, generatorParams} → fills canvas with procedural art
-    Generators: drawBokeh, drawGradientMesh, drawWaves, drawSunburst, drawSunsetScene, drawGrid, drawCircuit, drawPattern, drawStackedCircles, drawGeometricAbstract, drawWindField, drawFluidFlow, drawOrganicFlow, drawNoiseTexture
+    Generators: drawBokeh, drawGradientMesh, drawWaves, drawSunburst, drawSunsetScene, drawGrid, drawCircuit, drawPattern, drawStackedCircles, drawGeometricAbstract, drawWindField, drawFluidFlow, drawOrganicFlow, drawNoiseTexture, drawGlobeWireframe
+    PineMath: drawFunctionPlot (y=f(x) plots), drawParametricCurve (x(t),y(t)), drawSimulation (pendulum, Lorenz, spring-mass), drawSpectrumAnalyzer (FFT), draw3DSurface (torus, sphere, Klein bottle)
 
 ITEMS:
   create — {itemType, position: {x,y}, properties}
@@ -6140,23 +4820,27 @@ ITEMS:
 
 ANIMATION:
   animate — Loop animation: {itemId, animationType, animationOptions}
-    animationType: pulse, rotate, bounce, fade, wobble, slide, typewriter
+    animationType: ${SIMPLE_ANIMATION_TYPES_LIST}
   keyframe_animate — Timed animation: {itemId, keyframes: [{time, properties, easing}], duration, loop}
     Animatable properties: opacity, scale, scaleX, scaleY, x, y, rotation, fillColor, strokeColor, fontSize
     Easing: easeInOut, easeIn, easeOut, easeInCubic, easeOutCubic, easeOutBounce, linear
   relation — Behavioral link: {sourceId, targetId, relationType, relationOptions}
-    relationType: orbits, follows, attached_to, points_at, mirrors, parallax, wave_through, morphs_to (+ 9 more in schema)
+    relationType: orbits, follows, attached_to, points_at, mirrors, parallax, wave_through, morphs_to, group_morphs_to, moves_along_path (+ 9 more in schema)
 
 EFFECTS:
   apply_mask — Reveal effect: {itemId, maskPreset, maskOptions}
     maskPreset: wipeLeft, wipeRight, wipeUp, wipeDown, iris, irisOut, star, heart, curtainHorizontal, curtainVertical, cinematic, diagonalWipe, revealUp, revealDown
   apply_effect — Visual effect: {itemId, effectType, effectParams}
-    effectType: sparkle, blast
+    effectType: ${EFFECT_TYPES_LIST}
 
 PLAYBACK:
   play_timeline — {action: "play"|"stop"|"seek", duration, loop}
 
-VARIABLE REFERENCES: "$0", "$1" etc. reference items by creation order within the batch.
+VARIABLE REFERENCES: "$0", "$1" etc. reference items by creation order within the batch. Place ALL create ops before any ops that reference them so the indices stay stable.
+
+ANIMATION NOTES:
+- keyframe_animate position accepts [x, y] or { x, y } (normalized). fillColor/strokeColor accept rgba() for alpha. The create "opacity" and "blendMode" props are applied to the item.
+- For MP4/GIF export the keyframe timeline is rendered once across the duration; author motion to fill the clip and use loop:false. Looping item-animations (loop:true) are not advanced by the exporter and render frozen.
 
 EXAMPLE — Animated sky scene with timed reveals:
 {operations: [
@@ -6237,7 +4921,7 @@ EXAMPLE — Animated sky scene with timed reveals:
                             targetId: { type: 'string', description: 'For relation: target item ID or $N' },
                             relationType: {
                                 type: 'string',
-                                enum: ['orbits', 'follows', 'attached_to', 'points_at', 'mirrors', 'parallax', 'animates', 'grows_from', 'staggered_with', 'wave_through', 'circumscribes', 'morphs_to', 'maintains_distance', 'bounds_to', 'indicates', 'camera_follows', 'camera_animates'],
+                                enum: ['orbits', 'follows', 'attached_to', 'points_at', 'mirrors', 'parallax', 'animates', 'grows_from', 'staggered_with', 'wave_through', 'circumscribes', 'morphs_to', 'group_morphs_to', 'moves_along_path', 'maintains_distance', 'bounds_to', 'indicates', 'camera_follows', 'camera_animates'],
                                 description: 'For relation: type',
                             },
                             relationOptions: { type: 'object', description: 'For relation: options' },
@@ -6252,7 +4936,7 @@ EXAMPLE — Animated sky scene with timed reveals:
                             // Effects
                             effectType: {
                                 type: 'string',
-                                enum: ['sparkle', 'blast', 'smoke', 'fire', 'rain', 'snow', 'confetti', 'ripple', 'glow', 'electric'],
+                                enum: ['sparkle', 'blast', 'smoke', 'fire', 'rain', 'snow', 'confetti', 'ripple', 'glow', 'electric', 'bubbles', 'dust', 'fireflies', 'shockwave', 'trail'],
                                 description: 'For apply_effect: effect type',
                             },
                             effectParams: { type: 'object', description: 'For apply_effect: parameters' },
@@ -6272,6 +4956,10 @@ EXAMPLE — Animated sky scene with timed reveals:
                     type: 'boolean',
                     description: 'If true, all operations succeed or all fail (default: true)',
                 },
+                skipValidation: {
+                    type: 'boolean',
+                    description: 'Skip the ontology preflight that catches vocabulary typos before browser execution (default: false). Only set true when knowingly using experimental values.',
+                },
             },
             required: ['operations'],
         },
@@ -6299,6 +4987,7 @@ PLATFORMS & OPTIMAL FORMATS:
 
 FORMATS: svg, png, gif, mp4, webm, pdf.
 QUALITY: draft, standard, high.
+FRAMING: canvas (default, full canvas) | camera (camera_animates first-keyframe viewport — video formats only, requires a keyframe-mode walkthrough on the canvas; camera animation still drives motion within the fixed output frame).
 
 ⚠️ If export fails, do NOT retry with different formats — report the error to the user.
 ⚠️ When user asks for "video", always use format: "mp4".
@@ -6306,7 +4995,8 @@ QUALITY: draft, standard, high.
 EXAMPLES:
 - {platform: "instagram"} — auto-selects best format
 - {platform: "instagram", format: "mp4"} — force MP4
-- {platform: "web", format: "svg"} — animated SVG`,
+- {platform: "web", format: "svg"} — animated SVG
+- {platform: "youtube", format: "mp4", framing: "camera"} — render only what the camera frames during the walkthrough`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -6325,6 +5015,17 @@ EXAMPLES:
                     enum: ['draft', 'standard', 'high'],
                     description: 'Export quality level (default: standard)',
                 },
+                framing: {
+                    type: 'string',
+                    enum: ['canvas', 'camera'],
+                    description: 'Output framing. "canvas" (default) renders the full canvas. "camera" renders only the first-keyframe viewport of a camera_animates walkthrough — video formats only.',
+                },
+                duration: {
+                    type: 'number',
+                    minimum: 0.5,
+                    maximum: 60,
+                    description: 'Video duration in seconds for mp4/webm/gif (default 5, max 60). Static formats ignore this. If you set play_timeline to N seconds, pass the same N here.',
+                },
             },
             required: ['platform'],
         },
@@ -6385,38 +5086,6 @@ EXAMPLE RESPONSE:
         },
     },
     // ---------------------------------------------------------------------------
-    // LAYER 1 — ATOMS: CANVAS PRESETS TOOL
-    // ---------------------------------------------------------------------------
-    {
-        name: 'pinepaper_get_canvas_presets',
-        annotations: {
-            title: 'Get Canvas Presets',
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-        description: `[Utility] List all available canvas presets with their dimensions.
-
-USE WHEN:
-- Setting up canvas for specific platforms (YouTube, Instagram, TikTok, etc.)
-- Discovering available size presets
-- Planning content dimensions
-- Building UI for size selection
-
-PRESETS BY CATEGORY:
-- Video: youtube-thumbnail, youtube-short, tiktok, hd-720p, full-hd-1080p
-- Social: instagram-story, instagram-post, facebook-post, twitter-post, linkedin-post, pinterest-pin
-- Presentation: presentation-16x9, presentation-4x3
-
-RETURNS:
-Array of presets with: key, name, width, height, aspectRatio, category`,
-        inputSchema: {
-            type: 'object',
-            properties: {},
-        },
-    },
-    // ---------------------------------------------------------------------------
     // COMPATIBILITY: P5.JS TOOLS
     // ---------------------------------------------------------------------------
     {
@@ -6584,6 +5253,41 @@ EXAMPLES:
     // ---------------------------------------------------------------------------
     // ONTOLOGY TOOLS (Design Knowledge Graph)
     // ---------------------------------------------------------------------------
+    {
+        name: 'pinepaper_get_canvas_ontology',
+        annotations: {
+            title: 'Get Canvas Ontology',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        description: `Capture the live canvas as compact pp: ontology triples + a structured item summary.
+
+USE THIS instead of pinepaper_get_items when you need to REASON about composition (what's on the canvas, how items relate, what's animated). Typical scenes shrink 3-10× compared to a raw item dump while preserving relations, animations, effects, masks, and collage styling.
+
+OUTPUT (a snapshot of FxTool's canvas state):
+- canvasWidth, canvasHeight, canvasPreset
+- itemCount, itemTypes ([unique]), hasAnimations, relationCount
+- items: capped item summaries with positions, colors, group structure, collage metadata, keyframes, effects, deformations
+- triples: a TripleLanguage-serialized pp: triple block (compact tokenized form). Read this for structural reasoning.
+- viewport (when includeViewport: true): zoom + center + hasCameraAnimation flag
+
+OPTIONS:
+- maxItems (default 50): cap on item summaries. Larger scenes are truncated, not paginated — pinepaper_query_ontology and pinepaper_get_items remain available for full enumeration.
+- maxChildren (default 10): cap on per-group child summaries.
+- includeViewport (default false): include zoom/pan/camera-animation flag.
+
+NOTE: Requires FxTool with the canvas-ontology promotion. Returns { success: false, error } with a clear hint when running against an older build.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                maxItems: { type: 'number', description: 'Cap on item summaries (default 50, max 500).' },
+                maxChildren: { type: 'number', description: 'Cap on per-group child summaries (default 10, max 50).' },
+                includeViewport: { type: 'boolean', description: 'Include zoom/pan/camera-animation state (default false).' },
+            },
+        },
+    },
     {
         name: 'pinepaper_analyze_design',
         annotations: {
@@ -6727,8 +5431,10 @@ Lookup:
 
 USE WHEN: You need full parameter docs, examples, or workflow guidance — especially in minimal verbosity mode where tool descriptions are short summaries.
 
+PREFER RESOURCES WHERE POSSIBLE: The full AI Agent Guide is also available via the MCP resources API at pinepaper://docs/agent-guide — clients that support resources should pull it that way rather than calling this tool. Per-domain references live at pinepaper://docs/{generators,relations,masks,diagrams,maps,effects-and-filters,fonts,custom-paths,paperjs-in-pinepaper,templates,customization,getting-started}. Use this tool when the client doesn't support resources or when you want a specific tool's verbose description.
+
 MODES:
-- No args → returns the full AI Agent Guide (workflow, rules, batch operations, visual composition tips)
+- No args → returns the full AI Agent Guide (same content as pinepaper://docs/agent-guide)
 - tool: "pinepaper_agent_batch_execute" → returns that tool's full verbose description
 - category: "animation" → returns all tools in that category with full descriptions
 
@@ -6794,6 +5500,224 @@ VERBOSITY:
             },
         },
     },
+    // ---------------------------------------------------------------------------
+    // DATA VISUALIZATION (CHARTS)
+    // ---------------------------------------------------------------------------
+    {
+        name: 'pinepaper_create_chart',
+        annotations: {
+            title: 'Create Chart',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: `Create and manage data visualizations on the canvas.
+
+ACTIONS:
+- create: Create a chart. Params: chartType, data (array of objects), options
+- update: Update chart data. Params: chartId, data, options
+- reconfigure: Change chart styling. Params: chartId, options
+- remove: Delete a chart. Params: chartId
+
+CHART TYPES: bar, line, scatter, area
+
+DATA FORMAT: Array of objects, e.g. [{category: "A", value: 10}, {category: "B", value: 20}]
+
+OPTIONS (vary by chart type):
+- Common: title, width, height, x, y, colors, animation, axisColor, labelColor, labelFontSize
+- Bar: barWidth, barGap, xLabel, yLabel
+    orient: 'horizontal' flips bars to grow rightward from a left Y-axis — best for long category names
+    labelArrangement: 'auto'|'horizontal'|'slanted'|'vertical'|'truncate'|'wrap'
+      auto      — smart: measures widest label and picks horizontal → slanted (−45°) → vertical (−90°) by slot width
+      slanted   — force −45° rotation
+      vertical  — force −90° rotation
+      truncate  — ellipsis when label exceeds slot (uses ctx.measureText; override char cap with labelTruncateMaxChars)
+      wrap      — split on last space before midpoint, up to two lines
+    Bottom-margin is capped at 25% (slanted) / 35% (vertical) of chart height, so changing labelFontSize shifts labels inside a stable budget rather than shrinking the bars.
+- Line: lineColor, lineWidth, xLabel, yLabel
+- Scatter: dotColor, dotRadius
+- Area: fillColor, lineColor, lineWidth
+
+Data field mapping: use xField/yField in options to specify which data keys to use for axes.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['create', 'update', 'reconfigure', 'remove'],
+                    description: 'Chart action',
+                },
+                chartType: {
+                    type: 'string',
+                    enum: ['bar', 'line', 'scatter', 'area'],
+                    description: 'Chart type (for create)',
+                },
+                chartId: { type: 'string', description: 'Chart ID (for update/reconfigure/remove)' },
+                data: {
+                    type: 'array',
+                    items: { type: 'object' },
+                    description: 'Data array of objects (for create/update)',
+                },
+                options: {
+                    type: 'object',
+                    description: 'Chart options (colors, title, dimensions, field mapping, animation)',
+                },
+            },
+            required: ['action'],
+        },
+    },
+    // ---------------------------------------------------------------------------
+    // MAGIC SYSTEM
+    // ---------------------------------------------------------------------------
+    {
+        name: 'pinepaper_magic',
+        annotations: {
+            title: 'Magic',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: `Ontology-aware auto-animation and style remixing.
+
+ACTIONS:
+- animate: Apply mood-driven animations, effects, and deformations. Params: mood, selectionOnly
+- remix: Non-destructive style cycling (colors, fonts, shadows). Params: selectionOnly
+
+MOODS: calm, professional, energetic, dramatic, whimsical
+
+The magic system analyzes canvas content via the design graph, selects type-appropriate treatments (animations for shapes, collage for text, filters for images), and tracks provenance.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['animate', 'remix'],
+                    description: 'Magic action',
+                },
+                mood: {
+                    type: 'string',
+                    enum: ['calm', 'professional', 'energetic', 'dramatic', 'whimsical'],
+                    description: 'Energy/mood for animation selection',
+                },
+                selectionOnly: { type: 'boolean', description: 'Only affect selected items (default: false)' },
+            },
+            required: ['action'],
+        },
+    },
+    // ---------------------------------------------------------------------------
+    // PHYSICS (RIGID BODY SIMULATION)
+    // ---------------------------------------------------------------------------
+    {
+        name: 'pinepaper_physics',
+        annotations: {
+            title: 'Physics',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: `Rigid body physics simulation (Box2D/Planck.js).
+
+ACTIONS:
+- init: Start physics world. Params: gravity ({x, y}, default {x:0, y:980})
+- add_body: Register item as physics body. Params: itemId, bodyType (static|dynamic|kinematic), mass, friction, restitution, fixedRotation, shape (auto|circle|rect)
+- remove_body: Remove from physics. Params: itemId
+- apply_force: Continuous force in px/s². Params: itemId, force ({x, y})
+- apply_impulse: Instant velocity change. Params: itemId, impulse ({x, y})
+- set_velocity: Set linear velocity. Params: itemId, velocity ({x, y})
+- get_state: Get body position/velocity/rotation. Params: itemId
+- create_ground: Static floor plane. Params: y, width
+- create_joint: Connect two bodies. Params: itemId, targetItemId, jointType (revolute|distance|weld|prismatic), jointParams`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['init', 'add_body', 'remove_body', 'apply_force', 'apply_impulse', 'set_velocity', 'get_state', 'create_ground', 'create_joint'],
+                    description: 'Physics action',
+                },
+                itemId: { type: 'string', description: 'Target item ID' },
+                gravity: {
+                    type: 'object',
+                    properties: { x: { type: 'number' }, y: { type: 'number' } },
+                    description: 'Gravity vector (for init)',
+                },
+                bodyType: {
+                    type: 'string',
+                    enum: ['static', 'dynamic', 'kinematic'],
+                    description: 'Physics body type',
+                },
+                mass: { type: 'number', description: 'Body mass (default: 1)' },
+                friction: { type: 'number', description: 'Surface friction (default: 0.3)' },
+                restitution: { type: 'number', description: 'Bounciness 0-1 (default: 0.3)' },
+                fixedRotation: { type: 'boolean', description: 'Prevent rotation' },
+                shape: { type: 'string', enum: ['auto', 'circle', 'rect'], description: 'Collision shape (default: auto)' },
+                force: {
+                    type: 'object',
+                    properties: { x: { type: 'number' }, y: { type: 'number' } },
+                    description: 'Force vector in px/s²',
+                },
+                impulse: {
+                    type: 'object',
+                    properties: { x: { type: 'number' }, y: { type: 'number' } },
+                    description: 'Impulse vector',
+                },
+                velocity: {
+                    type: 'object',
+                    properties: { x: { type: 'number' }, y: { type: 'number' } },
+                    description: 'Velocity vector',
+                },
+                y: { type: 'number', description: 'Ground Y position' },
+                width: { type: 'number', description: 'Ground width' },
+                targetItemId: { type: 'string', description: 'Second item for joint' },
+                jointType: {
+                    type: 'string',
+                    enum: ['revolute', 'distance', 'weld', 'prismatic'],
+                    description: 'Joint type',
+                },
+                jointParams: {
+                    type: 'object',
+                    description: 'Joint-specific parameters (anchor, enableMotor, motorSpeed, etc.)',
+                },
+            },
+            required: ['action'],
+        },
+    },
+    // ---------------------------------------------------------------------------
+    // MEASUREMENT SYSTEM
+    // ---------------------------------------------------------------------------
+    {
+        name: 'pinepaper_measurement',
+        annotations: {
+            title: 'Measurement',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        description: `Rulers, grid overlay, snap-to-grid, and dimension readout.
+
+ACTIONS:
+- set_rulers: Show/hide rulers. Params: enabled (bool)
+- set_grid: Show/hide unit grid. Params: enabled (bool)
+- get_dimensions: Get item bounds. Params: itemId → returns {x, y, width, height, rotation}
+- set_snap: Enable/disable snap-to-grid. Params: enabled (bool)`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['set_rulers', 'set_grid', 'get_dimensions', 'set_snap'],
+                    description: 'Measurement action',
+                },
+                enabled: { type: 'boolean', description: 'Enable/disable (for set_rulers, set_grid, set_snap)' },
+                itemId: { type: 'string', description: 'Item ID (for get_dimensions)' },
+            },
+            required: ['action'],
+        },
+    },
 ];
 /**
  * Get a tool definition by name