@pinepaper.studio/mcp-server 1.6.24 → 1.6.26

package/README.md

@@ -80,11 +80,19 @@ shareable. It is in invite-only beta.
 
 ### Quick start
 
-Puppeteer is an **optional** install, so a plain `npx @pinepaper.studio/mcp-server`
-has no browser: every tool then returns the code it would run instead of running
-it (the result says so). To execute in a real browser, install Puppeteer **in the
-same `npx` call** — a separate `npm i puppeteer` in your project is not visible to
-`npx`'s copy of the server:
+**Claude Desktop:** download
+[pinepaper-mcp-server.mcpb](https://github.com/pinepaper/mcp-server/releases/latest/download/pinepaper-mcp-server.mcpb)
+and open it. Desktop installs the server, with no config file to edit. It
+drives your installed Google Chrome; its settings choose another Chromium-based
+browser, the export folder and the tool list. Each
+[release](https://github.com/pinepaper/mcp-server/releases) lists the file's
+SHA-256.
+
+For other MCP clients: this package does not install Puppeteer, so a plain
+`npx @pinepaper.studio/mcp-server` has no browser, and every tool returns the
+code it would run instead of running it (the result says so). To execute in a
+real browser, install Puppeteer **in the same `npx` call**. A separate
+`npm i puppeteer` in your project is not visible to `npx`'s copy of the server:
 
 ```json
 {
@@ -246,9 +254,149 @@ If you do not want an agent executing anything, `code` mode is a first-class pat
 
 - Code an agent writes runs with whatever that browser page has. Give this server the same trust you would give anything else you let write and run code on your machine — which is the trust you already extend to an MCP client with tool access.
 - 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.
+- Puppeteer itself is not a dependency at all (it was an optional peer until 1.6.25), kept out of the 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 loads it only from where its own dependencies would be found (the same `npx` call, a global install, a project install) or from a folder you name in `PINEPAPER_PUPPETEER_FROM`; never from the folder it happens to be started in. puppeteer 22 or newer is required.
+- The package starts one child process, and only when an export is saved: `ffprobe -show_entries … <file>` (via `execFile`, no shell, fixed binary and argument list, an absolute path) to check the saved video against what the studio encoded. Without `ffprobe` on `PATH` the check is skipped and said so; `PINEPAPER_FFPROBE=off` turns it off.
 - 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.26
+
+### Changed
+
+- The package installs two dependencies, zod and undici. Puppeteer is no
+  longer declared, not even as an optional peer; install it yourself for the
+  browser tools, as before (`-p puppeteer` in the `npx` call, a global install
+  or a project install). The Desktop extension includes what it needs.
+  puppeteer 22 or newer is required. With pnpm `hoist=false` or Yarn PnP
+  strict, set `PINEPAPER_PUPPETEER_FROM` to the project folder that has it.
+
+### Fixed
+
+- A video whose motion comes from relations (an orbit, an item attached to a
+  moving one, a generator, the camera) reported `animated: false` in its export
+  result, although the frames moved. When the studio says not animated, the
+  export now compares frames from across the video. If they differ, it reports
+  `animated: true` and says how it knows (`fidelity.checked.motion`). The
+  frozen-video check, which runs only on animated exports, now covers these
+  scenes too.
+
+## 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 +1865,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:
-
-| Client | Toolkit | Verbosity |
-|--------|---------|-----------|
-| `claude-ai` | `minimal` | `compact` |
-| `claude-desktop` | `full` | `compact` |
-| `claude-code` | `agent` | `compact` |
-| `cursor` | `full` | `compact` |
-| `windsurf` | `full` | `compact` |
+**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.
 
-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 +2463,10 @@ bun install
 bun run build
 ```
 
+### Claude Desktop extension (.mcpb)
+
+Each release ships it ready-made ([latest](https://github.com/pinepaper/mcp-server/releases/latest/download/pinepaper-mcp-server.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 +2582,11 @@ 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_PUPPETEER_FROM` | An absolute project folder to load `puppeteer` / `puppeteer-core` from, for a strict layout (pnpm `hoist=false`, Yarn PnP strict) where the server cannot see its project's packages | unset |
+| `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/SECURITY.md

@@ -41,6 +41,20 @@ Examples of what is in scope:
 - reading or writing files outside the folders the server is allowed to use (path traversal);
 - tool input that escapes the generated snippet and runs in the server process instead of the page;
 - exposing a credential such as `PINEPAPER_API_KEY`, or sending it somewhere it should not go;
-- a crash or hang of the server caused by a single crafted tool call.
+- a crash or hang of the server caused by a single crafted tool call;
+- the server loading `puppeteer` (or any module) from somewhere other than where its own dependencies resolve or `PINEPAPER_PUPPETEER_FROM`, or running a child process other than the `ffprobe` read-back described below.
 
 The server's own defences, `PINEPAPER_ALLOW_PRIVATE_NETWORK` and `PINEPAPER_ASSET_DIRS`, are documented in the README. Bypassing either one is in scope.
+
+## Dependencies
+
+The package installs two runtime dependencies and nothing else:
+
+- `zod`, for tool input schemas;
+- `undici`, used only by the guarded fetch (`src/utils/safe-fetch.ts`) to pin each connection to the addresses that passed the private-network check, which closes DNS rebinding. Node's built-in `fetch` cannot be given that pinned resolver, so undici stays.
+
+**Puppeteer is not a dependency**, not even an optional peer (it was one up to 1.6.25). It brings a browser download with an install script, shell access and a large network tree, and the browser tools are a minority of what the server does. Install it yourself to use them (`npm i puppeteer`, or `-p puppeteer` in the `npx` call; see the README). The server imports it by name only from where its own dependencies resolve, or from an absolute folder you set in `PINEPAPER_PUPPETEER_FROM`; never from its working directory, which can be an untrusted checkout. puppeteer 22 or newer is required and an older one is refused.
+
+**One child process.** When an exported video is saved, the server runs `ffprobe` through `execFile` (no shell) with a fixed argument list and the file's absolute path, to compare the file with what the studio encoded. It is skipped when `ffprobe` is not on `PATH`, and `PINEPAPER_FFPROBE=off` turns it off.
+
+The source contains no `eval` or `new Function`.

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

@@ -8,7 +8,7 @@ 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
- * an optional peer, absent on most installs (see connect()).
+ * not a dependency, absent on most installs (see loadPuppeteer()).
  */
 export type PageWaitUntil = 'load' | 'domcontentloaded' | 'networkidle0' | 'networkidle2';
 export declare const PAGE_WAIT_UNTIL: readonly PageWaitUntil[];
@@ -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,11 @@
  */
 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';
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
 export const PAGE_WAIT_UNTIL = ['load', 'domcontentloaded', 'networkidle0', 'networkidle2'];
 /**
  * Is PinePaper Studio actually usable? Evaluated IN THE PAGE, so it closes over
@@ -74,6 +79,96 @@ 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 NOT a dependency of this package, not even an
+ * optional peer (it was one up to 1.6.25): browser automation is a handful of tools, and a
+ * headless-browser download with an install script is what supply-chain
+ * scanners flag hardest. A declared peer, optional or not, still puts its whole
+ * tree in a scanner's view of this package. The user installs it beside the
+ * server when they want the executing mode (README, "Install").
+ *
+ * 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.
+ */
+const PUPPETEER_MIN_MAJOR = 22;
+/**
+ * Import a package this server does not depend on, by a name held in a
+ * variable (so neither the build nor a scanner sees a dependency it does not
+ * have). Resolution starts from THIS package, as a declared dependency's would:
+ * `npx -p puppeteer -p @pinepaper.studio/mcp-server`, a global install of both,
+ * and a project install all put puppeteer where that finds it.
+ *
+ * It is never resolved from process.cwd(): an MCP client starts the server in
+ * whatever folder is open, which can be a cloned repository, and a
+ * node_modules/puppeteer planted there would then run as this process. The one
+ * other place looked in is a folder the user names in PINEPAPER_PUPPETEER_FROM
+ * (for a strict layout — pnpm with hoist=false, Yarn PnP strict — where a
+ * package cannot see its project's undeclared packages).
+ */
+async function importOptional(name) {
+    const versionFrom = (base) => {
+        try {
+            const pkgPath = createRequire(base).resolve(`${name}/package.json`);
+            return String(JSON.parse(readFileSync(pkgPath, 'utf8')).version ?? '') || null;
+        }
+        catch {
+            return null; /* no exported package.json: version unknown, not refused */
+        }
+    };
+    try {
+        return { mod: await import(name), version: versionFrom(import.meta.url) };
+    }
+    catch { /* not beside this package (or present and failing to load: treated as absent, as before) */ }
+    const from = env('PINEPAPER_PUPPETEER_FROM')?.trim();
+    if (!from || !isAbsolute(from))
+        return null;
+    const base = pathToFileURL(join(from, 'package.json')).href;
+    try {
+        const entry = createRequire(base).resolve(name);
+        return { mod: await import(pathToFileURL(entry).href), version: versionFrom(base) };
+    }
+    catch {
+        return null;
+    }
+}
+function refuseOldPuppeteer(name, version) {
+    const major = version ? Number(version.split('.')[0]) : NaN;
+    if (Number.isFinite(major) && major < PUPPETEER_MIN_MAJOR) {
+        throw new Error(`The browser tools need ${name} ${PUPPETEER_MIN_MAJOR} or newer; ${version} is installed. Run \`npm i ${name}@latest\` (or add -p ${name}@latest to the npx call), then retry.`);
+    }
+}
+async function loadPuppeteer() {
+    const fullName = 'puppeteer'; // a variable: see importOptional
+    const full = await importOptional(fullName);
+    if (full) {
+        refuseOldPuppeteer(fullName, full.version);
+        return { launch: (opts) => full.mod.default.launch(opts) };
+    }
+    const coreName = 'puppeteer-core';
+    const coreLoaded = await importOptional(coreName);
+    if (coreLoaded)
+        refuseOldPuppeteer(coreName, coreLoaded.version);
+    const core = coreLoaded?.mod ?? null;
+    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 this package does not install: install puppeteer to use the browser tools (npm i puppeteer). 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` (with pnpm hoist=false or Yarn PnP strict, also set PINEPAPER_PUPPETEER_FROM to the project folder). Then retry. It is kept out of the dependency tree for supply-chain hygiene.');
+}
 export class PinePaperBrowserController {
     browser = null;
     page = null;
@@ -305,19 +400,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 +586,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 +633,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 +721,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 +825,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 evaluated here; the published package then carried an evaluating 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 +1084,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 +1227,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 +1350,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);
     }