@pinepaper.studio/mcp-server 1.6.18 → 1.6.19

package/dist/tools/handlers.js

@@ -6,7 +6,7 @@
  * Supports browser execution via Puppeteer.
  */
 import { codeGenerator, generateQueryMutationsCode, SHEET_RUBRIC } 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, CharacterInputSchema, GameInputSchema, World3DInputSchema, BrandKitInputSchema, ComponentInputSchema, ArtboardInputSchema, CommentInputSchema, ProvenanceInputSchema, SceneDiffInputSchema, AudioBeatsInputSchema, TemplateParamsInputSchema, RenderBatchInputSchema, AccessibilityCheckInputSchema, QueryMutationsInputSchema, ComposeInputSchema, CropImageInputSchema, PathOpInputSchema, MotionInputSchema, SoundInputSchema, InterchangeInputSchema, StickInputSchema, DesignSystemInputSchema, StoryInputSchema, 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, RelightInputSchema, ShaderGraphInputSchema, ShatterImageInputSchema, ImportLayeredCharacterInputSchema, CharacterInputSchema, GameInputSchema, World3DInputSchema, BrandKitInputSchema, ComponentInputSchema, ArtboardInputSchema, CommentInputSchema, ProvenanceInputSchema, SceneDiffInputSchema, AudioBeatsInputSchema, TemplateParamsInputSchema, RenderBatchInputSchema, AccessibilityCheckInputSchema, QueryMutationsInputSchema, 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
@@ -27,7 +27,7 @@ ImportImageInputSchema,
 // Scene management schemas
 ManageScenesInputSchema, ScenePlaybackInputSchema, SceneGraphInputSchema, SequenceInputSchema, StaggerInputSchema, FlipInputSchema, 
 // 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';
+SelectionInputSchema, TransformInputSchema, HistoryInputSchema, ImageFilterInputSchema, LassoInputSchema, CutoutStyleInputSchema, PrecompInputSchema, BackgroundInputSchema, QueryInputSchema, QueryCapabilitiesInputSchema, DeformInputSchema, SpriteSheetInputSchema, InteractionInputSchema, ExportWidgetInputSchema, ExportWidgetHtmlInputSchema, CreateChartInputSchema, MagicInputSchema, PhysicsInputSchema, MeasurementInputSchema, PlaceOnSurfaceInputSchema, StyledSceneInputSchema, ErrorCodes, } from '../types/schemas.js';
 import { ZodError, z } from 'zod';
 import { writeFile, mkdir, appendFile, unlink, readFile, stat } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
@@ -37,6 +37,7 @@ import { getBrowserController, resetBrowserController, } from '../browser/puppet
 import { sameStudioTarget, validateStudioUrl } from '../browser/url-target.js';
 import { getPerformanceTracker } from '../metrics/index.js';
 import { formatErrorContext, captureCanvasState } from '../execution/index.js';
+import { FILTER_PARAM_RANGES } from './engine-lists.js';
 import { getSessionManager } from '../agent/session-manager.js';
 import { vocabularyHintForPath, validateBatchVocabulary, detectBatchPropertyTypos } from '../ontology/hints.js';
 import { cameraHandlers } from './handlers/camera.js';
@@ -560,10 +561,37 @@ export function getExecutionMode() {
     // Default to 'puppeteer' for live browser execution
     return 'puppeteer';
 }
+/** Where a generated script travels for a host to record, beside the agent-visible text. */
+/** Relation types registered with register_custom_relation in this server session (gate D2). */
+export const CUSTOM_RELATION_NAMES = new Set();
+/**
+ * Tools whose browser work legitimately outlasts the governor's 10 s default.
+ * The first detection call downloads and initialises a model, which on a cold
+ * page took longer than 10 s and died as a timeout (gate C10, 1.6.19).
+ */
+const LONG_GOVERNOR_BUDGET_MS = {
+    pinepaper_detect_objects: 120_000,
+    pinepaper_extract_object: 120_000,
+};
+export const CODE_META_KEY = 'pinepaper.studio/code';
 // =============================================================================
 // RESULT HELPERS
 // =============================================================================
-function successResult(code, description) {
+function successResult(code, description, deferred = false) {
+    if (deferred) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        success: true,
+                        status: 'recorded',
+                        step: description || 'canvas step',
+                        note: 'Recorded on the scene. It runs in the studio when the scene renders or exports, not now; keep building, then render.',
+                    }, null, 2),
+                }],
+            _meta: { [CODE_META_KEY]: code },
+        };
+    }
     const content = [
         {
             type: 'text',
@@ -576,7 +604,7 @@ function successResult(code, description) {
             text: `\n${description}`,
         });
     }
-    return { content };
+    return { content, _meta: { [CODE_META_KEY]: code } };
 }
 /**
  * A plain data answer.
@@ -589,6 +617,18 @@ function successResult(code, description) {
 function dataResult(value) {
     return { content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] };
 }
+/**
+ * Where a call's time went (O1, per-request trace). In the result's _meta, the
+ * spec's slot for metadata, under one namespaced key, so it adds nothing to
+ * the text a model reads. browserMs includes the screenshot when one was taken.
+ * index.ts adds toolMs, the whole call, for every tool.
+ */
+export const TIMING_META_KEY = 'pinepaper.studio/timing';
+export function withTiming(out, t) {
+    const meta = (out._meta ?? {});
+    const prev = (meta[TIMING_META_KEY] ?? {});
+    return { ...out, _meta: { ...meta, [TIMING_META_KEY]: { ...prev, ...t } } };
+}
 /**
  * A call that only succeeded after the browser session was recovered says so,
  * in the result: the controller has reported `recovered` / `canvasReset` for
@@ -601,7 +641,7 @@ function withSessionNote(out, r) {
     const note = r.relaunched
         ? `The browser session had been lost; the browser was relaunched and this call ran on an EMPTY canvas${r.canvasSizeRestored ? ` (size restored to ${r.canvasSizeRestored.width}x${r.canvasSizeRestored.height})` : ' at the default size'}. Item ids from before are gone: rebuild the scene.`
         : r.canvasReset
-            ? 'The page had reloaded and the canvas came back EMPTY. Item ids from before are gone: rebuild the scene.'
+            ? 'The studio page had reloaded or navigated away, and the canvas came back EMPTY. Item ids from before are gone: rebuild the scene.'
             : 'The page connection was re-established; the scene survived.';
     const first = out.content[0];
     if (first && first.type === 'text') {
@@ -894,6 +934,40 @@ async function brandFromUrl(url, shots, options) {
         return errorResult(ErrorCodes.EXECUTION_ERROR, `could not read ${url}: ${e instanceof Error ? e.message : String(e)}`, {}, { toolName: 'pinepaper_brand_kit' });
     }
 }
+/**
+ * If an executed result carries `data` (a data URL, or JSON/text), write it to
+ * a file in the export dir and replace it with filePath + bytes.
+ */
+async function writeResultDataToFile(out, ext) {
+    const first = out.content?.[0];
+    if (out.isError || !first || first.type !== 'text')
+        return out;
+    let obj;
+    try {
+        obj = JSON.parse(first.text);
+    }
+    catch {
+        return out;
+    }
+    const r = obj.result;
+    if (!r || r.data === undefined || r.data === null)
+        return out;
+    let bytes;
+    if (typeof r.data === 'string' && r.data.startsWith('data:'))
+        bytes = Buffer.from(r.data.slice(r.data.indexOf(',') + 1), 'base64');
+    else if (typeof r.data === 'string')
+        bytes = Buffer.from(r.data, 'utf-8');
+    else
+        bytes = Buffer.from(JSON.stringify(r.data), 'utf-8');
+    const dir = getExportDir();
+    await mkdir(dir, { recursive: true });
+    const filePath = join(dir, `pinepaper_${String(r.format ?? 'export').replace(/[^a-z0-9-]/gi, '')}_${Date.now()}.${ext}`);
+    await writeFile(filePath, bytes);
+    const { data: _d, ...rest } = r;
+    void _d;
+    obj.result = { ...rest, filePath, bytes: bytes.length };
+    return { ...out, content: [{ type: 'text', text: JSON.stringify(obj, null, 2) }, ...out.content.slice(1)] };
+}
 /**
  * pinepaper_capture_frames with `sheet`: one tiled image of the film, saved
  * to a file (an image is never useful inline, see ALWAYS_SAVE_FORMATS), with
@@ -998,7 +1072,7 @@ The code is ready to use. Each subsequent tool call will also generate code you
             timestamp: Date.now(),
             success: true,
         });
-        return successResult(code, description);
+        return successResult(code, description, options.deferred === true);
     }
     const controller = browserController || getBrowserController();
     // Auto-connect in agent mode if not connected
@@ -1081,18 +1155,29 @@ ${code}
     // emitter is not (its verdict already describes what it left behind).
     const rollbackOnFailure = toolName === 'pinepaper_execute_custom_code'
         && await markItemsBeforeRun(controller);
-    const result = await controller.executeCode(code, shouldTakeScreenshot, stage ? { stage } : {});
+    const governorTimeoutMs = LONG_GOVERNOR_BUDGET_MS[toolName];
+    const result = await controller.executeCode(code, shouldTakeScreenshot, {
+        ...(stage ? { stage } : {}),
+        ...(governorTimeoutMs ? { governorTimeoutMs } : {}),
+    });
     const browserDuration = tracker.endTimer(`${timerId}_browser_execution`);
+    // THE METRIC RECORDS THE CALL'S VERDICT, NOT THE TRANSPORT'S (gate H2,
+    // 1.6.19). result.success only says the code RAN; an emitter that ran and
+    // returned { success: false } is a failed call, and get_performance_metrics
+    // reported "Success Rate: 100.0%" over exactly such a failure.
+    const innerVerdict = result.success ? innerFailure(result.result) : null;
     tracker.recordMetric({
         toolName,
         phase: 'browser_execution',
         duration: browserDuration,
         timestamp: Date.now(),
-        success: result.success,
-        error: result.error,
+        success: result.success && !innerVerdict,
+        error: result.error || innerVerdict || undefined,
     });
+    let screenshotMs;
     if (shouldTakeScreenshot) {
         const screenshotDuration = tracker.endTimer(`${timerId}_screenshot`);
+        screenshotMs = screenshotDuration;
         tracker.recordMetric({
             toolName,
             phase: 'screenshot',
@@ -1108,13 +1193,14 @@ ${code}
         phase: 'total',
         duration: totalDuration,
         timestamp: Date.now(),
-        success: result.success,
-        error: result.error,
+        success: result.success && !innerVerdict,
+        error: result.error || innerVerdict || undefined,
     });
+    const timing = { browserMs: Math.round(browserDuration), ...(screenshotMs !== undefined ? { screenshotMs: Math.round(screenshotMs) } : {}) };
     if (!result.success) {
         // Capture canvas state for error context
         const canvasState = await captureCanvasState(controller);
-        return errorResult(ErrorCodes.EXECUTION_ERROR, result.error || 'Failed to execute code in browser', 
+        return withTiming(errorResult(ErrorCodes.EXECUTION_ERROR, result.error || 'Failed to execute code in browser', 
         // errorCode surfaces the governor's structured code (PP_ITEM_BUDGET,
         // PP_LOOP_BUDGET, PP_TIMEOUT) so the model can correct on the next turn.
         {
@@ -1123,7 +1209,7 @@ ${code}
         }, {
             toolName,
             canvasState: canvasState || undefined,
-        });
+        }), timing);
     }
     // TWO VERDICTS. `result.success` says the CODE RAN. The emitted code has its
     // own verdict, and almost every emitter in this repo returns
@@ -1137,15 +1223,24 @@ ${code}
     // outer success and the agent kept building on a rig that did not exist.
     // pinepaper_agent_export got this check in 1.6.9; it belongs HERE, where
     // every tool inherits it.
-    const inner = innerFailure(result.result);
+    const inner = innerVerdict;
     if (inner) {
         const canvasState = await captureCanvasState(controller);
-        return errorResult(ErrorCodes.EXECUTION_ERROR, inner, {
+        return withTiming(errorResult(ErrorCodes.EXECUTION_ERROR, inner, {
             code, result: result.result, governorReport: result.report,
             ...(rollbackOnFailure ? await customCodeRollback(controller, inner) : {}),
-        }, { toolName, canvasState: canvasState || undefined });
+        }, { toolName, canvasState: canvasState || undefined }), timing);
     }
-    return withSessionNote(executedResult(code, result.result, result.screenshot, description, result.report), result);
+    // Session item counts come from the governor's own count of what this call
+    // created (gate H3: the session stats read 0 with items on the canvas).
+    const created = result.report?.items?.created;
+    if (typeof created === 'number' && created > 0) {
+        try {
+            getSessionManager().noteItemsCreated(created);
+        }
+        catch { /* no session */ }
+    }
+    return withTiming(withSessionNote(executedResult(code, result.result, result.screenshot, description, result.report), result), timing);
 }
 /**
  * The emitted code's own verdict, when it reported one and it was a failure.
@@ -1703,6 +1798,28 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
             }
             case 'pinepaper_validate_scene': {
                 const input = ValidateSceneInputSchema.parse(args);
+                // The validator reads { from, to, relation } on an addRelation op; the
+                // add_relation tool's own names (source, target, relationType) are what
+                // an agent reaches for, and the tool's example used them, so every
+                // example op failed SOURCE_NOT_FOUND "undefined" (gate D8, 1.6.19).
+                if (Array.isArray(input.ops)) {
+                    input.ops = input.ops.map((op) => {
+                        const o = { ...op };
+                        if (o.from === undefined && o.source !== undefined) {
+                            o.from = o.source;
+                            delete o.source;
+                        }
+                        if (o.to === undefined && o.target !== undefined) {
+                            o.to = o.target;
+                            delete o.target;
+                        }
+                        if (o.relation === undefined && o.relationType !== undefined) {
+                            o.relation = o.relationType;
+                            delete o.relationType;
+                        }
+                        return o;
+                    });
+                }
                 const code = codeGenerator.generateValidateScene(input);
                 const description = input.ops ? `Pre-validate ${input.ops.length} proposed op(s)` : 'Audit the live scene';
                 return executeOrGenerate(code, description, options, 'pinepaper_validate_scene');
@@ -1770,6 +1887,23 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
                 return executeOrGenerate(code, `Text effect: ${input.action}`, options, 'pinepaper_text_effect');
             }
             // ─── 1.6.4: agent surface for the Tier-2 engine features ───
+            case 'pinepaper_relight': {
+                const input = RelightInputSchema.parse(args);
+                return executeOrGenerate(codeGenerator.generateRelight(input), `Relight: ${input.action}`, options, 'pinepaper_relight');
+            }
+            case 'pinepaper_shader_graph': {
+                const input = ShaderGraphInputSchema.parse(args);
+                return executeOrGenerate(codeGenerator.generateShaderGraph(input), `Shader graph: ${input.action}`, options, 'pinepaper_shader_graph');
+            }
+            case 'pinepaper_styled_scene': {
+                const input = StyledSceneInputSchema.parse(args);
+                return executeOrGenerate(codeGenerator.generateStyledScene(input), `Styled scene${input.style ? `: ${input.style}` : ''}`, options, 'pinepaper_styled_scene');
+            }
+            case 'pinepaper_place_on_surface': {
+                const input = PlaceOnSurfaceInputSchema.parse(args);
+                const code = codeGenerator.generatePlaceOnSurface(input);
+                return executeOrGenerate(code, 'Place a UI onto a screen in a photo', options, 'pinepaper_place_on_surface');
+            }
             case 'pinepaper_brand_kit': {
                 const input = BrandKitInputSchema.parse(args);
                 if (input.action === 'from_url')
@@ -2031,8 +2165,17 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
             // RELATION TOOLS
             // -----------------------------------------------------------------------
             case 'pinepaper_add_relation': {
-                const input = AddRelationInputSchema.parse(args);
-                const code = codeGenerator.generateAddRelation(input);
+                // A relation registered with register_custom_relation this session is
+                // a valid type here (gate D2, 1.6.19: the enum refused the name just
+                // registered). Only those names; an unknown one is still refused.
+                const rt = args.relationType;
+                // The schema's refinements check presence, not which type, so a custom
+                // name is validated with a built-in stand-in and then put back.
+                const isCustom = typeof rt === 'string' && CUSTOM_RELATION_NAMES.has(rt);
+                const input = AddRelationInputSchema.parse(isCustom ? { ...args, relationType: 'orbits' } : args);
+                if (isCustom)
+                    input.relationType = rt;
+                const code = codeGenerator.generateAddRelation(input, isCustom);
                 const description = getLocalizedSuccessMessage(i18n, 'relationAdded', {
                     relationType: input.relationType ?? `preset:${input.presetId}`,
                     sourceId: input.sourceId,
@@ -2056,6 +2199,7 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
             }
             case 'pinepaper_register_custom_relation': {
                 const input = RegisterCustomRelationInputSchema.parse(args);
+                CUSTOM_RELATION_NAMES.add(input.name);
                 const code = codeGenerator.generateRegisterCustomRelation(input);
                 return executeOrGenerate(code, `Registers custom relation type: ${input.name}`, options, 'pinepaper_register_custom_relation');
             }
@@ -2197,10 +2341,9 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
             case 'pinepaper_set_canvas_size': {
                 const input = SetCanvasSizeInputSchema.parse(args);
                 const code = codeGenerator.generateSetCanvasSize(input);
-                const description = getLocalizedSuccessMessage(i18n, 'canvasSizeSet', {
-                    width: input.width,
-                    height: input.height,
-                });
+                const description = input.preset && input.width === undefined
+                    ? `Set canvas size to preset ${input.preset}`
+                    : getLocalizedSuccessMessage(i18n, 'canvasSizeSet', { width: input.width ?? '', height: input.height ?? '' });
                 return executeOrGenerate(code, description, options, 'pinepaper_set_canvas_size');
             }
             case 'pinepaper_get_canvas_size': {
@@ -2306,6 +2449,15 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
             // -----------------------------------------------------------------------
             case 'pinepaper_add_filter': {
                 const input = AddFilterInputSchema.parse(args);
+                // Out-of-range parameters are refused with the engine's own range
+                // (gate A, 1.6.19: dither levels 99 was accepted and quietly clamped).
+                const ranges = FILTER_PARAM_RANGES[input.filterType] ?? {};
+                for (const [k, v] of Object.entries((input.params ?? {}))) {
+                    const r = ranges[k];
+                    if (r && typeof v === 'number' && (v < r[0] || v > r[1])) {
+                        return errorResult(ErrorCodes.VALIDATION_ERROR, `${input.filterType} ${k} must be ${r[0]}..${r[1]} (got ${v}).`, { filterType: input.filterType, param: k, range: r });
+                    }
+                }
                 const code = codeGenerator.generateAddFilter(input.filterType, input.params);
                 const description = `Adds ${input.filterType} filter to the canvas`;
                 return executeOrGenerate(code, description, options, 'pinepaper_add_filter');
@@ -2516,7 +2668,19 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                         const perfTracker = getPerformanceTracker();
                         const recentMetrics = perfTracker.exportMetrics('json', { limit: metricsLimit });
                         const stats = perfTracker.getStats();
-                        metricsSection = { entries: recentMetrics, stats };
+                        // exportMetrics('json') returns a JSON STRING; embedded as-is it reached
+                        // the report as one escaped string, not an array (gate H3).
+                        let entries = recentMetrics;
+                        if (typeof recentMetrics === 'string') {
+                            try {
+                                entries = JSON.parse(recentMetrics);
+                            }
+                            catch { /* keep the string */ }
+                        }
+                        if (entries && typeof entries === 'object' && !Array.isArray(entries) && Array.isArray(entries.metrics)) {
+                            entries = entries.metrics;
+                        }
+                        metricsSection = { entries, stats };
                     }
                     catch { /* metrics not available */ }
                 }
@@ -2571,17 +2735,25 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                         },
                         recommendations: [],
                     };
-                    // Add actionable recommendations
+                    // RECOMMEND ONLY WHAT SAVES (gate H4, 1.6.19). This said "switch to
+                    // agent" on full, which saves under 1% (agent omits three small
+                    // tools). Each alternative is measured against the active set and
+                    // offered only when it saves at least 10%, with the saving stated.
                     const recs = toolDefsSection.recommendations;
-                    if (toolkit === 'full') {
-                        recs.push(`Switch to PINEPAPER_TOOLKIT=agent to reduce to ~${agentCompactTokens.toLocaleString()} tokens/turn (agent+compact)`);
-                    }
-                    if (verbosity === 'verbose') {
-                        recs.push(`Set PINEPAPER_VERBOSITY=compact to reduce tool definitions overhead`);
-                    }
-                    if (verbosity !== 'minimal') {
-                        recs.push(`Set PINEPAPER_VERBOSITY=minimal for maximum savings (~${agentMinimalTokens.toLocaleString()} tokens with agent toolkit) — use pinepaper_tool_guide for on-demand docs`);
+                    const alternatives = [];
+                    for (const v of ['compact', 'minimal']) {
+                        for (const k of ['full', 'agent', 'minimal']) {
+                            if (k === toolkit && v === verbosity)
+                                continue;
+                            const t = Math.ceil(Buffer.byteLength(JSON.stringify(getToolsForToolkit(getToolsForVerbosity(v), k)), 'utf-8') / 4);
+                            alternatives.push({ label: `${k}+${v}`, how: `PINEPAPER_TOOLKIT=${k} PINEPAPER_VERBOSITY=${v}`, tokens: t });
+                        }
                     }
+                    alternatives
+                        .filter((alt) => alt.tokens <= activeTokens * 0.9)
+                        .sort((x, y) => x.tokens - y.tokens)
+                        .slice(0, 3)
+                        .forEach((alt) => recs.push(`${alt.how}: ~${alt.tokens.toLocaleString()} tokens/turn (${Math.round((1 - alt.tokens / activeTokens) * 100)}% less)${alt.label.startsWith('minimal+') ? ' — a small core set; switch profiles at runtime with pinepaper_set_toolkit' : ''}`));
                     if (activeTokens > 20000) {
                         recs.push(`Tool definitions alone consume ~${activeTokens.toLocaleString()} tokens per API turn — this is a major context budget item`);
                     }
@@ -2700,11 +2872,19 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
             // ASSET TOOLS
             // -----------------------------------------------------------------------
             case 'pinepaper_search_assets': {
+                // Asked for by name, a removed repository says why rather than failing
+                // the enum check with a bare "invalid option".
+                {
+                    const { REMOVED_REPOSITORIES, REMOVED_REPOSITORY_REASON } = await import('../assets/index.js');
+                    if (typeof args.repository === 'string' && REMOVED_REPOSITORIES.includes(args.repository)) {
+                        return errorResult(ErrorCodes.INVALID_PARAMS, `${REMOVED_REPOSITORY_REASON} Search repository 'all', 'iconify' or 'fontawesome'.`, { repository: args.repository }, { toolName: 'pinepaper_search_assets' });
+                    }
+                }
                 const input = SearchAssetsInputSchema.parse(args);
                 const { getAssetManager } = await import('../assets/index.js');
                 const assetManager = getAssetManager();
                 try {
-                    const results = await assetManager.search(input.query, input.repository || 'all', input.limit || 10);
+                    const { results, sources } = await assetManager.searchWithStatus(input.query, input.repository || 'all', input.limit || 10);
                     // If includeSvgContent is true, fetch SVG content for each result
                     let resultsWithContent = [];
                     if (input.includeSvgContent) {
@@ -2776,6 +2956,7 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                                     query: input.query,
                                     repository: input.repository || 'all',
                                     count: resultsWithContent.length,
+                                    sources,
                                     includeSvgContent: input.includeSvgContent || false,
                                     attributionRequired: requiresAttribution.length > 0,
                                     attributionNotice,
@@ -2836,6 +3017,15 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                         svg = body;
                         metadata = { source: 'url', url: input.url };
                     }
+                    // `color` was accepted and never applied, so a recoloured icon
+                    // rendered black (gate D15, 1.6.19). A monochrome icon draws in
+                    // currentColor (stroke sets) or in the default fill (fill sets):
+                    // both take the colour.
+                    if (input.color) {
+                        const c = input.color.replace(/"/g, '');
+                        svg = svg.replace(/currentColor/g, c);
+                        svg = svg.replace(/<svg\b([^>]*)>/i, (m, attrs) => (/\sfill\s*=/.test(attrs) ? m : `<svg${attrs} fill="${c}">`));
+                    }
                     // Import the SVG onto canvas using existing import_svg tool
                     const code = codeGenerator.generateImportSVG(svg, undefined, input.position, input.scale);
                     // A URL import has no catalogue metadata (no title, no licence): this
@@ -3366,10 +3556,18 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                                 `Call action 'list_styles' and use one marked composable.`, { style: input.style }, { toolName: 'pinepaper_design_system' });
                         }
                         const ops = designSystems.sceneToOps(scene);
+                        // Some vendored styles lay out at their OWN fixed size and ignore
+                        // width/height (swiss_typographic is always 1280x720), so a caller
+                        // asking for 1080x1080 got a resized canvas (gate run 3). Say so.
+                        const sizeIgnored = (input.width !== undefined && input.width !== scene.width)
+                            || (input.height !== undefined && input.height !== scene.height);
+                        const sizeWarning = sizeIgnored
+                            ? `"${scene.style}" lays out at its own size, ${scene.width}x${scene.height}; the requested ${input.width ?? '?'}x${input.height ?? '?'} was not used`
+                            : undefined;
                         if (input.draw === false) {
-                            return dataResult({ scene, ops, drawn: false });
+                            return dataResult({ scene, ops, drawn: false, ...(sizeWarning ? { warning: sizeWarning } : {}) });
                         }
-                        const code = codeGenerator.generateDesignCompose(scene, ops, scene.style);
+                        const code = codeGenerator.generateDesignCompose(scene, ops, scene.style, sizeWarning);
                         return executeOrGenerate(code, `Composed a ${scene.style} scene (${ops.length} items)`, options, 'pinepaper_design_system');
                     }
                 }
@@ -3387,7 +3585,12 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
             case 'pinepaper_interchange': {
                 const input = InterchangeInputSchema.parse(args);
                 const code = codeGenerator.generateInterchange(input);
-                return executeOrGenerate(code, `Interchange: ${input.action}`, options, 'pinepaper_interchange');
+                const out = await executeOrGenerate(code, `Interchange: ${input.action}`, options, 'pinepaper_interchange');
+                // AN EXPORT IS A FILE (gate D7, 1.6.19): .lottie, GLB and the PNG-sequence
+                // zip came back as byte-index objects or inline data URLs, and a Lottie
+                // JSON can be large. Written out; the result names the path.
+                const ext = { export_lottie: 'json', export_dotlottie: 'lottie', export_glb: 'glb', export_png_sequence: 'zip', export_bvh: 'bvh' };
+                return ext[input.action] ? await writeResultDataToFile(out, ext[input.action]) : out;
             }
             case 'pinepaper_sound': {
                 const input = SoundInputSchema.parse(args);