@pinepaper.studio/mcp-server 1.6.7 → 1.6.9

package/README.zh-CN.md

@@ -14,7 +14,7 @@
 
 PinePaper MCP 服务器让 AI 助手通过 MCP 协议在 [PinePaper Studio](https://pinepaper.studio) 中创建和驱动图形动画。兼容任何支持 MCP 工具调用的 AI（Claude、GPT、Gemini、本地模型等）。
 
-服务器提供 **144 个工具**，覆盖绘图、动画、图表、地图、排版、物理、图像编辑、数据可视化与导出：
+服务器提供 **152 个工具**，覆盖绘图、动画、图表、地图、排版、物理、图像编辑、数据可视化与导出：
 
 - 创建文本、形状、几何图形与复杂图稿
 - 用行为驱动的**关系（relations）**做动画，而不是逐帧关键帧
@@ -77,9 +77,11 @@ npm install -g @pinepaper.studio/mcp-server
 服务器** —— 相同的工具、相同的版本，通过 HTTP 提供，无需安装，也不需要在你的
 机器上运行浏览器。
 
-托管需要成本，因此是付费的：**Starter 每月 $4.99**（每天 500 次请求）与
-**Pro 每月 $14.99**（每天 5,000 次，另含动画模板库）。如果你能在本地运行，
-就在本地运行 —— 这样不会损失任何功能。
+托管需要成本，因此是付费的，按额度（credits）运行。当前价格请见
+[cloud.pinepaper.studio](https://cloud.pinepaper.studio)。能在本地运行就在本地运行，
+但两者并不完全相同：托管服务使用经过测试的 LLM，并在生成的代码进入画布前
+进行修复 —— 这是本地服务器自身无法做到的。哪个模型更合适，你可以自己验证：基准测试用同一个提示词在多个模型上运行，
+并排展示结果，任意一次运行都可分享。目前为邀请制测试版。
 
 ## 更多
 

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

package/dist/browser/puppeteer-controller.js

@@ -4,6 +4,41 @@
  * Controls a real browser instance running PinePaper Studio.
  * Executes code directly via page.evaluate() and provides screenshots.
  */
+export const PAGE_WAIT_UNTIL = ['load', 'domcontentloaded', 'networkidle0', 'networkidle2'];
+/**
+ * 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 function pinePaperIsReady() {
+    const w = window;
+    return [w.app, w.PinePaper, w.pinepaper].some((api) => !!api && typeof api.create === 'function' && !!api.itemRegistry);
+}
+/**
+ * Floor for how long CDP waits on a single call. Puppeteer's default is 180s,
+ * which is shorter than a long video export's governor budget (handlers.ts,
+ * EXPORT_GOVERNOR_DEFAULT_MS — this number, deliberately) — the protocol must
+ * not be the thing that kills an export first, or the error blames the wrong
+ * layer. PINEPAPER_TIMEOUT raises it past this floor.
+ */
+const MIN_PROTOCOL_TIMEOUT_MS = 300_000;
 // =============================================================================
 // BROWSER CONTROLLER CLASS
 // =============================================================================
@@ -42,11 +77,48 @@ export class PinePaperBrowserController {
             viewportHeight: config.viewportHeight || 800,
             timeout: config.timeout || 30000,
             agentMode: true, // MCP server always uses agent mode
+            waitUntil: config.waitUntil || 'domcontentloaded',
+            proxy: config.proxy || '',
+            governor: config.governor ?? true,
         };
         console.error(`[PinePaper] Controller initialized:`);
         console.error(`[PinePaper]   Original URL: ${originalUrl}`);
         console.error(`[PinePaper]   Agent URL: ${studioUrl}`);
         console.error(`[PinePaper]   Headless: ${this.config.headless}`);
+        console.error(`[PinePaper]   waitUntil: ${this.config.waitUntil}, timeout: ${this.config.timeout}ms`);
+        if (this.config.proxy) {
+            console.error(`[PinePaper]   Proxy: ${this.config.proxy} — certificate errors ignored for this session`);
+        }
+        if (!this.config.governor) {
+            console.error('[PinePaper]   Governor: OFF — raw eval, no report, no seeded determinism');
+        }
+    }
+    /**
+     * Chrome flags shared by both launch paths, so a proxy configured once does
+     * not go missing from whichever path the caller happens to take.
+     */
+    launchArgs(viewportWidth, viewportHeight, extra = []) {
+        const args = [
+            '--no-sandbox',
+            '--disable-setuid-sandbox',
+            `--window-size=${viewportWidth},${viewportHeight}`,
+            ...extra,
+        ];
+        // Strictly gated on an explicitly configured proxy. Relaxing certificate
+        // checking for every run would be a silent downgrade; here it is the
+        // consequence of a flag the operator set for their own interception proxy.
+        if (this.config.proxy) {
+            args.push(`--proxy-server=${this.config.proxy}`, '--ignore-certificate-errors');
+        }
+        return args;
+    }
+    /** Launch options shared by both paths — see MIN_PROTOCOL_TIMEOUT_MS. */
+    launchOptions(headless, args) {
+        return {
+            headless,
+            args,
+            protocolTimeout: Math.max(this.config.timeout, MIN_PROTOCOL_TIMEOUT_MS),
+        };
     }
     /**
      * Get URL with agent mode parameter
@@ -87,6 +159,18 @@ export class PinePaperBrowserController {
     get isHeadless() {
         return this.config.headless;
     }
+    /**
+     * 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() {
+        return { ...this.config };
+    }
+    /** The Chrome flags this controller would launch with. Exposed for tests. */
+    chromeArgs() {
+        return this.launchArgs(this.config.viewportWidth, this.config.viewportHeight);
+    }
     /**
      * Launch browser and navigate to PinePaper Studio.
      * When agentMode is enabled (default), this automatically uses connectAgent().
@@ -144,14 +228,7 @@ export class PinePaperBrowserController {
                 throw new Error('The browser tools need puppeteer, which is an optional install: run `npm i puppeteer` (or `npm i -g puppeteer` for a global CLI) and retry. It is kept out of the default dependency tree for supply-chain hygiene.');
             }
             console.error('[PinePaper] Launching browser...');
-            this.browser = await puppeteer.default.launch({
-                headless: this.config.headless,
-                args: [
-                    '--no-sandbox',
-                    '--disable-setuid-sandbox',
-                    `--window-size=${this.config.viewportWidth},${this.config.viewportHeight}`,
-                ],
-            });
+            this.browser = await puppeteer.default.launch(this.launchOptions(this.config.headless, this.launchArgs(this.config.viewportWidth, this.config.viewportHeight)));
             // Get existing pages first, reuse if available (avoid creating multiple tabs)
             const pages = await this.browser.pages();
             if (pages.length > 0) {
@@ -170,17 +247,10 @@ export class PinePaperBrowserController {
             });
             console.error(`[PinePaper] Navigating to ${this.config.studioUrl}...`);
             await this.page.goto(this.config.studioUrl, {
-                waitUntil: 'networkidle2',
+                waitUntil: this.config.waitUntil,
                 timeout: this.config.timeout,
             });
-            // Wait for PinePaper to be ready (check for app object)
-            console.error('[PinePaper] Waiting for PinePaper Studio to initialize...');
-            await this.page.waitForFunction(() => {
-                // Check if PinePaper's global app or API is available
-                return (typeof window.app !== 'undefined' ||
-                    typeof window.pinepaper !== 'undefined' ||
-                    typeof window.paper !== 'undefined');
-            }, { timeout: this.config.timeout });
+            await this.waitForPinePaper();
             this.isConnected = true;
             console.error('[PinePaper] Connected to PinePaper Studio');
         }
@@ -272,7 +342,7 @@ export class PinePaperBrowserController {
     /**
      * Execute JavaScript code in PinePaper Studio
      */
-    async executeCode(code, takeScreenshot = true) {
+    async executeCode(code, takeScreenshot = true, options = {}) {
         if (!this.page || !this.isConnected) {
             return {
                 success: false,
@@ -285,11 +355,17 @@ export class PinePaperBrowserController {
             // budgets, bulk-create perf, and a machine-readable report. It returns the
             // code's trailing-expression value as result.value (FxTool captures it).
             // Fall back to raw eval on older builds that lack runGenerated.
-            const result = await this.page.evaluate(async (codeToRun) => {
+            const runOptions = {
+                bypass: options.bypassGovernor ?? !this.config.governor,
+                timeoutMs: options.governorTimeoutMs,
+            };
+            const result = await this.page.evaluate(async (codeToRun, opts) => {
                 const app = window.app || window.PinePaper;
-                if (app && typeof app.runGenerated === 'function') {
+                if (!opts.bypass && app && typeof app.runGenerated === 'function') {
                     try {
-                        const run = await app.runGenerated(codeToRun, { source: 'agent' });
+                        // timeoutMs is runGenerated's own option (RUN_DEFAULTS.timeoutMs,
+                        // 10s) — passing undefined leaves the default in place.
+                        const run = await app.runGenerated(codeToRun, { source: 'agent', timeoutMs: opts.timeoutMs });
                         if (run && run.ok === false) {
                             return {
                                 success: false,
@@ -305,7 +381,9 @@ export class PinePaperBrowserController {
                         return { success: false, error: e instanceof Error ? e.message : 'Execution error', executedVia: 'governed' };
                     }
                 }
-                // Fallback: raw eval (pre-governor FxTool build).
+                // Fallback: raw eval — a pre-governor FxTool build, or an explicit
+                // bypass. Both generated-code shapes are `(`-led expression statements,
+                // so eval returns the same trailing value runGenerated captures.
                 try {
                     // eslint-disable-next-line no-eval
                     const evalResult = eval(codeToRun);
@@ -321,7 +399,7 @@ export class PinePaperBrowserController {
                         executedVia: 'eval',
                     };
                 }
-            }, code);
+            }, code, runOptions);
             // Take screenshot if requested
             let screenshot;
             if (takeScreenshot && result.success) {
@@ -339,7 +417,10 @@ export class PinePaperBrowserController {
             // the canvas. Re-bind to the live page and retry ONCE instead.
             if (PinePaperBrowserController.isStaleFrameError(error) && await this.reacquirePage()) {
                 try {
-                    const retry = await this.executeCode(code, takeScreenshot);
+                    // Forward `options`: a recovered export that silently reverted to the
+                    // 10s governor budget would die at the same place the retry exists to
+                    // get past.
+                    const retry = await this.executeCode(code, takeScreenshot, options);
                     // 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.
@@ -407,7 +488,7 @@ export class PinePaperBrowserController {
             throw new Error('Not connected to browser');
         }
         await this.page.goto(url, {
-            waitUntil: 'networkidle2',
+            waitUntil: this.config.waitUntil,
             timeout: this.config.timeout,
         });
     }
@@ -419,7 +500,7 @@ export class PinePaperBrowserController {
             throw new Error('Not connected to browser');
         }
         await this.page.reload({
-            waitUntil: 'networkidle2',
+            waitUntil: this.config.waitUntil,
             timeout: this.config.timeout,
         });
     }
@@ -433,16 +514,11 @@ export class PinePaperBrowserController {
         }
         console.error('[PinePaper] Refreshing page...');
         await this.page.reload({
-            waitUntil: 'networkidle2',
+            waitUntil: this.config.waitUntil,
             timeout: this.config.timeout,
         });
         // Wait for PinePaper to be ready again
-        console.error('[PinePaper] Waiting for PinePaper Studio to reinitialize...');
-        await this.page.waitForFunction(() => {
-            return (typeof window.app !== 'undefined' ||
-                typeof window.pinepaper !== 'undefined' ||
-                typeof window.paper !== 'undefined');
-        }, { timeout: this.config.timeout });
+        await this.waitForPinePaper();
         console.error('[PinePaper] Page refreshed and ready');
     }
     /**
@@ -453,11 +529,7 @@ export class PinePaperBrowserController {
             return false;
         }
         try {
-            return await this.page.evaluate(() => {
-                return (typeof window.app !== 'undefined' ||
-                    typeof window.pinepaper !== 'undefined' ||
-                    typeof window.paper !== 'undefined');
-            });
+            return await this.page.evaluate(pinePaperIsReady);
         }
         catch {
             return false;
@@ -481,7 +553,7 @@ export class PinePaperBrowserController {
                     const agentUrl = this.getAgentUrl(this.config.studioUrl);
                     console.error(`[PinePaper] Switching to agent mode: ${agentUrl}`);
                     await this.page.goto(agentUrl, {
-                        waitUntil: 'networkidle2',
+                        waitUntil: this.config.waitUntil,
                         timeout: this.config.timeout,
                     });
                     await this.waitForPinePaper();
@@ -524,18 +596,12 @@ export class PinePaperBrowserController {
             const viewportWidth = options.viewportWidth ?? this.config.viewportWidth;
             const viewportHeight = options.viewportHeight ?? this.config.viewportHeight;
             console.error(`[PinePaper] Launching browser in agent mode (headless: ${useHeadless})...`);
-            this.browser = await puppeteer.default.launch({
-                headless: useHeadless,
-                args: [
-                    '--no-sandbox',
-                    '--disable-setuid-sandbox',
-                    `--window-size=${viewportWidth},${viewportHeight}`,
-                    // Additional optimization flags for agent mode
-                    '--disable-gpu',
-                    '--disable-dev-shm-usage',
-                    '--disable-extensions',
-                ],
-            });
+            this.browser = await puppeteer.default.launch(this.launchOptions(useHeadless, this.launchArgs(viewportWidth, viewportHeight, [
+                // Additional optimization flags for agent mode
+                '--disable-gpu',
+                '--disable-dev-shm-usage',
+                '--disable-extensions',
+            ])));
             // Get existing pages first, reuse if available (avoid creating multiple tabs)
             const pages = await this.browser.pages();
             // Use the first page (about:blank) and close ALL others
@@ -565,7 +631,7 @@ export class PinePaperBrowserController {
             console.error(`[PinePaper] Navigating to agent URL: ${targetUrl}`);
             // Navigate the existing page to PinePaper (converts about:blank to PinePaper)
             await this.page.goto(targetUrl, {
-                waitUntil: 'networkidle2',
+                waitUntil: this.config.waitUntil,
                 timeout: this.config.timeout,
             });
             // Wait for PinePaper to be ready
@@ -586,11 +652,7 @@ export class PinePaperBrowserController {
         if (!this.page)
             return;
         console.error('[PinePaper] Waiting for PinePaper Studio to initialize...');
-        await this.page.waitForFunction(() => {
-            return (typeof window.app !== 'undefined' ||
-                typeof window.pinepaper !== 'undefined' ||
-                typeof window.paper !== 'undefined');
-        }, { timeout: this.config.timeout });
+        await this.page.waitForFunction(pinePaperIsReady, { timeout: this.config.timeout });
     }
     /**
      * Execute multiple code blocks as a batch for optimal performance.
@@ -695,11 +757,16 @@ ${codes.map((code, i) => `
     /**
      * Execute code with a timeout
      */
-    async executeWithTimeout(code, timeoutMs, takeScreenshot = false) {
+    async executeWithTimeout(code, timeoutMs, takeScreenshot = false, options = {}) {
         const timeoutPromise = new Promise((_, reject) => {
             setTimeout(() => reject(new Error('Execution timeout')), timeoutMs);
         });
-        const executePromise = this.executeCode(code, takeScreenshot);
+        // The caller's outer deadline is the governor's too unless they said
+        // otherwise — a governor that fires first would report the wrong cause.
+        const executePromise = this.executeCode(code, takeScreenshot, {
+            governorTimeoutMs: timeoutMs,
+            ...options,
+        });
         try {
             return await Promise.race([executePromise, timeoutPromise]);
         }
@@ -775,12 +842,28 @@ let globalController = null;
  */
 export function getBrowserController(config) {
     if (!globalController) {
-        // Resolve headless: explicit config > env var > default (true)
+        // Env resolution lives here, not in the controller: explicit config wins,
+        // then the env var, then the default — the shape PINEPAPER_HEADLESS and
+        // PINEPAPER_STUDIO_URL already use.
         const envHeadless = process.env.PINEPAPER_HEADLESS;
         const headless = config?.headless ?? (envHeadless !== undefined ? envHeadless !== 'false' : true);
+        const envWaitUntil = process.env.PINEPAPER_WAIT_UNTIL?.trim();
+        if (envWaitUntil && !PAGE_WAIT_UNTIL.includes(envWaitUntil)) {
+            // Loudly, because a typo here silently reinstates the hang it was set to
+            // avoid — and a 30s connect failure looks nothing like a bad env var.
+            console.error(`[PinePaper] PINEPAPER_WAIT_UNTIL="${envWaitUntil}" is not one of ${PAGE_WAIT_UNTIL.join(', ')} — ignoring it.`);
+        }
+        const envTimeout = Number(process.env.PINEPAPER_TIMEOUT);
+        if (process.env.PINEPAPER_TIMEOUT && !Number.isFinite(envTimeout)) {
+            console.error(`[PinePaper] PINEPAPER_TIMEOUT="${process.env.PINEPAPER_TIMEOUT}" is not a number — ignoring it.`);
+        }
         const mcpConfig = {
             ...config,
             headless,
+            waitUntil: config?.waitUntil ?? (envWaitUntil && PAGE_WAIT_UNTIL.includes(envWaitUntil) ? envWaitUntil : undefined),
+            timeout: config?.timeout ?? (Number.isFinite(envTimeout) && envTimeout > 0 ? envTimeout : undefined),
+            proxy: config?.proxy ?? process.env.PINEPAPER_PROXY?.trim(),
+            governor: config?.governor ?? (process.env.PINEPAPER_GOVERNOR?.trim().toLowerCase() !== 'off'),
         };
         globalController = new PinePaperBrowserController(mcpConfig);
     }