@pinepaper.studio/mcp-server 1.6.29 → 1.6.31

package/README.de.md

@@ -74,7 +74,7 @@ Bitten Sie Ihre KI zum Beispiel:
 **Lokal ist kostenlos und vollständig.** Alle Tools funktionieren, wenn Sie
 diesen Server selbst betreiben. Es gibt keine reduzierte Stufe.
 
-Benötigt: Node 18 oder neuer, rund **320 MB** Speicherplatz (Puppeteer lädt
+Benötigt: Node 22.13 oder neuer, rund **320 MB** Speicherplatz (Puppeteer lädt
 Chrome herunter) und etwa 1 GB Arbeitsspeicher, solange ein Job läuft. Auf
 einem Laptop ist das unproblematisch, auf einem kleinen VPS oder einem
 gesperrten Arbeitsrechner eher nicht.

package/README.es.md

@@ -74,7 +74,7 @@ Prueba a pedirle a tu IA:
 **Local es gratis y completo.** Todas las herramientas funcionan si ejecuta
 este servidor usted mismo. No hay una versión reducida.
 
-Necesita: Node 18 o superior, unos **320 MB** de disco (Puppeteer descarga
+Necesita: Node 22.13 o superior, unos **320 MB** de disco (Puppeteer descarga
 Chrome) y alrededor de 1 GB de memoria mientras se ejecuta un trabajo. En un
 portátil no supone problema; en un VPS pequeño o un equipo de trabajo
 restringido, sí.

package/README.fr.md

@@ -74,7 +74,7 @@ Essayez de demander à votre IA :
 **Le local est gratuit et complet.** Tous les outils fonctionnent si vous
 exécutez ce serveur vous-même. Il n'existe pas de version réduite.
 
-Il faut : Node 18 ou plus récent, environ **320 Mo** de disque (Puppeteer
+Il faut : Node 22.13 ou plus récent, environ **320 Mo** de disque (Puppeteer
 télécharge Chrome) et à peu près 1 Go de mémoire pendant l'exécution d'une
 tâche. Sur un ordinateur portable, cela passe ; sur un petit VPS ou une machine
 de travail verrouillée, moins.

package/README.hi.md

@@ -74,7 +74,7 @@ npm install -g @pinepaper.studio/mcp-server
 **लोकल मुफ़्त और पूरा है।** अगर आप यह सर्वर खुद चलाते हैं तो सारे टूल काम करते
 हैं। कोई सीमित संस्करण नहीं है।
 
-ज़रूरत: Node 18 या नया, लगभग **320 MB** डिस्क (Puppeteer क्रोम डाउनलोड करता है)
+ज़रूरत: Node 22.13 या नया, लगभग **320 MB** डिस्क (Puppeteer क्रोम डाउनलोड करता है)
 और जॉब चलने के दौरान करीब 1 GB मेमोरी। लैपटॉप पर यह ठीक है; छोटे VPS या
 प्रतिबंधित ऑफ़िस मशीन पर मुश्किल।
 

package/README.ja.md

@@ -74,7 +74,7 @@ AI にこう頼んでみてください：
 **ローカルは無料で、機能に制限はありません。** 自分でこのサーバーを動かせば、
 すべてのツールが使えます。制限版はありません。
 
-必要なもの: Node 18 以降、約 **320 MB** のディスク (Puppeteer が Chrome を
+必要なもの: Node 22.13 以降、約 **320 MB** のディスク (Puppeteer が Chrome を
 ダウンロードします)、ジョブ実行中は約 1 GB のメモリ。ノート PC なら問題あり
 ませんが、小さな VPS や制限のある業務用マシンでは厳しいことがあります。
 

package/README.ko.md

@@ -74,7 +74,7 @@ AI에게 이렇게 말해 보세요:
 **로컬은 무료이며 기능 제한이 없습니다.** 이 서버를 직접 실행하면 모든 도구가
 동작합니다. 축소된 버전은 없습니다.
 
-필요한 것: Node 18 이상, 약 **320 MB** 디스크 (Puppeteer가 Chrome을
+필요한 것: Node 22.13 이상, 약 **320 MB** 디스크 (Puppeteer가 Chrome을
 내려받습니다), 작업 실행 중 약 1 GB 메모리. 노트북에서는 문제가 없지만 작은
 VPS나 제한된 업무용 컴퓨터에서는 부담스러울 수 있습니다.
 

package/README.md

@@ -48,7 +48,7 @@ What it needs:
 
 | | |
 |---|---|
-| Node | 18 or newer |
+| Node | 22.13 or newer (any supported Node release: 22, 24 or 26) |
 | Disk | With Puppeteer (below), Chrome is downloaded on install — roughly **320 MB** per version |
 | Memory | a Chrome process plus the Studio canvas, so budget ~1 GB while a job runs |
 
@@ -279,6 +279,108 @@ If you do not want an agent executing anything, `code` mode is a first-class pat
 - The npm package starts no process. Two export features use `ffprobe` and `ffmpeg`: checking a saved video against what the studio encoded, and joining the cached segments of a `perScene` export (`ffmpeg -f concat`). Only the Claude Desktop extension runs them, through a small runner it bundles that allows those two binaries alone, via `execFile` (no shell, argument lists the server writes, absolute paths). From npm, the check is skipped and said so, and a `perScene` export runs whole.
 - 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 with `PINEPAPER_ALLOW_LOCAL_FILES=1`, and then only from the working directory, the export folder, and folders listed in `PINEPAPER_ASSET_DIRS` (the export folder is readable without the switch). `PINEPAPER_ALLOW_PRIVATE_NETWORK=1` allows local and LAN hosts. Metadata addresses stay refused even with it set.
 
+## What's new in 1.6.31
+
+### Changed
+
+- **Requires Node 22.13 or newer.** Node 18 and 20 are end of life, and this
+  package's dependencies already needed 20.19 or 22.13, so `>=18` was never
+  really true. On an older Node, upgrade before updating.
+- The server reads only a fixed list of environment variables, each by name
+  (`src/utils/env.ts`), and SECURITY.md lists what each capability of the
+  package is for and where it lives.
+- Every module the package loads is named literally. `PINEPAPER_PUPPETEER_FROM`
+  now loads puppeteer from the folder you name with `createRequire`. The one
+  exception is the optional ffmpeg add-on that only the Claude Desktop
+  extension bundles.
+- A `PINEPAPER_LOCALE` that is not a supported language falls back to English.
+  Before, the value became part of a file path.
+
+### Fixed
+
+- A batch op now takes the parameter names its standalone tool takes, and the
+  reply lists each name it translated. Before, they were dropped, sometimes
+  without a word: `animationOptions: { intensity, speed, delay }` on an
+  `animate` op applied none of them. Relations, effects and generators take
+  `params`, masks take `preset` and `options`, generators take `region`,
+  `animate` takes `intensity` / `speed` / `delay` / `waveform` / `origin`,
+  and a `modify` op takes its changes beside `itemId`.
+- A batch op's ignored-argument check now knows which keys each op type reads.
+  A key that only another op type uses (`speed` on `animate`, `preset` on a
+  mask, `itemId` on a generator) is reported instead of passing as known.
+- An `animate` op names any `animationOptions` key the studio does not read,
+  with the likely intended name (`animationIntensty → animationIntensity?`).
+  The list comes from the studio's own code, so it follows the studio as it
+  changes.
+- A batch `keyframe_animate` op gives the same warnings as
+  `pinepaper_keyframe_animate`: a key that leaves out a property another key
+  animates, `loop` in an export, easing on the first key, and `x` keyed beside
+  `fontSize` on an older studio. The batch op used to give none of them.
+- An emitter warns about a `[min, max]` range only on keys that take one number
+  in every studio build (`count`, `aspect`, `strokeWidth`, `jitterHz`, the
+  fades). `gravity`, `drag`, `friction`, `opacity`, `sizeEnd` and `jitter` are
+  sampled per particle on the current studio, and an older one reports a range
+  it can't draw itself.
+- `on_event_step_active` works without a `targetId` on the current studio. On
+  an older studio, which runs an event reaction only when it has a target, a
+  target-less one used to report success and never step; it is now refused
+  there, with the fix in the message (point it at any member of the group).
+- The relation docs now say how a stepper or tab strip is built. Members join
+  an `exclusive_group` only through `exclusive_group` relations between them.
+  Being active has no look of its own: `on_enter_*` / `on_exit_*` reactions on
+  each member draw it, in exports too. `items` only sets the step order.
+
+## What's new in 1.6.30
+
+### Changed
+
+- An idle server pauses the studio page after 30 s with no tool call
+  (`PINEPAPER_IDLE_PAUSE_SECONDS`, `0` to turn it off), and the next call
+  resumes it. A 400-item scene's live preview used about half a core to one
+  and a half cores with nobody watching; paused, it uses almost none. Exports
+  come out identical either way.
+- Replies are much smaller for an agent editing a scene. JSON results are sent
+  compact; `pinepaper_lint_scene { only: "edit" }` returns just the ops that
+  change the scene, lists a group bound by a name pattern once instead of once
+  per member, and includes a custom relation's source only with
+  `withSource: true`; a batch reply leaves out entries that only repeat what you
+  sent (`verbose: true` lists every op); and the `edit` toolkit's batch
+  description covers editing, not building. One edit pass over a 20-dot scene
+  went from 44 KB to 15 KB.
+- New relation `on_event_step_active`, for next and previous arrows: an event
+  moves the active member of an `exclusive_group` forward or back by `delta`
+  (default +1), wrapping at the ends unless `wrap: false`.
+- `pinepaper_lint_scene` lists only the custom relations the scene uses, and
+  names the rest in `registeredUnused` (one registered before a
+  `pinepaper_clear_canvas` no longer shows up as part of the scene).
+
+- Housekeeping for supply-chain scanners, with no change in behaviour: the
+  hosted-API client's request helper is named for what it is, three long text
+  constants are typed as plain strings, and the p5 drawing generator checks
+  `PINEPAPER_ALLOW_CODE` itself as well as the tool handler.
+
+### Fixed
+
+- A very large batch (more than about 200 creates) now waits until every op has
+  run before it replies, and its reply lists the items it made. It used to
+  answer success immediately with no result while the work carried on, so the
+  next call could act on a half-built scene. An export sent right after it
+  could miss the background colour set in the same batch.
+- An opaque export of a scene with no background colour (`mp4`, `webm`, or
+  `apng` with `transparent: false`) warns that the frames are filled with the
+  studio's page colour. The warning used to say black, but the current studio
+  fills them white.
+- `skewX` and `skewY` keyframes are documented: the current studio animates
+  them (degrees, up to ±89). A `shear` key, which is not a channel on any
+  studio, is named in `ignoredProperties` with a pointer to `skewX` / `skewY`
+  instead of being accepted silently.
+- On the current studio, scale at create, text keyed on both `x` and
+  `fontSize`, `bloom`, ink `keepColor` and removing a look are now fixed in the
+  studio itself. The 1.6.29 warnings and workarounds for them only appear on
+  an older studio that still needs them.
+- `pinepaper_modify_item` no longer calls `scale`, `scaleX` or `scaleY`
+  ignored on the current studio.
+
 ## What's new in 1.6.29
 
 ### Changed
@@ -2759,6 +2861,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
 |----------|-------------|---------|
 | `PINEPAPER_STUDIO_URL` | PinePaper Studio URL to connect to (`/editor` is appended automatically) | `https://pinepaper.studio` |
 | `PINEPAPER_HEADLESS` | Run the browser headless (set `false` to watch it work) | `true` |
+| `PINEPAPER_IDLE_PAUSE_SECONDS` | Seconds with no tool call before the studio page is paused, so an idle server uses almost no CPU; the next call resumes it. Exports are unaffected. `0` never pauses | `30` |
 | `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` |

package/README.pt-BR.md

@@ -74,7 +74,7 @@ Experimente pedir à sua IA:
 **Local é gratuito e completo.** Todas as ferramentas funcionam se você mesmo
 executar este servidor. Não existe uma versão reduzida.
 
-Requisitos: Node 18 ou mais recente, cerca de **320 MB** de disco (o Puppeteer
+Requisitos: Node 22.13 ou mais recente, cerca de **320 MB** de disco (o Puppeteer
 baixa o Chrome) e aproximadamente 1 GB de memória enquanto um trabalho roda. Em
 um notebook isso é tranquilo; em um VPS pequeno ou uma máquina de trabalho
 restrita, nem tanto.

package/README.zh-CN.md

@@ -74,7 +74,7 @@ npm install -g @pinepaper.studio/mcp-server
 **本地运行免费且功能完整。** 只要你自己运行这个服务器，所有工具都可用，
 没有功能缩水的版本。
 
-需要：Node 18 或更高版本、约 **320 MB** 磁盘空间（Puppeteer 会下载 Chrome），
+需要：Node 22.13 或更高版本、约 **320 MB** 磁盘空间（Puppeteer 会下载 Chrome），
 以及任务运行期间约 1 GB 内存。笔记本电脑没问题，小型 VPS 或受限的办公电脑
 则未必。
 

package/SECURITY.md

@@ -58,3 +58,18 @@ Every outbound request goes through one file, `src/utils/safe-fetch.ts`, on Node
 **No child process in the npm package.** `ffprobe` and `ffmpeg` run through `packages/mcp-ffmpeg`, which is never published (`private`) and is copied only into the Claude Desktop extension's bundle. The server loads it by name when it is there. It runs those two binaries and nothing else, through `execFile` (no shell), with argument lists `src/tools/export-file-receipt.ts` writes and absolute file paths. Without it (any npm install) both features are unavailable and the server says so.
 
 The source contains no `eval` or `new Function`.
+
+## What this package does and why
+
+Supply-chain scanners list the capabilities a package's own code uses. This is each one, where it is in `src/`, and why it is there. `src/__tests__/unit/supply-chain-surface.test.ts` and `capability-footprint.test.ts` fail if any of it spreads to another file.
+
+| Capability | Where | Why |
+|---|---|---|
+| **Network access** | `src/utils/safe-fetch.ts` (the guarded fetch); `src/assets/repositories/` (fixed icon hosts); `src/tools/handlers/generate.ts` (PinePaper Cloud, opt-in) | Importing an image, SVG or font by URL, and searching the free icon repositories. Every user-supplied URL goes through the guarded fetch: private, loopback and link-local addresses and cloud metadata endpoints are refused, and each connection is pinned to the address that passed the check (no DNS rebinding). Generation calls the PinePaper Cloud only when you set `PINEPAPER_API_KEY`; the key is sent only to the cloud URL (`https://cloud.pinepaper.studio`, or `PINEPAPER_CLOUD_URL` if you set it). |
+| **Shell access** | None in this package. `src/tools/export-file-receipt.ts` loads the optional add-on `@pinepaper.studio/mcp-ffmpeg` (`packages/mcp-ffmpeg`), which is private, never published, and bundled only in the Claude Desktop extension (`.mcpb`) | `ffprobe` reads a saved video back to confirm it is what the studio encoded, and `ffmpeg` joins per-scene segments for a `perScene` export. The add-on runs only those two binaries, through `execFile` with argument lists the server writes: no shell, nothing from a tool call is interpreted as a command. Without the add-on, the read-back is skipped and a per-scene export runs whole; `PINEPAPER_FFPROBE=off` turns the read-back off. |
+| **Environment variables** | `src/utils/env.ts` (the complete list, each read by its literal name); one literal read of `PINEPAPER_ALLOW_PRIVATE_NETWORK` in `safe-fetch.ts` | Configuration only: `PINEPAPER_*` settings (browser, tool surface, export folder, asset folders, timeouts, the opt-in cloud key, the code and local-file switches) and the locale (`PINEPAPER_LOCALE`, `LC_ALL`, `LC_MESSAGES`, `LANG`). No value is sent anywhere except `PINEPAPER_API_KEY`, to the PinePaper Cloud, as above. |
+| **Browser code** | `src/types/code-generator.ts` writes it; `src/browser/puppeteer-controller.ts` sends it | Each tool compiles to JavaScript that runs in PinePaper Studio, in a Chrome that puppeteer drives on your machine (or that you paste, in `code` mode). It is sent to that page over the DevTools protocol. Nothing is evaluated in the Node process: the source has no `eval`, `new Function`, `vm` or `inspector`. |
+| **Dynamic import** | `src/browser/puppeteer-controller.ts`; `src/i18n/i18n-manager.ts`; `src/tools/export-file-receipt.ts` | Optional modules load on first use. `puppeteer` and `puppeteer-core` are imported by literal name, resolved from this package's own location (never the working directory, which can be an untrusted checkout). For strict pnpm/Yarn layouts, `PINEPAPER_PUPPETEER_FROM` names a folder they are required from by the same literal names (`createRequire`, Node ≥ 22.13). The one computed import is the ffmpeg add-on above: its name is held in a variable, so the published package never names a package it does not ship. Locale files load from a fixed table, so a locale name never becomes a file path. |
+| **Async context** | `src/tools/handlers.ts` (`AsyncLocalStorage`) | Carries which tool is running to the check that a mutating call changed something, across concurrent calls. |
+
+The package has no install scripts and one runtime dependency (`zod`).

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

@@ -12,6 +12,26 @@ import type { Page } from 'puppeteer';
  */
 export type PageWaitUntil = 'load' | 'domcontentloaded' | 'networkidle0' | 'networkidle2';
 export declare const PAGE_WAIT_UNTIL: readonly PageWaitUntil[];
+/**
+ * FxTool's governor (GeneratedCodeRunner) does not scan code longer than this:
+ * injectLoopGuards and wrapTrailingReturn both give up and run it as written.
+ */
+export declare const GOVERNOR_MAX_CODE_CHARS = 400000;
+/**
+ * Whether app.runGenerated would LOSE this code's value, so it must run
+ * ungoverned instead.
+ *
+ * Every emitter ends in a trailing `(async function () { … })();`, and the
+ * governor only hands its value back by rewriting that into `return (…)`. Past
+ * GOVERNOR_MAX_CODE_CHARS it does not rewrite, so the promise is dropped: the
+ * call answers success with no result AT ONCE while the code keeps running in
+ * the page. A 403-op batch (754 KB, ~1.9 KB per create) replied in 83 ms; the
+ * export sent next started before the batch's set_background ran, and the APNG
+ * came out on the empty page colour, intermittently, depending on who won.
+ * A batch passes the limit at about 215 creates. Running it ungoverned costs
+ * only what the governor had already given up at that size: its loop guards.
+ */
+export declare function governorDropsValue(code: string): boolean;
 export interface BrowserControllerConfig {
     /** PinePaper Studio URL (default: https://pinepaper.studio) */
     studioUrl?: string;
@@ -250,6 +270,24 @@ export declare class PinePaperBrowserController {
      * When agentMode is enabled (default), this automatically uses connectAgent().
      */
     connect(): Promise<void>;
+    private activity;
+    private frozen;
+    private freezing;
+    private idleTimer;
+    private idleSession;
+    /** Milliseconds of no activity before the page is frozen; 0 = never. */
+    static idlePauseMs(): number;
+    /** Whether the page is frozen for idleness right now. */
+    get isIdlePaused(): boolean;
+    /** A tool call starts: stop the idle countdown and thaw the page if it was frozen. */
+    beginActivity(): Promise<void>;
+    /** A tool call ends: when none is left, start the idle countdown. */
+    endActivity(): void;
+    /** Start (or restart) the idle countdown, if a page is up and the pause is on. */
+    scheduleIdlePause(): void;
+    private lifecycleSession;
+    private freezeForIdle;
+    private thaw;
     /**
      * Disconnect and close browser
      */
@@ -404,6 +442,8 @@ export declare class PinePaperBrowserController {
  * NOTE: MCP server ALWAYS uses agent mode with ?agent=1&mode=agent URL parameters.
  * This uses headless browser by default for optimal performance.
  */
+/** The controller if one exists, without creating it (code mode never launches a browser). */
+export declare function peekBrowserController(): PinePaperBrowserController | null;
 export declare function getBrowserController(config?: BrowserControllerConfig): PinePaperBrowserController;
 /**
  * Reset the global controller (for testing or when config needs to change).

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

@@ -13,6 +13,28 @@ 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'];
+/**
+ * FxTool's governor (GeneratedCodeRunner) does not scan code longer than this:
+ * injectLoopGuards and wrapTrailingReturn both give up and run it as written.
+ */
+export const GOVERNOR_MAX_CODE_CHARS = 400_000;
+/**
+ * Whether app.runGenerated would LOSE this code's value, so it must run
+ * ungoverned instead.
+ *
+ * Every emitter ends in a trailing `(async function () { … })();`, and the
+ * governor only hands its value back by rewriting that into `return (…)`. Past
+ * GOVERNOR_MAX_CODE_CHARS it does not rewrite, so the promise is dropped: the
+ * call answers success with no result AT ONCE while the code keeps running in
+ * the page. A 403-op batch (754 KB, ~1.9 KB per create) replied in 83 ms; the
+ * export sent next started before the batch's set_background ran, and the APNG
+ * came out on the empty page colour, intermittently, depending on who won.
+ * A batch passes the limit at about 215 creates. Running it ungoverned costs
+ * only what the governor had already given up at that size: its loop guards.
+ */
+export function governorDropsValue(code) {
+    return code.length > GOVERNOR_MAX_CODE_CHARS;
+}
 /**
  * Is PinePaper Studio actually usable? Evaluated IN THE PAGE, so it closes over
  * nothing.
@@ -83,9 +105,9 @@ 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
+ * headless-browser download with an install script is a large thing to put
+ * in every user's install. A declared peer, optional or not, still puts its whole
+ * tree in an audit 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
@@ -95,23 +117,39 @@ export const BROWSER_TIME = { executeMs: 0, screenshotMs: 0 };
  */
 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.
+ * How each browser driver is found. Every module specifier is a string LITERAL, so a reader sees exactly which two
+ * packages this file can load; nothing here builds a module name at run time.
+ *
+ * `importHere` is an ordinary `import('puppeteer')`. Node resolves a bare specifier from the importing file's own
+ * location, walking up through the node_modules folders above dist/browser/, as it would for a declared dependency:
+ * `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 NOT resolved from process.cwd() (ESM ignores the working directory and
+ * NODE_PATH): an MCP client starts the server in whatever folder is open, which can be a cloned repository, and a
+ * node_modules/puppeteer planted there must not run as this process.
  *
- * 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).
+ * `requireFrom` serves the one other place looked in: a folder the user names in PINEPAPER_PUPPETEER_FROM (an
+ * absolute path), for a strict layout — pnpm with hoist=false, Yarn PnP strict — where a package cannot see its
+ * project's undeclared packages. It requires the same literal specifier from that folder (createRequire), so every
+ * module the package loads is named in its source; it is reached only when the user has set the variable.
  */
+const DRIVERS = {
+    puppeteer: {
+        importHere: () => import('puppeteer'),
+        requireFrom: (req) => req('puppeteer'),
+        packageJson: (req) => req.resolve('puppeteer/package.json'),
+    },
+    'puppeteer-core': {
+        importHere: () => import('puppeteer-core'),
+        requireFrom: (req) => req('puppeteer-core'),
+        packageJson: (req) => req.resolve('puppeteer-core/package.json'),
+    },
+};
+/** Load a driver the user installed beside this package (or in PINEPAPER_PUPPETEER_FROM); null when absent. */
 async function importOptional(name) {
+    const driver = DRIVERS[name];
     const versionFrom = (base) => {
         try {
-            const pkgPath = createRequire(base).resolve(`${name}/package.json`);
+            const pkgPath = driver.packageJson(createRequire(base));
             return String(JSON.parse(readFileSync(pkgPath, 'utf8')).version ?? '') || null;
         }
         catch {
@@ -119,7 +157,7 @@ async function importOptional(name) {
         }
     };
     try {
-        return { mod: await import(name), version: versionFrom(import.meta.url) };
+        return { mod: await driver.importHere(), 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();
@@ -127,8 +165,9 @@ async function importOptional(name) {
         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) };
+        // require() of an ES module (Node ≥ 22.12 unflagged; engines says ≥ 22.13): the literal name, resolved from
+        // the folder the user named, and no import() of a computed path anywhere in the package.
+        return { mod: driver.requireFrom(createRequire(base)), version: versionFrom(base) };
     }
     catch {
         return null;
@@ -141,16 +180,14 @@ function refuseOldPuppeteer(name, version) {
     }
 }
 async function loadPuppeteer() {
-    const fullName = 'puppeteer'; // a variable: see importOptional
-    const full = await importOptional(fullName);
+    const full = await importOptional('puppeteer');
     if (full) {
-        refuseOldPuppeteer(fullName, full.version);
+        refuseOldPuppeteer('puppeteer', full.version);
         return { launch: (opts) => full.mod.default.launch(opts) };
     }
-    const coreName = 'puppeteer-core';
-    const coreLoaded = await importOptional(coreName);
+    const coreLoaded = await importOptional('puppeteer-core');
     if (coreLoaded)
-        refuseOldPuppeteer(coreName, coreLoaded.version);
+        refuseOldPuppeteer('puppeteer-core', coreLoaded.version);
     const core = coreLoaded?.mod ?? null;
     if (core) {
         const executablePath = env('PINEPAPER_CHROME_PATH')?.trim();
@@ -445,10 +482,121 @@ export class PinePaperBrowserController {
             throw new Error(`Failed to connect to PinePaper Studio: ${error instanceof Error ? error.message : 'Unknown error'}`);
         }
     }
+    // ---------------------------------------------------------------------------
+    // IDLE PAUSE (#45). With a scene loaded and nothing asked of it, the studio's
+    // live preview kept animating: 1.49 cores for a 400-item scene on a fast
+    // machine, 0.44 on the tester's VM. Nobody watches a headless preview. After
+    // PINEPAPER_IDLE_PAUSE_SECONDS (default 30; 0 = never) with no tool call in
+    // progress, the page is frozen (CDP Page.setWebLifecycleState), which stops
+    // its timers and animation frames: 0.03 cores. The next tool call thaws it
+    // first. A thawed page came back "hidden", with no animation frames, so focus
+    // emulation is switched on as it thaws, and the preview runs again. Exports
+    // render each frame at its exact time, so a pause changes nothing in a file
+    // (frame digests identical across a freeze, measured).
+    // ---------------------------------------------------------------------------
+    activity = 0;
+    frozen = false;
+    freezing = null;
+    idleTimer = null;
+    idleSession = null;
+    /** Milliseconds of no activity before the page is frozen; 0 = never. */
+    static idlePauseMs() {
+        const v = env('PINEPAPER_IDLE_PAUSE_SECONDS');
+        if (v === undefined || v.trim() === '')
+            return 30_000;
+        const n = Number(v);
+        return Number.isFinite(n) && n > 0 ? n * 1000 : 0;
+    }
+    /** Whether the page is frozen for idleness right now. */
+    get isIdlePaused() {
+        return this.frozen;
+    }
+    /** A tool call starts: stop the idle countdown and thaw the page if it was frozen. */
+    async beginActivity() {
+        this.activity++;
+        if (this.idleTimer) {
+            clearTimeout(this.idleTimer);
+            this.idleTimer = null;
+        }
+        if (this.freezing)
+            await this.freezing.catch(() => undefined);
+        if (this.frozen)
+            await this.thaw();
+    }
+    /** A tool call ends: when none is left, start the idle countdown. */
+    endActivity() {
+        this.activity = Math.max(0, this.activity - 1);
+        if (this.activity === 0)
+            this.scheduleIdlePause();
+    }
+    /** Start (or restart) the idle countdown, if a page is up and the pause is on. */
+    scheduleIdlePause() {
+        const ms = PinePaperBrowserController.idlePauseMs();
+        if (this.idleTimer) {
+            clearTimeout(this.idleTimer);
+            this.idleTimer = null;
+        }
+        if (!ms || !this.page || !this.isConnected || this.activity > 0)
+            return;
+        this.idleTimer = setTimeout(() => { this.idleTimer = null; void this.freezeForIdle(); }, ms);
+        this.idleTimer.unref?.();
+    }
+    async lifecycleSession() {
+        if (!this.page)
+            return null;
+        if (!this.idleSession || this.idleSession.page !== this.page) {
+            this.idleSession = { page: this.page, session: await this.page.createCDPSession() };
+        }
+        return this.idleSession.session;
+    }
+    async freezeForIdle() {
+        if (this.activity > 0 || this.frozen || !this.page)
+            return;
+        this.freezing = (async () => {
+            try {
+                const s = await this.lifecycleSession();
+                if (!s || this.activity > 0)
+                    return;
+                await s.send('Page.setWebLifecycleState', { state: 'frozen' });
+                this.frozen = true;
+            }
+            catch {
+                // A browser that cannot freeze keeps running, as before.
+            }
+        })();
+        try {
+            await this.freezing;
+        }
+        finally {
+            this.freezing = null;
+        }
+        // A call that began during the freeze waited for it; if it is still running, thaw now.
+        if (this.frozen && this.activity > 0)
+            await this.thaw();
+    }
+    async thaw() {
+        try {
+            const s = await this.lifecycleSession();
+            if (s) {
+                await s.send('Page.setWebLifecycleState', { state: 'active' });
+                await s.send('Emulation.setFocusEmulationEnabled', { enabled: true });
+            }
+        }
+        catch {
+            // The page went away while frozen: the call's own recovery takes over.
+        }
+        this.frozen = false;
+    }
     /**
      * Disconnect and close browser
      */
     async disconnect() {
+        if (this.idleTimer) {
+            clearTimeout(this.idleTimer);
+            this.idleTimer = null;
+        }
+        this.frozen = false;
+        this.idleSession = null;
         if (this.browser) {
             try {
                 await this.browser.close();
@@ -726,7 +874,7 @@ export class PinePaperBrowserController {
             // only once app.js has finished, so an early caller races init itself.
             const awaitBoot = BOOTSTRAP_SUBSYSTEMS.some((name) => code.includes(`app.${name}`));
             const runOptions = {
-                bypass: options.bypassGovernor ?? !this.config.governor,
+                bypass: options.bypassGovernor ?? (!this.config.governor || governorDropsValue(code)),
                 timeoutMs: options.governorTimeoutMs,
                 heavyClass: heavyClass ?? null,
                 awaitBoot,
@@ -841,8 +989,8 @@ export class PinePaperBrowserController {
                 // 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.
+                // to be evaluated inside this callback; CDP already does that job, so this
+                // package contains no evaluating call of its own, in the page or in Node.
                 window.__ppBridgeSafe = bridgeSafe;
                 return { success: true, __ppRaw: true, executedVia: 'eval' };
             }, code, runOptions);
@@ -1396,6 +1544,10 @@ let globalController = null;
  * NOTE: MCP server ALWAYS uses agent mode with ?agent=1&mode=agent URL parameters.
  * This uses headless browser by default for optimal performance.
  */
+/** The controller if one exists, without creating it (code mode never launches a browser). */
+export function peekBrowserController() {
+    return globalController;
+}
 export function getBrowserController(config) {
     if (!globalController) {
         // Env resolution lives here, not in the controller: explicit config wins,