@pinepaper.studio/mcp-server 1.6.16 → 1.6.18

package/README.de.md

@@ -19,7 +19,7 @@
 
 Der PinePaper MCP-Server lässt KI-Assistenten über das Model Context Protocol Grafiken in [PinePaper Studio](https://pinepaper.studio) erstellen und animieren. Funktioniert mit jeder KI, die MCP-Tool-Aufrufe unterstützt (Claude, GPT, Gemini, lokale Modelle usw.).
 
-Der Server bietet **157 Tools**: Zeichnen, Animation, Diagramme, Karten, Typografie, Physik, Bildbearbeitung, Datenvisualisierung und Export:
+Der Server bietet **159 Tools**: Zeichnen, Animation, Diagramme, Karten, Typografie, Physik, Bildbearbeitung, Datenvisualisierung und Export:
 
 - Text, Formen, Geometrie und komplexe Grafiken erstellen
 - Mit deklarativen **Relationen** animieren statt mit Keyframes

package/README.es.md

@@ -19,7 +19,7 @@
 
 El servidor MCP de PinePaper permite a los asistentes de IA crear y animar gráficos en [PinePaper Studio](https://pinepaper.studio) a través del Model Context Protocol. Funciona con cualquier IA que soporte llamadas a herramientas MCP (Claude, GPT, Gemini, modelos locales, etc.).
 
-Expone **157 herramientas**: dibujo, animación, diagramas, mapas, tipografía, física, edición de imágenes, visualización de datos y exportación:
+Expone **159 herramientas**: dibujo, animación, diagramas, mapas, tipografía, física, edición de imágenes, visualización de datos y exportación:
 
 - Crear texto, formas, geometría y gráficos complejos
 - Animar con **relaciones** declarativas en lugar de fotogramas clave

package/README.fr.md

@@ -19,7 +19,7 @@
 
 Le serveur MCP PinePaper permet aux assistants IA de créer et d'animer des graphiques dans [PinePaper Studio](https://pinepaper.studio) via le Model Context Protocol. Compatible avec toute IA gérant les appels d'outils MCP (Claude, GPT, Gemini, modèles locaux, etc.).
 
-Il expose **157 outils** : dessin, animation, diagrammes, cartes, typographie, physique, retouche d'image, visualisation de données et export :
+Il expose **159 outils** : dessin, animation, diagrammes, cartes, typographie, physique, retouche d'image, visualisation de données et export :
 
 - Créer du texte, des formes, de la géométrie et des graphiques complexes
 - Animer avec des **relations** déclaratives plutôt que des images clés

package/README.hi.md

@@ -19,7 +19,7 @@
 
 PinePaper MCP सर्वर AI असिस्टेंट्स को Model Context Protocol के ज़रिए [PinePaper Studio](https://pinepaper.studio) में ग्राफ़िक्स बनाने और एनिमेट करने देता है। MCP टूल कॉलिंग वाले किसी भी AI (Claude, GPT, Gemini, लोकल मॉडल आदि) के साथ काम करता है।
 
-सर्वर **157 टूल** देता है — ड्रॉइंग, एनिमेशन, डायग्राम, नक्शे, टाइपोग्राफ़ी, फिज़िक्स, इमेज एडिटिंग, डेटा विज़ुअलाइज़ेशन और एक्सपोर्ट:
+सर्वर **159 टूल** देता है — ड्रॉइंग, एनिमेशन, डायग्राम, नक्शे, टाइपोग्राफ़ी, फिज़िक्स, इमेज एडिटिंग, डेटा विज़ुअलाइज़ेशन और एक्सपोर्ट:
 
 - टेक्स्ट, आकृतियाँ, ज्यामिति और जटिल ग्राफ़िक्स बनाना
 - कीफ़्रेम की जगह व्यवहार बताने वाले **रिलेशन** से एनिमेशन

package/README.ja.md

@@ -19,7 +19,7 @@
 
 PinePaper MCP サーバーは、MCP 経由で AI アシスタントが [PinePaper Studio](https://pinepaper.studio) 上にグラフィックを作成・アニメーションさせるためのサーバーです。MCP ツールコールに対応した AI（Claude、GPT、Gemini、ローカルモデルなど）で動作します。
 
-**157 個のツール**を提供 — 描画・アニメーション・図・地図・タイポグラフィ・物理・画像編集・データ可視化・エクスポート：
+**159 個のツール**を提供 — 描画・アニメーション・図・地図・タイポグラフィ・物理・画像編集・データ可視化・エクスポート：
 
 - テキスト、図形、ジオメトリ、複雑なグラフィックの作成
 - キーフレームではなく、ふるまいを宣言する**リレーション**でアニメーション

package/README.ko.md

@@ -19,7 +19,7 @@
 
 PinePaper MCP 서버는 AI 어시스턴트가 MCP를 통해 [PinePaper Studio](https://pinepaper.studio)에서 그래픽을 만들고 애니메이션하게 해줍니다. MCP 툴 콜을 지원하는 모든 AI(Claude, GPT, Gemini, 로컬 모델 등)와 호환됩니다.
 
-**157개의 툴** 제공 — 드로잉, 애니메이션, 다이어그램, 지도, 타이포그래피, 물리, 이미지 편집, 데이터 시각화, 내보내기:
+**159개의 툴** 제공 — 드로잉, 애니메이션, 다이어그램, 지도, 타이포그래피, 물리, 이미지 편집, 데이터 시각화, 내보내기:
 
 - 텍스트·도형·기하·복잡한 그래픽 생성
 - 키프레임 대신 행동을 선언하는 **릴레이션**으로 애니메이션

package/README.md

@@ -30,7 +30,7 @@
 
 PinePaper MCP Server enables AI assistants to create and animate graphics in [PinePaper Studio](https://pinepaper.studio) via the Model Context Protocol (MCP). Works with any AI that supports MCP tool calling (Claude, GPT, Gemini, local models, etc.).
 
-The server exposes **157 tools** across drawing, animation, diagrams, maps, typography, physics, image editing, data visualization, and export. Using natural language, you can:
+The server exposes **159 tools** across drawing, animation, diagrams, maps, typography, physics, image editing, data visualization, and export. Using natural language, you can:
 
 - Create geometric shapes, text collages, diagrams, and data charts
 - Apply 37+ character-level text effects and 28+ vertex deformation presets
@@ -41,7 +41,7 @@ The server exposes **157 tools** across drawing, animation, diagrams, maps, typo
 
 ## Running it: local or hosted
 
-**Local is free and complete.** Every one of the 157 tools works when you run
+**Local is free and complete.** Every one of the 159 tools works when you run
 this server yourself. There is no reduced tier and nothing held back.
 
 What it needs:
@@ -246,6 +246,142 @@ If you do not want an agent executing anything, `code` mode is a first-class pat
 - Puppeteer mode launches Chrome with `--no-sandbox` and `--disable-setuid-sandbox`. That is routine for headless automation and it does weaken Chrome's own process sandbox. If that matters where you are running it, use `code` mode or put the server in a container.
 - Puppeteer itself is an **optional** peer dependency, kept out of the default tree precisely because a headless browser plus an install script is what scanners flag hardest. Install it only if you want the executing mode.
 
+## What's new in 1.6.18
+
+### New: spring easings, the standard easing set, and custom curves
+
+Keyframes take three spring easings: `spring` (settles with no overshoot),
+`springSnappy` (quick, one small overshoot) and `springPlayful` (bouncy, a few
+visible wobbles).
+
+The standard easings are here too: sine, quad, cubic, quart, quint, expo,
+circ and back as `easeIn…`, `easeOut…` and `easeInOut…` (for example
+`easeOutExpo`, `easeInOutQuart`), plus in and out bounce and elastic.
+`pinepaper_get_available_easings` lists every name.
+
+`pinepaper_keyframe_animate` and `pinepaper_camera_animate` also take a custom
+cubic-bezier `[x1, y1, x2, y2]`: x within 0..1, y may go outside it for
+overshoot.
+
+Every easing renders exactly in video, GIF and APNG. Lottie and CSS get the
+closest single curve, so `springPlayful` loses its wobble there and the in-out
+quart, quint, expo and circ curves are within a few percent.
+
+### New: look at your own animation
+
+`pinepaper_capture_frames` takes `sheet`: many frames tiled into one small
+image, saved to a file, with a rubric to score it against (hook, phone
+readability, motion, variety, composition, brand, sound sync). Choose the
+frames by time, every N seconds, a strip around a moment, or the loop's last
+frame beside its first. Tiles are 360 px wide by default, the width of a
+phone.
+
+### New: make one like this
+
+`pinepaper_media` takes `analyze_reference`: give it an uploaded reference
+video and it measures the format: where it cuts, how long each shot runs,
+each shot's colours, how fast it opens, and its beat. `remake_from_reference`
+then builds a new piece on that structure in your own words. Nothing of the
+reference's footage, words or sound is copied.
+
+### New: start from the real brand
+
+`pinepaper_brand_kit` takes `from_url`: give it a product's site and it saves
+screenshots and the logo, and proposes a brand kit from the colours and fonts
+the site actually uses, ready to review and apply. The site is read in a
+separate browser context; your canvas is not touched.
+
+### New: watercolour, oil paint and cut paper
+
+`pinepaper_design_medium` takes `apply`: render any shape in watercolour, oil
+paint, cut paper, thread or hatching, with that medium's own options. A medium
+the studio cannot make, or one that is a brush rather than a fill, is refused
+with the reason.
+
+### New: motion blur
+
+`pinepaper_agent_export` takes `motionBlur` for MP4 and WebM: each frame is
+rendered several times across the shutter and averaged, so fast movement
+smears the way it does on camera instead of strobing. It multiplies render
+time; `estimateOnly` reports by how much before you commit to it.
+
+### Changed: plan generations before paying for them
+
+`pinepaper_generate` and `pinepaper_generate_estimate` now tell agents to plan
+the whole timeline and price the whole plan before the first paid call, to
+reuse images already generated, and to pick video lengths the model supports
+rather than generating long and cropping. `pinepaper_beat_cuts` treats a
+generated song as the backbone of the edit, used whole.
+
+### Fixed
+
+- The scene validator no longer flags valid easings as unknown.
+- `pinepaper_agent_export` always saves PNG, JPG and WebP to a file and
+  returns its path. Small images used to come back inline as base64, which
+  could exceed a client's response limit.
+- `pinepaper_execute_custom_code`: when the code fails part-way, the items it
+  created are removed, so the scene is not left half-built. The error says
+  what was removed. Edits to items that already existed are not reverted. The
+  4-second loop limit is this tool's, per call: split long work across several
+  calls.
+- `pinepaper_design_medium` `apply_thread`: the spine points format is
+  documented (`{x, y}` or `[x, y]`).
+- `pinepaper_world3d`: colours take hex (`"#03050c"`) everywhere: the world's
+  sky, fog, light and ground colours, and material and light colours. A
+  refused `configure` now says why, naming the key. `ground_height` takes
+  `{x, z}`. `create` lists the configurable parameters by name.
+- A browser session lost while idle recovers by itself: `pinepaper_refresh_page`
+  and every other tool relaunch the browser when no page answers, restore the
+  canvas size, and say in the result that the canvas was reset.
+- `pinepaper_world3d` `extrude_path` takes `upright` (stand a drawing up, like
+  a sign) and `placement` (`centered`, the default, stands the mesh on the
+  ground at the point you give). JPG and WebP stills of a 3D world scene show
+  the world rather than a white frame.
+
+## What's new in 1.6.17
+
+### New: tell an agent "at 4 s, make it orange"
+
+`pinepaper_modify_item` takes `atTime`: the change is written as a keyframe at
+that moment, the same as dragging with auto-key on, eased from the previous
+value and without disturbing the rest of the animation.
+`pinepaper_query_mutations` shows a property's values over time.
+
+### New: cuts on the beat
+
+`pinepaper_beat_cuts` analyses a music track, fits a beat grid and returns cut
+points on every beat, every bar or every N beats — and can split a clip at each.
+When the tempo is uncertain it says so and lists the likely alternatives;
+`bpm` or `bpmHint` settles it.
+
+### New: exact frame counts, and larger canvases
+
+- `pinepaper_agent_export` takes `frames` for an exact frame count (a duration
+  rounds up), for segments that must line up.
+- Canvases up to 16384 px per side, for digital out-of-home and projection;
+  above 8192 the result notes that Safari and iOS may not manage it.
+- `pinepaper_import_image` takes `maxEdge` (or `'native'`) and `nativeSize`, and
+  says when the studio stored an image smaller than its source.
+- `pinepaper_media` `upload_video` takes `fit` (`contain`, `cover`, `none`), and
+  `scale` is documented as relative to it.
+
+### Changed: exports say more about what they produced
+
+- When an MP4 cannot be made at the requested size, the file is named by what it
+  is (WebM) and a warning says why.
+- A video whose animation did not play, or whose encoder froze, is flagged.
+- Asking for ProRes or HAP explains the route that works (a PNG sequence).
+- Frame captures, region stills and flash checks wait for video on screen, and
+  report whether they could.
+- The engine's structured warnings reach the caller whole.
+
+### Fixed
+
+- `pinepaper_accessibility_check` judged text only at the current playhead, so
+  timed captions could pass unchecked; it now samples the timeline, and says
+  when no text was visible rather than passing.
+- `pinepaper_agent_export` accepts `fps` and `scale` for APNG.
+
 ## What's new in 1.6.16
 
 ### New: video editing on the timeline
@@ -1226,7 +1362,7 @@ Fourteen new tools (121 → 135) and new actions across the surface — the rele
 
 ## Toolkits & Token Budget
 
-157 tools is a lot of context. The server ships a **toolkit** system that serves only the tools a given client needs, plus a **verbosity** system that controls how long each tool description is.
+159 tools is a lot of context. The server ships a **toolkit** system that serves only the tools a given client needs, plus a **verbosity** system that controls how long each tool description is.
 
 **Toolkit profiles** (`PINEPAPER_TOOLKIT`):
 
@@ -1431,7 +1567,7 @@ Generate instruction/code pairs for LLM fine-tuning:
 
 ## Tools Reference
 
-All 157 tools, grouped by the tag used for toolkit filtering.
+All 159 tools, grouped by the tag used for toolkit filtering.
 
 ### Canvas (`canvas`)
 | Tool | Description |
@@ -1653,6 +1789,8 @@ All 157 tools, grouped by the tag used for toolkit filtering.
 | `pinepaper_analyze_design` | Analyze design quality |
 | `pinepaper_validate_design` | Validate against design rules |
 | `pinepaper_validate` | General validation |
+| `pinepaper_beat_cuts` | Cut points on the music's beats or bars; split a clip at each |
+| `pinepaper_query_mutations` | A property's keyframe series over time |
 | `pinepaper_accessibility_check` | Text contrast and flashing (WCAG), as a heuristic screen |
 | `pinepaper_validate_scene` | Validate scene integrity |
 | `pinepaper_instantiate_ontology` | Compile a pp: design graph into a scene |

package/README.pt-BR.md

@@ -19,7 +19,7 @@
 
 O servidor MCP do PinePaper permite que assistentes de IA criem e animem gráficos no [PinePaper Studio](https://pinepaper.studio) via Model Context Protocol. Funciona com qualquer IA que suporte chamadas de ferramenta MCP (Claude, GPT, Gemini, modelos locais etc.).
 
-São **157 ferramentas**: desenho, animação, diagramas, mapas, tipografia, física, edição de imagens, visualização de dados e exportação:
+São **159 ferramentas**: desenho, animação, diagramas, mapas, tipografia, física, edição de imagens, visualização de dados e exportação:
 
 - Criar texto, formas, geometria e gráficos complexos
 - Animar com **relações** declarativas em vez de keyframes

package/README.zh-CN.md

@@ -19,7 +19,7 @@
 
 PinePaper MCP 服务器让 AI 助手通过 MCP 协议在 [PinePaper Studio](https://pinepaper.studio) 中创建和驱动图形动画。兼容任何支持 MCP 工具调用的 AI（Claude、GPT、Gemini、本地模型等）。
 
-服务器提供 **157 个工具**，覆盖绘图、动画、图表、地图、排版、物理、图像编辑、数据可视化与导出：
+服务器提供 **159 个工具**，覆盖绘图、动画、图表、地图、排版、物理、图像编辑、数据可视化与导出：
 
 - 创建文本、形状、几何图形与复杂图稿
 - 用行为驱动的**关系（relations）**做动画，而不是逐帧关键帧

package/dist/browser/puppeteer-controller.d.ts

@@ -4,6 +4,7 @@
  * Controls a real browser instance running PinePaper Studio.
  * Executes code directly via page.evaluate() and provides screenshots.
  */
+import type { Page } from 'puppeteer';
 /**
  * What a navigation waits for. Puppeteer's own union, spelled out here so the
  * env var can be validated against it without importing puppeteer — which is
@@ -123,6 +124,16 @@ export interface ExecuteResult {
      * keep referencing item ids from before the reload. undefined = unknown.
      */
     canvasReset?: boolean;
+    /**
+     * Set alongside `recovered` when no live tab could be re-bound and the
+     * browser was RELAUNCHED: the scene is gone for certain (canvasReset true).
+     */
+    relaunched?: boolean;
+    /** The canvas size put back after a relaunch, when one was known. */
+    canvasSizeRestored?: {
+        width: number;
+        height: number;
+    };
 }
 /**
  * Is PinePaper Studio actually usable? Evaluated IN THE PAGE, so it closes over
@@ -182,6 +193,28 @@ export declare class PinePaperBrowserController {
      * Check if connected to browser
      */
     get connected(): boolean;
+    /**
+     * The studio's video export, if one is running: its 0..100 progress. Read
+     * concurrently with the call that started it (the export awaits between
+     * frames, so a second evaluate gets a turn). null when nothing is exporting
+     * or the page cannot be read.
+     */
+    exportStatus(): Promise<{
+        percent: number;
+    } | null>;
+    /**
+     * Stop a running video export (VideoExporter.cancel: closes the encoders and
+     * the muxer). For a cancelled MCP request, so the studio does not keep
+     * rendering minutes of video nobody will receive. True if one was stopped.
+     */
+    cancelExport(): Promise<boolean>;
+    /**
+     * Run `fn` on a page in a fresh, ISOLATED browser context (its own cookies
+     * and storage), closed afterwards. For reading a site that is not the
+     * studio (brand intake): the studio tab, and the canvas in it, is never
+     * navigated away, and the site's cookies never mix with the studio's.
+     */
+    withIsolatedPage<T>(fn: (page: Page) => Promise<T>): Promise<T>;
     /**
      * Get current studio URL (always includes agent parameters for MCP server)
      */
@@ -229,6 +262,20 @@ export declare class PinePaperBrowserController {
      * @returns true when a responsive page was re-bound.
      */
     private reacquirePage;
+    /**
+     * The last canvas size seen on a healthy page. A relaunched browser comes
+     * up at the studio's default (800x600), so without this a session that
+     * died idle came back at the wrong size, silently (M6, 2026-10-02).
+     */
+    private lastCanvasSize;
+    private rememberCanvasSize;
+    /**
+     * Get a working page back after a stale-frame error. First re-bind a live
+     * tab (the scene may survive); if none answers, as after days idle when
+     * every frame is detached, relaunch ONCE and put the canvas size back.
+     * 'relaunched' means the scene is gone. false means even that failed.
+     */
+    private recoverSession;
     /** Number of registry items currently on the canvas, or null if unknown. */
     private canvasItemCount;
     /**
@@ -255,7 +302,20 @@ export declare class PinePaperBrowserController {
      * Refresh the page and wait for PinePaper to be ready again.
      * This is the most reliable way to get a clean canvas.
      */
-    refreshPage(): Promise<void>;
+    /**
+     * Reload the studio. The tool whose job is recovery could not recover: on a
+     * detached frame, page.reload() threw the same "detached Frame" error as
+     * every other call (M6, after ~2 days idle). A stale page is now recovered
+     * first: re-bound and reloaded, or the browser relaunched at the remembered
+     * canvas size. The return says which, so the caller knows the scene is gone.
+     */
+    refreshPage(): Promise<{
+        relaunched?: boolean;
+        canvasSizeRestored?: {
+            width: number;
+            height: number;
+        };
+    }>;
     /**
      * Check if PinePaper API is available
      */

package/dist/browser/puppeteer-controller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"puppeteer-controller.d.ts","sourceRoot":"","sources":["../../src/browser/puppeteer-controller.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"puppeteer-controller.d.ts","sourceRoot":"","sources":["../../src/browser/puppeteer-controller.ts"],"names":[],"mappings":"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"}

package/dist/browser/puppeteer-controller.js

@@ -4,6 +4,7 @@
  * Controls a real browser instance running PinePaper Studio.
  * Executes code directly via page.evaluate() and provides screenshots.
  */
+import { mcpLog } from '../utils/mcp-log.js';
 import { LAZY_HEAVY_SUBSYSTEMS, LAZY_HEAVY_CLASSES, ENGINE_SURFACE } from '../tools/engine-surface.js';
 export const PAGE_WAIT_UNTIL = ['load', 'domcontentloaded', 'networkidle0', 'networkidle2'];
 /**
@@ -157,6 +158,69 @@ export class PinePaperBrowserController {
     get connected() {
         return this.isConnected && this.page !== null;
     }
+    /**
+     * The studio's video export, if one is running: its 0..100 progress. Read
+     * concurrently with the call that started it (the export awaits between
+     * frames, so a second evaluate gets a turn). null when nothing is exporting
+     * or the page cannot be read.
+     */
+    async exportStatus() {
+        if (!this.page || !this.isConnected)
+            return null;
+        try {
+            return await this.page.evaluate(() => {
+                const app = window.app || window.PinePaper;
+                const ve = app && app.exportEngine && app.exportEngine.videoExporter;
+                if (!ve || !ve.isRecording)
+                    return null;
+                const p = Number(ve.progress);
+                return { percent: Number.isFinite(p) ? Math.max(0, Math.min(100, p)) : 0 };
+            });
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Stop a running video export (VideoExporter.cancel: closes the encoders and
+     * the muxer). For a cancelled MCP request, so the studio does not keep
+     * rendering minutes of video nobody will receive. True if one was stopped.
+     */
+    async cancelExport() {
+        if (!this.page || !this.isConnected)
+            return false;
+        try {
+            return await this.page.evaluate(async () => {
+                const app = window.app || window.PinePaper;
+                const ve = app && app.exportEngine && app.exportEngine.videoExporter;
+                if (!ve || !ve.isRecording || typeof ve.cancel !== 'function')
+                    return false;
+                await ve.cancel();
+                return true;
+            });
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Run `fn` on a page in a fresh, ISOLATED browser context (its own cookies
+     * and storage), closed afterwards. For reading a site that is not the
+     * studio (brand intake): the studio tab, and the canvas in it, is never
+     * navigated away, and the site's cookies never mix with the studio's.
+     */
+    async withIsolatedPage(fn) {
+        if (!this.browser)
+            throw new Error('Not connected to browser');
+        const context = await this.browser.createBrowserContext();
+        try {
+            const page = await context.newPage();
+            return await fn(page);
+        }
+        finally {
+            await context.close().catch(() => { });
+        }
+    }
     /**
      * Get current studio URL (always includes agent parameters for MCP server)
      */
@@ -340,6 +404,68 @@ export class PinePaperBrowserController {
             return false;
         }
     }
+    /**
+     * The last canvas size seen on a healthy page. A relaunched browser comes
+     * up at the studio's default (800x600), so without this a session that
+     * died idle came back at the wrong size, silently (M6, 2026-10-02).
+     */
+    lastCanvasSize = null;
+    async rememberCanvasSize() {
+        if (!this.page)
+            return;
+        try {
+            const size = await this.page.evaluate(() => {
+                const app = window.app || window.PinePaper;
+                const s = app && typeof app.getCanvasSize === 'function' ? app.getCanvasSize() : null;
+                return s && s.width > 0 && s.height > 0 ? { width: s.width, height: s.height } : null;
+            });
+            if (size)
+                this.lastCanvasSize = size;
+        }
+        catch { /* keep the last known size */ }
+    }
+    /**
+     * Get a working page back after a stale-frame error. First re-bind a live
+     * tab (the scene may survive); if none answers, as after days idle when
+     * every frame is detached, relaunch ONCE and put the canvas size back.
+     * 'relaunched' means the scene is gone. false means even that failed.
+     */
+    async recoverSession() {
+        if (await this.reacquirePage())
+            return { kind: 'reacquired' };
+        const size = this.lastCanvasSize;
+        try {
+            await this.disconnect();
+            await this.connect();
+        }
+        catch (e) {
+            console.error('[PinePaper] Relaunch after a lost session failed:', e instanceof Error ? e.message : e);
+            mcpLog('error', { event: 'session_lost', message: 'The browser session was lost and could not be relaunched: call pinepaper_browser_disconnect, then pinepaper_browser_connect.' });
+            return false;
+        }
+        if (!this.page || !this.isConnected)
+            return false;
+        let restored;
+        if (size) {
+            try {
+                const ok = await this.page.evaluate((w, h) => {
+                    const app = window.app || window.PinePaper;
+                    if (!app || typeof app.setCanvasSize !== 'function')
+                        return false;
+                    app.setCanvasSize(w, h);
+                    return true;
+                }, size.width, size.height);
+                if (ok) {
+                    restored = size;
+                    this.lastCanvasSize = size;
+                }
+            }
+            catch { /* reported as not restored */ }
+        }
+        console.error('[PinePaper] Session lost; browser relaunched' + (restored ? ` at ${restored.width}x${restored.height}` : ''));
+        mcpLog('warning', { event: 'session_relaunched', message: 'The browser session was lost; the browser was relaunched and the canvas is empty.', ...(restored ? { canvasSizeRestored: restored } : {}) });
+        return { kind: 'relaunched', ...(restored ? { canvasSizeRestored: restored } : {}) };
+    }
     /** Number of registry items currently on the canvas, or null if unknown. */
     async canvasItemCount() {
         if (!this.page)
@@ -538,6 +664,8 @@ export class PinePaperBrowserController {
             if (takeScreenshot && result.success) {
                 screenshot = await this.takeScreenshot();
             }
+            if (result.success)
+                await this.rememberCanvasSize();
             return {
                 ...result,
                 screenshot,
@@ -548,7 +676,8 @@ export class PinePaperBrowserController {
             // so every later call hit the same error until the caller manually
             // disconnected — and disconnect+connect relaunches the browser, losing
             // the canvas. Re-bind to the live page and retry ONCE instead.
-            if (PinePaperBrowserController.isStaleFrameError(error) && await this.reacquirePage()) {
+            const recovery = PinePaperBrowserController.isStaleFrameError(error) ? await this.recoverSession() : false;
+            if (recovery) {
                 try {
                     // Forward `options`: a recovered export that silently reverted to the
                     // 10s governor budget would die at the same place the retry exists to
@@ -557,6 +686,15 @@ export class PinePaperBrowserController {
                     // The page reloaded under us, so the scene may be gone even though
                     // execution now succeeds. Say so explicitly — silently continuing
                     // against vanished item ids is how this bug wasted a whole rebuild.
+                    if (recovery.kind === 'relaunched') {
+                        return {
+                            ...retry,
+                            recovered: true,
+                            relaunched: true,
+                            canvasReset: true,
+                            ...(recovery.canvasSizeRestored ? { canvasSizeRestored: recovery.canvasSizeRestored } : {}),
+                        };
+                    }
                     const items = await this.canvasItemCount();
                     return {
                         ...retry,
@@ -572,9 +710,12 @@ export class PinePaperBrowserController {
                     };
                 }
             }
+            const message = error instanceof Error ? error.message : 'Unknown execution error';
             return {
                 success: false,
-                error: error instanceof Error ? error.message : 'Unknown execution error',
+                error: PinePaperBrowserController.isStaleFrameError(error)
+                    ? `${message}. The browser session was lost and could not be recovered automatically: call pinepaper_browser_disconnect, then pinepaper_browser_connect.`
+                    : message,
             };
         }
     }
@@ -641,18 +782,39 @@ export class PinePaperBrowserController {
      * Refresh the page and wait for PinePaper to be ready again.
      * This is the most reliable way to get a clean canvas.
      */
+    /**
+     * Reload the studio. The tool whose job is recovery could not recover: on a
+     * detached frame, page.reload() threw the same "detached Frame" error as
+     * every other call (M6, after ~2 days idle). A stale page is now recovered
+     * first: re-bound and reloaded, or the browser relaunched at the remembered
+     * canvas size. The return says which, so the caller knows the scene is gone.
+     */
     async refreshPage() {
         if (!this.page) {
             throw new Error('Not connected to browser');
         }
         console.error('[PinePaper] Refreshing page...');
-        await this.page.reload({
-            waitUntil: this.config.waitUntil,
-            timeout: this.config.timeout,
-        });
+        try {
+            await this.page.reload({ waitUntil: this.config.waitUntil, timeout: this.config.timeout });
+        }
+        catch (error) {
+            if (!PinePaperBrowserController.isStaleFrameError(error))
+                throw error;
+            const recovery = await this.recoverSession();
+            if (!recovery) {
+                throw new Error('The browser session was lost and could not be recovered: call pinepaper_browser_disconnect, then pinepaper_browser_connect.');
+            }
+            if (recovery.kind === 'relaunched') {
+                console.error('[PinePaper] Page refreshed by relaunching the browser');
+                return { relaunched: true, ...(recovery.canvasSizeRestored ? { canvasSizeRestored: recovery.canvasSizeRestored } : {}) };
+            }
+            await this.page.reload({ waitUntil: this.config.waitUntil, timeout: this.config.timeout });
+        }
         // Wait for PinePaper to be ready again
         await this.waitForPinePaper();
+        await this.rememberCanvasSize();
         console.error('[PinePaper] Page refreshed and ready');
+        return {};
     }
     /**
      * Check if PinePaper API is available