pixifact-cli 0.7.0 → 0.8.0

package/README.md

@@ -38,6 +38,7 @@ pixifact scene validate --all
 ```bash
 pixifact runtime list
 pixifact runtime tree --output .pixifact/runtime/tree.json
+pixifact runtime screenshot
 pixifact runtime node <pixi-uid>
 pixifact runtime state
 pixifact runtime logs --after <seq>
@@ -49,6 +50,8 @@ pixifact runtime input key Space
 
 `runtime tree` 默认将节点树输出到终端；传入 `--output <json-path>` 时，改为保存运行时快照 JSON，终端只返回路径和采集元数据。快照包含 `schemaVersion`、`capturedAt`、当前 `runtimeId` 和 `root` 节点树，适合 Agent 使用文本搜索或 JSON 工具分析。快照中的 `runtimeId` 和 PixiJS `uid` 只对本次运行有效，不应写回项目源文件。
 
+`runtime screenshot` 默认将当前 PixiJS Canvas 的 PNG 截图写入项目根下的 `.pixifact/runtime/frame.png`，也可用 `--output <png-path>` 指定路径。截图使用当前 `app.screen` 逻辑尺寸和 renderer 背景色，只包含 `app.stage` 的 PixiJS 渲染内容，不包含浏览器 UI、HTML/CSS 或 DOM overlay；多个页面时添加 `--runtime <runtime-id>`。
+
 ## 浏览器 Editor
 
 在目标项目根目录运行：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixifact-cli",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Pixifact Scene 自动化 CLI。",
   "packageManager": "bun@1.3.13",
   "type": "module",
@@ -32,7 +32,7 @@
     "start": "bun src/pixifact-cli.ts"
   },
   "dependencies": {
-    "pixifact": "^0.7.0",
+    "pixifact": "^0.8.0",
     "vite": "^8.0.10"
   }
 }

package/src/pixifact-cli.ts

@@ -8,7 +8,7 @@ import { CompileSceneError, compileScenes } from 'pixifact/compiler-node';
 import type { SceneValidationDiagnostic } from 'pixifact/compiler';
 import { startEditorServer } from './editorServer';
 import { captureEditorScreenshot, queryEditorContext } from './editorSession';
-import { queryRuntime, queryRuntimeList } from './runtimeSession';
+import { captureRuntimeScreenshot, queryRuntime, queryRuntimeList } from './runtimeSession';
 import type { RuntimeLogLevel, RuntimeRequest } from 'pixifact/runtime-dev';
 import {
     buildPixifactTarget,
@@ -23,6 +23,7 @@ type Automation = ReturnType<typeof createPixifactAutomation>;
 interface CliOptions {
     automation?: Automation;
     captureEditorScreenshot?: typeof captureEditorScreenshot;
+    captureRuntimeScreenshot?: typeof captureRuntimeScreenshot;
     onDevEvent?: (event: PixifactDevEvent) => void;
     readEditorContext?: typeof queryEditorContext;
     listRuntimes?: typeof queryRuntimeList;
@@ -46,6 +47,8 @@ interface ParsedArgs {
     flags: Record<string, string | true>;
 }
 
+const runtimeScreenshotDefaultOutput = '.pixifact/runtime/frame.png';
+
 function parseArgs(argv: string[]): ParsedArgs {
     const positionals: string[] = [];
     const flags: Record<string, string | true> = {};
@@ -274,6 +277,7 @@ async function executeFileCommand(
     captureScreenshot: typeof captureEditorScreenshot = captureEditorScreenshot,
     listRuntimes: typeof queryRuntimeList = queryRuntimeList,
     sendRuntimeRequest: typeof queryRuntime = queryRuntime,
+    captureRuntime: typeof captureRuntimeScreenshot = captureRuntimeScreenshot,
 ) {
     const [area, action] = positionals;
     const projectRoot = projectRootFlag(flags);
@@ -282,6 +286,30 @@ async function executeFileCommand(
         return listRuntimes({ projectRoot });
     }
 
+    if (area === 'runtime' && action === 'screenshot') {
+        assertAllowedFlags(flags, ['output', 'project-root', 'runtime'], 'runtime screenshot');
+        const output = flags.output === undefined
+            ? path.resolve(projectRoot, runtimeScreenshotDefaultOutput)
+            : path.resolve(requireFlag(flags, 'output'));
+        const screenshot = await captureRuntime({
+            projectRoot,
+            runtimeId: optionalFlag(flags, 'runtime'),
+        });
+        if (!screenshot.ok) return screenshot;
+        const capturedAt = new Date().toISOString();
+        fs.mkdirSync(path.dirname(output), { recursive: true });
+        fs.writeFileSync(output, screenshot.data);
+        return {
+            ok: true,
+            runtimeId: screenshot.runtimeId,
+            width: screenshot.width,
+            height: screenshot.height,
+            bytes: screenshot.data.byteLength,
+            output,
+            capturedAt,
+        };
+    }
+
     if (area === 'runtime' && action !== undefined) {
         const runtimeId = optionalFlag(flags, 'runtime');
         let request: RuntimeRequest;
@@ -525,6 +553,7 @@ export async function executePixifactCli(argv: string[], options: CliOptions = {
                     runtimeCommands: [
                         'runtime list',
                         'runtime tree [--output <json-path>] [--runtime <runtime-id>]',
+                        'runtime screenshot [--output <png-path>] [--runtime <runtime-id>]',
                         'runtime node <pixi-uid> [--runtime <runtime-id>]',
                         'runtime state [--runtime <runtime-id>]',
                         'runtime logs [--after <seq>] [--level <level>] [--runtime <runtime-id>]',
@@ -544,6 +573,7 @@ export async function executePixifactCli(argv: string[], options: CliOptions = {
                     nodeLocatorSource: 'scene inspect --scene <scene-path> returns node locator values',
                     defaults: {
                         projectRoot: 'current working directory',
+                        runtimeScreenshotOutput: runtimeScreenshotDefaultOutput,
                     },
                 }),
                 stderr: '',
@@ -561,6 +591,7 @@ export async function executePixifactCli(argv: string[], options: CliOptions = {
             options.captureEditorScreenshot,
             options.listRuntimes,
             options.queryRuntime,
+            options.captureRuntimeScreenshot,
         );
         if (isFailedResult(result)) {
             return {

package/src/runtimeSession.ts

@@ -4,6 +4,8 @@ import {
 } from 'pixifact/compiler-node';
 import type { RuntimePageDescriptor, RuntimeRequest } from 'pixifact/runtime-dev';
 
+const pngSignature = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+
 interface RuntimeSessionLookupOptions {
     projectRoot: string;
     sessionsRoot?: string;
@@ -131,3 +133,61 @@ export async function queryRuntime(options: RuntimeQueryOptions) {
         }),
     });
 }
+
+export async function captureRuntimeScreenshot(
+    options: RuntimeSessionLookupOptions & { runtimeId?: string },
+): Promise<
+    | { ok: true; runtimeId: string; width: number; height: number; data: Uint8Array }
+    | { ok: false; error: string; [key: string]: unknown }
+> {
+    const active = await activeDescriptor(options);
+    if (!active.ok) return active;
+    const fetcher = options.fetch ?? fetch;
+    const listed = await runtimeHostFetch(active.descriptor, 'list', fetcher);
+    if (listed.ok !== true || !Array.isArray(listed.runtimes)) return listed;
+    const selected = selectRuntime(
+        listed.runtimes as Array<RuntimePageDescriptor & { connectedAt: string }>,
+        options.runtimeId,
+    );
+    if (!selected.ok) return selected;
+
+    let response: Response;
+    try {
+        response = await fetcher(`${active.descriptor.origin}/__pixifact_runtime__/screenshot`, {
+            method: 'POST',
+            headers: {
+                authorization: `Bearer ${active.descriptor.token}`,
+                'content-type': 'application/json',
+            },
+            body: JSON.stringify({ runtimeId: selected.runtime.runtimeId }),
+        });
+    } catch {
+        return {
+            ok: false,
+            error: 'Pixifact Runtime Vite server is not reachable for this project.',
+        };
+    }
+    if (!response.ok) {
+        return await response.json() as { ok: false; error: string; [key: string]: unknown };
+    }
+
+    const runtimeId = response.headers.get('x-pixifact-runtime');
+    const width = Number(response.headers.get('x-pixifact-width'));
+    const height = Number(response.headers.get('x-pixifact-height'));
+    if (
+        response.headers.get('content-type') !== 'image/png'
+        || runtimeId !== selected.runtime.runtimeId
+        || !Number.isInteger(width)
+        || width <= 0
+        || !Number.isInteger(height)
+        || height <= 0
+    ) {
+        return { ok: false, error: 'Pixifact Runtime Host returned invalid screenshot metadata.' };
+    }
+
+    const data = new Uint8Array(await response.arrayBuffer());
+    if (!Buffer.from(data.subarray(0, pngSignature.length)).equals(pngSignature)) {
+        return { ok: false, error: 'Pixifact Runtime Host did not return PNG screenshot data.' };
+    }
+    return { ok: true, runtimeId, width, height, data };
+}

package/src/viteTarget.ts

@@ -1,4 +1,4 @@
-import { access, readFile, readdir, stat } from 'node:fs/promises';
+import { access, readFile, readdir, realpath, stat } from 'node:fs/promises';
 import path from 'node:path';
 import {
     build,
@@ -55,7 +55,7 @@ export class PixifactTargetError extends Error {
 }
 
 export async function validatePixifactTarget(projectRootInput: string, mode: string) {
-    const projectRoot = path.resolve(projectRootInput);
+    const projectRoot = await realpath(path.resolve(projectRootInput));
     const { platform } = loadPixifactEnv(projectRoot, mode);
     const config = parsePixifactProjectConfig(JSON.parse(await readFile(
         path.join(projectRoot, pixifactProjectConfigFileName),