multiplane 0.3.0 → 0.3.3

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.
@@ -252,6 +254,8 @@ npx multiplane stills shot.html --every 0.5
 
 ## 3D layer
 
+The desktop app and its bundled command already include three.js (pinned at 0.180.0) for the 3D layer; nothing else to install. With the npm package, three.js is an optional dependency that projects using the 3D layer install themselves:
+
 ```sh
 npm install three@0.180.0
 ```

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 会话。
@@ -252,6 +254,8 @@ npx multiplane stills shot.html --every 0.5
 
 ## 三维层
 
+用桌面软件或它自带的命令行渲染时，三维层要用的 three.js（固定 0.180.0）已经带在软件里，不用另装。通过 npm 使用时，three.js 是可选依赖，用三维层的项目自己装：
+
 ```sh
 npm install three@0.180.0
 ```

package/package.json

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

package/skills/multiplane/SKILL.md

@@ -117,7 +117,7 @@ Use `/* multiplane-disable-next-line css_animation */` in CSS and `<!-- multipla
 
 ## 3D layer (optional)
 
-Use `multiplane/three` when you need 3D cards or depth of field. Install `three@0.180.0` in the project (`npm install three@0.180.0`).
+Use `multiplane/three` when you need 3D cards or depth of field. When the renderer is the desktop app's bundled command, three.js 0.180.0 is already included. With the npm package, install `three@0.180.0` in the project (`npm install three@0.180.0`). `multiplane doctor` reports whether three.js is available, its version and where it comes from.
 
 ```html
 <script type="importmap">{"imports":{

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/doctor.mjs

@@ -3,6 +3,7 @@ import { runCommand } from './events.mjs';
 import { launchBrowser, environment, warnGpuFallback } from './environment.mjs';
 import { inspectFFmpeg, ffmpegOutput } from './ffmpeg.mjs';
 import { MultiplaneError } from './errors.mjs';
+import { threeCheck } from './three-package.mjs';
 
 export function benchmarkCheck(record, machine) {
   const current = validBenchmark(record, machine);
@@ -48,8 +49,7 @@ export const doctor = (options = {}) => runCommand('doctor', null, options, asyn
     for (const name of ['libvpx-vp9', 'prores_ks']) checks.push({ name, ok: false, detail: `${name} is optional; encoder availability could not be inspected.` });
   }
   if (info) events.emit('environment', { ...info, ffmpeg: ffmpeg ?? null });
-  try { await import('three'); checks.push({ name: 'three', ok: true, detail: 'Optional three.js is available.' }); }
-  catch { checks.push({ name: 'three', ok: false, detail: 'Optional three.js is not installed.' }); }
+  checks.push(await threeCheck());
   if (failure && checks.some(c => ['ffmpeg', 'libx264'].includes(c.name) && !c.ok)) failure.hint = (failure.hint ? failure.hint + ' ' : '') + 'Run multiplane config set ffmpeg <path> to save an FFmpeg executable.';
   if (failure) { failure.result = { data: { checks, config: events.config } }; throw failure; }
   return { checks, config: events.config };

package/src/server.mjs

@@ -5,6 +5,7 @@ import { stat, readdir } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { MultiplaneError, invalidOption } from './errors.mjs';
+import { resolveThree } from './three-package.mjs';
 
 export const root = process.cwd();
 const packageRoot = fileURLToPath(new URL('../', import.meta.url));
@@ -52,7 +53,7 @@ export async function startServer(port = 0, root = process.cwd()) {
         if (pathname.startsWith('/multiplane/runtime/')) { resourceRoot = path.join(packageRoot, 'src/runtime'); resourcePath = pathname.slice('/multiplane/runtime'.length); }
         else if (pathname === '/multiplane/three.js') { resourceRoot = path.join(packageRoot, 'src/three'); resourcePath = '/index.js'; }
         else if (pathname.startsWith('/multiplane/vendor/three/')) {
-          resourceRoot = path.dirname(path.dirname(fileURLToPath(import.meta.resolve('three'))));
+          resourceRoot = (await resolveThree()).root;
           resourcePath = pathname.slice('/multiplane/vendor/three'.length);
           if (!/^\/(build|examples\/jsm)\/.*\.js$/.test(resourcePath)) { res.writeHead(403); return res.end(); }
         } else { res.writeHead(404); return res.end(); }

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'

package/src/three-package.mjs

@@ -0,0 +1,26 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Desktop bundles keep the tested subset separate from optional npm peers.
+export async function resolveThree() {
+  let root = fileURLToPath(new URL('../vendor/three/', import.meta.url));
+  let source = 'bundled';
+  let pkg;
+  try { pkg = JSON.parse(await readFile(path.join(root, 'package.json'), 'utf8')); }
+  catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    root = path.dirname(path.dirname(fileURLToPath(import.meta.resolve('three'))));
+    pkg = JSON.parse(await readFile(path.join(root, 'package.json'), 'utf8'));
+    source = 'project';
+  }
+  return { root, version: pkg.version, source };
+}
+
+export async function threeCheck() {
+  try {
+    const { root, version, source } = await resolveThree();
+    await readFile(path.join(root, 'build/three.module.js'));
+    return { name: 'three', ok: true, detail: `three.js ${version} is available (${source === 'bundled' ? 'bundled with software' : 'installed by project'}).` };
+  } catch { return { name: 'three', ok: false, detail: 'Optional three.js is not installed.' }; }
+}