@pinepaper.studio/mcp-server 1.6.6 → 1.6.8

package/dist/tools/handlers.js

@@ -6,25 +6,30 @@
  * Supports browser execution via Puppeteer.
  */
 import { codeGenerator } from '../types/code-generator.js';
-import { CreateItemInputSchema, ModifyItemInputSchema, DeleteItemInputSchema, AddRelationInputSchema, RemoveRelationInputSchema, QueryRelationsInputSchema, AnimateItemInputSchema, KeyframeAnimateInputSchema, ExecuteGeneratorInputSchema, ApplyEffectInputSchema, GetItemsInputSchema, PlayTimelineInputSchema, SetBackgroundColorInputSchema, SetCanvasSizeInputSchema, ImportSVGInputSchema, ImportMermaidInputSchema, AddFilterInputSchema, CreateGlossySphereInputSchema, CreateDiagonalStripesInputSchema, BatchCreateInputSchema, BatchModifyInputSchema, CreateGridInputSchema, GeometryInputSchema, EquationPathInputSchema, EventInputSchema, ConstructionSequenceInputSchema, ValidateSceneInputSchema, CaptureFramesInputSchema, InstantiateOntologyInputSchema, LintSceneInputSchema, MediaInputSchema, TextStyleInputSchema, ShatterImageInputSchema, ImportLayeredCharacterInputSchema, GameInputSchema, World3DInputSchema, BrandKitInputSchema, ComponentInputSchema, ArtboardInputSchema, CommentInputSchema, ProvenanceInputSchema, SceneDiffInputSchema, AudioBeatsInputSchema, TemplateParamsInputSchema, ComposeInputSchema, CropImageInputSchema, ChromaKeyInputSchema, RiggingInputSchema, GroupInputSchema, CameraDirectorInputSchema, DetectObjectsInputSchema, ExtractObjectInputSchema, ArrangeInputSchema, CreateSceneInputSchema, GetPerformanceMetricsInputSchema, DiagnosticReportInputSchema, SearchAssetsInputSchema, ImportAssetInputSchema, P5DrawInputSchema, 
+import { CreateItemInputSchema, ModifyItemInputSchema, DeleteItemInputSchema, AddRelationInputSchema, RemoveRelationInputSchema, QueryRelationsInputSchema, AnimateItemInputSchema, ImportMotionCaptureInputSchema, KeyframeAnimateInputSchema, ExecuteGeneratorInputSchema, ApplyEffectInputSchema, GetItemsInputSchema, PlayTimelineInputSchema, SetBackgroundColorInputSchema, SetCanvasSizeInputSchema, ImportSVGInputSchema, ImportMermaidInputSchema, AddFilterInputSchema, CreateGlossySphereInputSchema, CreateDiagonalStripesInputSchema, BatchCreateInputSchema, BatchModifyInputSchema, CreateGridInputSchema, GeometryInputSchema, EquationPathInputSchema, EventInputSchema, ConstructionSequenceInputSchema, ValidateSceneInputSchema, CaptureFramesInputSchema, InstantiateOntologyInputSchema, LintSceneInputSchema, MediaInputSchema, TextStyleInputSchema, TextEffectInputSchema, DesignMediumInputSchema, ShatterImageInputSchema, ImportLayeredCharacterInputSchema, CharacterInputSchema, GameInputSchema, World3DInputSchema, BrandKitInputSchema, ComponentInputSchema, ArtboardInputSchema, CommentInputSchema, ProvenanceInputSchema, SceneDiffInputSchema, AudioBeatsInputSchema, TemplateParamsInputSchema, ComposeInputSchema, CropImageInputSchema, PathOpInputSchema, MotionInputSchema, SoundInputSchema, InterchangeInputSchema, StickInputSchema, DesignSystemInputSchema, StoryInputSchema, ChromaKeyInputSchema, RiggingInputSchema, GroupInputSchema, CameraDirectorInputSchema, DetectObjectsInputSchema, ExtractObjectInputSchema, ArrangeInputSchema, CreateSceneInputSchema, GetPerformanceMetricsInputSchema, DiagnosticReportInputSchema, SearchAssetsInputSchema, ImportAssetInputSchema, P5DrawInputSchema, 
 // Diagram schemas
 CreateDiagramShapeInputSchema, ConnectInputSchema, ConnectPortsInputSchema, AddPortsInputSchema, AutoLayoutInputSchema, GetDiagramShapesInputSchema, UpdateConnectorInputSchema, RemoveConnectorInputSchema, DiagramModeInputSchema, 
 // Agent flow mode schemas
 AgentStartJobInputSchema, AgentEndJobInputSchema, AgentResetInputSchema, AgentBatchExecuteInputSchema, AgentExportInputSchema, AgentAnalyzeInputSchema, 
 // Letter collage schemas
-CreateLetterCollageInputSchema, AnimateLetterCollageInputSchema, ApplyTemplateInputSchema, 
+CreateLetterCollageInputSchema, AnimateLetterCollageInputSchema, 
+// Map schemas
+ApplyTemplateInputSchema, 
+// Map animation/CSV schemas
 // Custom relation/code schemas
 RegisterCustomRelationInputSchema, ExecuteCustomCodeInputSchema, 
 // Mask schemas
 ApplyAnimatedMaskInputSchema, ApplyCustomMaskInputSchema, RemoveMaskInputSchema, 
 // Image import schemas
 ImportImageInputSchema, 
+// Tool guide schema
+// Ontology schemas
 // Scene management schemas
-ManageScenesInputSchema, ScenePlaybackInputSchema, 
+ManageScenesInputSchema, ScenePlaybackInputSchema, SceneGraphInputSchema, SequenceInputSchema, StaggerInputSchema, FlipInputSchema, 
 // New consolidated tool schemas
-SelectionInputSchema, TransformInputSchema, HistoryInputSchema, ImageFilterInputSchema, LassoInputSchema, CutoutStyleInputSchema, PrecompInputSchema, BackgroundInputSchema, QueryInputSchema, DeformInputSchema, SpriteSheetInputSchema, InteractionInputSchema, ExportWidgetInputSchema, ExportWidgetHtmlInputSchema, CreateChartInputSchema, MagicInputSchema, PhysicsInputSchema, MeasurementInputSchema, ErrorCodes, } from '../types/schemas.js';
+SelectionInputSchema, TransformInputSchema, HistoryInputSchema, ImageFilterInputSchema, LassoInputSchema, CutoutStyleInputSchema, PrecompInputSchema, BackgroundInputSchema, QueryInputSchema, QueryCapabilitiesInputSchema, DeformInputSchema, SpriteSheetInputSchema, InteractionInputSchema, ExportWidgetInputSchema, ExportWidgetHtmlInputSchema, CreateChartInputSchema, MagicInputSchema, PhysicsInputSchema, MeasurementInputSchema, ErrorCodes, } from '../types/schemas.js';
 import { ZodError } from 'zod';
-import { writeFile, mkdir } from 'node:fs/promises';
+import { writeFile, mkdir, appendFile, unlink } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { getBrowserController, resetBrowserController, } from '../browser/puppeteer-controller.js';
@@ -38,20 +43,24 @@ import { fontHandlers } from './handlers/font.js';
 import { toolGuideHandlers } from './handlers/tool-guide.js';
 import { mapHandlers } from './handlers/maps.js';
 import { ontologyHandlers } from './handlers/ontology.js';
+import * as designSystems from '../design/design-systems.js';
 import { exportHandlers } from './handlers/export.js';
+import { planCharacter, generateCharacterCode } from './handlers/character.js';
 /**
  * Registry of per-domain handler maps. Tools listed here short-circuit the
  * main switch at dispatch time (see handleToolCallInner). New domains are
  * folded in incrementally as they are migrated out of the monolithic switch.
  */
-const DOMAIN_HANDLERS = [
-    cameraHandlers,
-    fontHandlers,
-    toolGuideHandlers,
-    mapHandlers,
-    ontologyHandlers,
-    exportHandlers,
-];
+function getDomainHandlers() {
+    return [
+        cameraHandlers,
+        fontHandlers,
+        toolGuideHandlers,
+        mapHandlers,
+        ontologyHandlers,
+        exportHandlers,
+    ];
+}
 /**
  * Get screenshot mode from environment variable.
  * Defaults to 'on_request' for optimal performance.
@@ -70,10 +79,13 @@ export function getScreenshotMode() {
 function getExportDir() {
     return process.env.PINEPAPER_EXPORT_DIR || join(tmpdir(), 'pinepaper-exports');
 }
-const ALWAYS_SAVE_FORMATS = new Set(['mp4', 'webm', 'gif', 'pdf']);
+// wav joins them: a minute of 48kHz 16-bit is ~5.8 MB of base64 and the ten
+// minutes the schema allows is ~77 MB. Deliverable across the bridge, useless
+// pasted into a response.
+export const ALWAYS_SAVE_FORMATS = new Set(['mp4', 'webm', 'gif', 'pdf', 'wav']);
 const SAVE_THRESHOLD_BYTES = 500_000; // ~500KB base64 ≈ 375KB decoded
-function getFileExtension(format) {
-    const extMap = { mp4: 'mp4', webm: 'webm', gif: 'gif', pdf: 'pdf', png: 'png', svg: 'svg' };
+export function getFileExtension(format) {
+    const extMap = { mp4: 'mp4', webm: 'webm', gif: 'gif', pdf: 'pdf', png: 'png', svg: 'svg', wav: 'wav' };
     return extMap[format] || format;
 }
 async function saveExportToFile(data, format, platform) {
@@ -95,6 +107,78 @@ async function saveExportToFile(data, format, platform) {
         return { filePath, fileSize: Buffer.byteLength(data, 'utf-8') };
     }
 }
+/**
+ * Page a RETAINED export out of the studio's export store into a local file.
+ *
+ * The bytes never cross the bridge as one string. The studio holds the encoded
+ * file in its origin-private store and hands back an id; this reads it a chunk
+ * at a time and appends each one, so at most one chunk (4 MB by default) is in
+ * memory on either side. The agent still made one tool call and still gets one
+ * filePath — the paging is entirely inside the tool, because an agent-facing
+ * pager would only expose a transport limit the agent cannot act on.
+ *
+ * On failure the export is deliberately LEFT HELD: the store is the only copy,
+ * so the id and the byte count reached go back in the error and the bytes stay
+ * recoverable. `releaseExport` runs only once the whole file is written.
+ */
+async function streamRetainedExportToFile(controller, retained, platform) {
+    const exportDir = getExportDir();
+    await mkdir(exportDir, { recursive: true });
+    const ext = getFileExtension(retained.format);
+    const fileName = `pinepaper_${platform}_${Date.now()}.${ext}`;
+    const filePath = join(exportDir, fileName);
+    const chunkBytes = retained.chunkBytes && retained.chunkBytes > 0 ? retained.chunkBytes : 4 * 1024 * 1024;
+    let offset = 0;
+    let chunks = 0;
+    // Start from empty: appendFile would otherwise extend a same-millisecond file.
+    await writeFile(filePath, Buffer.alloc(0));
+    // Returns the error rather than throwing it, so `throw await abandon(...)`
+    // reads as a throw to the type checker and narrows what follows.
+    const abandon = async (why) => {
+        try {
+            await unlink(filePath);
+        }
+        catch { /* nothing written yet */ }
+        return new Error(`${why} (export "${retained.exportId}" is still held in the studio, ${offset} of ${retained.size} bytes read; ` +
+            `it can be paged again, and is released only once a whole file is written)`);
+    };
+    for (;;) {
+        const code = codeGenerator.generateReadExportChunk(retained.exportId, offset, Math.min(chunkBytes, retained.size - offset));
+        const run = await controller.executeCode(code, false);
+        if (!run.success)
+            throw await abandon(`reading the export failed: ${run.error || 'unknown error'}`);
+        const chunk = run.result;
+        if (!chunk || chunk.ok !== true) {
+            // An evicted id is its own failure: a later export reclaimed the space.
+            // Re-exporting is the caller's decision, never this loop's.
+            throw await abandon(chunk?.evicted
+                ? `the export was evicted mid-read: ${chunk.reason}`
+                : `the studio refused the read: ${chunk?.reason || 'no reason given'}`);
+        }
+        const buf = Buffer.from(chunk.data || '', 'base64');
+        if (buf.length === 0 && chunk.eof !== true)
+            throw await abandon('the studio returned an empty chunk before the end of the file');
+        await appendFile(filePath, buf);
+        offset += buf.length;
+        chunks++;
+        if (chunk.eof === true)
+            break;
+        if (offset >= retained.size)
+            break;
+    }
+    if (offset !== retained.size) {
+        throw await abandon(`reassembled ${offset} bytes but the studio reported ${retained.size}`);
+    }
+    // Only now is it safe to drop the studio's copy.
+    try {
+        await controller.executeCode(codeGenerator.generateReleaseExport(retained.exportId), false);
+    }
+    catch (releaseError) {
+        // A held export costs quota, not correctness — the file is already whole.
+        console.error('[PinePaper] Export written but releaseExport failed:', releaseError);
+    }
+    return { filePath, fileSize: offset, chunks };
+}
 /**
  * Get execution mode from environment variable.
  * Defaults to 'puppeteer' for live execution.
@@ -125,6 +209,17 @@ function successResult(code, description) {
     }
     return { content };
 }
+/**
+ * A plain data answer.
+ *
+ * successResult() fences its payload as "Generated PinePaper code", which is
+ * right for an emitter and wrong for a tool that computes its answer here —
+ * a caller reading design tokens should not be handed something that looks
+ * like a script to paste.
+ */
+function dataResult(value) {
+    return { content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] };
+}
 function executedResult(code, result, screenshot, description, report) {
     const resultObj = { success: true, result };
     if (description)
@@ -415,7 +510,15 @@ export function getLocalizedSuccessMessage(i18n, key, params) {
 // =============================================================================
 /**
  * Execute a tool handler with automatic performance tracking for validation and code generation
+ *
+ * NOT CALLED ANYWHERE. Kept rather than deleted because it is a complete,
+ * working helper and nothing equivalent replaced it — the performance tracking
+ * it implements was written and never wired, which is a gap worth closing
+ * rather than a dead symbol worth removing. Deleting it would erase the intent
+ * along with the code; wiring it is a behaviour change and belongs in its own
+ * commit.
  */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- written, never wired; see above
 async function executeToolWithTracking(toolName, args, options, validator, codeGenerator, description) {
     const tracker = getPerformanceTracker();
     const baseTimerId = `${toolName}_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
@@ -490,7 +593,7 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
         // Domain-module dispatch: tools migrated to per-domain handler files
         // short-circuit before the main switch. See DOMAIN_HANDLERS for the
         // current registry.
-        for (const domainMap of DOMAIN_HANDLERS) {
+        for (const domainMap of getDomainHandlers()) {
             const handler = domainMap[toolName];
             if (handler)
                 return await handler(args, options);
@@ -587,6 +690,29 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
                 const code = codeGenerator.generateScenePlayback(input);
                 return executeOrGenerate(code, `Scene playback: ${input.action}`, options, 'pinepaper_scene_playback');
             }
+            case 'pinepaper_sequence': {
+                const input = SequenceInputSchema.parse(args);
+                const code = codeGenerator.generateSequence(input);
+                return executeOrGenerate(code, `Sequence: ${input.action}`, options, 'pinepaper_sequence');
+            }
+            case 'pinepaper_stagger': {
+                const input = StaggerInputSchema.parse(args);
+                const code = codeGenerator.generateStagger(input);
+                return executeOrGenerate(code, `Stagger: ${input.action}`, options, 'pinepaper_stagger');
+            }
+            case 'pinepaper_flip': {
+                const input = FlipInputSchema.parse(args);
+                const code = codeGenerator.generateFlip(input);
+                return executeOrGenerate(code, `Flip: ${input.action}`, options, 'pinepaper_flip');
+            }
+            case 'pinepaper_scene_graph': {
+                const input = SceneGraphInputSchema.parse(args);
+                const code = codeGenerator.generateSceneGraph(input);
+                const summary = input.action === 'validate'
+                    ? `Scene graph: validating ${input.graph.nodes.length} node(s)`
+                    : `Scene graph: ${input.graph.nodes.length} node(s)`;
+                return executeOrGenerate(code, summary, options, 'pinepaper_scene_graph');
+            }
             // -----------------------------------------------------------------------
             // SELECTION, TRANSFORM & HISTORY TOOLS
             // -----------------------------------------------------------------------
@@ -644,6 +770,11 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
                 const code = codeGenerator.generateQuery(input);
                 return executeOrGenerate(code, `Query: ${input.action}`, options, 'pinepaper_query');
             }
+            case 'pinepaper_query_capabilities': {
+                const input = QueryCapabilitiesInputSchema.parse(args);
+                const code = codeGenerator.generateQueryCapabilities(input);
+                return executeOrGenerate(code, `Capabilities: ${input.action || 'list'}`, options, 'pinepaper_query_capabilities');
+            }
             // -----------------------------------------------------------------------
             // DEFORMATION, SPRITE SHEETS, STORAGE, INTERACTION
             // -----------------------------------------------------------------------
@@ -698,6 +829,28 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
             // -----------------------------------------------------------------------
             // BATCH OPERATION TOOLS
             // -----------------------------------------------------------------------
+            case 'pinepaper_character': {
+                const input = CharacterInputSchema.parse(args);
+                const plan = planCharacter(input);
+                if (!plan.ok) {
+                    // A refusal that names what WOULD have worked. The caller cannot see
+                    // the design graph, and a bare "no" is how a model came to ask for a
+                    // concept that has never had a drawing.
+                    return {
+                        content: [{ type: 'text', text: `pinepaper_character: ${plan.reason}` }],
+                        isError: true,
+                    };
+                }
+                const code = generateCharacterCode(plan, {
+                    generateCreateItem: (i) => codeGenerator.generateCreateItem(i),
+                    generateKeyframeAnimate: (i) => codeGenerator.generateKeyframeAnimate(i),
+                }, {
+                    createItem: (a) => CreateItemInputSchema.parse(a),
+                    keyframeAnimate: (a) => KeyframeAnimateInputSchema.parse(a),
+                });
+                const description = `Places ${input.concept} as ${plan.parts.length} parts with ${plan.tracks} keyframe tracks`;
+                return executeOrGenerate(code, description, options, 'pinepaper_character');
+            }
             case 'pinepaper_batch_create': {
                 const input = BatchCreateInputSchema.parse(args);
                 const code = codeGenerator.generateBatchCreate(input);
@@ -808,6 +961,16 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
                 const code = codeGenerator.generateTextStyle(input);
                 return executeOrGenerate(code, `Text style: ${input.action}`, options, 'pinepaper_text_style');
             }
+            case 'pinepaper_design_medium': {
+                const input = DesignMediumInputSchema.parse(args);
+                const code = codeGenerator.generateDesignMedium(input);
+                return executeOrGenerate(code, `Medium: ${input.action}`, options, 'pinepaper_design_medium');
+            }
+            case 'pinepaper_text_effect': {
+                const input = TextEffectInputSchema.parse(args);
+                const code = codeGenerator.generateTextEffect(input);
+                return executeOrGenerate(code, `Text effect: ${input.action}`, options, 'pinepaper_text_effect');
+            }
             // ─── 1.6.4: agent surface for the Tier-2 engine features ───
             case 'pinepaper_brand_kit': {
                 const input = BrandKitInputSchema.parse(args);
@@ -896,7 +1059,7 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
                 const input = AddRelationInputSchema.parse(args);
                 const code = codeGenerator.generateAddRelation(input);
                 const description = getLocalizedSuccessMessage(i18n, 'relationAdded', {
-                    relationType: input.relationType,
+                    relationType: input.relationType ?? `preset:${input.presetId}`,
                     sourceId: input.sourceId,
                     targetId: input.targetId || 'self',
                 });
@@ -938,6 +1101,14 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
                 });
                 return executeOrGenerate(code, description, options, 'pinepaper_animate');
             }
+            case 'pinepaper_import_motion_capture': {
+                const input = ImportMotionCaptureInputSchema.parse(args);
+                const code = codeGenerator.generateImportMotionCapture(input);
+                const what = input.mode === 'retarget'
+                    ? `Retargets a BVH clip onto rig ${input.skeletonId}`
+                    : 'Imports a BVH clip as a new animated skeleton';
+                return executeOrGenerate(code, what, options, 'pinepaper_import_motion_capture');
+            }
             case 'pinepaper_keyframe_animate': {
                 const input = KeyframeAnimateInputSchema.parse(args);
                 const code = codeGenerator.generateKeyframeAnimate(input);
@@ -945,7 +1116,7 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
             }
             case 'pinepaper_play_timeline': {
                 const input = PlayTimelineInputSchema.parse(args);
-                const code = codeGenerator.generatePlayTimeline(input.action, input.duration, input.loop, input.time, input.deterministic);
+                const code = codeGenerator.generatePlayTimeline(input.action, input.duration, input.loop, input.time, input.deterministic, { rate: input.rate, progress: input.progress, scroll: input.scroll });
                 return executeOrGenerate(code, `Timeline action: ${input.action}`, options, 'pinepaper_play_timeline');
             }
             // -----------------------------------------------------------------------
@@ -1867,7 +2038,7 @@ You can now start creating new items on a clean canvas.`,
                     try {
                         await controller.connect();
                     }
-                    catch (connectError) {
+                    catch (_connectError) {
                         // Fall back to executeOrGenerate which handles the fallback gracefully
                         return executeOrGenerate(code, description, options, 'pinepaper_agent_export');
                     }
@@ -1885,16 +2056,52 @@ You can now start creating new items on a clean canvas.`,
                 const exportResult = exportBrowserResult.result;
                 const format = exportResult?.format || input.format || 'png';
                 const data = exportResult?.data;
+                // RETAINED: the studio held the encoded file in its export store rather
+                // than returning bytes, because base64 of a long video is a bigger
+                // string than the video and it would cross the bridge as one value.
+                // Page it into a file here. mp4/webm were always going to be written to
+                // a file anyway (ALWAYS_SAVE_FORMATS), so the agent's result is the
+                // same shape it has always been — a filePath — just reachable at sizes
+                // that used to run out of memory.
+                if (exportResult?.retained === true && typeof exportResult.exportId === 'string') {
+                    try {
+                        const { filePath, fileSize, chunks } = await streamRetainedExportToFile(controller, {
+                            exportId: exportResult.exportId,
+                            size: Number(exportResult.size) || 0,
+                            format,
+                            chunkBytes: Number(exportResult.chunkBytes) || undefined,
+                        }, input.platform || 'auto');
+                        const cleanResult = { ...exportResult, data: undefined, filePath, fileSize, chunks };
+                        return {
+                            content: [{
+                                    type: 'text',
+                                    text: `Export saved to file:\n\nFile: ${filePath}\nFormat: ${format}\nSize: ${(fileSize / 1024).toFixed(1)} KB\nPlatform: ${input.platform}\nPaged out of the studio's export store in ${chunks} chunk${chunks === 1 ? '' : 's'}\n\nResult: ${JSON.stringify(cleanResult, null, 2)}`,
+                                }],
+                        };
+                    }
+                    catch (streamError) {
+                        // The export is still held — the message says so and names the id,
+                        // because the bytes are recoverable and re-exporting is not free.
+                        const canvasState = await captureCanvasState(controller);
+                        return errorResult(ErrorCodes.EXECUTION_ERROR, streamError instanceof Error ? streamError.message : 'Paging the export out of the store failed', { code, exportId: exportResult.exportId, size: exportResult.size }, { toolName: 'pinepaper_agent_export', canvasState: canvasState || undefined });
+                    }
+                }
                 const shouldSaveToFile = data && typeof data === 'string' && (ALWAYS_SAVE_FORMATS.has(format) ||
                     data.length > SAVE_THRESHOLD_BYTES);
                 if (shouldSaveToFile) {
                     try {
                         const { filePath, fileSize } = await saveExportToFile(data, format, input.platform || 'auto');
                         const cleanResult = { ...exportResult, data: undefined, filePath, fileSize };
+                        // A mix that dropped sounds wrote a perfectly good file that is
+                        // missing tracks. It rides the SUCCESS path, which is exactly why
+                        // it has to be said out loud here rather than left in the JSON.
+                        const dropNote = exportResult.incomplete;
                         return {
                             content: [{
                                     type: 'text',
-                                    text: `Export saved to file:\n\nFile: ${filePath}\nFormat: ${format}\nSize: ${(fileSize / 1024).toFixed(1)} KB\nPlatform: ${input.platform}\n\nResult: ${JSON.stringify(cleanResult, null, 2)}`,
+                                    text: `Export saved to file:\n\nFile: ${filePath}\nFormat: ${format}\nSize: ${(fileSize / 1024).toFixed(1)} KB\nPlatform: ${input.platform}\n`
+                                        + (dropNote ? `DROPPED: ${dropNote}\n` : '')
+                                        + `\nResult: ${JSON.stringify(cleanResult, null, 2)}`,
                                 }],
                         };
                     }
@@ -1908,6 +2115,158 @@ You can now start creating new items on a clean canvas.`,
                 // Small export — return inline (existing behavior)
                 return executedResult(code, exportResult, exportBrowserResult.screenshot, description);
             }
+            case 'pinepaper_design_styles':
+                return dataResult({ styles: designSystems.listStyles() });
+            case 'pinepaper_design_systems':
+            case 'pinepaper_design_system': {
+                const rawArgs = { ...args };
+                if (!rawArgs.action && rawArgs.systemName) {
+                    if (rawArgs.systemName === 'all') {
+                        rawArgs.action = 'list_systems';
+                    }
+                    else {
+                        rawArgs.action = 'get_system';
+                        rawArgs.systemId = String(rawArgs.systemName);
+                    }
+                }
+                if (!rawArgs.action && rawArgs.style && !rawArgs.title) {
+                    rawArgs.action = 'list_styles';
+                }
+                const input = DesignSystemInputSchema.parse(rawArgs);
+                // Answered HERE, not in the browser — these are decisions over
+                // vendored data, and only `compose` with draw:true needs the canvas.
+                switch (input.action) {
+                    case 'list_systems':
+                        return dataResult({ systems: designSystems.listSystems() });
+                    case 'get_system': {
+                        const sys = designSystems.getSystem(input.systemId, input.tokenType);
+                        if (!sys) {
+                            return errorResult(ErrorCodes.INVALID_PARAMS, `no design system "${input.systemId}" — call action 'list_systems' for the ids`, { systemId: input.systemId }, { toolName: 'pinepaper_design_system' });
+                        }
+                        return dataResult(sys);
+                    }
+                    case 'list_easings':
+                        return dataResult({ easings: designSystems.listEasings(input.authoredOnly) });
+                    case 'list_styles':
+                        return dataResult({ styles: designSystems.listStyles() });
+                    case 'compose': {
+                        let scene;
+                        try {
+                            scene = designSystems.compose(input.style, {
+                                title: input.title, subtitle: input.subtitle, body: input.body,
+                                width: input.width, height: input.height, variant: input.variant,
+                            });
+                        }
+                        catch (composeError) {
+                            return errorResult(ErrorCodes.EXECUTION_ERROR, composeError instanceof Error ? composeError.message : 'the style could not compose', { style: input.style }, { toolName: 'pinepaper_design_system' });
+                        }
+                        if (!scene) {
+                            return errorResult(ErrorCodes.INVALID_PARAMS, `"${input.style}" cannot compose — it is a style this surface can name but not build. ` +
+                                `Call action 'list_styles' and use one marked composable.`, { style: input.style }, { toolName: 'pinepaper_design_system' });
+                        }
+                        const ops = designSystems.sceneToOps(scene);
+                        if (input.draw === false) {
+                            return dataResult({ scene, ops, drawn: false });
+                        }
+                        const code = codeGenerator.generateDesignCompose(scene, ops, scene.style);
+                        return executeOrGenerate(code, `Composed a ${scene.style} scene (${ops.length} items)`, options, 'pinepaper_design_system');
+                    }
+                }
+                break;
+            }
+            case 'pinepaper_stick_figure':
+            case 'pinepaper_stick': {
+                const input = StickInputSchema.parse(args);
+                return executeOrGenerate(codeGenerator.generateStick(input), `Stick ${input.action}`, options, 'pinepaper_stick');
+            }
+            case 'pinepaper_story': {
+                const input = StoryInputSchema.parse(args);
+                return executeOrGenerate(codeGenerator.generateStory(input), `Story: ${input.action}`, options, 'pinepaper_story');
+            }
+            case 'pinepaper_interchange': {
+                const input = InterchangeInputSchema.parse(args);
+                const code = codeGenerator.generateInterchange(input);
+                return executeOrGenerate(code, `Interchange: ${input.action}`, options, 'pinepaper_interchange');
+            }
+            case 'pinepaper_sound': {
+                const input = SoundInputSchema.parse(args);
+                const code = codeGenerator.generateSound(input);
+                const soundDescription = `Sound: ${input.action}`;
+                // A RENDERED SOUNDTRACK IS A FILE, not a response field. 48kHz 16-bit
+                // mono is ~96 KB/s, so a minute is ~5.8 MB of base64 and the ten
+                // minutes the schema allows is ~77 MB — deliverable across the bridge,
+                // useless pasted into a conversation. This mirrors what agent_export
+                // already does for video and PDF, and reuses the same helper rather
+                // than growing a second copy of the save path.
+                if (input.action === 'render_soundtrack') {
+                    const execMode = options.executionMode ?? getExecutionMode();
+                    if (execMode === 'code' || !options.executeInBrowser) {
+                        return executeOrGenerate(code, soundDescription, options, 'pinepaper_sound');
+                    }
+                    const soundController = options.browserController || getBrowserController();
+                    if (!soundController.connected) {
+                        try {
+                            await soundController.connect();
+                        }
+                        catch {
+                            return executeOrGenerate(code, soundDescription, options, 'pinepaper_sound');
+                        }
+                    }
+                    const wavResult = await soundController.executeCode(code, false);
+                    if (!wavResult.success) {
+                        const canvasState = await captureCanvasState(soundController);
+                        return errorResult(ErrorCodes.EXECUTION_ERROR, wavResult.error || 'Rendering the soundtrack failed', { code }, { toolName: 'pinepaper_sound', canvasState: canvasState || undefined });
+                    }
+                    const soundtrack = wavResult.result;
+                    // A refusal is a real answer — "no sounds are placed" travels intact
+                    // rather than becoming an empty file.
+                    if (!soundtrack?.success || !soundtrack.wavBase64) {
+                        return executedResult(code, soundtrack, wavResult.screenshot, soundDescription);
+                    }
+                    try {
+                        const { filePath, fileSize } = await saveExportToFile(`data:audio/wav;base64,${soundtrack.wavBase64}`, 'wav', 'soundtrack');
+                        const clean = { ...soundtrack, wavBase64: undefined, filePath, fileSize };
+                        return {
+                            content: [{
+                                    type: 'text',
+                                    text: `Soundtrack rendered to file:\n\nFile: ${filePath}\n`
+                                        + `Size: ${(fileSize / 1024).toFixed(1)} KB\n`
+                                        + `Duration: ${soundtrack.duration}s at ${soundtrack.sampleRate} Hz\n`
+                                        + `Mixed: ${soundtrack.placed} sound(s)\n`
+                                        // The drop count rides on the success path, because a file
+                                        // that wrote fine while missing sounds is the case nobody
+                                        // goes looking for.
+                                        + (soundtrack.dropped ? `DROPPED: ${soundtrack.incomplete}\n` : '')
+                                        + `\nResult: ${JSON.stringify(clean, null, 2)}`,
+                                }],
+                        };
+                    }
+                    catch (saveError) {
+                        const stripped = {
+                            ...soundtrack,
+                            wavBase64: `[${soundtrack.byteLength} bytes of WAV — file save failed: ${saveError instanceof Error ? saveError.message : 'unknown error'}]`,
+                        };
+                        return executedResult(code, stripped, wavResult.screenshot, soundDescription);
+                    }
+                }
+                return executeOrGenerate(code, soundDescription, options, 'pinepaper_sound');
+            }
+            case 'pinepaper_motion': {
+                const input = MotionInputSchema.parse(args);
+                const code = codeGenerator.generateMotion(input);
+                const described = input.action === 'list'
+                    ? 'Listed the generator motion catalogue'
+                    : `Applied motion ${input.motion}`;
+                return executeOrGenerate(code, described, options, 'pinepaper_motion');
+            }
+            case 'pinepaper_path': {
+                const input = PathOpInputSchema.parse(args);
+                const code = codeGenerator.generatePathOp(input);
+                const described = input.action === 'boolean'
+                    ? `Path boolean (${input.op}) over ${input.itemIds?.length ?? 0} items`
+                    : `Path ${input.action}${input.itemId ? ` on ${input.itemId}` : ''}`;
+                return executeOrGenerate(code, described, options, 'pinepaper_path');
+            }
             case 'pinepaper_agent_analyze': {
                 const input = AgentAnalyzeInputSchema.parse(args);
                 const code = codeGenerator.generateAgentAnalyze(input);
@@ -2041,6 +2400,10 @@ You can now start creating new items on a clean canvas.`,
                         'pinepaper_create_scene',
                         'pinepaper_manage_scenes',
                         'pinepaper_scene_playback',
+                        'pinepaper_scene_graph',
+                        'pinepaper_sequence',
+                        'pinepaper_stagger',
+                        'pinepaper_flip',
                         // Agent flow mode tools
                         'pinepaper_agent_start_job',
                         'pinepaper_agent_end_job',
@@ -2084,6 +2447,7 @@ You can now start creating new items on a clean canvas.`,
                         'pinepaper_background',
                         // Canvas query tools
                         'pinepaper_query',
+                        'pinepaper_query_capabilities',
                         // Deformation, sprite sheets, interaction
                         'pinepaper_deform',
                         'pinepaper_sprite_sheet',
@@ -2113,7 +2477,7 @@ You can now start creating new items on a clean canvas.`,
                 canvasState = await captureCanvasState(controller);
             }
         }
-        catch (stateError) {
+        catch (_stateError) {
             // Ignore errors from canvas state capture
         }
         if (error instanceof Error) {