@pinepaper.studio/mcp-server 1.6.8 → 1.6.9

package/README.de.md

@@ -14,7 +14,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 **151 Tools**: Zeichnen, Animation, Diagramme, Karten, Typografie, Physik, Bildbearbeitung, Datenvisualisierung und Export:
+Der Server bietet **152 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

@@ -14,7 +14,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 **151 herramientas**: dibujo, animación, diagramas, mapas, tipografía, física, edición de imágenes, visualización de datos y exportación:
+Expone **152 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

@@ -14,7 +14,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 **151 outils** : dessin, animation, diagrammes, cartes, typographie, physique, retouche d'image, visualisation de données et export :
+Il expose **152 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

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

package/README.ja.md

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

package/README.ko.md

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

package/README.md

@@ -25,7 +25,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 **151 tools** across drawing, animation, diagrams, maps, typography, physics, image editing, data visualization, and export. Using natural language, you can:
+The server exposes **152 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
@@ -36,7 +36,7 @@ The server exposes **151 tools** across drawing, animation, diagrams, maps, typo
 
 ## Running it: local or hosted
 
-**Local is free and complete.** Every one of the 151 tools works when you run
+**Local is free and complete.** Every one of the 152 tools works when you run
 this server yourself. There is no reduced tier and nothing held back.
 
 What it needs:
@@ -208,6 +208,80 @@ 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.9
+
+### New: `pinepaper_export_store`
+
+Recover an export the studio is still holding, instead of re-rendering it.
+
+- `list` — what is held: `{id, format, size, createdAt}`, newest first. IDs survive a page reload.
+- `save` — page it out to a file and release it. Returns a `filePath`, and is safe to repeat.
+- `release` — drop it without saving.
+
+Reach for it when an export fails with `Failed to write data to data pipe` — that is the browser's transport, not the encoder, so the bytes are often already stored — or when an error names an `exportId`.
+
+**Retention:** held exports last until released, or until a later export needs the space, and eviction drops the oldest first. Save or release each export before starting the next one.
+
+### New: `scale` on `pinepaper_agent_export`
+
+Render video at a fraction of the platform preset (`0.1`–`1`).
+
+- `scale: 0.5` with `quality: "draft"` is a fast look-check before committing to a full render.
+- Smaller frames also mean smaller files: the encoder derives its target from resolution, so this is the size control. There is no bitrate option.
+- Video only (`mp4`/`webm`/`gif`) — passing it to `png`/`svg`/`pdf`/`wav` is rejected rather than ignored. Omitting it leaves exports exactly as before.
+
+### New: `list_motion` on `pinepaper_design_system`
+
+Returns each licensed design system's motion curves **and** its durations; previously only the curves were reachable. Durations come back in milliseconds and in seconds.
+
+These are the design systems' motion scales — Material's duration ladder, and so on. Aesthetic styles such as `bauhaus_geometric` carry no motion data of their own, so pair a system's motion with a style.
+
+### `list_styles` now returns style tokens
+
+`pinepaper_design_system` `list_styles` returns each style's palette, background, font stacks, type sizes and variants, not just its name. Building in a style by hand no longer means reading the generator source to find its colours.
+
+### Fixed: `compose` placed everything off-centre
+
+`compose` positioned items by their top-left corner while the canvas positions by centre, so every composed scene was displaced and left-aligned headlines ran off the edge of the canvas. Composed scenes now land where the layout intends.
+
+### Fixed: exports could report success while failing
+
+`pinepaper_agent_export` could return success when the export itself had failed, so a failed render passed silently and a batch could lose chunks without saying so. A failed export is now an error, and names a recovery path when the failure looks like a transport problem.
+
+### Fixed: long exports timed out at ten seconds
+
+Video exports running longer than about ten seconds failed with a `PP_TIMEOUT` that looked like a problem with the scene.
+
+- `PINEPAPER_EXPORT_TIMEOUT` sets the budget (default `300000` ms). For exports over five minutes, raise `PINEPAPER_TIMEOUT` to match.
+- `PINEPAPER_GOVERNOR=off` is an escape hatch for older studio builds.
+
+### Fixed: exports failed on a fresh session
+
+Exporting immediately after connecting failed with a message blaming the studio's version. The export now waits for the studio's export subsystem to finish loading.
+
+### Fixed: large exports could be left undeliverable
+
+A read failure partway through paging a large export left the file unrecoverable. Reads now retry at a smaller size, and anything still held can be recovered with `pinepaper_export_store`.
+
+### Fixed: connection failures behind proxies, and a false "ready"
+
+Connecting could burn the full timeout against a studio that was already usable, and the connection had no configuration.
+
+- `PINEPAPER_WAIT_UNTIL` — what a navigation waits for (default `domcontentloaded`; set `networkidle2` for the previous behaviour).
+- `PINEPAPER_TIMEOUT` — navigation and readiness timeout in ms (default `30000`).
+- `PINEPAPER_PROXY` — routes Chrome through a proxy, for origins that reject headless Chrome. Setting it also relaxes certificate checking, which an intercepting proxy requires.
+
+Connections now wait for the studio's API rather than for its canvas library, so "connected" means tool calls will work.
+
+### Fixed: `pinepaper_animate_letter_collage` ignored its animation type
+
+The requested animation type was discarded on every call. **This fix also needs a studio update** — the other half is an engine change that has not shipped yet, so collage animation stays static until it does.
+
+### Documentation
+
+- **Rotation** — `pinepaper_create_item` documents `properties: { rotation: 45 }`, and that rotation is baked into the geometry, so reading `item.rotation` back returns `0`. Verify a rotation by geometry or pixels, not by re-reading the property.
+- **Dense motion** — `pinepaper_keyframe_animate` points at cheaper routes before you author hundreds of keyframes: the `time_expression` relation for motion that is a function of time, `staggered_with` / `wave_through` for a whole group, and `pinepaper_execute_custom_code` for procedural scenes.
+
 ## What's new in 1.6.8
 
 **Long-form export stops crossing the bridge as one string.** `pinepaper_agent_export` handed the bytes back as a base64 data URL. Two things were wrong with that and only one of them was a bug.
@@ -490,7 +564,7 @@ Fourteen new tools (121 → 135) and new actions across the surface — the rele
 
 ## Toolkits & Token Budget
 
-151 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.
+152 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`):
 
@@ -695,7 +769,7 @@ Generate instruction/code pairs for LLM fine-tuning:
 
 ## Tools Reference
 
-All 151 tools, grouped by the tag used for toolkit filtering.
+All 152 tools, grouped by the tag used for toolkit filtering.
 
 ### Canvas (`canvas`)
 | Tool | Description |
@@ -936,6 +1010,7 @@ All 151 tools, grouped by the tag used for toolkit filtering.
 | `pinepaper_agent_batch_execute` | Execute multiple operations in batch |
 | `pinepaper_interchange` | Lottie, dotLottie, GLB, BVH, PNG sequence |
 | `pinepaper_agent_export` | Smart export with platform auto-detection |
+| `pinepaper_export_store` | Recover an export the studio is still holding — list, save to a file, or release |
 | `pinepaper_agent_analyze` | Analyze content for export recommendations |
 
 ### Browser (`browser`)
@@ -1197,6 +1272,16 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
 | `PINEPAPER_METRICS_ENABLED` | Enable performance metrics tracking | `true` |
 | `PINEPAPER_METRICS_RETENTION` | Max metrics to retain in memory | `1000` |
 | `PINEPAPER_SCREENSHOT_MODE` | Screenshot mode (`on_request`/`always`/`never`) | `on_request` |
+| `PINEPAPER_WAIT_UNTIL` | What a navigation waits for (`load`/`domcontentloaded`/`networkidle0`/`networkidle2`) | `domcontentloaded` |
+| `PINEPAPER_TIMEOUT` | Navigation and readiness timeout, in ms | `30000` |
+| `PINEPAPER_PROXY` | Chrome `--proxy-server` value; also ignores certificate errors, for an intercepting proxy | unset |
+| `PINEPAPER_EXPORT_TIMEOUT` | Governor budget for an export run, in ms (raise `PINEPAPER_TIMEOUT` alongside it) | `300000` |
+| `PINEPAPER_GOVERNOR` | `off` runs code by raw eval — no governor report, no error codes, no seeded determinism | on |
+
+Behind a proxy, or against a Studio with analytics or polling connections open,
+`networkidle2` may never settle: set `PINEPAPER_WAIT_UNTIL` only if you need the
+old behaviour back. Readiness does not depend on it — the connection waits for
+Studio's `app.create` either way.
 
 ### Performance Metrics
 

package/README.pt-BR.md

@@ -14,7 +14,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 **151 ferramentas**: desenho, animação, diagramas, mapas, tipografia, física, edição de imagens, visualização de dados e exportação:
+São **152 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

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

package/dist/browser/index.d.ts

@@ -4,5 +4,5 @@
  * Exports for browser-side usage of PinePaper MCP tools.
  */
 export { PinePaperBridge, PinePaperStudioHandler, createBridge, createStudioHandler, type BridgeMessage, type BridgeConfig, } from './bridge.js';
-export { PinePaperBrowserController, getBrowserController, resetBrowserController, resetBrowserControllerSync, type BrowserControllerConfig, type ExecuteResult, type AgentConnectOptions, type BatchExecuteResult, } from './puppeteer-controller.js';
+export { PinePaperBrowserController, getBrowserController, resetBrowserController, resetBrowserControllerSync, PAGE_WAIT_UNTIL, type BrowserControllerConfig, type ExecuteCodeOptions, type PageWaitUntil, type ExecuteResult, type AgentConnectOptions, type BatchExecuteResult, } from './puppeteer-controller.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/browser/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,eAAe,EACf,sBAAsB,EACtB,YAAY,EACZ,mBAAmB,EACnB,KAAK,aAAa,EAClB,KAAK,YAAY,GAClB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,0BAA0B,EAC1B,oBAAoB,EACpB,sBAAsB,EACtB,0BAA0B,EAC1B,KAAK,uBAAuB,EAC5B,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,GACxB,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,eAAe,EACf,sBAAsB,EACtB,YAAY,EACZ,mBAAmB,EACnB,KAAK,aAAa,EAClB,KAAK,YAAY,GAClB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,0BAA0B,EAC1B,oBAAoB,EACpB,sBAAsB,EACtB,0BAA0B,EAC1B,eAAe,EACf,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,GACxB,MAAM,2BAA2B,CAAC"}

package/dist/browser/index.js

@@ -4,5 +4,5 @@
  * Exports for browser-side usage of PinePaper MCP tools.
  */
 export { PinePaperBridge, PinePaperStudioHandler, createBridge, createStudioHandler, } from './bridge.js';
-export { PinePaperBrowserController, getBrowserController, resetBrowserController, resetBrowserControllerSync, } from './puppeteer-controller.js';
+export { PinePaperBrowserController, getBrowserController, resetBrowserController, resetBrowserControllerSync, PAGE_WAIT_UNTIL, } from './puppeteer-controller.js';
 //# sourceMappingURL=index.js.map

package/dist/browser/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,eAAe,EACf,sBAAsB,EACtB,YAAY,EACZ,mBAAmB,GAGpB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,0BAA0B,EAC1B,oBAAoB,EACpB,sBAAsB,EACtB,0BAA0B,GAK3B,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,eAAe,EACf,sBAAsB,EACtB,YAAY,EACZ,mBAAmB,GAGpB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,0BAA0B,EAC1B,oBAAoB,EACpB,sBAAsB,EACtB,0BAA0B,EAC1B,eAAe,GAOhB,MAAM,2BAA2B,CAAC"}

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

@@ -4,6 +4,13 @@
  * Controls a real browser instance running PinePaper Studio.
  * Executes code directly via page.evaluate() and provides screenshots.
  */
+/**
+ * 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
+ * an optional peer, absent on most installs (see connect()).
+ */
+export type PageWaitUntil = 'load' | 'domcontentloaded' | 'networkidle0' | 'networkidle2';
+export declare const PAGE_WAIT_UNTIL: readonly PageWaitUntil[];
 export interface BrowserControllerConfig {
     /** PinePaper Studio URL (default: https://pinepaper.studio) */
     studioUrl?: string;
@@ -17,6 +24,45 @@ export interface BrowserControllerConfig {
     timeout?: number;
     /** Enable agent mode with ?agent=1 URL parameter */
     agentMode?: boolean;
+    /**
+     * What navigations wait for (default: 'domcontentloaded').
+     *
+     * Every goto/reload used to be networkidle2, which asks for two-or-fewer
+     * connections held for half a second — a bar Studio never clears behind a
+     * proxy, or with analytics and polling sockets open. Connect then burned the
+     * entire timeout and failed against a page that had been usable for seconds.
+     * Readiness is waitForPinePaper()'s job; a navigation only has to hand us a
+     * document.
+     */
+    waitUntil?: PageWaitUntil;
+    /**
+     * Chrome --proxy-server value (e.g. 'http://127.0.0.1:8080'). Setting it also
+     * passes --ignore-certificate-errors, because a proxy that intercepts TLS
+     * presents its own certificate and Chrome would otherwise refuse every
+     * origin. Unset → neither flag, and certificate checking stays on.
+     */
+    proxy?: string;
+    /**
+     * Run code through FxTool's governor (app.runGenerated) when the build has
+     * one. Default true. False raw-evals instead — see ExecuteCodeOptions.
+     */
+    governor?: boolean;
+}
+export interface ExecuteCodeOptions {
+    /**
+     * Governor budget for this run, in ms. FxTool's runGenerated defaults to
+     * 10_000 (RUN_DEFAULTS.timeoutMs, an async-tail Promise.race): a sane guard
+     * against a runaway script, and the wrong number for an export — the one
+     * operation that legitimately runs for minutes.
+     */
+    governorTimeoutMs?: number;
+    /**
+     * Skip app.runGenerated entirely and raw-eval the code. That gives up the
+     * governor report, the structured error codes and the seeded PRNG, so it is
+     * the escape hatch for a deployed build whose governor ignores the budget
+     * above — never a fast path. Defaults to the controller's `governor: false`.
+     */
+    bypassGovernor?: boolean;
 }
 export interface AgentConnectOptions {
     /** Run browser in headless mode (default: true for agent workflows) */
@@ -62,6 +108,29 @@ export interface ExecuteResult {
      */
     canvasReset?: boolean;
 }
+/**
+ * Is PinePaper Studio actually usable? Evaluated IN THE PAGE, so it closes over
+ * nothing.
+ *
+ * The old test was `app !== undefined || pinepaper !== undefined || paper !==
+ * undefined`, hand-copied into four places. `window.paper` is Paper.js, which
+ * attaches the moment the canvas script loads — long before Studio has built
+ * its API — so all four sites could report ready against a page that would
+ * throw on the first call.
+ *
+ * The test is FxTool's own, mirrored rather than invented: js/app.js polls
+ * `app && app.itemRegistry && typeof app.create === 'function'` under the
+ * comment "No global ready event exists — poll for the app surface the executor
+ * needs". Two ordering details make both halves earn their place:
+ * `window.PinePaper` is first assigned the CLASS at module load (no `create` —
+ * create() is an instance method) and only later the instance, and the instance
+ * assigns itself to the global from INSIDE its own constructor.
+ *
+ * Every candidate global is tested, not just the first truthy one: picking
+ * `window.app` because it exists and then failing it would trade a false ready
+ * for a false not-ready, which costs the whole timeout.
+ */
+export declare function pinePaperIsReady(): boolean;
 /**
  * Controls PinePaper Studio via Puppeteer.
  *
@@ -78,6 +147,13 @@ export declare class PinePaperBrowserController {
     private isAgentMode;
     private connectingPromise;
     constructor(config?: BrowserControllerConfig);
+    /**
+     * Chrome flags shared by both launch paths, so a proxy configured once does
+     * not go missing from whichever path the caller happens to take.
+     */
+    private launchArgs;
+    /** Launch options shared by both paths — see MIN_PROTOCOL_TIMEOUT_MS. */
+    private launchOptions;
     /**
      * Get URL with agent mode parameter
      */
@@ -102,6 +178,14 @@ export declare class PinePaperBrowserController {
      * Whether the browser is running in headless mode
      */
     get isHeadless(): boolean;
+    /**
+     * The resolved connection settings. Read-only, and a copy: these are what the
+     * env vars and the caller's config actually worked out to, which is otherwise
+     * only observable by launching a browser.
+     */
+    get connectionSettings(): Readonly<Required<BrowserControllerConfig>>;
+    /** The Chrome flags this controller would launch with. Exposed for tests. */
+    chromeArgs(): string[];
     /**
      * Launch browser and navigate to PinePaper Studio.
      * When agentMode is enabled (default), this automatically uses connectAgent().
@@ -134,7 +218,7 @@ export declare class PinePaperBrowserController {
     /**
      * Execute JavaScript code in PinePaper Studio
      */
-    executeCode(code: string, takeScreenshot?: boolean): Promise<ExecuteResult>;
+    executeCode(code: string, takeScreenshot?: boolean, options?: ExecuteCodeOptions): Promise<ExecuteResult>;
     /**
      * Take a screenshot of the current canvas
      */
@@ -180,7 +264,7 @@ export declare class PinePaperBrowserController {
     /**
      * Execute code with a timeout
      */
-    executeWithTimeout(code: string, timeoutMs: number, takeScreenshot?: boolean): Promise<ExecuteResult>;
+    executeWithTimeout(code: string, timeoutMs: number, takeScreenshot?: boolean, options?: ExecuteCodeOptions): Promise<ExecuteResult>;
     /**
      * Quick reset: Clear canvas without full page refresh
      */

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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"}