@pinepaper.studio/mcp-server 1.6.16 → 1.6.18

package/dist/tools/handlers.js

@@ -5,8 +5,8 @@
  * Supports i18n for localized error and success messages.
  * 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, CharacterInputSchema, GameInputSchema, World3DInputSchema, BrandKitInputSchema, ComponentInputSchema, ArtboardInputSchema, CommentInputSchema, ProvenanceInputSchema, SceneDiffInputSchema, AudioBeatsInputSchema, TemplateParamsInputSchema, RenderBatchInputSchema, AccessibilityCheckInputSchema, 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, 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
@@ -47,6 +47,7 @@ import { ontologyHandlers } from './handlers/ontology.js';
 import * as designSystems from '../design/design-systems.js';
 import { exportHandlers } from './handlers/export.js';
 import { generateHandlers } from './handlers/generate.js';
+import { beatHandlers } from './handlers/beats.js';
 import { planCharacter, generateCharacterCode } from './handlers/character.js';
 import { buildZip } from '../utils/zip.js';
 import { buildScc } from '../utils/scc.js';
@@ -66,6 +67,7 @@ function getDomainHandlers() {
         ontologyHandlers,
         exportHandlers,
         generateHandlers,
+        beatHandlers,
     ];
 }
 /**
@@ -83,13 +85,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
@@ -581,6 +589,33 @@ function successResult(code, description) {
 function dataResult(value) {
     return { content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] };
 }
+/**
+ * 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 page had reloaded 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)
@@ -738,6 +773,170 @@ 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' });
+    }
+}
+/**
+ * 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
@@ -878,6 +1077,10 @@ ${code}
     if (shouldTakeScreenshot) {
         tracker.startTimer(`${timerId}_screenshot`);
     }
+    // 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 result = await controller.executeCode(code, shouldTakeScreenshot, stage ? { stage } : {});
     const browserDuration = tracker.endTimer(`${timerId}_browser_execution`);
     tracker.recordMetric({
@@ -914,7 +1117,10 @@ ${code}
         return 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,
         });
@@ -934,9 +1140,12 @@ ${code}
     const inner = innerFailure(result.result);
     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 errorResult(ErrorCodes.EXECUTION_ERROR, inner, {
+            code, result: result.result, governorReport: result.report,
+            ...(rollbackOnFailure ? await customCodeRollback(controller, inner) : {}),
+        }, { toolName, canvasState: canvasState || undefined });
     }
-    return executedResult(code, result.result, result.screenshot, description, result.report);
+    return withSessionNote(executedResult(code, result.result, result.screenshot, description, result.report), result);
 }
 /**
  * The emitted code's own verdict, when it reported one and it was a failure.
@@ -1093,6 +1302,8 @@ const IGNORED_ARGUMENT_SCHEMAS = {
     // common slip here (round 7 retest, 1.63).
     pinepaper_create_item: CreateItemInputSchema,
     pinepaper_modify_item: ModifyItemInputSchema,
+    // Its options live in `options` / `spec`; a key beside them was dropped.
+    pinepaper_sound: SoundInputSchema,
 };
 const IGNORED_ARGUMENT_HINTS = {
     pinepaper_create_item: Object.fromEntries(['width', 'height', 'radius', 'color', 'fillColor', 'strokeColor', 'strokeWidth', 'content', 'fontSize', 'fontFamily', 'opacity', 'rotation', 'x', 'y']
@@ -1498,8 +1709,10 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
             }
             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': {
@@ -1559,6 +1772,8 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
             // ─── 1.6.4: agent surface for the Tier-2 engine features ───
             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');
             }
@@ -1615,6 +1830,11 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
                 const code = codeGenerator.generateAudioBeats({ ...input, source: staged ? `__ppStage:${stageKey}` : source });
                 return executeOrGenerate(code, `Audio: ${input.action}`, options, 'pinepaper_audio_beats', staged ? { [stageKey]: source } : undefined);
             }
+            case 'pinepaper_query_mutations': {
+                const input = QueryMutationsInputSchema.parse(args);
+                const code = generateQueryMutationsCode(input.itemId, input.property, input.range, input.fps);
+                return executeOrGenerate(code, `Keyframe series: ${input.itemId}`, options, 'pinepaper_query_mutations');
+            }
             case 'pinepaper_accessibility_check': {
                 const input = AccessibilityCheckInputSchema.parse(args);
                 const code = codeGenerator.generateAccessibilityCheck(input);
@@ -1632,9 +1852,23 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
                 const report = {};
                 const page = parseCssColor(m.page);
                 if (m.texts) {
+                    // Samples over time: each text judged at every moment it showed,
+                    // reported at its worst. Nothing visible at any sampled time is not
+                    // a pass — it was a vacuous one (round 12, 12.9).
                     const c = checkContrast(m.texts, page);
-                    report.contrast = { pass: c.failing.length === 0, checked: c.checked, failing: c.failing, skipped: c.skipped,
-                        method: 'WCAG 1.4.3 AA (4.5:1, 3:1 for large text) between each text fill and the solid fill of the topmost item under its centre, or the page background' + (c.pageAssumed ? ' (none set, so white was assumed)' : '') + '. Approximate: text over a photo or gradient is not judged.' };
+                    const worst = new Map();
+                    for (const f of c.failing) {
+                        const prev = worst.get(f.id);
+                        if (!prev || f.ratio < prev.ratio)
+                            worst.set(f.id, f);
+                    }
+                    const ids = new Set(m.texts.filter((t) => t.fill).map((t) => t.id));
+                    const skippedIds = [...new Map(c.skipped.map((x) => [x.id, x])).values()];
+                    report.contrast = ids.size === 0
+                        ? { pass: null, checked: 0, sampledTimes: m.sampledTimes, skipped: skippedIds,
+                            note: 'no text was visible at any sampled time (0 s, each text\'s lifetime, keyframe times, every second of duration), so contrast was not checked — pass the scene duration, or check a frame where the text shows.' }
+                        : { pass: worst.size === 0, checked: ids.size, sampledTimes: m.sampledTimes, failing: [...worst.values()], skipped: skippedIds,
+                            method: 'WCAG 1.4.3 AA (4.5:1, 3:1 for large text) between each text fill and the solid fill of the topmost item under its centre, or the page background' + (c.pageAssumed ? ' (none set, so white was assumed)' : '') + ', at every sampled time the text showed; the worst is reported. Approximate: text over a photo or gradient is not judged.' };
                 }
                 if (m.flashUnavailable)
                     report.flash = { checked: false, reason: m.flashUnavailable };
@@ -1644,7 +1878,9 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
                         frames: m.series.length, fps: m.fps,
                         method: 'WCAG 2.3.1 general flash: opposing luminance changes of >= 10% with the darker state below 0.8, over a 3 x 3 grid; more than 3 flashes in any second fails. A heuristic screen, not a certified PSE test (red flashes are not checked).' };
                 }
-                const pass = Object.values(report).every((r) => r.pass !== false);
+                // A check that could not run (pass: null) is not a pass.
+                const verdicts = Object.values(report).map((r) => r.pass);
+                const pass = verdicts.some((v) => v === false) ? false : verdicts.some((v) => v === null) ? null : true;
                 return dataResult({ success: true, pass, ...report });
             }
             case 'pinepaper_render_batch': {
@@ -1982,8 +2218,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
@@ -1995,7 +2236,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) {
@@ -2904,6 +3145,16 @@ You can now start creating new items on a clean canvas.`,
                 }
             }
             case 'pinepaper_agent_export': {
+                // Formats a DOOH / projection deliverable asks for that no browser
+                // encoder can make (round 12, 12.12): named, with the route that works,
+                // not a generic enum error.
+                const askedFormat = String(args.format ?? '').toLowerCase();
+                if (/^(prores|prores4444|prores422|hap|hapq|hap-alpha|dnxhd|dnxhr|cineform)$/.test(askedFormat)) {
+                    return errorResult(ErrorCodes.INVALID_PARAMS, `${askedFormat} is not supported: the studio encodes in the browser, which has no ${askedFormat.startsWith('hap') ? 'HAP' : askedFormat.startsWith('prores') ? 'ProRes' : askedFormat.toUpperCase()} encoder. `
+                        + 'Export a lossless png sequence (pinepaper_interchange export_png_sequence, transparent if you need alpha) and convert it, e.g. '
+                        + (askedFormat.startsWith('hap') ? 'ffmpeg -i frame_%05d.png -c:v hap -format hap_q out.mov' : 'ffmpeg -i frame_%05d.png -c:v prores_ks -profile:v 4444 out.mov')
+                        + ' — or webm / apng for alpha in the browser.');
+                }
                 const input = AgentExportInputSchema.parse(args);
                 const code = codeGenerator.generateAgentExport(input);
                 const description = `Smart export for ${input.platform} as ${input.format || 'auto'}`;