@pinepaper.studio/mcp-server 1.6.24 → 1.6.25

package/README.md

@@ -249,6 +249,124 @@ If you do not want an agent executing anything, `code` mode is a first-class pat
 - 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.
 - The server itself fetches the images, SVGs and media a tool call names by URL, and reads local files named by path. URLs that resolve to loopback, private, link-local or reserved addresses are refused, redirects included, and so are cloud metadata addresses. Local files are read only from the working directory, the export folder, and folders listed in `PINEPAPER_ASSET_DIRS`. `PINEPAPER_ALLOW_PRIVATE_NETWORK=1` allows local and LAN hosts. Metadata addresses stay refused even with it set.
 
+## What's new in 1.6.25
+
+### Added
+
+- `pinepaper_pattern` kinds `ring` and `orbit`: members spaced evenly round a
+  turning circle, with a fixed `center` or a `target` item the centre follows.
+  The list of kinds now comes from the studio, so a kind it adds appears here
+  too.
+
+### Changed
+
+- The server speaks MCP itself instead of through the MCP SDK, so installing
+  it pulls in 2 packages (`zod` and `undici`) instead of 78. It behaves the
+  same on the wire: the same protocol versions (2024-10-07 to 2025-11-25),
+  errors, progress, cancellation and logging, checked against recordings of
+  the previous server. `createServer()` still accepts any MCP transport,
+  including the SDK's.
+- The published code no longer uses `eval` or runs `git`, and it reads
+  environment variables in one place.
+- New sessions start with a leaner tool list: the `core` toolkit, about half
+  the context of the previous default, with every craft tool the server
+  recommends. Other tools load when needed with `pinepaper_set_toolkit`
+  `{"load": ["map"]}` (a group) or a tool's name, and the list updates at
+  once. Claude Desktop, Cursor and Windsurf used to get all 178 tools.
+  `PINEPAPER_TOOLKIT=agent` or `full` restores a larger list.
+- Exports are saved to `~/Downloads/PinePaper` instead of a temporary folder,
+  so Desktop users can find them (`PINEPAPER_EXPORT_DIR` still overrides it,
+  and machines without a Downloads folder keep the temporary folder). Each
+  saved file also comes back as a link the client can open, and
+  `resources/read` returns files up to 10 MB from the export folder.
+- A Claude Desktop extension (`.mcpb`) can be built with `bun run
+  build:mcpb`: one file to open, no config to edit. It uses your installed
+  Chrome for the canvas tools. Without full `puppeteer`, the server now also
+  works with `puppeteer-core` and your installed Chrome, or another browser
+  set in `PINEPAPER_CHROME_PATH`.
+
+### Fixed
+
+- `pinepaper_pattern` no longer warns "NO CHANGE" after a `create` or
+  `modify` that has not moved anything yet, such as a wave at time 0 or one
+  whose window starts later.
+- A failed batch step addressed by `$N` names the item that `$N` resolved to,
+  not `"$N"`.
+- Batch `animate` and `relation` operations quote their `animationType` and
+  `relationType` correctly in the generated code.
+- The scene lint that batches and custom code run on every call no longer
+  checks every pair of items, which made each call on a large scene slower.
+  It reports the same warnings.
+- A video export that goes over the bitrate you asked for says so: the studio
+  reports `bitrate_exceeded` with the bitrate the file actually has, and how
+  to land under the target.
+- The agent toolkit's export description now says what each format returns:
+  only MP4 and WebM carry a frame digest, and a small SVG comes back inline
+  rather than as a file.
+- `on_event_fire_if` is documented: its predicate is an ExpressionIR object
+  (comparisons, and/or/not, reads of an item's data, active or visible
+  state), and it fires the event in `params.event`, not its target. A
+  predicate written as a string, or a relation with no event to fire, is
+  refused with the shape that works, wherever the relation comes from:
+  `pinepaper_add_relation`, a batch `relation` step, `pinepaper_create_scene`,
+  `pinepaper_instantiate_ontology`, or an `on_event_add_relation` that adds
+  one later. Before, the relation silently never fired.
+- An emitter given a `[min, max]` range for a key that takes one number
+  (such as `gravity`, `opacity` or `count`) now gets a warning: the key draws
+  one value for every particle, not a spread. Before, there was no warning.
+- `pinepaper_import_image` takes a `name`, so a batch `patch` can address an
+  imported image by name.
+- Custom code that returns nothing is reported as returning nothing, not as
+  `{}`, when the scene lint has warnings.
+- An export whose file was saved but could not be hashed or read back says
+  so. It used to report the save as failed.
+- A batch step other than `create` that carries a key it does not read
+  now gets an `IGNORED ARGUMENTS` note naming the step and the key. Before,
+  the key had no effect and nothing said so. The common mix-ups get a hint:
+  `params` on a `relation` step (it takes `relationOptions`), and `x`/`y` on
+  a `modify` step (changes go inside `properties`).
+- Clearing the canvas starts item ids again at `item_1`
+  (`pinepaper_clear_canvas`, `pinepaper_agent_start_job` and
+  `pinepaper_agent_reset`), so a batch sent after a clear gets the same ids
+  every time. Before, the numbering carried on from the cleared items, and
+  only a server restart reset it.
+- A `group` step in a batch now takes the next `$N`, as a `create` does, so
+  a later step can animate the group: in `[create, create, group, …]` the
+  group is `$2`. This renumbers batches that create items after a group:
+  in `[create, create, group, create]` the last item was `$2` and is now
+  `$3`. Before, a `$N` meant for the group failed with "it has created 2 so
+  far".
+- An event reaction that shows or hides an item (`on_event_set_visibility`,
+  and its `on_enter_` and `on_exit_` forms) refuses `value` and asks for
+  `visible`, the field it reads. Before, `{"value": false}` showed the item
+  instead of hiding it.
+- A PNG, JPG, WebP, SVG or PDF of a scene that is playing is its first frame
+  (time 0), the frame a video starts on, and the result says so. Before, it
+  was whatever frame playback had reached, so items moved by relations (an
+  orbit) were in a different place on every export. `time` still picks
+  another moment.
+- A closed shape given a `strokeColor` and no fill is drawn as an outline.
+  Before, it got the default fill, or the active brand's colour.
+- A batch no longer flags `ttl` or `bornAt` on a `line` as a likely typo.
+- A line created with `from` and `to` reports where it actually is, and says
+  that `position` does not move it: `from` and `to` are canvas coordinates.
+  Before, the result reported the position asked for while the line was
+  drawn at the top left.
+- `pinepaper_transform` `nudge` moves an item the way `pinepaper_modify_item`
+  does, so an item with a loop animation keeps its new place, and the
+  result no longer reports the move as no change.
+- `create_item` documents `properties.id`: an id of your own, so replays
+  address the same items. An id with a quote, backslash or line break is
+  refused, since later calls could not address it.
+- An item id containing a quote no longer breaks `pinepaper_modify_item`,
+  `pinepaper_delete_item`, `pinepaper_animate`,
+  `pinepaper_keyframe_animate`, `pinepaper_apply_effect` or
+  `pinepaper_query_relations`. Before, the call failed with a syntax error.
+- The `lane` toolkit adds `pinepaper_event`, for things that happen at a
+  set time or on a click (a panel that hides at 3 s), and
+  `pinepaper_clear_canvas`, to start over. Its batch description shows how
+  to attach an event's reactions and triggers.
+
 ## What's new in 1.6.24
 
 ### Added
@@ -1717,27 +1835,20 @@ Fourteen new tools (121 → 135) and new actions across the surface — the rele
 
 | Profile | Contents |
 |---------|----------|
+| `core` | **The default.** The craft tools the server's instructions point to, the agent workflow, canvas and query tools, plus every tool those name, so no listed tool points at a missing one. About half the tokens of `agent`. Anything else loads on demand (below) |
 | `full` | Every tool, no filtering |
-| `agent` | Every tool except the diagnostics (`pinepaper_get_performance_metrics`, `pinepaper_diagnostic_report`) and `pinepaper_register_item`. The default for a client not listed below |
+| `agent` | Every tool except the diagnostics (`pinepaper_get_performance_metrics`, `pinepaper_diagnostic_report`) and `pinepaper_register_item` |
 | `diagram` | Canvas + diagram + query/export |
 | `map` | Canvas + map + query/export |
 | `font` | Canvas + font + letter collage + export |
 | `minimal` | Agent, browser, canvas, and guide only |
-| `lane` | **The agent lane**: exactly five tools — `pinepaper_agent_batch_execute`, `pinepaper_keyframe_animate`, `pinepaper_pattern`, `pinepaper_agent_export`, `pinepaper_lint_scene` — shown with descriptions that carry the rules an agent otherwise learns by failing (the keyframe shape, an item's words and look inside `properties`, a position being the item's centre, the export's 5 s default). The whole contract, instructions included, is ~3.3k tokens. For scripted builds of shapes, text, keyframes and relations; use `agent` for characters, styled scenes, maps, diagrams and sound |
+| `lane` | **The agent lane**: exactly seven tools — `pinepaper_agent_batch_execute`, `pinepaper_keyframe_animate`, `pinepaper_pattern`, `pinepaper_agent_export`, `pinepaper_lint_scene`, `pinepaper_event`, `pinepaper_clear_canvas` — shown with descriptions that carry the rules an agent otherwise learns by failing (the keyframe shape, an item's words and look inside `properties`, a position being the item's centre, the export's 5 s default). The whole contract, instructions included, is ~4.3k tokens. For scripted builds of shapes, text, keyframes and relations; use `core` for characters, styled scenes, maps, diagrams and sound |
 
 **Verbosity tiers** (`PINEPAPER_VERBOSITY`): `verbose`, `compact` (default), `minimal`.
 
-**Client auto-detection.** When neither env var is set explicitly, the server picks a profile from the MCP `initialize` handshake:
+**Load on demand.** Every client starts on `core`. When a task needs more, the model calls `pinepaper_set_toolkit` with `load`: a group (`{"load": ["map"]}`, `["diagram"]`, `["font"]`, `["physics"]`, …) or a tool's own name. The tools are added for the session, along with any tools they mention, and the client is told the list changed. The server logs each client's name at start-up.
 
-| Client | Toolkit | Verbosity |
-|--------|---------|-----------|
-| `claude-ai` | `minimal` | `compact` |
-| `claude-desktop` | `full` | `compact` |
-| `claude-code` | `agent` | `compact` |
-| `cursor` | `full` | `compact` |
-| `windsurf` | `full` | `compact` |
-
-Explicit env vars always win. You can also hand-pick tools with `PINEPAPER_TOOLS` (comma-separated names), or switch profiles at runtime with the `pinepaper_set_toolkit` tool. Start with `pinepaper_tool_guide` to have the server explain its own surface.
+`PINEPAPER_TOOLKIT` always wins. You can also hand-pick tools with `PINEPAPER_TOOLS` (comma-separated names), or switch profiles at runtime with the `pinepaper_set_toolkit` tool. Start with `pinepaper_tool_guide` to have the server explain its own surface.
 
 ## Features
 
@@ -2322,6 +2433,10 @@ bun install
 bun run build
 ```
 
+### Claude Desktop extension (.mcpb)
+
+`bun run build:mcpb` builds `mcpb/pinepaper-mcp-server-<version>.mcpb`, a one-file Claude Desktop extension: open it and Desktop installs the server, with no config file to edit. The extension drives your installed Google Chrome (choose another Chromium-based browser in its settings), and its settings also set the export folder and the tool list.
+
 ### Test with MCP Client (Local)
 
 1. Build the server:
@@ -2437,9 +2552,10 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
 | `PINEPAPER_API_KEY` | Service-account key (`pp_sa_…`) for the cloud-backed tools (`pinepaper_generate`) | — |
 | `PINEPAPER_CLOUD_URL` | The PinePaper cloud those tools call | `https://cloud.pinepaper.studio` |
 | `PINEPAPER_EXECUTION_MODE` | `puppeteer` (execute in a real browser) or `code` (return generated code only) | `puppeteer` |
-| `PINEPAPER_EXPORT_DIR` | Directory for exported files | `<tmpdir>/pinepaper-exports` |
+| `PINEPAPER_CHROME_PATH` | A Chromium-based browser for the canvas tools when full `puppeteer` is not installed (the Desktop extension uses your installed Chrome by default) | installed Google Chrome |
+| `PINEPAPER_EXPORT_DIR` | Directory for exported files | `~/Downloads/PinePaper` (`<tmpdir>/pinepaper-exports` where there is no Downloads folder) |
 | `PINEPAPER_LOCALE` | Language locale code | `en` |
-| `PINEPAPER_TOOLKIT` | Toolkit profile (`full`/`agent`/`diagram`/`map`/`font`/`minimal`/`lane`) | auto-detected |
+| `PINEPAPER_TOOLKIT` | Toolkit profile (`core`/`full`/`agent`/`diagram`/`map`/`font`/`minimal`/`lane`) | `core` |
 | `PINEPAPER_TOOLS` | Explicit comma-separated tool allowlist | unset |
 | `PINEPAPER_VERBOSITY` | Description verbosity (`verbose`/`compact`/`minimal`) | `compact` |
 | `PINEPAPER_TOOL_VERBOSITY` | Deprecated alias for `PINEPAPER_VERBOSITY` | unset |

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

@@ -305,6 +305,12 @@ export declare class PinePaperBrowserController {
     /**
      * Execute JavaScript code in PinePaper Studio
      */
+    /**
+     * The ungoverned path: the code as a CDP Runtime.evaluate (Puppeteer's string form awaits a promise and keeps the
+     * script's trailing value), then the in-page bridgeSafe the governed path uses, so a value holding live Paper items
+     * still crosses. A throw comes back as { success: false, error }, as it did from eval.
+     */
+    private runUngoverned;
     executeCode(code: string, takeScreenshot?: boolean, options?: ExecuteCodeOptions): Promise<ExecuteResult>;
     /**
      * Take a screenshot of the current canvas

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

@@ -6,6 +6,7 @@
  */
 import { mcpLog } from '../utils/mcp-log.js';
 import { LAZY_HEAVY_SUBSYSTEMS, LAZY_HEAVY_CLASSES, ENGINE_SURFACE } from '../tools/engine-surface.js';
+import { env } from '../utils/env.js';
 export const PAGE_WAIT_UNTIL = ['load', 'domcontentloaded', 'networkidle0', 'networkidle2'];
 /**
  * Is PinePaper Studio actually usable? Evaluated IN THE PAGE, so it closes over
@@ -74,6 +75,46 @@ const BOOTSTRAP_SUBSYSTEMS = Object.freeze(Object.entries(ENGINE_SURFACE)
  * not go through executeOrGenerate (gate A2, 1.6.19).
  */
 export const BROWSER_TIME = { executeMs: 0, screenshotMs: 0 };
+/**
+ * The browser driver. Puppeteer is an OPTIONAL peer (1.6.5): browser automation
+ * is a handful of tools, and a headless-browser download with an install script
+ * in the default tree is what supply-chain scanners flag hardest.
+ *
+ * Tried in order: `puppeteer` (its own Chrome), then `puppeteer-core` driving a
+ * browser already on the machine (1.6.25: the Claude Desktop bundle ships
+ * puppeteer-core, not a Chrome download): PINEPAPER_CHROME_PATH when set, else
+ * the installed Chrome. Neither present → the install instruction, not a crash.
+ */
+async function loadPuppeteer() {
+    try {
+        const full = await import('puppeteer');
+        return { launch: (opts) => full.default.launch(opts) };
+    }
+    catch { /* not installed: try the core driver */ }
+    let core = null;
+    try {
+        const specifier = 'puppeteer-core'; // a variable, so the build does not need the package installed
+        core = await import(specifier);
+    }
+    catch { /* not installed either */ }
+    if (core) {
+        const executablePath = env('PINEPAPER_CHROME_PATH')?.trim();
+        return {
+            launch: async (opts) => {
+                try {
+                    return await core.default.launch({ ...opts, ...(executablePath ? { executablePath } : { channel: 'chrome' }) });
+                }
+                catch (e) {
+                    const why = e instanceof Error ? e.message.split('\n')[0] : String(e);
+                    throw new Error(executablePath
+                        ? `Could not start the browser at PINEPAPER_CHROME_PATH (${executablePath}): ${why}`
+                        : `The canvas tools drive your installed Google Chrome, and it could not be started (${why}). Install Chrome from https://www.google.com/chrome/, or set PINEPAPER_CHROME_PATH to another Chromium-based browser (Edge, Brave, Chromium), then retry.`);
+                }
+            },
+        };
+    }
+    throw new Error('The browser tools need puppeteer, which is an optional install. Under npx, add it to the same call — args ["-y", "-p", "puppeteer", "-p", "@pinepaper.studio/mcp-server", "pinepaper-mcp"] — since a separate `npm i puppeteer` is not visible to npx\'s copy. Installed globally: `npm i -g puppeteer`; in a project: `npm i puppeteer`. Then retry. It is kept out of the default dependency tree for supply-chain hygiene.');
+}
 export class PinePaperBrowserController {
     browser = null;
     page = null;
@@ -305,19 +346,9 @@ export class PinePaperBrowserController {
                 this.browser = null;
                 this.page = null;
             }
-            // Puppeteer is an OPTIONAL peer (1.6.5): browser automation is 4 of 135
-            // tools, and carrying a headless-browser + install-script dependency in
-            // the default tree is what supply-chain scanners flag hardest. Absent →
-            // a clear instruction, not a crash.
-            let puppeteer;
-            try {
-                puppeteer = await import('puppeteer');
-            }
-            catch {
-                throw new Error('The browser tools need puppeteer, which is an optional install. Under npx, add it to the same call — args ["-y", "-p", "puppeteer", "-p", "@pinepaper.studio/mcp-server", "pinepaper-mcp"] — since a separate `npm i puppeteer` is not visible to npx\'s copy. Installed globally: `npm i -g puppeteer`; in a project: `npm i puppeteer`. Then retry. It is kept out of the default dependency tree for supply-chain hygiene.');
-            }
+            const puppeteer = await loadPuppeteer();
             console.error('[PinePaper] Launching browser...');
-            this.browser = await puppeteer.default.launch(this.launchOptions(this.config.headless, this.launchArgs(this.config.viewportWidth, this.config.viewportHeight)));
+            this.browser = await puppeteer.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) {
@@ -501,7 +532,7 @@ export class PinePaperBrowserController {
     async ensureStudioPage() {
         if (!this.page)
             return 'ok';
-        let state = null;
+        let state;
         try {
             state = await this.page.evaluate(() => {
                 const app = window.app || window.PinePaper;
@@ -548,6 +579,31 @@ export class PinePaperBrowserController {
     /**
      * Execute JavaScript code in PinePaper Studio
      */
+    /**
+     * The ungoverned path: the code as a CDP Runtime.evaluate (Puppeteer's string form awaits a promise and keeps the
+     * script's trailing value), then the in-page bridgeSafe the governed path uses, so a value holding live Paper items
+     * still crosses. A throw comes back as { success: false, error }, as it did from eval.
+     */
+    async runUngoverned(code) {
+        if (!this.page)
+            return { success: false, error: 'Browser not connected', executedVia: 'eval' };
+        let handle = null;
+        try {
+            handle = await this.page.evaluateHandle(code);
+            const value = await this.page.evaluate((v) => {
+                const safe = window.__ppBridgeSafe;
+                return safe ? safe(v) : v;
+            }, handle);
+            return { success: true, result: value, executedVia: 'eval' };
+        }
+        catch (e) {
+            return { success: false, error: e instanceof Error ? e.message : 'Execution error', executedVia: 'eval' };
+        }
+        finally {
+            if (handle)
+                await handle.dispose().catch(() => { });
+        }
+    }
     async executeCode(code, takeScreenshot = true, options = {}) {
         if (!this.page || !this.isConnected) {
             return {
@@ -611,7 +667,7 @@ export class PinePaperBrowserController {
                 stage: options.stage ?? null,
             };
             const __evalStart = Date.now();
-            const result = await this.page.evaluate(async (codeToRun, opts) => {
+            const evaluated = await this.page.evaluate(async (codeToRun, opts) => {
                 // THE BRIDGE USES STRUCTURED CLONE, AND JSON.stringify DOES NOT PROVE IT.
                 //
                 // A result crosses CDP by structured clone, which refuses to carry a
@@ -715,25 +771,18 @@ export class PinePaperBrowserController {
                         return { success: false, error: e instanceof Error ? e.message : 'Execution error', executedVia: 'governed' };
                     }
                 }
-                // 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);
-                    if (evalResult instanceof Promise) {
-                        return evalResult.then((r) => ({ success: true, result: bridgeSafe(r), executedVia: 'eval' }));
-                    }
-                    return { success: true, result: bridgeSafe(evalResult), executedVia: 'eval' };
-                }
-                catch (e) {
-                    return {
-                        success: false,
-                        error: e instanceof Error ? e.message : 'Execution error',
-                        executedVia: 'eval',
-                    };
-                }
+                // Fallback: run ungoverned — a pre-governor FxTool build, or an explicit
+                // bypass. The code is run from the Node side as a CDP Runtime.evaluate
+                // (below), which returns the script's trailing value exactly as eval did:
+                // both generated-code shapes are `(`-led expression statements. It used
+                // to be eval() here; the published package then carried an eval call
+                // that supply-chain scanners flag, for what CDP already does.
+                window.__ppBridgeSafe = bridgeSafe;
+                return { success: true, __ppRaw: true, executedVia: 'eval' };
             }, code, runOptions);
+            let result = evaluated;
+            if (evaluated.__ppRaw)
+                result = await this.runUngoverned(code);
             BROWSER_TIME.executeMs += Date.now() - __evalStart;
             // Take screenshot if requested
             let screenshot;
@@ -981,23 +1030,13 @@ export class PinePaperBrowserController {
                 this.browser = null;
                 this.page = null;
             }
-            // Puppeteer is an OPTIONAL peer (1.6.5): browser automation is 4 of 135
-            // tools, and carrying a headless-browser + install-script dependency in
-            // the default tree is what supply-chain scanners flag hardest. Absent →
-            // a clear instruction, not a crash.
-            let puppeteer;
-            try {
-                puppeteer = await import('puppeteer');
-            }
-            catch {
-                throw new Error('The browser tools need puppeteer, which is an optional install. Under npx, add it to the same call — args ["-y", "-p", "puppeteer", "-p", "@pinepaper.studio/mcp-server", "pinepaper-mcp"] — since a separate `npm i puppeteer` is not visible to npx\'s copy. Installed globally: `npm i -g puppeteer`; in a project: `npm i puppeteer`. Then retry. It is kept out of the default dependency tree for supply-chain hygiene.');
-            }
+            const puppeteer = await loadPuppeteer();
             // Agent mode defaults to visible browser so user can see PinePaper Studio
             const useHeadless = options.headless ?? this.config.headless;
             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(this.launchOptions(useHeadless, this.launchArgs(viewportWidth, viewportHeight, [
+            this.browser = await puppeteer.launch(this.launchOptions(useHeadless, this.launchArgs(viewportWidth, viewportHeight, [
                 // '--disable-gpu' USED TO BE HERE, AND IT TURNED OFF WEBGL.
                 //
                 // It was carried in as a headless convention under "optimization
@@ -1134,24 +1173,13 @@ ${codes.map((code, i) => `
 })();
     `.trim();
         try {
-            const result = await this.page.evaluate((codeToRun) => {
-                try {
-                    // eslint-disable-next-line no-eval
-                    const evalResult = eval(codeToRun);
-                    if (evalResult instanceof Promise) {
-                        return evalResult;
-                    }
-                    return evalResult;
-                }
-                catch (e) {
-                    return {
-                        success: false,
-                        error: e instanceof Error ? e.message : 'Batch execution error',
-                        results: [],
-                        itemIds: [],
-                    };
-                }
-            }, batchCode);
+            // A string is run as a CDP Runtime.evaluate: the script's value, awaited, by value (no eval in this package).
+            const result = await this.page.evaluate(batchCode).catch((e) => ({
+                success: false,
+                error: e instanceof Error ? e.message : 'Batch execution error',
+                results: [],
+                itemIds: [],
+            }));
             const executionTime = Date.now() - startTime;
             // Take screenshot if requested
             let screenshot;
@@ -1268,25 +1296,25 @@ export function getBrowserController(config) {
         // 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 envHeadless = env('PINEPAPER_HEADLESS');
         const headless = config?.headless ?? (envHeadless !== undefined ? envHeadless !== 'false' : true);
-        const envWaitUntil = process.env.PINEPAPER_WAIT_UNTIL?.trim();
+        const envWaitUntil = 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 envTimeout = Number(env('PINEPAPER_TIMEOUT'));
+        if (env('PINEPAPER_TIMEOUT') && !Number.isFinite(envTimeout)) {
+            console.error(`[PinePaper] PINEPAPER_TIMEOUT="${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'),
+            proxy: config?.proxy ?? env('PINEPAPER_PROXY')?.trim(),
+            governor: config?.governor ?? (env('PINEPAPER_GOVERNOR')?.trim().toLowerCase() !== 'off'),
         };
         globalController = new PinePaperBrowserController(mcpConfig);
     }