multiplane 0.3.0 → 0.3.1

package/README.en.md

@@ -48,9 +48,11 @@ Requires Node.js 24 or later and FFmpeg with libx264 support.
 npm install multiplane
 npx playwright install chromium
 npx multiplane doctor
-npx multiplane render node_modules/multiplane/examples/animation.html
+npx multiplane render examples/animation.html --root node_modules/multiplane
 ```
 
+The examples live inside the installed package, so `--root` points the resource root at the package; for safety, renders never serve files from under `node_modules`.
+
 Recent npm versions do not run install scripts of dependencies, so the second command downloads the Chromium build that Playwright uses. To work from a clone of this repository instead, run `npm install` in it and render `examples/animation.html` directly.
 
 Give your agent the usage skill with `npx multiplane skill install --host all` (Claude Code: `~/.claude/skills/multiplane`, Codex: `~/.agents/skills/multiplane`), or let the desktop app install it. Start a new agent session afterwards.

package/README.md

@@ -48,9 +48,11 @@
 npm install multiplane
 npx playwright install chromium
 npx multiplane doctor
-npx multiplane render node_modules/multiplane/examples/animation.html
+npx multiplane render examples/animation.html --root node_modules/multiplane
 ```
 
+示例在安装好的包里，所以用 `--root` 把资源根指向包目录；出于安全，渲染时不会提供 `node_modules` 下的文件。
+
 新版 npm 默认不运行依赖包的安装脚本，所以第二条命令用来下载 Playwright 使用的 Chromium。如果是克隆了本仓库，在仓库里运行 `npm install`，直接渲染 `examples/animation.html` 即可。
 
 把使用说明 skill 交给你的 agent：运行 `npx multiplane skill install --host all`（Claude Code 装到 `~/.claude/skills/multiplane`，Codex 装到 `~/.agents/skills/multiplane`），或者让桌面软件来安装。装好后新开一个 agent 会话。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "multiplane",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "module",
   "license": "Apache-2.0",
   "publishConfig": {

package/src/capture.mjs

@@ -35,6 +35,10 @@ async function openShotOnce(shot, scale = 1, options = {}) {
     relative = path.relative(root, await normalizeResourcePath(entry));
   }
   if (path.extname(relative).toLowerCase() !== '.html') throw invalidOption('shot', 'Shot must be an HTML file.');
+  if (relative.split(path.sep).includes('node_modules')) throw new MultiplaneError('shot_outside_root', undefined, {
+    details: { path: relative },
+    hint: 'Files under node_modules are not served. Use --root to point to the package directory (for example, --root node_modules/multiplane).',
+  });
   try { await access(entry); } catch { throw new MultiplaneError('shot_not_found'); }
   const server = await startServer(0, root);
   let browser, page, crashed = false;
@@ -42,7 +46,7 @@ async function openShotOnce(shot, scale = 1, options = {}) {
     browser = await launchBrowser(options);
     await options.onBrowser?.(browser);
     page = await browser.newPage({ viewport: { width: 1920, height: 1080 }, deviceScaleFactor: scale });
-    if (reuseEnabled(options)) await page.addInitScript(installStaticObserver);
+    if (reuseEnabled(options)) await page.addInitScript(installStaticObserver, { platform: process.platform });
     page.on('crash', () => { crashed = true; });
     const errors = [];
     const observerProbe = request => {
@@ -57,8 +61,12 @@ async function openShotOnce(shot, scale = 1, options = {}) {
     page.on('response', response => { if (response.status() >= 400 && !observerProbe(response.request())) errors.push(new MultiplaneError(response.headers()['x-multiplane-error'] === 'three_not_installed' ? 'three_not_installed' : 'resource_failed', undefined, { details: { status: response.status(), url: response.url() } })); });
     page.on('requestfailed', request => { if (!observerProbe(request)) errors.push(new MultiplaneError('resource_failed', undefined, { details: { url: request.url() } })); });
     const url = `${server.url}/${relative.split(path.sep).map(encodeURIComponent).join('/')}?mode=render`;
-    const response = await page.goto(url).catch(cause => { throw new MultiplaneError('shot_load_failed', undefined, { cause }); });
-    if (!response.ok()) throw new MultiplaneError('shot_load_failed');
+    const response = await page.goto(url).catch(cause => {
+      const failedResponse = errors.find(error => error.details?.url === url && error.details.status);
+      throw new MultiplaneError('shot_load_failed', undefined, { cause,
+        details: { path: relative, url, status: failedResponse?.details.status ?? null, reason: cause.message } });
+    });
+    if (!response?.ok()) throw new MultiplaneError('shot_load_failed', undefined, { details: { path: relative, url, status: response?.status() ?? null } });
     if (errors.length) throw errors[0];
     if (!await page.evaluate(() => typeof window.SHOT?.render === 'function')) throw new MultiplaneError('shot_contract_invalid');
     const metadata = await page.evaluate(async () => {

package/src/static-reuse.mjs

@@ -47,7 +47,7 @@ export async function* verifiedFrames(source, options, count, { owned = false }
 }
 
 // Runs before any shot script, so saved drawing functions are instrumented too.
-export function installStaticObserver() {
+export function installStaticObserver({ platform } = {}) {
   let dirty = true, suspended = false, unsafe = false, styleSignature, stylesDirty = true, stylesUnsafe = false, previousSheets = [], readingStyles = false;
   const exposedDeclarations = new Map();
   let reason = null;
@@ -248,6 +248,8 @@ export function installStaticObserver() {
     finally { readingStyles = false; }
   };
   const uncertain = () => unsafe ? 'unobservable_api' : !hooks.every(check => check()) ? 'hook_replaced'
+    // Native macOS textarea scrollbars can animate outside observable DOM/CSS state.
+    : platform === 'darwin' && document.querySelector('textarea') ? 'unobservable_api'
     : document.querySelector('video,iframe,object,embed,marquee,animate,animateTransform,animateMotion,set') ? 'dynamic_element'
     : document.activeElement?.matches('input,textarea,[contenteditable]:not([contenteditable="false"])') ? 'editable_focus'
     : document.getAnimations().some(animation => animation.playState === 'running' || (animation.pending && animation.playState !== 'paused')) || document.fonts.status !== 'loaded' ? 'animation_or_font'