@pinepaper.studio/mcp-server 1.4.3 → 1.5.1

package/dist/index.js

@@ -11,92 +11,128 @@
  */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-import { PINEPAPER_TOOLS } from './tools/definitions.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { PINEPAPER_TOOLS, getToolsForVerbosity } from './tools/definitions.js';
+import { getToolsForToolkit, detectToolkitFromEnvironment, detectVerbosityFromEnvironment, isToolkitExplicitlySet, isVerbosityExplicitlySet, getClientProfile, } from './tools/toolkits.js';
 import { handleToolCall, getExecutionMode } from './tools/handlers.js';
 import { initI18n, DEFAULT_LOCALE, } from './i18n/index.js';
+import { PROMPTS, getPromptMessages } from './prompts/index.js';
 // =============================================================================
 // SERVER INFO
 // =============================================================================
 const SERVER_INFO = {
     name: 'pinepaper-mcp',
-    version: '1.4.0',
+    version: '1.5.1',
     description: 'MCP Server for PinePaper Studio - Create animated graphics with AI',
 };
 // =============================================================================
 // RESOURCES (Documentation & Examples)
 // =============================================================================
 const RESOURCES = [
+    // === CORE GUIDES (Start here) ===
     {
         uri: 'pinepaper://docs/getting-started',
-        name: 'Getting Started Guide',
-        description: 'Introduction to PinePaper MCP tools',
+        name: '🚀 Getting Started',
+        description: 'START HERE: Tool categories, quick examples, and how to find the right tools',
+        mimeType: 'text/markdown',
+    },
+    {
+        uri: 'pinepaper://docs/templates',
+        name: '📋 Templates Guide',
+        description: 'Pre-built templates with animations ready - just change content. Check here first!',
+        mimeType: 'text/markdown',
+    },
+    // === FEATURE GUIDES (How to use each feature) ===
+    {
+        uri: 'pinepaper://docs/map-tools',
+        name: '🗺️ Maps Guide',
+        description: 'Create USA state maps, world maps, choropleth coloring, and animated map regions',
+        mimeType: 'text/markdown',
+    },
+    {
+        uri: 'pinepaper://docs/diagrams',
+        name: '📊 Diagrams Guide',
+        description: 'Create flowcharts, UML diagrams, network diagrams, and auto-layout',
+        mimeType: 'text/markdown',
+    },
+    {
+        uri: 'pinepaper://docs/masks',
+        name: '🎭 Masks Guide',
+        description: 'Create reveal effects: wipes, iris, curtains, and custom animated masks',
         mimeType: 'text/markdown',
     },
     {
         uri: 'pinepaper://docs/relations',
-        name: 'Relations Guide',
-        description: 'How to use relations for behavior-driven animation',
+        name: '🔄 Animation Guide',
+        description: 'Animate with relations: orbit, follow, attached, bounce, and more',
         mimeType: 'text/markdown',
     },
     {
         uri: 'pinepaper://docs/generators',
-        name: 'Background Generators',
-        description: 'Available procedural background generators',
+        name: '🎨 Backgrounds Guide',
+        description: 'Create procedural backgrounds: 14 generators including sunburst, grid, waves, bokeh, gradient mesh, wind field, noise textures',
         mimeType: 'text/markdown',
     },
     {
-        uri: 'pinepaper://docs/custom-paths',
-        name: 'Custom Paths Guide',
-        description: 'Advanced path creation with SVG, Paper.js paths, and animations',
+        uri: 'pinepaper://docs/effects-and-filters',
+        name: '✨ Effects Guide',
+        description: 'Add visual effects: sparkle, blast, filters, and post-processing',
         mimeType: 'text/markdown',
     },
     {
-        uri: 'pinepaper://docs/mathematical-patterns',
-        name: 'Mathematical Patterns',
-        description: 'Create spirals, waves, fractals, geometric patterns, and physics simulations',
+        uri: 'pinepaper://docs/customization',
+        name: '🔧 Customization Guide',
+        description: 'How to adapt templates, create custom designs, and handle any user request',
         mimeType: 'text/markdown',
     },
+    // === EXAMPLES (Copy-paste workflows) ===
     {
-        uri: 'pinepaper://docs/effects-and-filters',
-        name: 'Effects & Filters Guide',
-        description: 'Complete reference for visual effects, filters, and post-processing',
+        uri: 'pinepaper://examples/us-states-animated',
+        name: '🇺🇸 US States Animated',
+        description: 'EXAMPLE: Create a US map with random colors that animate in a loop',
         mimeType: 'text/markdown',
     },
     {
-        uri: 'pinepaper://docs/interactive-animations',
-        name: 'Interactive Animations',
-        description: 'Create game-like behaviors with follows, bounds, and dynamic interactions',
+        uri: 'pinepaper://examples/world-population-map',
+        name: '🌍 World Population Map',
+        description: 'EXAMPLE: Choropleth map with population data and color scale',
         mimeType: 'text/markdown',
     },
     {
-        uri: 'pinepaper://docs/paperjs-in-pinepaper',
-        name: 'Paper.js in PinePaper',
-        description: 'Write Paper.js code directly in PinePaper - API reference and examples',
+        uri: 'pinepaper://examples/flowchart',
+        name: '📋 Flowchart Example',
+        description: 'EXAMPLE: Create a decision flowchart with auto-layout',
         mimeType: 'text/markdown',
     },
     {
         uri: 'pinepaper://examples/solar-system',
-        name: 'Solar System Example',
-        description: 'Create an animated solar system with custom paths, orbital rings, and planetary details',
+        name: '🪐 Solar System',
+        description: 'EXAMPLE: Orbiting planets with relations',
         mimeType: 'text/markdown',
     },
     {
-        uri: 'pinepaper://examples/logo-animation',
-        name: 'Logo Animation Example',
-        description: 'Animate a company logo with entrance effects and continuous motion',
+        uri: 'pinepaper://examples/reveal-animation',
+        name: '🎬 Reveal Animation',
+        description: 'EXAMPLE: Text reveal with mask animations',
         mimeType: 'text/markdown',
     },
     {
-        uri: 'pinepaper://examples/data-visualization',
-        name: 'Data Visualization Example',
-        description: 'Create animated charts, graphs, and infographics',
+        uri: 'pinepaper://docs/fonts',
+        name: 'Guide: Font Studio',
+        description: 'Create custom hand-drawn fonts with Font Studio tools',
         mimeType: 'text/markdown',
     },
+    // === ADVANCED (For developers) ===
     {
-        uri: 'pinepaper://examples/particle-systems',
-        name: 'Particle Systems Example',
-        description: 'Build particle effects like fireworks, snow, and starfields',
+        uri: 'pinepaper://docs/custom-paths',
+        name: 'Advanced: Custom Paths',
+        description: 'SVG paths, Paper.js paths, and path animations',
+        mimeType: 'text/markdown',
+    },
+    {
+        uri: 'pinepaper://docs/paperjs-in-pinepaper',
+        name: 'Advanced: Paper.js API',
+        description: 'Write Paper.js code directly for full control',
         mimeType: 'text/markdown',
     },
 ];
@@ -105,70 +141,457 @@ const RESOURCE_CONTENTS = {
 
 ## Overview
 
-PinePaper is a canvas-based animation tool. This MCP server lets you create and animate graphics using natural language.
+PinePaper is a canvas-based animation tool with 121 tools for creating animated graphics, custom fonts, maps, diagrams, and more. This guide helps you find the right tools.
 
-## Quick Start
+## FIRST: Check Templates
 
-1. **Connect to browser**: Use \`pinepaper_browser_connect\` to launch PinePaper Studio
-2. **Clear the canvas**: Use \`pinepaper_clear_canvas\` or \`pinepaper_refresh_page\` to start fresh
-3. **Create items**: Use \`pinepaper_create_item\` to add text, shapes, or graphics
-4. **Add animation**: Use \`pinepaper_add_relation\` for behavior-based animation
-5. **Verify**: Use \`pinepaper_browser_screenshot\` to see your work
-6. **Export**: Use \`pinepaper_export_svg\` to save your work
+PinePaper Studio includes pre-built templates for common use cases. **Templates already have animations configured** - you just change the content!
 
-## IMPORTANT: Welcome Template
+**Before building from scratch, consider:**
+- Is there a template that matches this use case?
+- Can I modify an existing template instead of building new?
+- Templates save time: just update text, colors, or data
+
+**Use \`pinepaper_create_scene\` for complex animated scenes** - it's 4-8x faster than individual tool calls:
+
+\`\`\`
+pinepaper_create_scene
+  backgroundColor: "#0a0a0a"
+  items:
+    - name: "sun", itemType: "circle", position: {x: 400, y: 300}, properties: {radius: 50, color: "#fbbf24"}
+    - name: "earth", itemType: "circle", position: {x: 550, y: 300}, properties: {radius: 20, color: "#3b82f6"}
+  relations:
+    - source: "earth", target: "sun", type: "orbits", params: {radius: 150, speed: 0.5}
+  animations:
+    - target: "sun", type: "pulse", speed: 0.3
+\`\`\`
+
+## Tool Categories at a Glance
+
+| Category | Use When | Key Tools |
+|----------|----------|-----------|
+| **Scenes** | Multi-item animated scenes | \`pinepaper_create_scene\` (FASTEST) |
+| **Maps** | US states, world maps, choropleth | \`pinepaper_load_map\`, \`pinepaper_apply_data_colors\`, \`pinepaper_animate_map_regions\` |
+| **Shapes** | Circles, stars, text, rectangles | \`pinepaper_create_item\` |
+| **Animation** | Orbiting, following, pulsing | \`pinepaper_add_relation\`, \`pinepaper_animate\` |
+| **Masks** | Reveal effects, wipes, transitions | \`pinepaper_apply_animated_mask\` |
+| **Diagrams** | Flowcharts, UML, connections | \`pinepaper_create_diagram_shape\`, \`pinepaper_connect\` |
+| **Backgrounds** | Patterns, gradients, generators | \`pinepaper_execute_generator\` |
+
+## Quick Examples
+
+### Create a US Map with Animated Colors
+\`\`\`
+1. pinepaper_load_map mapId: "usa", options: { projection: "albers" }
+2. pinepaper_apply_data_colors data: { "CA": 100, "TX": 80, "NY": 70 }, options: { colorScale: "blues" }
+3. pinepaper_animate_map_wave duration: 10, loop: true, colors: ["#ef4444", "#22c55e", "#3b82f6"]
+\`\`\`
+
+### Create Orbiting Animation (Using create_scene - Recommended)
+\`\`\`
+pinepaper_create_scene
+  items:
+    - name: "sun", itemType: "circle", position: {x: 400, y: 300}, properties: {radius: 50, color: "#fbbf24"}
+    - name: "planet", itemType: "circle", position: {x: 550, y: 300}, properties: {radius: 15, color: "#3b82f6"}
+  relations:
+    - source: "planet", target: "sun", type: "orbits"
+\`\`\`
+
+### Create Reveal Animation
+\`\`\`
+1. pinepaper_create_item type: "text", params: { x: 400, y: 300, content: "Hello", fontSize: 48 }
+2. pinepaper_apply_animated_mask itemId: "item_1", preset: "wipeLeft", options: { duration: 0.5 }
+\`\`\`
+
+## Quick Start
+
+Agent mode connects automatically on first tool call. Just start creating!
 
-First-time visitors to PinePaper Studio see a **welcome template** with example items on the canvas. Before creating your own content:
+1. **Check templates first** - existing designs just need content changes
+2. **Use \`pinepaper_create_scene\`** for multi-item animated scenes (fastest)
+3. **Or create items individually**: \`pinepaper_create_item\` for shapes/text
+4. **Add animation**: \`pinepaper_add_relation\` for behavior-based animation
+5. **Verify**: \`pinepaper_browser_screenshot\` to see your work
+6. **Export**: \`pinepaper_export_svg\` to save
 
-### To Clear the Welcome Template:
-- **Option 1**: Use \`pinepaper_clear_canvas\` to remove all items
-- **Option 2**: Use \`pinepaper_refresh_page\` to reload the page (most reliable)
-- After clearing, verify with \`pinepaper_get_items\` that the canvas is empty
+## IMPORTANT: Welcome Template
 
-The welcome template only appears once. After refreshing or clearing, it won't appear again.
+First-time visitors see a welcome template. Clear it with:
+- \`pinepaper_clear_canvas\` - removes all items
+- \`pinepaper_agent_reset\` - quick reset
 
 ## Key Concepts
 
 ### Items
-Everything on the canvas is an item with a registry ID (e.g., "item_1"). Use this ID to reference items in other operations.
-
-**Creating Items:**
-- Use \`pinepaper_create_item\` with \`itemType\` (text, circle, star, rectangle, etc.)
-- Specify \`position\` as {x, y} coordinates
-- Add \`properties\` for styling (color, fontSize, radius, etc.)
-
-### Relations (Primary Animation Method)
-Relations describe HOW items behave relative to each other. This is the **recommended way** to create animations:
-- \`orbits\`: Circular motion around another item
-- \`follows\`: Move toward another item with smoothing
-- \`attached_to\`: Fixed offset from parent item
-- \`points_at\`: Rotate to face another item
-- \`maintains_distance\`: Keep fixed distance from target
-
-**Verifying Animations:**
-After adding a relation, use \`pinepaper_browser_screenshot\` to verify the animation is working. Check that:
-1. Items are positioned correctly
-2. Animation is visibly moving (take multiple screenshots at intervals)
-3. The relation appears in \`pinepaper_query_relations\`
-
-### Deleting Items
-- Use \`pinepaper_delete_item\` with the item's registry ID
-- Use \`pinepaper_get_items\` first to find item IDs
-- If deletion fails, try \`pinepaper_clear_canvas\` to remove everything
-
-### Generators
-Procedural backgrounds like sunburst, waves, grid patterns.
-
-## Example Workflow
-
-\`\`\`
-1. Connect: pinepaper_browser_connect
-2. Clear canvas: pinepaper_clear_canvas (removes welcome template)
-3. Verify empty: pinepaper_get_items (should return count: 0)
-4. Create sun: pinepaper_create_item type=circle, color=#fbbf24, radius=60
-5. Create earth: pinepaper_create_item type=circle, color=#3b82f6, radius=20
-6. Add orbit: pinepaper_add_relation earth orbits sun, radius=150
-7. Screenshot: pinepaper_browser_screenshot (verify animation)
+Everything on canvas has a registry ID (e.g., "item_1"). Use this ID for animations and modifications.
+
+### Relations (Animation)
+Describe behavior between items:
+- \`orbits\`: Circular motion around target
+- \`follows\`: Move toward target with smoothing
+- \`attached_to\`: Fixed offset from parent
+- \`points_at\`: Rotate to face target
+
+### Maps
+Built-in maps: \`world\`, \`worldHighRes\`, \`usa\` (US states)
+Load with \`pinepaper_load_map\`, animate with \`pinepaper_animate_map_regions\` or \`pinepaper_animate_map_wave\`
+
+### Masks
+Reveal effects: wipeLeft, wipeRight, wipeUp, wipeDown, iris, irisOut, star, heart, curtainHorizontal, curtainVertical, cinematic, diagonalWipe, revealUp, revealDown
+Apply with \`pinepaper_apply_animated_mask\`
+
+## Agent Workflow (Recommended)
+
+For AI agents, use the batch pipeline for maximum efficiency:
+
+1. \`pinepaper_agent_start_job\` — clear canvas, set preset → returns canvasSize {width, height} for positioning
+2. \`pinepaper_agent_batch_execute\` — ONE call with ALL operations (12 types: canvas, background, generators, items, animations, keyframes, relations, masks, effects, playback)
+3. \`pinepaper_agent_end_job\` — returns screenshot for user validation
+4. User reviews → modify specific items or start new job
+
+See the \`pinepaper_agent_batch_execute\` tool description for full operation reference.
+
+**Note:** Diagrams (flowcharts, UML) use their own tools — \`pinepaper_create_diagram_shape\` + \`pinepaper_connect\` — not batch_execute. See \`pinepaper://docs/diagrams\`.
+
+## Detailed Guides
+
+- Maps: Read \`pinepaper://docs/map-tools\`
+- Diagrams: Read \`pinepaper://docs/diagrams\`
+- Masks: Read \`pinepaper://docs/masks\`
+- Relations: Read \`pinepaper://docs/relations\`
+- Generators: Read \`pinepaper://docs/generators\`
+- Fonts: Read \`pinepaper://docs/fonts\`
+- Customization: Read \`pinepaper://docs/customization\`
+`,
+    'pinepaper://docs/customization': `# Customization Guide
+
+**Intent:** Learn how to handle any user design request by combining tools, adapting templates, and creating custom solutions.
+
+## Understanding User Requests
+
+Users will ask for varied graphics. Here's how to approach any request:
+
+### Step 1: Identify the Category
+
+| Request Type | Primary Tools | Example |
+|-------------|---------------|---------|
+| Map visualization | \`load_map\`, \`apply_data_colors\` | "Show sales by state" |
+| Animated logo | \`create_item\`, \`add_relation\` | "Make my logo pulse" |
+| Infographic | \`create_diagram_shape\`, \`connect\` | "Create a flowchart" |
+| Social media | \`set_canvas_size\`, \`create_item\` | "Instagram post" |
+| Data chart | \`create_item\` (rectangles for bars) | "Bar chart of values" |
+| Reveal/intro | \`apply_animated_mask\` | "Text wipe animation" |
+
+### Step 2: Choose Your Approach
+
+| Complexity | Approach | When |
+|------------|----------|------|
+| Simple | Single tools | One shape, one animation |
+| Medium | \`create_scene\` | Multiple items with relations |
+| Complex | Step-by-step tools | Custom logic, conditional design |
+
+## Customization Patterns
+
+### Pattern 1: Color Scheme Changes
+
+User: "Make it blue instead of red"
+
+\`\`\`
+// Original
+pinepaper_create_item itemType: "circle" properties: {color: "#ef4444"}
+
+// Customized - change color property
+pinepaper_create_item itemType: "circle" properties: {color: "#3b82f6"}
+\`\`\`
+
+**Common color palettes:**
+| Theme | Colors |
+|-------|--------|
+| Professional | #1e293b, #3b82f6, #f8fafc |
+| Vibrant | #ef4444, #fbbf24, #22c55e, #3b82f6 |
+| Pastel | #fecaca, #fef08a, #bbf7d0, #bfdbfe |
+| Dark mode | #0f172a, #1e293b, #334155, #f8fafc |
+
+### Pattern 2: Size and Position Adjustments
+
+User: "Make it bigger" or "Center it"
+
+\`\`\`
+// Get canvas size first
+pinepaper_get_canvas_size → {width: 800, height: 600}
+
+// Center position = (width/2, height/2)
+pinepaper_create_item itemType: "text" position: {x: 400, y: 300}
+  properties: {content: "Centered", fontSize: 48}
+
+// Make bigger - increase radius, fontSize, width/height
+pinepaper_modify_item itemId: "item_1" properties: {scale: 1.5}
+\`\`\`
+
+### Pattern 3: Animation Speed/Style Changes
+
+User: "Make it faster" or "Smoother animation"
+
+\`\`\`
+// Faster orbit
+pinepaper_add_relation sourceId: "item_1" targetId: "item_2" relationType: "orbits"
+  params: {speed: 2.0}  // Higher = faster
+
+// Smoother following
+pinepaper_add_relation sourceId: "item_1" targetId: "item_2" relationType: "follows"
+  params: {smoothing: 0.95}  // Higher = smoother (0-1)
+
+// Different easing for masks
+pinepaper_apply_animated_mask itemId: "item_1" preset: "wipeLeft"
+  options: {easing: "easeInOut"}  // linear, easeIn, easeOut, easeInOut, bounce
+\`\`\`
+
+### Pattern 4: Adding Text to Any Design
+
+User: "Add a title" or "Label the items"
+
+\`\`\`
+// Title at top
+pinepaper_create_item itemType: "text" position: {x: 400, y: 50}
+  properties: {content: "My Title", fontSize: 36, fontWeight: "bold", color: "#ffffff"}
+
+// Label attached to item (moves with it)
+pinepaper_create_item itemType: "text" position: {x: 400, y: 280}
+  properties: {content: "Earth", fontSize: 14, color: "#94a3b8"}
+→ label_1
+
+pinepaper_add_relation sourceId: "label_1" targetId: "earth" relationType: "attached_to"
+  params: {offset: [0, -30]}  // Above the item
+\`\`\`
+
+### Pattern 5: Creating Data-Driven Graphics
+
+User: "Show these numbers as a chart"
+
+\`\`\`
+// Bar chart from data
+// Data: [10, 25, 15, 30, 20]
+
+// Bar 1 (height proportional to value)
+pinepaper_create_item itemType: "rectangle" position: {x: 150, y: 350}
+  properties: {width: 40, height: 100, color: "#3b82f6"}  // height = value * scale
+
+// Bar 2
+pinepaper_create_item itemType: "rectangle" position: {x: 210, y: 275}
+  properties: {width: 40, height: 250, color: "#3b82f6"}
+
+// Continue for each data point...
+// Position x increases by spacing, height = value * multiplier
+\`\`\`
+
+### Pattern 6: Responsive Canvas Sizes
+
+User: "Make it for Instagram" or "YouTube thumbnail"
+
+\`\`\`
+// Set canvas FIRST, then position items relative to it
+pinepaper_set_canvas_size preset: "instagram-post"  // 1080x1080
+
+// Now center = (540, 540)
+pinepaper_create_item itemType: "text" position: {x: 540, y: 540}
+  properties: {content: "Centered!", fontSize: 64}
+\`\`\`
+
+**Common presets:**
+| Preset | Size | Use |
+|--------|------|-----|
+| instagram-post | 1080x1080 | Square posts |
+| instagram-story | 1080x1920 | Stories, Reels |
+| youtube-thumbnail | 1280x720 | Video thumbnails |
+| twitter-post | 1200x675 | Twitter/X images |
+
+### Pattern 7: Complex Animations with Multiple Relations
+
+User: "Make planets orbit the sun with moons"
+
+\`\`\`
+pinepaper_create_scene
+  backgroundColor: "#0a0a0a"
+  items:
+    - name: "sun", itemType: "circle", position: {x: 400, y: 300}
+      properties: {radius: 50, color: "#fbbf24"}
+    - name: "earth", itemType: "circle", position: {x: 550, y: 300}
+      properties: {radius: 20, color: "#3b82f6"}
+    - name: "moon", itemType: "circle", position: {x: 580, y: 300}
+      properties: {radius: 6, color: "#9ca3af"}
+    - name: "mars", itemType: "circle", position: {x: 650, y: 300}
+      properties: {radius: 15, color: "#ef4444"}
+  relations:
+    - source: "earth", target: "sun", type: "orbits", params: {radius: 150, speed: 0.5}
+    - source: "moon", target: "earth", type: "orbits", params: {radius: 30, speed: 2}
+    - source: "mars", target: "sun", type: "orbits", params: {radius: 250, speed: 0.3}
+  animations:
+    - target: "sun", type: "pulse", speed: 0.3
+\`\`\`
+
+## Handling Edge Cases
+
+### User Provides Specific Colors
+Always use their exact hex codes:
+\`\`\`
+User: "Use #FF5733 for the background"
+→ properties: {color: "#FF5733"}
+\`\`\`
+
+### User Wants Something Not Directly Supported
+Combine tools creatively:
+\`\`\`
+User: "3D cube effect"
+→ Create 3 parallelograms with offset positions and colors
+   Use paths with segments to draw isometric shapes
+\`\`\`
+
+### User Changes Mind Mid-Design
+Use modify and delete:
+\`\`\`
+pinepaper_modify_item itemId: "item_1" properties: {color: "#new_color"}
+pinepaper_delete_item itemId: "item_2"
+\`\`\`
+
+### Performance with Many Items
+Use batch operations:
+\`\`\`
+pinepaper_batch_create items: [{...}, {...}, {...}]  // Instead of multiple create_item calls
+\`\`\`
+
+## Decision Tree for Any Request
+
+\`\`\`
+Is it a MAP? → pinepaper_load_map
+Is it a DIAGRAM/FLOWCHART? → pinepaper_create_diagram_shape + pinepaper_connect
+Is it ANIMATED? → pinepaper_add_relation or pinepaper_animate
+Is it a REVEAL/INTRO? → pinepaper_apply_animated_mask
+Is it DATA VISUALIZATION? → Create shapes proportional to data values
+Is it a BACKGROUND? → pinepaper_execute_generator
+Otherwise → pinepaper_create_item for shapes/text
+\`\`\`
+
+## Example: Complete Custom Request
+
+User: "Create an animated infographic showing 3 steps with arrows"
+
+\`\`\`
+// 1. Set canvas
+pinepaper_set_canvas_size preset: "presentation-16x9"
+
+// 2. Create step boxes
+pinepaper_create_diagram_shape shapeType: "process" position: {x: 300, y: 400}
+  label: "Step 1: Research" style: {fillColor: "#3b82f6"} → item_1
+
+pinepaper_create_diagram_shape shapeType: "process" position: {x: 600, y: 400}
+  label: "Step 2: Design" style: {fillColor: "#8b5cf6"} → item_2
+
+pinepaper_create_diagram_shape shapeType: "process" position: {x: 900, y: 400}
+  label: "Step 3: Build" style: {fillColor: "#22c55e"} → item_3
+
+// 3. Connect with arrows
+pinepaper_connect sourceItemId: "item_1" targetItemId: "item_2"
+  routing: "direct" animated: true
+
+pinepaper_connect sourceItemId: "item_2" targetItemId: "item_3"
+  routing: "direct" animated: true
+
+// 4. Add title
+pinepaper_create_item itemType: "text" position: {x: 600, y: 150}
+  properties: {content: "Our Process", fontSize: 48, fontWeight: "bold"}
+
+// 5. Apply reveal animations
+pinepaper_apply_animated_mask itemId: "item_1" preset: "wipeLeft"
+  options: {startTime: 0, duration: 0.4}
+
+pinepaper_apply_animated_mask itemId: "item_2" preset: "wipeLeft"
+  options: {startTime: 0.3, duration: 0.4}
+
+pinepaper_apply_animated_mask itemId: "item_3" preset: "wipeLeft"
+  options: {startTime: 0.6, duration: 0.4}
+\`\`\`
+
+## Key Principles
+
+1. **Understand first** - What is the user trying to achieve?
+2. **Start simple** - Use the most direct tool for the job
+3. **Build incrementally** - Add complexity one step at a time
+4. **Verify with screenshots** - \`pinepaper_browser_screenshot\` after each major step
+5. **Offer alternatives** - If something can't be done exactly, suggest similar approaches
+`,
+    'pinepaper://docs/templates': `# Templates & Timed Animation Guide
+
+## Apply a Template
+
+\`pinepaper_list_templates\` — browse available pre-built templates.
+\`pinepaper_apply_template\` — load a template by name. Animations are pre-configured.
+After applying: modify text/colors with \`pinepaper_modify_item\`, then export.
+
+## Template Categories
+
+| Category | Examples |
+|----------|----------|
+| Map | US Election, World Data, Travel Route |
+| Animation | Solar System, Logo Reveal, Text Intro, Particle Burst |
+| Diagram | Flowchart, Org Chart, Network |
+| Social Media | YouTube Thumbnail (1280x720), Instagram Story (1080x1920), TikTok |
+
+## Modifying Templates
+
+Change safely: \`properties.content\`, \`properties.color\`, \`backgroundColor\`, positions, sizes.
+Preserve: \`relations\` array, \`animations\` array, item \`name\` values (relations reference these).
+
+## Building Timed Animations (4 steps)
+
+For invitations, intros, promos, reveals — any timed animation:
+
+**1. Create items** — \`pinepaper_create_scene\` with all items. Timed reveals: set \`opacity: 0\`.
+Items get sequential IDs: first = \`item_1\`, second = \`item_2\`, etc.
+
+**2. Animate items** — ONE \`pinepaper_execute_custom_code\` call with all animations:
+\`\`\`
+app.addAnimation(registryId, keyframes, options)
+  registryId: 'item_1'
+  keyframes:  [{time: 0, properties: {opacity: 0}, easing: 'easeInOut'},
+               {time: 1, properties: {opacity: 1}}]
+  options:    {duration: number, loop?: boolean, pingPong?: boolean}
+\`\`\`
+Animatable properties: \`opacity\`, \`scale\`, \`scaleX\`, \`scaleY\`, \`x\`, \`y\`, \`rotation\`, \`fillColor\`, \`strokeColor\`, \`fontSize\`.
+Stagger items by offsetting \`time\` values across items.
+
+**3. Play** — \`pinepaper_play_timeline\`
+
+**4. Export** — \`pinepaper_agent_export\` (SVG/PNG/GIF/MP4/WebM/PDF)
+
+## Text Reveal Pattern
+
+Create text items, then apply mask reveals with staggered start times:
+\`\`\`
+pinepaper_apply_animated_mask  itemId: "item_1"  preset: "wipeLeft"  options: {duration: 0.5}
+pinepaper_apply_animated_mask  itemId: "item_2"  preset: "wipeLeft"  options: {startTime: 0.3, duration: 0.5}
+\`\`\`
+Mask presets: wipeLeft, wipeRight, wipeUp, wipeDown, iris, irisOut, star, heart, curtainHorizontal, curtainVertical, cinematic, diagonalWipe, revealUp, revealDown.
+
+## Advanced Capabilities (via execute_custom_code)
+
+**Time-scoped relations** — relation active only during a time window:
+\`\`\`
+app.addRelation(sourceId, targetId, type, {startTime: 2, endTime: 5, autoRemove: true, ...params})
+\`\`\`
+
+**Keyframe priority** — when keyframes and relations target the same property:
+\`\`\`
+app.addRelation(sourceId, targetId, type, {relationBehavior: 'keyframeFirst', ...params})
+\`\`\`
+
+**Per-item timing** — offset an item into the global timeline:
+\`\`\`
+app.setTimeOffset(registryId, offsetSeconds)
+\`\`\`
+
+**Atomic relation replace** — swap relation params without remove+add:
+\`\`\`
+app.replaceRelation(sourceId, targetId, type, newParams)
 \`\`\`
 `,
     'pinepaper://docs/relations': `# Relations Guide
@@ -226,6 +649,101 @@ Stay within target's bounds.
 - \`padding\`: Inner padding
 - \`bounce\`: Bounce off edges
 
+### morphs_to
+Smoothly transform source shape into target shape over time.
+- \`duration\`: Morph duration in seconds (default: 1)
+- \`hideTarget\`: Hide target item since it's just a shape reference (default: true)
+- \`removeTargetOnComplete\`: Delete target after morph completes (default: false)
+- \`easing\`: Timing function ('linear', 'easeIn', 'easeOut', 'easeInOut')
+
+**Usage patterns:**
+\`\`\`
+// Default: Circle morphs to star's shape, star stays hidden
+pinepaper_add_relation sourceId: "circle" targetId: "star" relationType: "morphs_to"
+  params: {duration: 1}
+
+// Clean up: Delete star after morph completes
+pinepaper_add_relation sourceId: "circle" targetId: "star" relationType: "morphs_to"
+  params: {duration: 1, removeTargetOnComplete: true}
+
+// Both visible: Keep star visible (you'll see two stars at end)
+pinepaper_add_relation sourceId: "circle" targetId: "star" relationType: "morphs_to"
+  params: {duration: 1, hideTarget: false}
+\`\`\`
+
+**Great for:** Logo animations, shape transitions, loading indicators, morphing icons
+
+### camera_follows
+Camera pans to follow a target item (like Manim MovingCameraScene).
+- \`smoothing\`: 0-1 (higher = smoother following)
+- \`offset\`: [x, y] offset from target
+- \`zoom\`: Zoom level to maintain
+- \`deadzone\`: Pixels before camera starts moving
+- \`bounds\`: {minX, maxX, minY, maxY} camera movement limits
+
+\`\`\`
+// Camera follows the player character
+pinepaper_add_relation sourceId: "camera" targetId: "player" relationType: "camera_follows"
+  params: {smoothing: 0.9, zoom: 1.5, deadzone: 50}
+\`\`\`
+
+**Great for:** Game-like scenes, following animations, focus tracking
+
+### camera_animates
+Keyframe-based camera zoom and pan animations. Use the special "camera" virtual item.
+- \`keyframes\`: Array of keyframe objects with time, zoom, center, easing
+- \`duration\`: Total animation duration in seconds
+- \`loop\`: Whether to loop the animation
+- \`delay\`: Delay before starting
+
+**Keyframe properties:**
+- \`time\`: Normalized time 0-1
+- \`zoom\`: Zoom level (1 = normal, 2 = 2x zoom in)
+- \`center\`: [x, y] pan center position
+- \`easing\`: Easing function for this keyframe
+
+\`\`\`
+// Cinematic zoom and pan sequence
+pinepaper_add_relation sourceId: "camera" targetId: "camera" relationType: "camera_animates"
+  params:
+    duration: 5
+    loop: false
+    keyframes:
+      - time: 0, zoom: 1, center: [400, 300], easing: "easeOut"
+      - time: 0.3, zoom: 1.5, center: [200, 200], easing: "easeInOut"
+      - time: 0.7, zoom: 2, center: [600, 400], easing: "easeInOut"
+      - time: 1, zoom: 1, center: [400, 300], easing: "easeIn"
+\`\`\`
+
+**Great for:** Cinematic intros, presentations, dramatic reveals, tour animations
+
+## Camera API (Direct Code)
+
+For simpler camera control, use the \`app.camera\` helper API:
+
+\`\`\`javascript
+// Zoom
+app.camera.zoomIn(1.5, 0.5);    // Zoom to 1.5x over 0.5 seconds
+app.camera.zoomOut(0.5, 0.5);   // Zoom out to 0.5x
+
+// Pan
+app.camera.panTo(200, 300, 1);   // Pan to coordinates
+app.camera.panBy(100, 0, 0.5);   // Pan right by 100px
+app.camera.panLeft(50, 0.3);     // Pan left
+app.camera.panRight(50, 0.3);    // Pan right
+app.camera.panUp(50, 0.3);       // Pan up
+app.camera.panDown(50, 0.3);     // Pan down
+
+// Combined
+app.camera.moveTo(200, 300, 2, 1);  // Pan to (200,300) and zoom to 2x
+
+// Control
+app.camera.reset(0.5);          // Reset to default
+app.camera.stop();              // Stop current animation
+app.camera.getState();          // Returns { zoom, center: [x, y] }
+app.camera.isAnimating();       // Check if animating
+\`\`\`
+
 ## Verifying Animations Are Working
 
 After adding a relation, **always verify** that the animation is actually running:
@@ -268,44 +786,136 @@ addRelation(label, planet, 'attached_to', { offset: [0, -30] })
 
 The label will follow the planet as it orbits the star!
 `,
-    'pinepaper://docs/generators': `# Background Generators
+    'pinepaper://docs/generators': `# Background Generators Guide
+
+**Intent:** Create procedural backgrounds with 14 generators covering patterns, effects, organic flows, particles, and textures.
 
-Procedural backgrounds that create dynamic patterns.
+## Key Tool
 
-## Available Generators
+\`\`\`
+pinepaper_execute_generator
+  generatorName: "drawSunburst"
+  params: { rayCount: 16, colors: ["#fbbf24", "#f59e0b"], animated: true }
+\`\`\`
+
+## Classic Generators (7)
 
 ### drawSunburst
-Radial rays from center.
-- \`rayCount\`: Number of rays (default: 16)
-- \`colors\`: Array of ray colors
-- \`bgColor\`: Background color
-- \`animated\`: Enable rotation
+Radial rays from center — energy, attention-grabbing backgrounds.
+- **Core:** rayCount (16), colors, bgColor, animated
+- **Enhanced:** opacity, rayGap (degrees between rays), gradientRays (radial gradient per ray)
 
 ### drawSunsetScene
-Animated sunset with clouds.
-- \`sunColor\`: Sun fill color
-- \`skyColors\`: Array for gradient
-- \`cloudCount\`: Number of clouds
+Animated sunset with clouds — calm, atmospheric.
+- **Core:** sunColor, skyColors, cloudCount
+- **Enhanced:** skyOpacity, starCount, starColor, reflectionEnabled, reflectionOpacity
 
 ### drawGrid
-Geometric grid patterns.
-- \`gridType\`: 'lines', 'dots', or 'squares'
-- \`spacing\`: Cell size
-- \`lineColor\`: Grid color
+Lines, dots, or squares — clean, technical, modern.
+- **Core:** gridType (lines|dots|squares), spacing (40), lineColor, bgColor, lineWidth
+- **Enhanced:** opacity, gap (pixel gap), randomRotation, colorMode (checkerboard|gradient|random|rows|columns), strokeColor, strokeWidth
 
 ### drawWaves
-Layered wave pattern.
-- \`waveCount\`: Number of layers
-- \`colors\`: Wave colors
-- \`amplitude\`: Wave height
-- \`animated\`: Animate waves
+Layered wave pattern — organic, flowing.
+- **Core:** waveCount (5), colors, amplitude (50), frequency (2), bgColor, animated
+- **Enhanced:** opacity, fill (fill between waves), fillOpacity, amplitudeVariation, blendMode
 
 ### drawCircuit
-Tech circuit board.
-- \`lineColor\`: Circuit lines
-- \`nodeColor\`: Junction color
-- \`density\`: 0-1 complexity
-- \`animated\`: Enable bolt effect
+Circuit board pattern — futuristic, digital.
+- **Core:** lineColor, nodeColor, bgColor, density (0-1), animated, boltColor
+- **Enhanced:** traceOpacity, nodeOpacity, diagonalPaths (45-degree traces), chipDensity (auto|none|low|medium|high)
+
+### drawStackedCircles
+Overlapping circles with distribution algorithms.
+- **Core:** count (8), colors, distribution (random|poisson|golden)
+- **Enhanced:** opacityMin/opacityMax, blendMode, strokeWidth, strokeColor, sizeGradient, animationType (pulse|float|none)
+
+### drawPattern
+Geometric shapes in orbit rings.
+- **Core:** patternType, size, color, bgColor
+- **Enhanced:** opacity, blendMode, layers (1-5 concentric rings), layerScaleDecay
+
+## New Generators (7)
+
+### drawBokeh (effects)
+Soft-focus circles — dreamy, photographic depth-of-field.
+\`\`\`
+params: { count: 30, colors: ["#f472b6", "#818cf8", "#34d399"], bgColor: "#0f172a",
+  shadowBlur: 20, distribution: "poisson", driftAnimation: true }
+\`\`\`
+
+### drawGradientMesh (organic)
+Radial gradient blobs with screen blending — modern, vibrant.
+\`\`\`
+params: { colors: ["#ec4899", "#8b5cf6", "#06b6d4"], blobCount: 5,
+  blendMode: "screen", drift: true }
+\`\`\`
+
+### drawGeometricAbstract (geometric)
+Mixed translucent shapes with blend modes — artistic, contemporary.
+\`\`\`
+params: { colors: ["#f43f5e", "#3b82f6", "#10b981"], shapeCount: 12,
+  blendMode: "multiply", rotation: true }
+\`\`\`
+
+### drawWindField (particles)
+Directional wind particles with noise turbulence — weather, motion.
+\`\`\`
+params: { particleCount: 200, colors: ["#e0f2fe", "#bae6fd"], direction: 45,
+  turbulence: 0.5, trailLength: 30, speed: 1.5 }
+\`\`\`
+
+### drawFluidFlow (organic)
+Sinusoidal stream paths with depth layering — liquid, flowing.
+\`\`\`
+params: { streamCount: 8, colors: ["#67e8f9", "#a78bfa", "#f9a8d4"],
+  depthLayers: 3, speed: 0.8 }
+\`\`\`
+
+### drawOrganicFlow (organic)
+Aurora/silk layers — natural, ethereal glow.
+\`\`\`
+params: { layerCount: 4, colors: ["#34d399", "#6ee7b7", "#a7f3d0"],
+  blendMode: "screen", fillToBottom: true, animated: true }
+\`\`\`
+
+### drawNoiseTexture (textures)
+Perlin/grain/stipple noise — subtle, textured.
+\`\`\`
+params: { noiseType: "perlin", colors: ["#94a3b8", "#64748b"],
+  scale: 0.01, density: 0.7, animated: true }
+\`\`\`
+noiseType options: perlin, grain, stipple
+
+## Quick Mood Guide
+
+| Mood | Generators |
+|------|-----------|
+| Dreamy/soft | drawBokeh, drawGradientMesh, drawOrganicFlow |
+| Techy/modern | drawCircuit, drawGrid, drawWindField |
+| Nature/warm | drawSunsetScene, drawSunburst, drawWaves |
+| Abstract | drawGeometricAbstract, drawFluidFlow, drawNoiseTexture |
+| Decorative | drawPattern, drawStackedCircles |
+
+## Combining Generators with Items
+
+\`\`\`
+// Background + content on top
+pinepaper_execute_generator
+  generatorName: "drawBokeh"
+  params: {count: 20, colors: ["#f472b6", "#818cf8"], shadowBlur: 25}
+
+pinepaper_create_item itemType: "text" position: {x: 400, y: 300}
+  properties: {content: "Welcome", fontSize: 72, color: "#ffffff"}
+\`\`\`
+
+## Best Practices
+
+1. **Call generator first** — before creating items
+2. **Use complementary colors** — items should contrast with background
+3. **Consider animation performance** — animated generators + many animated items can slow down
+4. **Match themes** — sunburst for energy, waves for calm, circuit for tech, bokeh for elegance, noise for texture
+5. **Use blendMode** — "screen" brightens, "multiply" darkens, great for layered effects
 `,
     'pinepaper://docs/custom-paths': `# Custom Paths Guide
 
@@ -593,8 +1203,7 @@ Create an animated solar system featuring custom paths, orbital rings, and plane
 ## Step 1: Canvas Setup
 
 \`\`\`
-pinepaper_browser_connect
-pinepaper_clear_canvas
+pinepaper_clear_canvas  # Browser auto-connects in agent mode
 pinepaper_set_background_color color: "#0a0a1a"
 \`\`\`
 
@@ -2341,8 +2950,7 @@ An animated company logo featuring:
 ## Step 1: Canvas Setup
 
 \`\`\`
-pinepaper_browser_connect
-pinepaper_clear_canvas
+pinepaper_clear_canvas  # Browser auto-connects in agent mode
 pinepaper_set_background_color color: "#0f172a"
 pinepaper_set_canvas_size width: 800 height: 600
 \`\`\`
@@ -2581,8 +3189,7 @@ Create animated charts and infographics that bring data to life.
 
 ### Step 1: Setup
 \`\`\`
-pinepaper_browser_connect
-pinepaper_clear_canvas
+pinepaper_clear_canvas  # Browser auto-connects in agent mode
 pinepaper_set_background_color color: "#1f2937"
 \`\`\`
 
@@ -2903,8 +3510,7 @@ Build dynamic particle effects like fireworks, starfields, snow, and fire.
 
 ### Step 1: Create Background
 \`\`\`
-pinepaper_browser_connect
-pinepaper_clear_canvas
+pinepaper_clear_canvas  # Browser auto-connects in agent mode
 pinepaper_set_background_color color: "#000011"
 \`\`\`
 
@@ -3183,29 +3789,1995 @@ pinepaper_animate_item itemId: "bubble4" animationType: "wobble" speed: 0.7
 | Dust | Tiny circles, slow fade, random positions |
 | Confetti | Small rectangles, rotate + bounce, rainbow colors |
 `,
-};
-// =============================================================================
-// SERVER CREATION
-// =============================================================================
-export async function createServer(options = {}) {
-    // Initialize i18n with specified locale
-    const locale = options.locale || detectLocaleFromEnvironment();
-    const i18n = await initI18n(locale);
-    const server = new Server(SERVER_INFO, {
-        capabilities: {
-            tools: {},
-            resources: {},
-        },
-    });
-    // ---------------------------------------------------------------------------
-    // TOOL HANDLERS
+    'pinepaper://docs/map-tools': `# Map Tools Guide
+
+Create geographic visualizations with world maps, choropleth coloring, markers, and labels.
+
+## Available Maps
+
+| Map | Description | Region ID Format |
+|-----|-------------|------------------|
+| \`world\` | World countries (110m) | Full names: "United States of America", "France" |
+| \`worldHighRes\` | World countries (50m, detailed) | Full names |
+| \`usa\` | US states | State codes: "CA", "TX", "NY" |
+
+## Projections
+
+| Projection | Best For |
+|------------|----------|
+| \`naturalEarth\` | World maps (recommended) |
+| \`mercator\` | Web-style maps |
+| \`equalEarth\` | Equal-area comparisons |
+| \`orthographic\` | Globe/3D sphere view |
+| \`albers\` | USA maps (recommended) |
+| \`stereographic\` | Polar regions |
+
+## Loading Maps
+
+\`\`\`
+// Load world map with Natural Earth projection
+pinepaper_load_map mapId: "world"
+  options:
+    projection: "naturalEarth"
+    quality: "balanced"
+    fillColor: "#e5e7eb"
+    strokeColor: "#9ca3af"
+    enableHover: true
+
+// Load USA with Albers projection
+pinepaper_load_map mapId: "usa"
+  options:
+    projection: "albers"
+    quality: "professional"
+\`\`\`
+
+## Highlighting Regions
+
+\`\`\`
+// Highlight countries (use full names for world map)
+pinepaper_highlight_regions
+  regionIds: ["United States of America", "Canada", "Mexico"]
+  options:
+    fillColor: "#3b82f6"
+    strokeColor: "#1d4ed8"
+    animate: true
+
+// Highlight US states (use state codes)
+pinepaper_highlight_regions
+  regionIds: ["CA", "TX", "NY", "FL"]
+  options:
+    fillColor: "#22c55e"
+
+// Remove highlights
+pinepaper_unhighlight_regions regionIds: "all"
+\`\`\`
+
+## Choropleth (Data-Driven Colors)
+
+\`\`\`
+// Population data visualization
+pinepaper_apply_data_colors
+  data:
+    "California": 39538223
+    "Texas": 29145505
+    "Florida": 21538187
+    "New York": 20201249
+  options:
+    colorScale: "blues"
+    showLegend: true
+    legendPosition: "bottom-right"
+    legendTitle: "Population"
+\`\`\`
+
+### Color Scales
+- \`blues\` - Light to dark blue
+- \`greens\` - Light to dark green
+- \`reds\` - Light to dark red
+- \`oranges\` - Light to dark orange
+- \`purples\` - Light to dark purple
+- \`heat\` - Yellow to red heat map
+
+## Map Markers
+
+\`\`\`
+// Add marker at coordinates
+pinepaper_add_marker
+  lat: 37.7749
+  lon: -122.4194
+  label: "San Francisco"
+  color: "#ef4444"
+  size: 8
+  pulse: true
+
+// Add marker with different shape
+pinepaper_add_marker
+  lat: 40.7128
+  lon: -74.0060
+  label: "New York"
+  shape: "pin"
+\`\`\`
+
+### Marker Shapes
+- \`circle\` - Simple circle (default)
+- \`pin\` - Map pin icon
+- \`star\` - Star shape
+
+## Map Labels
+
+\`\`\`
+// Add labels to all visible regions
+pinepaper_add_map_labels
+  options:
+    fontSize: 10
+    fontColor: "#374151"
+    labelType: "name"
+
+// Add labels to specific regions
+pinepaper_add_map_labels
+  regions: ["California", "Texas"]
+  options:
+    labelType: "code"
+\`\`\`
+
+### Label Types
+- \`name\` - Full region name
+- \`code\` - Region code (e.g., "CA")
+- \`value\` - Data value (after applyDataColors)
+
+## Map Navigation
+
+\`\`\`
+// Pan to coordinates
+pinepaper_pan_map lat: 50 lon: 10 animate: true duration: 1
+
+// Zoom in
+pinepaper_zoom_map level: 2 animate: true
+\`\`\`
+
+## Importing Custom Maps
+
+\`\`\`
+// Import from URL
+pinepaper_import_custom_map
+  url: "https://example.com/custom-boundaries.geojson"
+  options:
+    projection: "mercator"
+
+// Import GeoJSON directly
+pinepaper_import_custom_map
+  geoJson: { "type": "FeatureCollection", "features": [...] }
+  options:
+    projection: "naturalEarth"
+\`\`\`
+
+## Example: US Population Map
+
+\`\`\`
+// 1. Load USA map
+pinepaper_load_map mapId: "usa"
+  options:
+    projection: "albers"
+    quality: "professional"
+    fillColor: "#e5e7eb"
+    strokeColor: "#9ca3af"
+    strokeWidth: 0.5
+    enableHover: true
+
+// 2. Apply population data
+pinepaper_apply_data_colors
+  data:
+    "CA": 39538223
+    "TX": 29145505
+    "FL": 21538187
+    "NY": 20201249
+    "PA": 13002700
+    "IL": 12812508
+    "OH": 11799448
+    "GA": 10711908
+  options:
+    colorScale: "blues"
+    showLegend: true
+    legendTitle: "Population"
+
+// 3. Add major city markers
+pinepaper_add_marker lat: 34.0522 lon: -118.2437 label: "Los Angeles" pulse: true
+pinepaper_add_marker lat: 40.7128 lon: -74.0060 label: "New York" pulse: true
+pinepaper_add_marker lat: 41.8781 lon: -87.6298 label: "Chicago" pulse: true
+
+// 4. Export final map
+pinepaper_export_map
+\`\`\`
+
+## Example: World Comparison
+
+\`\`\`
+// 1. Load world map
+pinepaper_load_map mapId: "worldHighRes"
+  options:
+    projection: "naturalEarth"
+    quality: "balanced"
+    fillColor: "#f3f4f6"
+    strokeColor: "#d1d5db"
+
+// 2. Highlight regions of interest
+pinepaper_highlight_regions
+  regionIds: ["United States of America", "China", "Japan", "Germany", "United Kingdom"]
+  options:
+    fillColor: "#3b82f6"
+    animate: true
+
+// 3. Add capital markers
+pinepaper_add_marker lat: 38.9072 lon: -77.0369 label: "Washington DC"
+pinepaper_add_marker lat: 39.9042 lon: 116.4074 label: "Beijing"
+pinepaper_add_marker lat: 35.6762 lon: 139.6503 label: "Tokyo"
+pinepaper_add_marker lat: 52.5200 lon: 13.4050 label: "Berlin"
+pinepaper_add_marker lat: 51.5074 lon: -0.1278 label: "London"
+\`\`\`
+
+## Hit Testing
+
+\`\`\`
+// Find region at canvas coordinates
+pinepaper_get_region_at_point x: 400 y: 300
+// Returns: { regionId, regionName, properties }
+\`\`\`
+
+## Region Animations
+
+Animate map regions with keyframe-based color transitions:
+
+\`\`\`
+// Animate specific regions with keyframes
+pinepaper_animate_map_regions
+  duration: 8
+  loop: true
+  regions:
+    "USA":
+      - time: 0, fillColor: "#ef4444"
+      - time: 4, fillColor: "#22c55e"
+      - time: 8, fillColor: "#ef4444"
+    "France":
+      - time: 0, fillColor: "#3b82f6"
+      - time: 8, fillColor: "#fbbf24"
+
+// Wave animation across all regions
+pinepaper_animate_map_wave
+  duration: 10
+  loop: true
+  colors: ["#ef4444", "#fbbf24", "#22c55e", "#3b82f6"]
+  waveDirection: "horizontal"
+
+// Stop animations
+pinepaper_stop_map_animations
+pinepaper_stop_map_animations regions: ["USA", "France"] resetColors: true
+
+// Query animated regions
+pinepaper_get_animated_map_regions
+\`\`\`
+
+## CSV Export & Import
+
+Export and import map state via CSV for data-driven workflows:
+
+\`\`\`
+// Export region data as CSV
+pinepaper_export_map_region_csv
+  includeHighlighted: true
+  includeColors: true
+  download: true
+  filename: "map-export.csv"
+
+// Import CSV to update regions
+pinepaper_import_map_region_csv
+  csvText: "regionId,fillColor,highlighted\\nUSA,#22c55e,1\\nFrance,#3b82f6,0"
+  applyColors: true
+  applyHighlight: true
+\`\`\`
+
+## Programmatic Selection
+
+Control region selection programmatically:
+
+\`\`\`
+// Select regions
+pinepaper_select_map_regions regionIds: ["USA", "Canada", "Mexico"]
+
+// Deselect specific regions
+pinepaper_deselect_map_regions regionIds: ["USA"]
+
+// Deselect all
+pinepaper_deselect_map_regions
+
+// Query highlighted regions
+pinepaper_get_highlighted_map_regions
+\`\`\`
+`,
+    'pinepaper://examples/world-population-map': `# World Population Map Example
+
+Create an animated choropleth map showing world population data with country highlights and major city markers.
+
+## Final Result
+
+A beautiful world map showing population density by color intensity, with pulsing markers on major capitals.
+
+---
+
+## Step 1: Set Up Canvas and Background
+
+\`\`\`
+// Set dark background for contrast
+pinepaper_set_background_color color: "#1a1a2e"
+
+// Set canvas size for presentation
+pinepaper_set_canvas_size preset: "presentation-16x9"
+\`\`\`
+
+---
+
+## Step 2: Load World Map
+
+\`\`\`
+pinepaper_load_map mapId: "worldHighRes"
+  options:
+    projection: "naturalEarth"
+    quality: "professional"
+    fillColor: "#374151"
+    strokeColor: "#4b5563"
+    strokeWidth: 0.3
+    enableHover: true
+    hoverFill: "#6b7280"
+\`\`\`
+
+---
+
+## Step 3: Apply Population Data (Choropleth)
+
+\`\`\`
+pinepaper_apply_data_colors
+  data:
+    "China": 1412
+    "India": 1408
+    "United States of America": 332
+    "Indonesia": 276
+    "Pakistan": 229
+    "Brazil": 215
+    "Nigeria": 218
+    "Bangladesh": 169
+    "Russia": 144
+    "Mexico": 130
+    "Japan": 125
+    "Ethiopia": 120
+    "Philippines": 113
+    "Egypt": 104
+    "Vietnam": 99
+    "Germany": 84
+    "Turkey": 85
+    "Iran": 87
+    "Thailand": 70
+    "United Kingdom": 67
+    "France": 68
+    "Italy": 59
+    "South Africa": 60
+    "Tanzania": 63
+    "Kenya": 54
+    "South Korea": 52
+    "Colombia": 51
+    "Spain": 47
+    "Argentina": 46
+    "Algeria": 45
+    "Sudan": 45
+    "Ukraine": 41
+    "Iraq": 42
+    "Poland": 38
+    "Canada": 38
+    "Morocco": 37
+    "Saudi Arabia": 35
+    "Peru": 33
+    "Malaysia": 33
+    "Australia": 26
+  options:
+    colorScale: "blues"
+    showLegend: true
+    legendPosition: "bottom-right"
+    legendTitle: "Population (millions)"
+\`\`\`
+
+---
+
+## Step 4: Highlight Top 5 Countries
+
+\`\`\`
+pinepaper_highlight_regions
+  regionIds: ["China", "India", "United States of America", "Indonesia", "Pakistan"]
+  options:
+    strokeColor: "#fbbf24"
+    strokeWidth: 2
+    animate: true
+\`\`\`
+
+---
+
+## Step 5: Add Capital City Markers
+
+\`\`\`
+// Beijing - China
+pinepaper_add_marker lat: 39.9042 lon: 116.4074
+  label: "Beijing"
+  color: "#ef4444"
+  size: 10
+  pulse: true
+
+// New Delhi - India
+pinepaper_add_marker lat: 28.6139 lon: 77.2090
+  label: "New Delhi"
+  color: "#ef4444"
+  size: 10
+  pulse: true
+
+// Washington DC - USA
+pinepaper_add_marker lat: 38.9072 lon: -77.0369
+  label: "Washington DC"
+  color: "#ef4444"
+  size: 8
+  pulse: true
+
+// Jakarta - Indonesia
+pinepaper_add_marker lat: -6.2088 lon: 106.8456
+  label: "Jakarta"
+  color: "#f59e0b"
+  size: 8
+  pulse: true
+
+// Islamabad - Pakistan
+pinepaper_add_marker lat: 33.6844 lon: 73.0479
+  label: "Islamabad"
+  color: "#f59e0b"
+  size: 8
+  pulse: true
+\`\`\`
+
+---
+
+## Step 6: Add Title
+
+\`\`\`
+pinepaper_create_item itemType: "text"
+  position: {x: 640, y: 50}
+  properties:
+    content: "World Population 2024"
+    fontSize: 36
+    fontFamily: "Inter, sans-serif"
+    fontWeight: "bold"
+    color: "#ffffff"
+\`\`\`
+
+---
+
+## Step 7: Export
+
+\`\`\`
+pinepaper_export_svg
+pinepaper_export_map
+\`\`\`
+
+---
+
+## Variations
+
+### Heat Map Version
+\`\`\`
+pinepaper_apply_data_colors
+  data: { ... }
+  options:
+    colorScale: "heat"
+    showLegend: true
+\`\`\`
+
+### Regional Focus (Asia)
+\`\`\`
+pinepaper_pan_map lat: 35 lon: 100 animate: true duration: 2
+pinepaper_zoom_map level: 2.5 animate: true
+\`\`\`
+`,
+    'pinepaper://examples/us-election-map': `# US Election Map Example
+
+Build an interactive US election results visualization with state-by-state coloring and key battleground state highlights.
+
+## Final Result
+
+A classic red/blue election map with swing states highlighted and electoral vote counts.
+
+---
+
+## Step 1: Set Up Canvas
+
+\`\`\`
+pinepaper_set_background_color color: "#f8fafc"
+pinepaper_set_canvas_size preset: "presentation-16x9"
+\`\`\`
+
+---
+
+## Step 2: Load USA Map
+
+\`\`\`
+pinepaper_load_map mapId: "usa"
+  options:
+    projection: "albers"
+    quality: "professional"
+    fillColor: "#e2e8f0"
+    strokeColor: "#94a3b8"
+    strokeWidth: 1
+    enableHover: true
+    enableClick: true
+\`\`\`
+
+---
+
+## Step 3: Color Democratic States (Blue)
+
+\`\`\`
+pinepaper_highlight_regions
+  regionIds: ["CA", "WA", "OR", "NV", "CO", "NM", "MN", "IL", "VA", "MD", "DE", "NJ", "CT", "RI", "MA", "VT", "NH", "ME", "NY", "HI"]
+  options:
+    fillColor: "#2563eb"
+    strokeColor: "#1d4ed8"
+\`\`\`
+
+---
+
+## Step 4: Color Republican States (Red)
+
+\`\`\`
+pinepaper_highlight_regions
+  regionIds: ["TX", "OK", "KS", "NE", "SD", "ND", "MT", "WY", "ID", "UT", "AZ", "AK", "MO", "AR", "LA", "MS", "AL", "TN", "KY", "WV", "IN", "OH", "SC", "FL"]
+  options:
+    fillColor: "#dc2626"
+    strokeColor: "#b91c1c"
+\`\`\`
+
+---
+
+## Step 5: Highlight Swing States
+
+\`\`\`
+// Key battleground states with gold border
+pinepaper_highlight_regions
+  regionIds: ["PA", "MI", "WI", "GA", "NC", "AZ"]
+  options:
+    strokeColor: "#fbbf24"
+    strokeWidth: 3
+    animate: true
+\`\`\`
+
+---
+
+## Step 6: Add Electoral Vote Labels
+
+\`\`\`
+// California - 54 votes
+pinepaper_add_marker lat: 36.7783 lon: -119.4179
+  label: "54"
+  color: "#2563eb"
+  size: 12
+
+// Texas - 40 votes
+pinepaper_add_marker lat: 31.9686 lon: -99.9018
+  label: "40"
+  color: "#dc2626"
+  size: 12
+
+// Florida - 30 votes
+pinepaper_add_marker lat: 27.6648 lon: -81.5158
+  label: "30"
+  color: "#dc2626"
+  size: 10
+
+// New York - 28 votes
+pinepaper_add_marker lat: 42.1657 lon: -74.9481
+  label: "28"
+  color: "#2563eb"
+  size: 10
+
+// Pennsylvania - 19 votes (swing)
+pinepaper_add_marker lat: 41.2033 lon: -77.1945
+  label: "19"
+  color: "#fbbf24"
+  size: 10
+  pulse: true
+
+// Michigan - 15 votes (swing)
+pinepaper_add_marker lat: 44.3148 lon: -85.6024
+  label: "15"
+  color: "#fbbf24"
+  size: 9
+  pulse: true
+
+// Georgia - 16 votes (swing)
+pinepaper_add_marker lat: 32.1656 lon: -82.9001
+  label: "16"
+  color: "#fbbf24"
+  size: 9
+  pulse: true
+\`\`\`
+
+---
+
+## Step 7: Add Title and Legend
+
+\`\`\`
+// Title
+pinepaper_create_item itemType: "text"
+  position: {x: 640, y: 40}
+  properties:
+    content: "US Presidential Election Results"
+    fontSize: 32
+    fontWeight: "bold"
+    color: "#1e293b"
+
+// Legend - Democratic
+pinepaper_create_item itemType: "rectangle"
+  position: {x: 100, y: 550}
+  properties:
+    width: 20
+    height: 20
+    color: "#2563eb"
+
+pinepaper_create_item itemType: "text"
+  position: {x: 130, y: 550}
+  properties:
+    content: "Democratic"
+    fontSize: 14
+    color: "#1e293b"
+
+// Legend - Republican
+pinepaper_create_item itemType: "rectangle"
+  position: {x: 250, y: 550}
+  properties:
+    width: 20
+    height: 20
+    color: "#dc2626"
+
+pinepaper_create_item itemType: "text"
+  position: {x: 280, y: 550}
+  properties:
+    content: "Republican"
+    fontSize: 14
+    color: "#1e293b"
+
+// Legend - Swing State
+pinepaper_create_item itemType: "rectangle"
+  position: {x: 400, y: 550}
+  properties:
+    width: 20
+    height: 20
+    color: "#fbbf24"
+
+pinepaper_create_item itemType: "text"
+  position: {x: 430, y: 550}
+  properties:
+    content: "Swing State"
+    fontSize: 14
+    color: "#1e293b"
+\`\`\`
+
+---
+
+## Step 8: Add Vote Totals
+
+\`\`\`
+// Electoral vote boxes
+pinepaper_create_item itemType: "rectangle"
+  position: {x: 200, y: 100}
+  properties:
+    width: 150
+    height: 80
+    color: "#2563eb"
+    cornerRadius: 8
+
+pinepaper_create_item itemType: "text"
+  position: {x: 200, y: 90}
+  properties:
+    content: "270"
+    fontSize: 36
+    fontWeight: "bold"
+    color: "#ffffff"
+
+pinepaper_create_item itemType: "text"
+  position: {x: 200, y: 120}
+  properties:
+    content: "Electoral Votes"
+    fontSize: 12
+    color: "#bfdbfe"
+
+// Republican votes
+pinepaper_create_item itemType: "rectangle"
+  position: {x: 1080, y: 100}
+  properties:
+    width: 150
+    height: 80
+    color: "#dc2626"
+    cornerRadius: 8
+
+pinepaper_create_item itemType: "text"
+  position: {x: 1080, y: 90}
+  properties:
+    content: "268"
+    fontSize: 36
+    fontWeight: "bold"
+    color: "#ffffff"
+
+pinepaper_create_item itemType: "text"
+  position: {x: 1080, y: 120}
+  properties:
+    content: "Electoral Votes"
+    fontSize: 12
+    color: "#fecaca"
+\`\`\`
+
+---
+
+## Step 9: Export
+
+\`\`\`
+pinepaper_export_svg
+\`\`\`
+`,
+    'pinepaper://examples/travel-route-map': `# Travel Route Map Example
+
+Visualize a travel itinerary across Europe with city markers, connecting routes, and animated journey highlights.
+
+## Final Result
+
+An elegant travel map showing a European tour with cities connected by animated paths.
+
+---
+
+## Step 1: Set Up Canvas
+
+\`\`\`
+pinepaper_set_background_color color: "#0f172a"
+pinepaper_set_canvas_size preset: "presentation-16x9"
+\`\`\`
+
+---
+
+## Step 2: Load World Map (Focused on Europe)
+
+\`\`\`
+pinepaper_load_map mapId: "worldHighRes"
+  options:
+    projection: "mercator"
+    quality: "professional"
+    fillColor: "#1e293b"
+    strokeColor: "#334155"
+    strokeWidth: 0.5
+    center: [10, 50]
+    enableHover: true
+\`\`\`
+
+---
+
+## Step 3: Zoom to Europe
+
+\`\`\`
+pinepaper_pan_map lat: 48 lon: 10 animate: true duration: 1
+pinepaper_zoom_map level: 4 animate: true duration: 1
+\`\`\`
+
+---
+
+## Step 4: Highlight Countries on Itinerary
+
+\`\`\`
+pinepaper_highlight_regions
+  regionIds: ["United Kingdom", "France", "Germany", "Italy", "Spain"]
+  options:
+    fillColor: "#334155"
+    strokeColor: "#60a5fa"
+    strokeWidth: 1
+    animate: true
+\`\`\`
+
+---
+
+## Step 5: Add City Markers (The Journey)
+
+\`\`\`
+// Day 1-3: London
+pinepaper_add_marker lat: 51.5074 lon: -0.1278
+  label: "London"
+  color: "#f59e0b"
+  size: 12
+  shape: "pin"
+  pulse: true
+
+// Day 4-5: Paris
+pinepaper_add_marker lat: 48.8566 lon: 2.3522
+  label: "Paris"
+  color: "#f59e0b"
+  size: 12
+  shape: "pin"
+  pulse: true
+
+// Day 6-7: Berlin
+pinepaper_add_marker lat: 52.5200 lon: 13.4050
+  label: "Berlin"
+  color: "#f59e0b"
+  size: 12
+  shape: "pin"
+  pulse: true
+
+// Day 8-10: Rome
+pinepaper_add_marker lat: 41.9028 lon: 12.4964
+  label: "Rome"
+  color: "#f59e0b"
+  size: 12
+  shape: "pin"
+  pulse: true
+
+// Day 11-12: Barcelona
+pinepaper_add_marker lat: 41.3851 lon: 2.1734
+  label: "Barcelona"
+  color: "#f59e0b"
+  size: 12
+  shape: "pin"
+  pulse: true
+\`\`\`
+
+---
+
+## Step 6: Draw Route Lines
+
+\`\`\`
+// London to Paris
+pinepaper_create_item itemType: "line"
+  properties:
+    from: {x: 380, y: 180}
+    to: {x: 420, y: 220}
+    strokeColor: "#60a5fa"
+    strokeWidth: 2
+    dashArray: [5, 5]
+→ route1
+
+// Paris to Berlin
+pinepaper_create_item itemType: "line"
+  properties:
+    from: {x: 420, y: 220}
+    to: {x: 520, y: 180}
+    strokeColor: "#60a5fa"
+    strokeWidth: 2
+    dashArray: [5, 5]
+→ route2
+
+// Berlin to Rome
+pinepaper_create_item itemType: "line"
+  properties:
+    from: {x: 520, y: 180}
+    to: {x: 500, y: 340}
+    strokeColor: "#60a5fa"
+    strokeWidth: 2
+    dashArray: [5, 5]
+→ route3
+
+// Rome to Barcelona
+pinepaper_create_item itemType: "line"
+  properties:
+    from: {x: 500, y: 340}
+    to: {x: 380, y: 330}
+    strokeColor: "#60a5fa"
+    strokeWidth: 2
+    dashArray: [5, 5]
+→ route4
+\`\`\`
+
+---
+
+## Step 7: Animate Routes
+
+\`\`\`
+pinepaper_animate_item itemId: "route1" animationType: "pulse" speed: 2
+pinepaper_animate_item itemId: "route2" animationType: "pulse" speed: 2
+pinepaper_animate_item itemId: "route3" animationType: "pulse" speed: 2
+pinepaper_animate_item itemId: "route4" animationType: "pulse" speed: 2
+\`\`\`
+
+---
+
+## Step 8: Add Day Numbers
+
+\`\`\`
+// London days
+pinepaper_create_item itemType: "text"
+  position: {x: 360, y: 160}
+  properties:
+    content: "Days 1-3"
+    fontSize: 10
+    color: "#94a3b8"
+
+// Paris days
+pinepaper_create_item itemType: "text"
+  position: {x: 440, y: 235}
+  properties:
+    content: "Days 4-5"
+    fontSize: 10
+    color: "#94a3b8"
+
+// Berlin days
+pinepaper_create_item itemType: "text"
+  position: {x: 540, y: 165}
+  properties:
+    content: "Days 6-7"
+    fontSize: 10
+    color: "#94a3b8"
+
+// Rome days
+pinepaper_create_item itemType: "text"
+  position: {x: 520, y: 355}
+  properties:
+    content: "Days 8-10"
+    fontSize: 10
+    color: "#94a3b8"
+
+// Barcelona days
+pinepaper_create_item itemType: "text"
+  position: {x: 360, y: 345}
+  properties:
+    content: "Days 11-12"
+    fontSize: 10
+    color: "#94a3b8"
+\`\`\`
+
+---
+
+## Step 9: Add Title and Decorations
+
+\`\`\`
+// Title
+pinepaper_create_item itemType: "text"
+  position: {x: 640, y: 40}
+  properties:
+    content: "European Adventure 2024"
+    fontSize: 28
+    fontWeight: "bold"
+    color: "#f8fafc"
+
+// Subtitle
+pinepaper_create_item itemType: "text"
+  position: {x: 640, y: 70}
+  properties:
+    content: "12 Days • 5 Cities • 1 Amazing Journey"
+    fontSize: 14
+    color: "#94a3b8"
+
+// Airplane icon at start
+pinepaper_create_item itemType: "text"
+  position: {x: 340, y: 180}
+  properties:
+    content: "✈️"
+    fontSize: 20
+\`\`\`
+
+---
+
+## Step 10: Add Summary Box
+
+\`\`\`
+// Summary background
+pinepaper_create_item itemType: "rectangle"
+  position: {x: 1100, y: 300}
+  properties:
+    width: 180
+    height: 200
+    color: "#1e293b"
+    cornerRadius: 12
+    strokeColor: "#334155"
+    strokeWidth: 1
+
+// Summary title
+pinepaper_create_item itemType: "text"
+  position: {x: 1100, y: 230}
+  properties:
+    content: "Trip Summary"
+    fontSize: 14
+    fontWeight: "bold"
+    color: "#f8fafc"
+
+// Stats
+pinepaper_create_item itemType: "text"
+  position: {x: 1100, y: 260}
+  properties:
+    content: "📍 5 Cities"
+    fontSize: 12
+    color: "#94a3b8"
+
+pinepaper_create_item itemType: "text"
+  position: {x: 1100, y: 285}
+  properties:
+    content: "📅 12 Days"
+    fontSize: 12
+    color: "#94a3b8"
+
+pinepaper_create_item itemType: "text"
+  position: {x: 1100, y: 310}
+  properties:
+    content: "🛫 4 Flights"
+    fontSize: 12
+    color: "#94a3b8"
+
+pinepaper_create_item itemType: "text"
+  position: {x: 1100, y: 335}
+  properties:
+    content: "🏨 11 Nights"
+    fontSize: 12
+    color: "#94a3b8"
+\`\`\`
+
+---
+
+## Step 11: Export
+
+\`\`\`
+pinepaper_export_svg
+\`\`\`
+
+---
+
+## Variations
+
+### Animated Route Reveal
+Use keyframe animations to reveal the route step by step:
+\`\`\`
+pinepaper_keyframe_animate itemId: "route1"
+  keyframes:
+    - time: 0, properties: {opacity: 0}
+    - time: 1, properties: {opacity: 1}
+
+pinepaper_keyframe_animate itemId: "route2"
+  keyframes:
+    - time: 1, properties: {opacity: 0}
+    - time: 2, properties: {opacity: 1}
+\`\`\`
+
+### Distance Labels
+Add distance between cities:
+\`\`\`
+pinepaper_create_item itemType: "text"
+  position: {x: 400, y: 200}
+  properties:
+    content: "344 km"
+    fontSize: 8
+    color: "#60a5fa"
+\`\`\`
+`,
+    'pinepaper://docs/diagrams': `# Diagrams Guide
+
+**Intent:** Create flowcharts, UML diagrams, network architectures, and connect any visual elements with smart arrows.
+
+## When to Use Diagrams
+
+Use diagram tools when you need to:
+- Build flowcharts with decision logic
+- Create UML diagrams (class, use case)
+- Design network/architecture diagrams
+- Connect any items (images, shapes, text) with arrows
+- Show process flows with animated connectors
+
+## Key Tools
+
+| Tool | Purpose |
+|------|---------|
+| \`pinepaper_create_diagram_shape\` | Create flowchart/UML/network shapes |
+| \`pinepaper_connect\` | Connect items with smart arrows |
+| \`pinepaper_auto_layout\` | Automatically arrange connected shapes |
+| \`pinepaper_get_diagram_shapes\` | List available shape types |
+| \`pinepaper_diagram_mode\` | Enable/disable diagram editing mode |
+
+## Shape Types
+
+### Flowchart Shapes
+| Shape | Use For |
+|-------|---------|
+| \`process\` | Actions, steps (rectangle) |
+| \`decision\` | Yes/No branching (diamond) |
+| \`terminal\` | Start/End points (rounded) |
+| \`data\` | Input/Output (parallelogram) |
+| \`document\` | Documents (wavy bottom) |
+| \`database\` | Data storage (cylinder) |
+| \`preparation\` | Setup steps (hexagon) |
+
+### UML Shapes
+| Shape | Use For |
+|-------|---------|
+| \`uml-class\` | Class definitions |
+| \`uml-usecase\` | Use case ellipse |
+| \`uml-actor\` | Stick figure actor |
+
+### Network Shapes
+| Shape | Use For |
+|-------|---------|
+| \`cloud\` | Cloud services |
+| \`server\` | Server/computer |
+
+## Creating a Flowchart
+
+\`\`\`
+// Step 1: Create shapes
+pinepaper_create_diagram_shape
+  shapeType: "terminal"
+  position: {x: 400, y: 100}
+  label: "Start"
+  style: {fillColor: "#22c55e"}
+→ item_1
+
+pinepaper_create_diagram_shape
+  shapeType: "process"
+  position: {x: 400, y: 200}
+  label: "Process Data"
+→ item_2
+
+pinepaper_create_diagram_shape
+  shapeType: "decision"
+  position: {x: 400, y: 320}
+  label: "Valid?"
+  style: {fillColor: "#fbbf24"}
+→ item_3
+
+pinepaper_create_diagram_shape
+  shapeType: "terminal"
+  position: {x: 400, y: 440}
+  label: "End"
+  style: {fillColor: "#ef4444"}
+→ item_4
+
+// Step 2: Connect shapes
+pinepaper_connect
+  sourceItemId: "item_1"
+  targetItemId: "item_2"
+  routing: "orthogonal"
+
+pinepaper_connect
+  sourceItemId: "item_2"
+  targetItemId: "item_3"
+
+pinepaper_connect
+  sourceItemId: "item_3"
+  targetItemId: "item_4"
+  label: "Yes"
+\`\`\`
+
+## Connector Options
+
+### Routing Styles
+| Style | Description |
+|-------|-------------|
+| \`orthogonal\` | Right-angle paths (default, best for flowcharts) |
+| \`curved\` | Smooth curved paths |
+| \`direct\` | Straight line |
+
+### Arrow Styles
+| Style | Description |
+|-------|-------------|
+| \`classic\` | Standard arrow (default) |
+| \`stealth\` | Sleek pointed arrow |
+| \`sharp\` | Sharp angular arrow |
+| \`open\` | Outlined arrow |
+| \`diamond\` | Diamond shape |
+| \`circle\` | Circle endpoint |
+| \`none\` | No arrowhead |
+
+### Line Styles
+| Style | Description |
+|-------|-------------|
+| \`solid\` | Continuous line |
+| \`dashed\` | Dashed line |
+| \`dotted\` | Dotted line |
+
+## Connector Example
+
+\`\`\`
+pinepaper_connect
+  sourceItemId: "item_1"
+  targetItemId: "item_2"
+  routing: "curved"
+  lineColor: "#3b82f6"
+  lineWidth: 2
+  lineStyle: "dashed"
+  headStyle: "stealth"
+  label: "Yes"
+  animated: true    // Bolt effect shows direction
+\`\`\`
+
+## Connecting Any Items
+
+Diagram connectors work with ANY canvas items, not just diagram shapes:
+
+\`\`\`
+// Connect images
+pinepaper_import_svg url: "https://example.com/icon1.svg" → item_1
+pinepaper_import_svg url: "https://example.com/icon2.svg" → item_2
+pinepaper_connect sourceItemId: "item_1" targetItemId: "item_2"
+
+// Connect text labels
+pinepaper_create_item itemType: "text" properties: {content: "A"} → item_3
+pinepaper_create_item itemType: "text" properties: {content: "B"} → item_4
+pinepaper_connect sourceItemId: "item_3" targetItemId: "item_4"
+\`\`\`
+
+## Auto Layout
+
+Automatically arrange connected shapes:
+
+\`\`\`
+pinepaper_auto_layout
+  direction: "TB"           // TB, BT, LR, RL
+  spacing: {horizontal: 80, vertical: 60}
+\`\`\`
+
+| Direction | Description |
+|-----------|-------------|
+| \`TB\` | Top to Bottom |
+| \`BT\` | Bottom to Top |
+| \`LR\` | Left to Right |
+| \`RL\` | Right to Left |
+`,
+    'pinepaper://docs/masks': `# Masks Guide
+
+**Intent:** Create reveal animations and transitions using animated clipping masks (wipes, iris, curtains, custom shapes).
+
+## When to Use Masks
+
+Use mask tools when you need to:
+- Reveal text or images with wipe effects
+- Create iris/zoom reveal animations
+- Build curtain-style transitions
+- Design custom reveal sequences
+- Add cinematic letterbox effects
+
+## Key Tools
+
+| Tool | Purpose |
+|------|---------|
+| \`pinepaper_apply_animated_mask\` | Apply reveal animation (preset or custom) |
+| \`pinepaper_apply_custom_mask\` | Full keyframe control |
+| \`pinepaper_remove_mask\` | Remove mask from item |
+| \`pinepaper_get_mask_animations\` | List available presets |
+| \`pinepaper_get_mask_types\` | List mask shapes |
+| \`pinepaper_get_animatable_properties\` | Get keyframeable properties |
+| \`pinepaper_get_available_easings\` | List easing functions |
+
+## Animation Presets
+
+### Wipe Effects
+| Preset | Effect |
+|--------|--------|
+| \`wipeLeft\` | Reveal from left to right |
+| \`wipeRight\` | Reveal from right to left |
+| \`wipeUp\` | Reveal from bottom to top |
+| \`wipeDown\` | Reveal from top to bottom |
+| \`diagonalWipe\` | Angled reveal from corner |
+
+### Iris Effects
+| Preset | Effect |
+|--------|--------|
+| \`iris\` | Circle expands from center |
+| \`irisOut\` | Circle shrinks to center (hide) |
+
+### Shape Reveals
+| Preset | Effect |
+|--------|--------|
+| \`star\` | Star shape scales up |
+| \`heart\` | Heart shape scales up |
+
+### Curtain Effects
+| Preset | Effect |
+|--------|--------|
+| \`curtainHorizontal\` | Opens from center horizontally |
+| \`curtainVertical\` | Opens from center vertically |
+| \`cinematic\` | Letterbox bars animate away |
+
+### Text Reveals
+| Preset | Effect |
+|--------|--------|
+| \`revealUp\` | Text slides up within mask |
+| \`revealDown\` | Text slides down within mask |
+
+## Quick Start: Preset Mode
+
+\`\`\`
+// Create an item
+pinepaper_create_item
+  itemType: "text"
+  position: {x: 400, y: 300}
+  properties: {content: "Hello World", fontSize: 48, color: "#ffffff"}
+→ item_1
+
+// Apply wipe reveal
+pinepaper_apply_animated_mask
+  itemId: "item_1"
+  preset: "wipeLeft"
+  options:
+    duration: 0.5
+    easing: "easeOut"
+\`\`\`
+
+## Preset Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| \`startTime\` | number | 0 | Delay before animation starts (seconds) |
+| \`duration\` | number | 0.8 | Animation duration (seconds) |
+| \`easing\` | string | "easeOut" | Timing function |
+| \`reversed\` | boolean | false | Play in reverse (hide instead of reveal) |
+| \`loop\` | boolean | false | Loop the animation |
+
+## Easing Functions
+
+| Easing | Description |
+|--------|-------------|
+| \`linear\` | Constant speed |
+| \`easeIn\` | Slow start, fast end |
+| \`easeOut\` | Fast start, slow end |
+| \`easeInOut\` | Slow start and end |
+| \`bounce\` | Bouncing effect at end |
+| \`elastic\` | Spring-like overshoot |
+
+## Custom Keyframe Animation
+
+For full control, define keyframes manually:
+
+\`\`\`
+pinepaper_apply_animated_mask
+  itemId: "item_1"
+  maskType: "rectangle"
+  keyframes:
+    - time: 0
+      properties: {x: 200, y: 250, width: 0, height: 100}
+      easing: "linear"
+    - time: 0.5
+      properties: {x: 200, y: 250, width: 100, height: 100}
+      easing: "easeIn"
+    - time: 1
+      properties: {x: 200, y: 250, width: 200, height: 100}
+      easing: "easeOut"
+\`\`\`
+
+## Mask Types
+
+| Type | Animatable Properties |
+|------|----------------------|
+| \`rectangle\` | x, y, width, height, rotation, opacity |
+| \`circle\` | x, y, radius, scale, opacity |
+| \`ellipse\` | x, y, radiusX, radiusY, rotation, scale, opacity |
+| \`star\` | x, y, radius, scale, rotation, opacity |
+| \`triangle\` | x, y, scale, rotation, opacity |
+| \`hexagon\` | x, y, scale, rotation, opacity |
+| \`heart\` | x, y, scale, rotation, opacity |
+| \`rounded\` | x, y, width, height, cornerRadius, opacity |
+
+## Hybrid Mode: Preset + Custom Keyframes
+
+Combine preset behavior with custom timing:
+
+\`\`\`
+pinepaper_apply_animated_mask
+  itemId: "item_1"
+  preset: "iris"
+  keyframes:
+    - time: 0
+      properties: {scale: 0.01}
+      easing: "linear"
+    - time: 0.3
+      properties: {scale: 0.3}
+      easing: "easeIn"
+    - time: 0.7
+      properties: {scale: 0.8}
+      easing: "easeOut"
+    - time: 1
+      properties: {scale: 1}
+      easing: "bounce"
+\`\`\`
+
+## Staggered Text Reveal
+
+Reveal multiple words with delays:
+
+\`\`\`
+// Create words
+pinepaper_create_item itemType: "text" position: {x: 200, y: 300}
+  properties: {content: "Hello", fontSize: 36} → item_1
+
+pinepaper_create_item itemType: "text" position: {x: 350, y: 300}
+  properties: {content: "Beautiful", fontSize: 36} → item_2
+
+pinepaper_create_item itemType: "text" position: {x: 550, y: 300}
+  properties: {content: "World", fontSize: 36} → item_3
+
+// Apply staggered reveals
+pinepaper_apply_animated_mask itemId: "item_1" preset: "wipeUp"
+  options: {startTime: 0, duration: 0.3}
+
+pinepaper_apply_animated_mask itemId: "item_2" preset: "wipeUp"
+  options: {startTime: 0.2, duration: 0.3}
+
+pinepaper_apply_animated_mask itemId: "item_3" preset: "wipeUp"
+  options: {startTime: 0.4, duration: 0.3}
+\`\`\`
+
+## Removing Masks
+
+\`\`\`
+pinepaper_remove_mask itemId: "item_1"
+\`\`\`
+`,
+    'pinepaper://docs/fonts': `# Font Studio Guide
+
+**Intent:** Create custom hand-drawn fonts by drawing glyphs on a dedicated canvas, then export as OTF files or use directly in PinePaper documents.
+
+## Overview
+
+Font Studio provides 16 tools for creating custom fonts programmatically. You draw each character as a Paper.js path, clean it up, and convert it to a font glyph.
+
+## Key Tools
+
+| Tool | Purpose |
+|------|---------|
+| \`pinepaper_font_show_studio\` | Open the Font Studio UI with guide lines |
+| \`pinepaper_font_set_name\` | Set font family name |
+| \`pinepaper_font_get_required_chars\` | Get list of characters needed |
+| \`pinepaper_font_get_status\` | Check completion progress |
+| \`pinepaper_font_create_glyph\` | Convert a drawn path to a glyph |
+| \`pinepaper_font_create_space\` | Create the space character |
+| \`pinepaper_font_remove_glyph\` | Remove a glyph for redrawing |
+| \`pinepaper_font_set_metrics\` | Configure font metrics (advanced) |
+| \`pinepaper_font_export\` | Export as OTF file |
+| \`pinepaper_font_load_into_document\` | Use font in current document |
+| \`pinepaper_font_export_data\` | Save progress as JSON |
+| \`pinepaper_font_import_data\` | Resume from saved data |
+| \`pinepaper_font_clear\` | Reset all glyphs |
+| \`pinepaper_font_remove_overlap\` | Merge overlapping path strokes |
+| \`pinepaper_font_correct_direction\` | Fix path winding for fills |
+| \`pinepaper_font_cleanup_path\` | All-in-one path preparation |
+
+## Workflow
+
+### Step 1: Open Font Studio
+\`\`\`
+pinepaper_font_show_studio
+\`\`\`
+
+Opens the interactive Font Studio UI with typography guide lines:
+- **Cap Height** (Red): Top of capital letters (H, T, A)
+- **x-Height** (Cyan): Top of lowercase letters (a, e, x)
+- **Baseline** (Green): Where letters sit
+- **Descender** (Purple): Below baseline for g, p, y, j
+
+### Step 2: Set Font Name
+\`\`\`
+pinepaper_font_set_name name: "MyHandwriting"
+\`\`\`
+
+### Step 3: Check Required Characters
+\`\`\`
+pinepaper_font_get_required_chars set: "minimum"
+\`\`\`
+
+Two character sets available:
+- **minimum**: A-Z, a-z, 0-9, space (63 chars) - enough for basic text
+- **standard**: adds punctuation and symbols (90+ chars)
+
+### Step 4: Draw and Create Glyphs
+
+For each character:
+
+1. **Draw the character** as a Paper.js path on the canvas
+2. **Clean up the path** (recommended):
+\`\`\`
+pinepaper_font_cleanup_path pathId: "item_42"
+\`\`\`
+3. **Create the glyph**:
+\`\`\`
+pinepaper_font_create_glyph character: "A" pathId: "item_42"
+\`\`\`
+
+For the space character (no visible path needed):
+\`\`\`
+pinepaper_font_create_space width: 250
+\`\`\`
+
+### Step 5: Check Progress
+\`\`\`
+pinepaper_font_get_status
+\`\`\`
+
+Returns: font name, total/completed/pending counts, percentage, and character lists.
+
+### Step 6: Export
+
+Export as OTF file:
+\`\`\`
+pinepaper_font_export
+\`\`\`
+
+Or load directly into the document:
+\`\`\`
+pinepaper_font_load_into_document
+\`\`\`
+
+## Path Cleanup Tools
+
+Before converting a drawn path to a glyph, clean it up for best results:
+
+| Tool | What It Does |
+|------|-------------|
+| \`pinepaper_font_remove_overlap\` | Merges overlapping strokes into one outline |
+| \`pinepaper_font_correct_direction\` | Fixes winding so fills render correctly |
+| \`pinepaper_font_cleanup_path\` | Does all cleanup in one call (overlap + direction + smooth) |
+
+The \`cleanup_path\` tool accepts options:
+\`\`\`
+pinepaper_font_cleanup_path
+  pathId: "item_42"
+  removeOverlap: true
+  correctDirection: true
+  smooth: true
+  smoothTolerance: 2.5
+\`\`\`
+
+## Font Metrics (Advanced)
+
+Configure the font's coordinate system:
+\`\`\`
+pinepaper_font_set_metrics
+  unitsPerEm: 1000
+  ascender: 800
+  descender: -200
+  xHeight: 500
+  capHeight: 700
+\`\`\`
+
+## Save and Resume Progress
+
+Save work-in-progress:
+\`\`\`
+pinepaper_font_export_data
+\`\`\`
+
+Resume later:
+\`\`\`
+pinepaper_font_import_data data: { ... }
+\`\`\`
+
+## Best Practices
+
+- Keep stroke width consistent across all characters
+- Uppercase letters should touch the cap height line
+- Lowercase (except b, d, f, h, k, l, t) stay within x-height
+- Letters g, j, p, q, y extend below baseline to descender
+- Always run \`cleanup_path\` before \`create_glyph\` for cleanest results
+- Use \`get_status\` frequently to track progress
+- Save progress with \`export_data\` periodically
+`,
+    'pinepaper://examples/us-states-animated': `# US States Animated Map Example
+
+**Intent:** Create a US map with animated color transitions that loop continuously.
+
+## What You'll Build
+
+A USA map where states randomly change colors in a flowing wave animation.
+
+## Step 1: Load the Map
+
+\`\`\`
+pinepaper_load_map
+  mapId: "usa"
+  options:
+    projection: "albers"
+    quality: "balanced"
+    fillColor: "#e5e7eb"
+    strokeColor: "#9ca3af"
+\`\`\`
+
+## Step 2: Apply Wave Animation
+
+\`\`\`
+pinepaper_animate_map_wave
+  duration: 10
+  loop: true
+  colors: ["#ef4444", "#f97316", "#fbbf24", "#22c55e", "#3b82f6", "#8b5cf6"]
+  options:
+    delayBetween: 0.1
+    easing: "easeInOut"
+\`\`\`
+
+## Result
+
+States will animate through the color palette in a wave pattern, creating a mesmerizing continuous animation.
+
+## Alternative: Data-Driven Colors
+
+Apply colors based on data values:
+
+\`\`\`
+pinepaper_apply_data_colors
+  data:
+    "CA": 100
+    "TX": 85
+    "FL": 70
+    "NY": 65
+    "PA": 50
+    "IL": 45
+    "OH": 40
+  options:
+    colorScale: "blues"
+    legend: true
+    legendPosition: "bottom-right"
+\`\`\`
+
+## Alternative: Highlight Specific States
+
+\`\`\`
+pinepaper_highlight_regions
+  regionIds: ["CA", "OR", "WA"]
+  options:
+    fillColor: "#22c55e"
+    strokeColor: "#16a34a"
+    animated: true
+\`\`\`
+
+## Key Tools Used
+
+| Tool | Purpose |
+|------|---------|
+| \`pinepaper_load_map\` | Load USA map with Albers projection |
+| \`pinepaper_animate_map_wave\` | Create looping color animation |
+| \`pinepaper_apply_data_colors\` | Color by numeric values |
+| \`pinepaper_highlight_regions\` | Highlight specific states |
+
+## Region ID Format
+
+For USA maps, use 2-letter state codes:
+- CA, TX, NY, FL, WA, OR, etc.
+
+## Export
+
+\`\`\`
+pinepaper_export_svg animated: true
+\`\`\`
+`,
+    'pinepaper://examples/flowchart': `# Flowchart Example
+
+**Intent:** Create a decision flowchart with auto-layout and animated connectors.
+
+## What You'll Build
+
+A simple decision flowchart: Start → Process → Decision → End
+
+## Step 1: Create Shapes
+
+\`\`\`
+// Start terminal
+pinepaper_create_diagram_shape
+  shapeType: "terminal"
+  position: {x: 400, y: 80}
+  label: "Start"
+  style: {fillColor: "#22c55e", strokeColor: "#16a34a"}
+→ item_1
+
+// Process step
+pinepaper_create_diagram_shape
+  shapeType: "process"
+  position: {x: 400, y: 180}
+  label: "Check Input"
+  style: {fillColor: "#3b82f6", strokeColor: "#2563eb"}
+→ item_2
+
+// Decision diamond
+pinepaper_create_diagram_shape
+  shapeType: "decision"
+  position: {x: 400, y: 300}
+  label: "Valid?"
+  style: {fillColor: "#fbbf24", strokeColor: "#f59e0b"}
+→ item_3
+
+// Success path
+pinepaper_create_diagram_shape
+  shapeType: "process"
+  position: {x: 250, y: 420}
+  label: "Process Data"
+  style: {fillColor: "#3b82f6", strokeColor: "#2563eb"}
+→ item_4
+
+// Error path
+pinepaper_create_diagram_shape
+  shapeType: "process"
+  position: {x: 550, y: 420}
+  label: "Show Error"
+  style: {fillColor: "#ef4444", strokeColor: "#dc2626"}
+→ item_5
+
+// End terminal
+pinepaper_create_diagram_shape
+  shapeType: "terminal"
+  position: {x: 400, y: 540}
+  label: "End"
+  style: {fillColor: "#6b7280", strokeColor: "#4b5563"}
+→ item_6
+\`\`\`
+
+## Step 2: Connect Shapes
+
+\`\`\`
+// Start to Check
+pinepaper_connect
+  sourceItemId: "item_1"
+  targetItemId: "item_2"
+  routing: "orthogonal"
+  lineColor: "#374151"
+
+// Check to Decision
+pinepaper_connect
+  sourceItemId: "item_2"
+  targetItemId: "item_3"
+  routing: "orthogonal"
+  lineColor: "#374151"
+
+// Decision Yes path
+pinepaper_connect
+  sourceItemId: "item_3"
+  targetItemId: "item_4"
+  routing: "orthogonal"
+  lineColor: "#22c55e"
+  label: "Yes"
+
+// Decision No path
+pinepaper_connect
+  sourceItemId: "item_3"
+  targetItemId: "item_5"
+  routing: "orthogonal"
+  lineColor: "#ef4444"
+  label: "No"
+
+// Process to End
+pinepaper_connect
+  sourceItemId: "item_4"
+  targetItemId: "item_6"
+  routing: "orthogonal"
+  lineColor: "#374151"
+
+// Error to End
+pinepaper_connect
+  sourceItemId: "item_5"
+  targetItemId: "item_6"
+  routing: "orthogonal"
+  lineColor: "#374151"
+\`\`\`
+
+## Step 3: Apply Auto-Layout (Optional)
+
+\`\`\`
+pinepaper_auto_layout
+  direction: "TB"
+  spacing: {horizontal: 100, vertical: 80}
+\`\`\`
+
+## Adding Animation
+
+Make connectors animated to show flow direction:
+
+\`\`\`
+pinepaper_connect
+  sourceItemId: "item_1"
+  targetItemId: "item_2"
+  animated: true          // Bolt effect shows direction
+  lineColor: "#3b82f6"
+\`\`\`
+
+## Key Tools Used
+
+| Tool | Purpose |
+|------|---------|
+| \`pinepaper_create_diagram_shape\` | Create flowchart symbols |
+| \`pinepaper_connect\` | Draw smart connectors |
+| \`pinepaper_auto_layout\` | Automatic arrangement |
+
+## Shape Reference
+
+| Shape | Symbol | Use For |
+|-------|--------|---------|
+| \`terminal\` | Rounded rectangle | Start/End |
+| \`process\` | Rectangle | Actions |
+| \`decision\` | Diamond | Yes/No branching |
+| \`data\` | Parallelogram | Input/Output |
+| \`document\` | Wavy rectangle | Documents |
+`,
+    'pinepaper://examples/reveal-animation': `# Reveal Animation Example
+
+**Intent:** Create a text reveal animation using mask effects.
+
+## What You'll Build
+
+Text that reveals with a smooth wipe animation, perfect for intros and titles.
+
+## Method 1: Simple Preset
+
+\`\`\`
+// Create text
+pinepaper_create_item
+  itemType: "text"
+  position: {x: 400, y: 300}
+  properties:
+    content: "Welcome"
+    fontSize: 64
+    fontWeight: "bold"
+    color: "#ffffff"
+→ item_1
+
+// Apply wipe reveal
+pinepaper_apply_animated_mask
+  itemId: "item_1"
+  preset: "wipeLeft"
+  options:
+    duration: 0.6
+    easing: "easeOut"
+\`\`\`
+
+## Method 2: Staggered Word Reveal
+
+\`\`\`
+// Word 1
+pinepaper_create_item itemType: "text" position: {x: 200, y: 300}
+  properties: {content: "Create", fontSize: 48, color: "#3b82f6"}
+→ item_1
+
+// Word 2
+pinepaper_create_item itemType: "text" position: {x: 370, y: 300}
+  properties: {content: "Beautiful", fontSize: 48, color: "#8b5cf6"}
+→ item_2
+
+// Word 3
+pinepaper_create_item itemType: "text" position: {x: 580, y: 300}
+  properties: {content: "Graphics", fontSize: 48, color: "#ec4899"}
+→ item_3
+
+// Staggered reveals
+pinepaper_apply_animated_mask itemId: "item_1" preset: "wipeUp"
+  options: {startTime: 0, duration: 0.4, easing: "easeOut"}
+
+pinepaper_apply_animated_mask itemId: "item_2" preset: "wipeUp"
+  options: {startTime: 0.15, duration: 0.4, easing: "easeOut"}
+
+pinepaper_apply_animated_mask itemId: "item_3" preset: "wipeUp"
+  options: {startTime: 0.3, duration: 0.4, easing: "easeOut"}
+\`\`\`
+
+## Method 3: Iris Reveal for Images
+
+\`\`\`
+// Create a shape or import image
+pinepaper_create_item itemType: "circle" position: {x: 400, y: 300}
+  properties: {radius: 100, color: "#3b82f6"}
+→ item_1
+
+// Iris reveal from center
+pinepaper_apply_animated_mask
+  itemId: "item_1"
+  preset: "iris"
+  options:
+    duration: 0.8
+    easing: "easeOut"
+\`\`\`
+
+## Method 4: Cinematic Letterbox
+
+\`\`\`
+// Create main content
+pinepaper_create_item itemType: "rectangle" position: {x: 400, y: 300}
+  properties: {width: 600, height: 300, color: "#1e40af"}
+→ item_1
+
+// Cinematic reveal (letterbox bars animate away)
+pinepaper_apply_animated_mask
+  itemId: "item_1"
+  preset: "cinematic"
+  options:
+    duration: 1.2
+    easing: "easeInOut"
+\`\`\`
+
+## Available Presets
+
+| Preset | Effect | Best For |
+|--------|--------|----------|
+| \`wipeLeft\` | Left to right | Text, titles |
+| \`wipeRight\` | Right to left | Text |
+| \`wipeUp\` | Bottom to top | Credits, lists |
+| \`wipeDown\` | Top to bottom | Headers |
+| \`iris\` | Circle from center | Images, focus |
+| \`irisOut\` | Circle shrinks | Transitions out |
+| \`star\` | Star shape reveal | Fun, playful |
+| \`heart\` | Heart shape reveal | Love themes |
+| \`curtainHorizontal\` | Opens from center | Stage, dramatic |
+| \`curtainVertical\` | Opens vertically | Reveals |
+| \`cinematic\` | Letterbox effect | Film style |
+| \`diagonalWipe\` | Angled wipe | Dynamic |
+
+## Combining with Other Animations
+
+\`\`\`
+// Create text
+pinepaper_create_item itemType: "text" position: {x: 400, y: 300}
+  properties: {content: "Animated!", fontSize: 48}
+→ item_1
+
+// Apply mask reveal
+pinepaper_apply_animated_mask itemId: "item_1" preset: "wipeLeft"
+  options: {duration: 0.5}
+
+// Add pulse animation after reveal
+pinepaper_animate_item itemId: "item_1" animationType: "pulse" speed: 0.5
+\`\`\`
+
+## Key Tools
+
+| Tool | Purpose |
+|------|---------|
+| \`pinepaper_apply_animated_mask\` | Apply reveal preset |
+| \`pinepaper_get_mask_animations\` | List all presets |
+| \`pinepaper_remove_mask\` | Remove mask effect |
+`,
+};
+// =============================================================================
+// SERVER CREATION
+// =============================================================================
+export async function createServer(options = {}) {
+    // Initialize i18n with specified locale
+    const locale = options.locale || detectLocaleFromEnvironment();
+    const i18n = await initI18n(locale);
+    // Mutable effective settings — may be upgraded by client auto-detection
+    let effectiveVerbosity = options.verbosity || detectVerbosityFromEnvironment();
+    let effectiveToolkit = options.toolkit || detectToolkitFromEnvironment();
+    /** Compute the current filtered tools list (sub-ms, called per tools/list request). */
+    const getEffectiveTools = () => getToolsForToolkit(getToolsForVerbosity(effectiveVerbosity), effectiveToolkit);
+    const server = new Server(SERVER_INFO, {
+        capabilities: {
+            tools: { listChanged: true },
+            resources: {},
+            prompts: {},
+        },
+    });
+    // Client auto-detection: upgrade toolkit/verbosity based on MCP client identity
+    server.oninitialized = () => {
+        const clientVersion = server.getClientVersion();
+        if (!clientVersion?.name)
+            return;
+        const profile = getClientProfile(clientVersion.name);
+        if (!profile)
+            return;
+        let changed = false;
+        // Only upgrade if env vars / CLI flags weren't explicitly set
+        if (!options.toolkit && !isToolkitExplicitlySet() && profile.toolkit !== effectiveToolkit) {
+            console.error(`[auto-select] Client "${clientVersion.name}" → toolkit=${profile.toolkit}`);
+            effectiveToolkit = profile.toolkit;
+            changed = true;
+        }
+        if (!options.verbosity && !isVerbosityExplicitlySet() && profile.verbosity !== effectiveVerbosity) {
+            console.error(`[auto-select] Client "${clientVersion.name}" → verbosity=${profile.verbosity}`);
+            effectiveVerbosity = profile.verbosity;
+            changed = true;
+        }
+        if (changed) {
+            // Notify client that tool list has changed
+            server.sendToolListChanged().catch(() => { });
+        }
+    };
+    // ---------------------------------------------------------------------------
+    // TOOL HANDLERS
     // ---------------------------------------------------------------------------
-    // List available tools (with optional localization)
+    // List available tools — dynamic, recomputed each request (sub-ms)
     server.setRequestHandler(ListToolsRequestSchema, async () => {
-        // Tool descriptions are kept in English for AI understanding
-        // but can be localized if needed for UI display
         return {
-            tools: PINEPAPER_TOOLS,
+            tools: getEffectiveTools(),
         };
     });
     // Handle tool calls with i18n support for errors and success messages
@@ -3215,6 +5787,32 @@ export async function createServer(options = {}) {
     const executionMode = options.executionMode ?? getExecutionMode();
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: args } = request.params;
+        // Runtime toolkit/verbosity switching — handled here because it needs
+        // direct access to mutable effectiveToolkit/effectiveVerbosity state
+        if (name === 'pinepaper_set_toolkit') {
+            const { SetToolkitInputSchema } = await import('./types/schemas.js');
+            const { TOOLKIT_PROFILES_LIST } = await import('./tools/toolkits.js');
+            const input = SetToolkitInputSchema.parse(args);
+            let changed = false;
+            if (input.toolkit && input.toolkit !== effectiveToolkit) {
+                effectiveToolkit = input.toolkit;
+                changed = true;
+            }
+            if (input.verbosity && input.verbosity !== effectiveVerbosity) {
+                effectiveVerbosity = input.verbosity;
+                changed = true;
+            }
+            if (changed) {
+                server.sendToolListChanged().catch(() => { });
+            }
+            const tools = getEffectiveTools();
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Toolkit: ${effectiveToolkit}, Verbosity: ${effectiveVerbosity}, Tools: ${tools.length}${changed ? ' (updated)' : ' (no change)'}`,
+                    }],
+            };
+        }
         return handleToolCall(name, args, {
             i18n,
             executeInBrowser,
@@ -3247,6 +5845,16 @@ export async function createServer(options = {}) {
             ],
         };
     });
+    // ---------------------------------------------------------------------------
+    // PROMPT HANDLERS
+    // ---------------------------------------------------------------------------
+    server.setRequestHandler(ListPromptsRequestSchema, async () => {
+        return { prompts: PROMPTS };
+    });
+    server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        return getPromptMessages(name, args);
+    });
     return server;
 }
 // =============================================================================
@@ -3331,19 +5939,30 @@ function isValidLocale(locale) {
 // =============================================================================
 async function main() {
     const locale = detectLocaleFromEnvironment();
-    const server = await createServer({ locale });
+    const verbosity = detectVerbosityFromEnvironment();
+    const toolkit = detectToolkitFromEnvironment();
+    const server = await createServer({ locale, verbosity, toolkit });
     const transport = new StdioServerTransport();
     console.error('PinePaper MCP Server starting...');
     console.error(`Version: ${SERVER_INFO.version}`);
     console.error(`Locale: ${locale}`);
-    console.error(`Tools: ${PINEPAPER_TOOLS.length}`);
+    console.error(`Verbosity: ${verbosity}`);
+    console.error(`Toolkit: ${toolkit}`);
+    const toolCount = getToolsForToolkit(getToolsForVerbosity(verbosity), toolkit).length;
+    console.error(`Tools: ${toolCount}/${PINEPAPER_TOOLS.length}`);
     console.error(`Resources: ${RESOURCES.length}`);
     await server.connect(transport);
     console.error('PinePaper MCP Server running on stdio');
 }
-// Run if executed directly
-main().catch((error) => {
-    console.error('Fatal error:', error);
-    process.exit(1);
-});
+// Run if executed directly (not when imported by cli.ts or other modules)
+// Check: Node uses process.argv[1], Bun supports import.meta.main
+const isDirectExecution = typeof import.meta.main === 'boolean'
+    ? import.meta.main
+    : process.argv[1]?.replace(/\\/g, '/').endsWith('index.js');
+if (isDirectExecution) {
+    main().catch((error) => {
+        console.error('Fatal error:', error);
+        process.exit(1);
+    });
+}
 //# sourceMappingURL=index.js.map