@pinepaper.studio/mcp-server 1.6.7 → 1.6.9

package/dist/tools/handlers.js

@@ -6,11 +6,11 @@
  * Supports browser execution via Puppeteer.
  */
 import { codeGenerator } from '../types/code-generator.js';
-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, 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, 
+AgentStartJobInputSchema, AgentEndJobInputSchema, AgentResetInputSchema, AgentBatchExecuteInputSchema, AgentExportInputSchema, ExportStoreInputSchema, AgentAnalyzeInputSchema, 
 // Letter collage schemas
 CreateLetterCollageInputSchema, AnimateLetterCollageInputSchema, 
 // Map schemas
@@ -29,7 +29,7 @@ ManageScenesInputSchema, ScenePlaybackInputSchema, SceneGraphInputSchema, Sequen
 // New consolidated tool schemas
 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';
@@ -43,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.
@@ -75,10 +79,41 @@ 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' };
+/**
+ * Governor budget for the export run itself.
+ *
+ * FxTool's runGenerated defaults to a 10s async-tail timeout — right for a
+ * scene-building script that has no business running longer, and fatal for an
+ * export, which renders frame by frame and is capped at 600s of footage. The
+ * export died at ten seconds with a PP_TIMEOUT that read like a bug in the
+ * scene. This raises the budget rather than bypassing the governor, so the
+ * report, the item budget and the seeded PRNG all survive.
+ *
+ * PINEPAPER_EXPORT_TIMEOUT overrides it. The default matches the floor put on
+ * CDP's own per-call timeout (MIN_PROTOCOL_TIMEOUT_MS in
+ * puppeteer-controller.ts), so raising this past the default without also
+ * raising PINEPAPER_TIMEOUT just moves the execution to a protocol error —
+ * which is why that case says so out loud rather than failing obscurely later.
+ */
+const EXPORT_GOVERNOR_DEFAULT_MS = 300_000;
+function exportGovernorTimeoutMs() {
+    const raw = Number(process.env.PINEPAPER_EXPORT_TIMEOUT);
+    if (!Number.isFinite(raw) || raw <= 0)
+        return EXPORT_GOVERNOR_DEFAULT_MS;
+    const protocolFloor = Math.max(Number(process.env.PINEPAPER_TIMEOUT) || 0, EXPORT_GOVERNOR_DEFAULT_MS);
+    if (raw > protocolFloor) {
+        console.error(`[PinePaper] PINEPAPER_EXPORT_TIMEOUT=${raw}ms is above the browser's protocol timeout (${protocolFloor}ms) — ` +
+            'raise PINEPAPER_TIMEOUT to match, or an export past that point fails as a protocol error rather than a governor timeout.');
+    }
+    return raw;
+}
+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) {
@@ -100,6 +135,140 @@ 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) {
+    // Reassigned once if the store corrects the size below.
+    let corrected = false;
+    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(
+        // The promise now names the call that keeps it. It was true before and
+        // unreachable: reading a held export mutates nothing, so "it can be paged
+        // again" was always correct and there was no door to page it through.
+        `${why} (export "${retained.exportId}" is still held in the studio, ${offset} of ${retained.size} bytes read; ` +
+            `page it out with pinepaper_export_store action 'save', exportId "${retained.exportId}" — reading is idempotent, ` +
+            'so retrying costs nothing and the export is released only once a whole file is written. Do it BEFORE the next ' +
+            'export: a new one evicts the oldest held bytes to make room)');
+    };
+    // A READ THAT FAILS ON SIZE IS NOT A READ THAT FAILS.
+    //
+    // A 17 MB memphis chunk died on its FOURTH 4 MB read — three had already
+    // landed — with "Failed to write data to data pipe". That is CDP refusing to
+    // carry one oversized value across the bridge, not the store refusing to
+    // serve it: the render had succeeded and the bytes were sitting right there.
+    // The loop abandoned the whole export anyway, and the caller was left with an
+    // error that explained the bytes were still held and no way to go get them.
+    //
+    // So a transport failure halves the request and asks again, down to a floor,
+    // before giving up. The offset does not move, so a retry costs one re-read,
+    // never a corrupt file. A refusal from the STORE (evicted, out of range) is
+    // NOT retried — that answer will not change with a smaller window, and
+    // retrying it would only spend the caller's time to reach the same place.
+    const MIN_CHUNK_BYTES = 256 * 1024;
+    let window = chunkBytes;
+    for (;;) {
+        const want = Math.min(window, retained.size - offset);
+        const code = codeGenerator.generateReadExportChunk(retained.exportId, offset, want);
+        // Deliberately governed at the default budget: a chunk read is a slice of a
+        // string already in memory. If one of these ever needs ten seconds, the
+        // store is wedged and a timeout is the correct answer, not a longer wait.
+        const run = await controller.executeCode(code, false);
+        if (!run.success) {
+            if (want > MIN_CHUNK_BYTES) {
+                window = Math.max(MIN_CHUNK_BYTES, Math.floor(want / 2));
+                console.error(`[PinePaper] a ${want}-byte read of "${retained.exportId}" failed (${run.error || 'unknown error'}); `
+                    + `retrying the same offset at ${window} bytes`);
+                continue;
+            }
+            throw await abandon(`reading the export failed even at the ${MIN_CHUNK_BYTES}-byte floor: ${run.error || 'unknown error'}`);
+        }
+        const chunk = run.result;
+        if (!chunk || chunk.ok !== true) {
+            // A RANGE REFUSAL IS A CORRECTION, and it carries the real size.
+            //
+            // readExport refuses an out-of-range read by name rather than clamping —
+            // deliberately, so a miscounting caller is told instead of handed a short
+            // chunk it treats as the tail, which surfaces later as a truncated video
+            // with nothing pointing back at the cause. The size this loop is working
+            // from came from the export result, and `save` works from a listing; when
+            // either disagrees with the file, the refusal is the authority. Take it
+            // ONCE — a second disagreement is not a miscount, it is a moving target.
+            // Only when it DISAGREES. Every range refusal quotes the real size,
+            // including the ones that are refusing for some other reason — so
+            // matching the number alone treated an eviction as a miscount, spent the
+            // one correction on a no-op re-read, and hid the actual reason for an
+            // iteration.
+            const stated = /\(size (\d+)\)/.exec(chunk?.reason ?? '');
+            if (stated && !corrected && Number(stated[1]) !== retained.size) {
+                corrected = true;
+                const was = retained.size;
+                retained = { ...retained, size: Number(stated[1]) };
+                console.error(`[PinePaper] the store reports "${retained.exportId}" as ${retained.size} bytes, not ${was}; `
+                    + "taking the store's number and continuing");
+                continue;
+            }
+            // An evicted id is its own failure: a later export reclaimed the space.
+            // Re-exporting is the caller's decision, never this loop's. The engine
+            // records an eviction in browser storage so it survives a reload, but
+            // that storage is best-effort — a private window, cleared site data or
+            // storage switched off all fall back to memory-only. So `evicted` being
+            // ABSENT means unknown, never that the export was not there.
+            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.
@@ -130,6 +299,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)
@@ -503,7 +683,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);
@@ -739,6 +919,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);
@@ -947,7 +1149,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',
                 });
@@ -1909,6 +2111,74 @@ You can now start creating new items on a clean canvas.`,
                 }
                 return batchResult;
             }
+            case 'pinepaper_export_store': {
+                const input = ExportStoreInputSchema.parse(args);
+                const controller = options.browserController || getBrowserController();
+                if (!controller.connected) {
+                    try {
+                        await controller.connect();
+                    }
+                    catch (connectError) {
+                        return errorResult(ErrorCodes.EXECUTION_ERROR, `the export store lives in the studio, and connecting to it failed: ${connectError instanceof Error ? connectError.message : 'unknown error'}`, {}, { toolName: 'pinepaper_export_store' });
+                    }
+                }
+                const held = await controller.executeCode(codeGenerator.generateListExports(), false);
+                if (!held.success) {
+                    return errorResult(ErrorCodes.EXECUTION_ERROR, `listing the export store failed: ${held.error || 'unknown error'}`, {}, { toolName: 'pinepaper_export_store' });
+                }
+                const listing = held.result;
+                if (!listing || listing.ok !== true) {
+                    return errorResult(ErrorCodes.EXECUTION_ERROR, listing?.reason || 'the studio did not answer with a listing', {}, { toolName: 'pinepaper_export_store' });
+                }
+                const exports = listing.exports ?? [];
+                if (input.action === 'list') {
+                    return dataResult({
+                        exports,
+                        held: exports.length,
+                        heldBytes: exports.reduce((n, e) => n + (e.size || 0), 0),
+                        note: exports.length > 1
+                            ? 'A later export evicts the OLDEST held ones to make room. Save or release each before starting the next.'
+                            : undefined,
+                    });
+                }
+                // Both remaining actions name an id, and an id the store does not have
+                // is the one thing worth saying carefully. The engine records an
+                // eviction durably enough to survive a reload, so a read of that id
+                // will usually say "evicted" — but the record is best-effort browser
+                // storage and a listing cannot consult it at all. Absence of the id
+                // here is therefore "gone, cause unknown", and stating one cause as
+                // fact would be inventing the more interesting half of the answer.
+                const entry = exports.find((e) => e.id === input.exportId);
+                if (!entry) {
+                    return errorResult(ErrorCodes.INVALID_PARAMS, `the studio is not holding "${input.exportId}". It was released, evicted to make room for a later export, `
+                        + `or never existed here — a listing cannot tell which. `
+                        + `${exports.length ? `Held right now: ${exports.map((e) => e.id).join(', ')}.` : 'The store is empty.'}`, { exportId: input.exportId, held: exports.map((e) => e.id) }, { toolName: 'pinepaper_export_store' });
+                }
+                if (input.action === 'release') {
+                    const dropped = await controller.executeCode(codeGenerator.generateReleaseExport(entry.id), false);
+                    const outcome = dropped.result;
+                    if (!dropped.success || outcome?.ok !== true) {
+                        return errorResult(ErrorCodes.EXECUTION_ERROR, `releasing "${entry.id}" failed: ${dropped.error || outcome?.reason || 'unknown error'}`, { exportId: entry.id }, { toolName: 'pinepaper_export_store' });
+                    }
+                    return dataResult({ released: entry.id, freedBytes: entry.size });
+                }
+                // save: the same pager agent_export uses, pointed at an id instead of a
+                // fresh render. Reading is idempotent, so a save that failed halfway
+                // can simply be run again — there is no partial state to clean up here.
+                try {
+                    const { filePath, fileSize, chunks } = await streamRetainedExportToFile(controller, { exportId: entry.id, size: entry.size, format: entry.format }, input.platform || 'recovered');
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: `Export recovered from the studio's store:\n\nFile: ${filePath}\nFormat: ${entry.format}\n`
+                                    + `Size: ${(fileSize / 1024).toFixed(1)} KB\nPaged out in ${chunks} chunk${chunks === 1 ? '' : 's'}, then released\n`,
+                            }],
+                    };
+                }
+                catch (streamError) {
+                    return errorResult(ErrorCodes.EXECUTION_ERROR, streamError instanceof Error ? streamError.message : 'paging the export out of the store failed', { exportId: entry.id, size: entry.size }, { toolName: 'pinepaper_export_store' });
+                }
+            }
             case 'pinepaper_agent_export': {
                 const input = AgentExportInputSchema.parse(args);
                 const code = codeGenerator.generateAgentExport(input);
@@ -1936,24 +2206,94 @@ You can now start creating new items on a clean canvas.`,
                 if (!exportSessionManager.hasActiveJob()) {
                     exportSessionManager.startJob({ name: 'auto_session', screenshotPolicy: 'on_complete' });
                 }
-                const exportBrowserResult = await controller.executeCode(code, false);
+                const exportBrowserResult = await controller.executeCode(code, false, {
+                    governorTimeoutMs: exportGovernorTimeoutMs(),
+                });
                 if (!exportBrowserResult.success) {
                     const canvasState = await captureCanvasState(controller);
                     return errorResult(ErrorCodes.EXECUTION_ERROR, exportBrowserResult.error || 'Export failed', { code }, { toolName: 'pinepaper_agent_export', canvasState: canvasState || undefined });
                 }
                 const exportResult = exportBrowserResult.result;
+                // TWO VERDICTS, and only one of them was being read.
+                //
+                // `exportBrowserResult.success` says the CODE RAN. The export's own
+                // verdict is `exportResult.success`, and every emitted branch that
+                // cannot deliver returns `{ success: false, error }` — a studio without
+                // the renderer, an encoder that died, a blob past the inline ceiling.
+                // None of that was checked: the value fell through to the inline return
+                // below, which reports a success and hands back a result object nobody
+                // reads past the first line.
+                //
+                // Measured cost: a five-chunk video where two chunks came back
+                // `success: false, error: "export failed: Failed to write data to data
+                // pipe"` under an outer `"success": true`. The caller shipped a
+                // three-chunk video believing it had five. A silent success is the one
+                // failure mode this surface can never afford, because nothing
+                // downstream has any reason to look again.
+                if (exportResult && exportResult.success === false) {
+                    const canvasState = await captureCanvasState(controller);
+                    // A "data pipe" failure is the BROWSER TRANSPORT refusing to carry
+                    // the result back, not the encoder refusing to make it — the string
+                    // exists nowhere in the engine. So the render may well have finished
+                    // and the bytes may be sitting in the export store right now. Saying
+                    // so is the difference between recovering an export and re-rendering
+                    // one, and re-rendering is what evicts an earlier chunk's bytes.
+                    const looksLikeTransport = /data pipe/i.test(String(exportResult.error ?? ''));
+                    return errorResult(ErrorCodes.EXECUTION_ERROR, `export failed: ${exportResult.error || 'the studio reported failure without naming a reason'}`
+                        + (looksLikeTransport
+                            ? ' — that is the browser transport failing to carry the result back, not necessarily the render failing.'
+                                + " Call pinepaper_export_store action 'list' BEFORE re-rendering: the bytes may already be held, and a"
+                                + ' fresh export can evict an earlier one to make room.'
+                            : ''), { code, format: exportResult.format ?? input.format, result: exportResult }, { toolName: 'pinepaper_agent_export', canvasState: canvasState || undefined });
+                }
                 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)}`,
                                 }],
                         };
                     }
@@ -1967,6 +2307,170 @@ 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_motion': {
+                        // Curves and durations together, because a motion token is a shape
+                        // AND a length. The curves were published and the durations beside
+                        // them in the same store were not, so a caller could match a
+                        // system's easing and had to invent its timing.
+                        const easings = designSystems.listEasings(input.authoredOnly);
+                        const durations = designSystems.listDurations(input.authoredOnly);
+                        return dataResult({
+                            easings, durations,
+                            note: 'These are the licensed SYSTEMS\' motion scales. An aesthetic style (bauhaus_geometric, memphis_group) carries no upstream motion data — pair one of these with a style rather than expecting the style to name its own.',
+                        });
+                    }
+                    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);