@pinepaper.studio/mcp-server 1.6.17 → 1.6.19

package/dist/tools/handlers.js

@@ -5,8 +5,8 @@
  * Supports i18n for localized error and success messages.
  * Supports browser execution via Puppeteer.
  */
-import { codeGenerator, generateQueryMutationsCode } 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 { 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, 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';
@@ -85,13 +86,19 @@ export function getScreenshotMode() {
 // =============================================================================
 // EXPORT FILE SAVE HELPERS
 // =============================================================================
-function getExportDir() {
+export function getExportDir() {
     return process.env.PINEPAPER_EXPORT_DIR || join(tmpdir(), 'pinepaper-exports');
 }
 // 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', 'apng', 'pdf', 'wav', 'srt', 'vtt', 'scc', 'html5-ad', 'playable']);
+// Stills join them too. The threshold below is in CHARACTERS of base64, and a
+// 59 KB 1920x1080 PNG is ~79k of them: under the threshold, so it came back
+// inline, and over the token limit of the client reading it (a Halloween
+// look-frame session, 2026-09-29), while bigger PNGs saved to a file. Same
+// format, two shapes, decided by file size. An image is never useful as
+// base64 in a text result, so png/jpg/webp always save and name the path.
+export const ALWAYS_SAVE_FORMATS = new Set(['mp4', 'webm', 'gif', 'apng', 'pdf', 'wav', 'srt', 'vtt', 'scc', 'html5-ad', 'playable', 'png', 'jpg', 'webp']);
 // 500_000 was chosen against the bridge's limits, not the CALLER's. A pilot
 // session hit a 263K-character end_job result — comfortably under this, so it
 // was returned inline, and over the tool-result limit of the client reading
@@ -554,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',
@@ -570,7 +604,7 @@ function successResult(code, description) {
             text: `\n${description}`,
         });
     }
-    return { content };
+    return { content, _meta: { [CODE_META_KEY]: code } };
 }
 /**
  * A plain data answer.
@@ -583,6 +617,45 @@ 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
+ * a while, but nothing read them, so an agent kept using item ids from a
+ * scene that was gone (M6).
+ */
+function withSessionNote(out, r) {
+    if (!r.recovered)
+        return out;
+    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 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') {
+        try {
+            const obj = JSON.parse(first.text);
+            obj.session = { recovered: true, ...(r.relaunched ? { relaunched: true } : {}), ...(r.canvasReset !== undefined ? { canvasReset: r.canvasReset } : {}), note };
+            return { ...out, content: [{ type: 'text', text: JSON.stringify(obj, null, 2) }, ...out.content.slice(1)] };
+        }
+        catch {
+            return { ...out, content: [{ type: 'text', text: `${note}\n\n${first.text}` }, ...out.content.slice(1)] };
+        }
+    }
+    return out;
+}
 function executedResult(code, result, screenshot, description, report) {
     const resultObj = { success: true, result };
     if (description)
@@ -740,6 +813,204 @@ function handleValidationError(error, i18n) {
  *
  * Default is 'on_request' for optimal performance per best practices.
  */
+/** Page code: remember the id of every item on the canvas. */
+const MARK_ITEMS_BEFORE_RUN = `(function () {
+  if (typeof paper === 'undefined' || !paper.project) return { ok: false };
+  const ids = new Set();
+  paper.project.getItems({}).forEach(function (i) { ids.add(i.id); });
+  window.__ppPreRunIds = ids;
+  return { ok: true };
+})();`;
+/** Page code: remove every item that was not there at the mark, outermost first. */
+const REMOVE_ITEMS_CREATED_SINCE_MARK = `(function () {
+  const pre = window.__ppPreRunIds;
+  window.__ppPreRunIds = null;
+  if (!pre || typeof paper === 'undefined' || !paper.project) return { ok: false };
+  const fresh = paper.project.getItems({}).filter(function (i) { return !pre.has(i.id); });
+  const freshIds = new Set(fresh.map(function (i) { return i.id; }));
+  const tops = fresh.filter(function (i) { return !(i.parent && freshIds.has(i.parent.id)); });
+  let removed = 0;
+  tops.forEach(function (it) {
+    try { if (typeof app !== 'undefined' && typeof app.deleteItem === 'function' && app.deleteItem(it)) { removed++; return; } } catch (e) {}
+    try { if (it.parent) { it.remove(); removed++; } } catch (e) {}
+  });
+  const left = paper.project.getItems({}).filter(function (i) { return !pre.has(i.id); }).length;
+  try { if (paper.view) paper.view.update(); } catch (e) {}
+  return { ok: left === 0, removed: removed, left: left };
+})();`;
+/**
+ * Record which canvas items exist before agent-written code runs, so a failed
+ * run's leftovers can be told apart from the scene it started with. Returns
+ * false when the page could not be marked (the rollback is then skipped and
+ * the failure note says nothing about the scene it cannot vouch for).
+ */
+async function markItemsBeforeRun(controller) {
+    try {
+        const r = await controller.executeCode(MARK_ITEMS_BEFORE_RUN, false, { bypassGovernor: true });
+        return !!(r.success && r.result?.ok);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Remove what agent-written code created before it failed, and say so.
+ *
+ * A run stopped by the loop deadline after drawing 42 strokes left them on
+ * the canvas: a half-painted scene. Undo cannot fix that. The governor's one
+ * history entry only covers mutations that announce themselves, and raw
+ * `new paper.Path(...)` does not (measured: report.mutated false, 30 paths
+ * left behind). So the rollback is by identity instead: every item that was
+ * not on the canvas before the call goes, through app.deleteItem where the
+ * engine knows the item (registry, trackers) and item.remove() otherwise.
+ * Edits to items that already existed are NOT reverted; the note says so.
+ */
+export async function customCodeRollback(controller, error) {
+    let rolledBack = false;
+    let removed = 0;
+    let left = -1;
+    try {
+        const r = await controller.executeCode(REMOVE_ITEMS_CREATED_SINCE_MARK, false, { bypassGovernor: true });
+        const v = (r.result || {});
+        rolledBack = !!(r.success && v.ok);
+        removed = v.removed ?? 0;
+        left = typeof v.left === 'number' ? v.left : -1;
+    }
+    catch {
+        rolledBack = false;
+    }
+    const scene = rolledBack
+        ? (removed > 0
+            ? `The ${removed} item(s) this call created before it stopped were removed. Changes it made to items that already existed are not reverted.`
+            : 'This call created no items before it stopped. Changes it made to items that already existed are not reverted.')
+        : `Items this call created could not all be removed${left > 0 ? ` (${left} remain)` : ''}: check the canvas before continuing.`;
+    const how = /Synchronous execution exceeded|Loop budget exceeded/i.test(error || '')
+        ? ' This is execute_custom_code\'s per-call guard, not a limit on the scene: its loops may run about 4 s (and 2,000,000 iterations per loop) so the studio tab stays responsive. Split the work across several calls, each of which gets a fresh budget. For example, paint 10 strokes per call instead of 40 in one.'
+        : '';
+    return { rolledBack, note: scene + how };
+}
+/**
+ * pinepaper_brand_kit from_url: the product's real brand, read from its own
+ * site (see handlers/brand-intake.ts). Runs in the MCP server's browser, in an
+ * isolated context, so code mode cannot do it and says so.
+ */
+async function brandFromUrl(url, shots, options) {
+    const effectiveExecMode = options.executionMode ?? getExecutionMode();
+    if (effectiveExecMode === 'code' || !options.executeInBrowser) {
+        return errorResult(ErrorCodes.EXECUTION_ERROR, 'brand_kit from_url reads the site in the MCP server\'s browser, so it needs browser mode; it cannot run as generated code.', {}, { toolName: 'pinepaper_brand_kit' });
+    }
+    const controller = options.browserController || getBrowserController();
+    if (!controller.connected) {
+        try {
+            await controller.connect();
+        }
+        catch (e) {
+            return errorResult(ErrorCodes.BROWSER_NOT_CONNECTED, `could not start the browser: ${e instanceof Error ? e.message : String(e)}`, {}, { toolName: 'pinepaper_brand_kit' });
+        }
+    }
+    const host = (() => { try {
+        return new URL(url).hostname.replace(/[^a-z0-9.-]/gi, '_');
+    }
+    catch {
+        return 'site';
+    } })();
+    const outDir = join(getExportDir(), `brand-${host}-${Date.now()}`);
+    try {
+        const { intakeBrand } = await import('./handlers/brand-intake.js');
+        const r = await controller
+            .withIsolatedPage((page) => intakeBrand(page, url, outDir, shots));
+        const text = [
+            `Brand read from ${url}. Files in ${outDir}:`,
+            ...r.screenshots.map((f) => `- screenshot: ${f}`),
+            r.logo ? `- logo: ${r.logo.file} (from ${r.logo.source})` : '- logo: none found in the header, icons or og:image',
+            '',
+            'Review the proposed kit against the screenshots, then apply it with pinepaper_brand_kit { action: "apply", kit } (or "plan" first). Import the logo or a screenshot with pinepaper_import_image { url: <file> }.',
+            '',
+            JSON.stringify({ success: true, ...r }, null, 2),
+        ].join('\n');
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (e) {
+        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
+ * the rubric the agent scores it against. Code mode returns the code as usual.
+ */
+async function captureSheet(input, options) {
+    const code = codeGenerator.generateCaptureSheet(input);
+    const description = 'Contact sheet';
+    const effectiveExecMode = options.executionMode ?? getExecutionMode();
+    if (effectiveExecMode === 'code' || !options.executeInBrowser) {
+        return executeOrGenerate(code, description, options, 'pinepaper_capture_frames');
+    }
+    const controller = options.browserController || getBrowserController();
+    if (!controller.connected) {
+        try {
+            await controller.connect();
+        }
+        catch {
+            return executeOrGenerate(code, description, options, 'pinepaper_capture_frames');
+        }
+    }
+    // Frames wait for video seeks one at a time, so 48 of them can outlast the
+    // governor's 10 s default.
+    const run = await controller.executeCode(code, false, { governorTimeoutMs: 120_000 });
+    const value = (run.result ?? {});
+    if (!run.success || value.success === false || typeof value.dataUrl !== 'string') {
+        return errorResult(ErrorCodes.EXECUTION_ERROR, run.error || value.error || 'the contact sheet could not be made', { code, governorReport: run.report }, { toolName: 'pinepaper_capture_frames' });
+    }
+    const format = input.sheet?.format === 'png' ? 'png' : 'jpg';
+    const { filePath, fileSize } = await saveExportToFile(value.dataUrl, format, 'sheet');
+    const { dataUrl: _d, success: _s, ...facts } = value;
+    void _d;
+    void _s;
+    const result = { success: true, filePath, fileSize, format, ...facts, review: SHEET_RUBRIC };
+    return {
+        content: [{
+                type: 'text',
+                text: `Contact sheet saved: ${filePath} (${(fileSize / 1024).toFixed(1)} KB, ${String(facts.tiles)} tiles).\n`
+                    + 'Open the image and score it against review.criteria (1-10 each), then check review.checklist.\n\n'
+                    + JSON.stringify(result, null, 2),
+            }],
+    };
+}
 export async function executeOrGenerate(code, description, options, toolName, 
 /**
  * Values too large to live inside the generated code. Written to
@@ -801,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
@@ -880,18 +1151,33 @@ ${code}
     if (shouldTakeScreenshot) {
         tracker.startTimer(`${timerId}_screenshot`);
     }
-    const result = await controller.executeCode(code, shouldTakeScreenshot, stage ? { stage } : {});
+    // Agent-written code is rolled back when it fails part-way; a tool's own
+    // emitter is not (its verdict already describes what it left behind).
+    const rollbackOnFailure = toolName === 'pinepaper_execute_custom_code'
+        && await markItemsBeforeRun(controller);
+    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',
@@ -907,19 +1193,23 @@ ${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.
-        { code, errorCode: result.errorCode, governorReport: result.report }, {
+        {
+            code, errorCode: result.errorCode, governorReport: result.report,
+            ...(rollbackOnFailure ? await customCodeRollback(controller, result.error) : {}),
+        }, {
             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
@@ -933,12 +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, { code, result: result.result, governorReport: result.report }, { toolName, canvasState: canvasState || undefined });
+        return withTiming(errorResult(ErrorCodes.EXECUTION_ERROR, inner, {
+            code, result: result.result, governorReport: result.report,
+            ...(rollbackOnFailure ? await customCodeRollback(controller, inner) : {}),
+        }, { toolName, canvasState: canvasState || undefined }), timing);
+    }
+    // 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 executedResult(code, result.result, result.screenshot, description, result.report);
+    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.
@@ -1496,14 +1798,38 @@ 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');
             }
             case 'pinepaper_capture_frames': {
                 const input = CaptureFramesInputSchema.parse(args);
+                if (input.sheet)
+                    return captureSheet(input, options);
                 const code = codeGenerator.generateCaptureFrames(input);
-                const description = `Deterministic capture of ${input.times.length} frame(s)`;
+                const description = `Deterministic capture of ${(input.times ?? []).length} frame(s)`;
                 return executeOrGenerate(code, description, options, 'pinepaper_capture_frames');
             }
             case 'pinepaper_instantiate_ontology': {
@@ -1561,8 +1887,27 @@ 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')
+                    return brandFromUrl(input.url, input.screenshots ?? 3, options);
                 const code = codeGenerator.generateBrandKit(input);
                 return executeOrGenerate(code, `Brand kit: ${input.action}`, options, 'pinepaper_brand_kit');
             }
@@ -1820,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,
@@ -1845,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');
             }
@@ -1986,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': {
@@ -2007,8 +2361,13 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
                     return errorResult(ErrorCodes.BROWSER_NOT_CONNECTED, 'Not connected to PinePaper Studio. Call pinepaper_browser_connect first.');
                 }
                 try {
-                    // Refresh the page
-                    await controller.refreshPage();
+                    // Refresh the page (recovers a dead session first; M6)
+                    const refreshed = await controller.refreshPage();
+                    const sizeNote = refreshed.relaunched
+                        ? (refreshed.canvasSizeRestored
+                            ? `\n\nThe browser session had been lost, so the browser was relaunched. The canvas size was restored to ${refreshed.canvasSizeRestored.width}x${refreshed.canvasSizeRestored.height}.`
+                            : '\n\nThe browser session had been lost, so the browser was relaunched at the default canvas size: set the size again if you need another.')
+                        : '';
                     // Wait a moment for the page to stabilize
                     await new Promise(resolve => setTimeout(resolve, 2000));
                     // Take a screenshot to show the result
@@ -2020,7 +2379,7 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
 
 The canvas is now completely empty. The welcome template will not appear (it only shows for first-time visitors).
 
-You can now start creating new items on a clean canvas.`,
+You can now start creating new items on a clean canvas.${sizeNote}`,
                         },
                     ];
                     if (screenshot) {
@@ -2090,6 +2449,15 @@ You can now start creating new items on a clean canvas.`,
             // -----------------------------------------------------------------------
             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');
@@ -2300,7 +2668,19 @@ You can now start creating new items on a clean canvas.`,
                         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 */ }
                 }
@@ -2355,17 +2735,25 @@ You can now start creating new items on a clean canvas.`,
                         },
                         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`);
                     }
@@ -2484,11 +2872,19 @@ You can now start creating new items on a clean canvas.`,
             // 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) {
@@ -2560,6 +2956,7 @@ You can now start creating new items on a clean canvas.`,
                                     query: input.query,
                                     repository: input.repository || 'all',
                                     count: resultsWithContent.length,
+                                    sources,
                                     includeSvgContent: input.includeSvgContent || false,
                                     attributionRequired: requiresAttribution.length > 0,
                                     attributionNotice,
@@ -2620,6 +3017,15 @@ You can now start creating new items on a clean canvas.`,
                         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
@@ -3150,10 +3556,18 @@ You can now start creating new items on a clean canvas.`,
                                 `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');
                     }
                 }
@@ -3171,7 +3585,12 @@ You can now start creating new items on a clean canvas.`,
             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);