pixifact-cli 0.5.0 → 0.6.1

package/editor/assets/init-CuKNsO_k.js

@@ -0,0 +1 @@
+import{n as e,r as t,t as n,u as r}from"./index-DoPhYWF1.js";r.add(n,t),r.add(e);

package/editor/assets/webworkerAll-DM9kdU0t.js

@@ -0,0 +1 @@
+import"./index-DoPhYWF1.js";import"./init-CuKNsO_k.js";

package/editor/index.html

@@ -4,8 +4,8 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Pixifact Editor</title>
-    <script type="module" crossorigin src="/assets/index-CAe9Mkmr.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-CVrKIfXK.css">
+    <script type="module" crossorigin src="/assets/index-DoPhYWF1.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-D3t5XxiB.css">
   </head>
   <body>
     <div id="app"></div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixifact-cli",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Pixifact Scene 自动化 CLI。",
   "packageManager": "bun@1.3.13",
   "type": "module",
@@ -33,6 +33,6 @@
   },
   "dependencies": {
     "esbuild": "^0.27.2",
-    "pixifact": "^0.5.0"
+    "pixifact": "^0.6.1"
   }
 }

package/src/automation.ts

@@ -432,7 +432,7 @@ function validateAllCompilerScenes(root: string) {
     const failures = results.filter((result): result is CompilerSceneValidationFailure => !result.ok);
     const scenes = results
         .filter((result): result is CompilerSceneValidationSuccess => result.ok)
-        .map(({ scenePath, revision, summary }) => ({ scenePath, revision, summary }));
+        .map(({ scenePath, revision }) => ({ scenePath, revision }));
     if (failures.length > 0) {
         return {
             ok: false as const,
@@ -447,7 +447,6 @@ function validateAllCompilerScenes(root: string) {
         ok: true as const,
         projectRoot: root,
         sceneCount: results.length,
-        scenes,
     };
 }
 
@@ -637,7 +636,7 @@ export function createPixifactAutomation() {
             const nodeId = assertString(args.node, 'node');
             const node = collectDetailedCompilerNodes(template.children).find((item) => item.locator === nodeId);
             if (!node) {
-                throw new Error(`Node "${nodeId}" was not found.`);
+                throw new Error(`Node locator "${nodeId}" was not found.`);
             }
             return node;
         },

package/src/editorSession.ts

@@ -4,9 +4,10 @@ import os from 'node:os';
 import path from 'node:path';
 import { parseSceneTemplate } from 'pixifact/compiler';
 
-export const editorSessionProtocolVersion = 2;
+export const editorSessionProtocolVersion = 3;
 
 export type EditorContextSyncState = 'synced' | 'saving' | 'conflict' | 'error';
+export type EditorPreviewState = 'loading' | 'ready' | 'error';
 
 export type EditorNodeContext =
     | {
@@ -41,6 +42,7 @@ export type EditorSelectionContext =
 export interface EditorBrowserContext {
     scene: {
         path: string;
+        previewState: EditorPreviewState;
         revision: string;
         syncState: EditorContextSyncState;
     };
@@ -75,6 +77,7 @@ interface EditorBrowserSocket {
 
 interface EditorHostSessionOptions {
     projectRoot: string;
+    screenshotTimeoutMs?: number;
     token: string;
     now?: () => Date;
 }
@@ -89,6 +92,25 @@ interface ClaimEditorSessionOptions extends EditorSessionLookupOptions {
     descriptor: EditorSessionDescriptor;
 }
 
+interface PendingEditorScreenshot {
+    browser: EditorBrowserSocket;
+    resolve(response: Response): void;
+    scene: {
+        path: string;
+        revision: string;
+    };
+    timeout: ReturnType<typeof setTimeout>;
+}
+
+export interface EditorScreenshotResult {
+    ok: true;
+    scene: string;
+    revision: string;
+    width: number;
+    height: number;
+    data: Uint8Array;
+}
+
 function jsonResponse(value: unknown, status = 200) {
     return Response.json(value, { status });
 }
@@ -138,6 +160,7 @@ function isEditorBrowserContext(value: unknown): value is EditorBrowserContext {
         typeof value.scene.path !== 'string'
         || typeof value.scene.revision !== 'string'
         || !['synced', 'saving', 'conflict', 'error'].includes(String(syncState))
+        || !['loading', 'ready', 'error'].includes(String(value.scene.previewState))
     ) {
         return false;
     }
@@ -152,10 +175,29 @@ function isEditorBrowserContext(value: unknown): value is EditorBrowserContext {
 export function createEditorHostSession(options: EditorHostSessionOptions) {
     const projectRoot = fs.realpathSync(options.projectRoot);
     const now = options.now ?? (() => new Date());
+    const screenshotTimeoutMs = options.screenshotTimeoutMs ?? 10_000;
     const browsers = new Set<EditorBrowserSocket>();
+    const pendingScreenshots = new Map<string, PendingEditorScreenshot>();
     let activeBrowser: EditorBrowserSocket | undefined;
     let context: EditorContext | undefined;
     let resume: EditorSessionResumeState | undefined;
+    let screenshotSequence = 0;
+
+    function settleScreenshot(requestId: string, response: Response) {
+        const pending = pendingScreenshots.get(requestId);
+        if (!pending) return;
+        pendingScreenshots.delete(requestId);
+        clearTimeout(pending.timeout);
+        pending.resolve(response);
+    }
+
+    function rejectBrowserScreenshots(browser: EditorBrowserSocket, error: string) {
+        for (const [requestId, pending] of pendingScreenshots) {
+            if (pending.browser === browser) {
+                settleScreenshot(requestId, jsonResponse({ ok: false, error }, 409));
+            }
+        }
+    }
 
     function sendState(
         socket: EditorBrowserSocket,
@@ -190,6 +232,7 @@ export function createEditorHostSession(options: EditorHostSessionOptions) {
     function close(socket: EditorBrowserSocket) {
         browsers.delete(socket);
         if (socket === activeBrowser) {
+            rejectBrowserScreenshots(socket, 'Active Editor browser disconnected during screenshot capture.');
             activeBrowser = undefined;
             context = undefined;
         }
@@ -209,6 +252,9 @@ export function createEditorHostSession(options: EditorHostSessionOptions) {
                 return;
             }
             const previous = activeBrowser;
+            if (previous) {
+                rejectBrowserScreenshots(previous, 'Active Editor browser changed during screenshot capture.');
+            }
             activeBrowser = socket;
             context = undefined;
             for (const browser of browsers) {
@@ -222,6 +268,57 @@ export function createEditorHostSession(options: EditorHostSessionOptions) {
             }
             return;
         }
+        if (
+            socket === activeBrowser
+            && (parsed.type === 'editorScreenshotCompleted' || parsed.type === 'editorScreenshotFailed')
+        ) {
+            const requestId = typeof parsed.requestId === 'string' ? parsed.requestId : '';
+            const pending = pendingScreenshots.get(requestId);
+            if (!pending || pending.browser !== socket) return;
+            if (parsed.type === 'editorScreenshotFailed') {
+                const error = typeof parsed.error === 'string'
+                    ? parsed.error
+                    : 'Editor browser failed to capture the Scene screenshot.';
+                settleScreenshot(requestId, jsonResponse({ ok: false, error }, 500));
+                return;
+            }
+            if (
+                !isRecord(parsed.scene)
+                || parsed.scene.path !== pending.scene.path
+                || parsed.scene.revision !== pending.scene.revision
+                || !Number.isInteger(parsed.width)
+                || Number(parsed.width) <= 0
+                || !Number.isInteger(parsed.height)
+                || Number(parsed.height) <= 0
+                || typeof parsed.dataUrl !== 'string'
+            ) {
+                settleScreenshot(requestId, jsonResponse({
+                    ok: false,
+                    error: 'Editor browser returned an invalid screenshot response.',
+                }, 502));
+                return;
+            }
+            const match = parsed.dataUrl.match(/^data:image\/png;base64,([A-Za-z0-9+/]+={0,2})$/);
+            const png = match ? Buffer.from(match[1], 'base64') : undefined;
+            if (!png || !png.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))) {
+                settleScreenshot(requestId, jsonResponse({
+                    ok: false,
+                    error: 'Editor browser did not return PNG screenshot data.',
+                }, 502));
+                return;
+            }
+            settleScreenshot(requestId, new Response(png, {
+                headers: {
+                    'cache-control': 'no-store',
+                    'content-type': 'image/png',
+                    'x-pixifact-height': String(parsed.height),
+                    'x-pixifact-revision': pending.scene.revision,
+                    'x-pixifact-scene': encodeURIComponent(pending.scene.path),
+                    'x-pixifact-width': String(parsed.width),
+                },
+            }));
+            return;
+        }
         if (socket !== activeBrowser || parsed.type !== 'editorContextChanged') return;
         if (!isEditorBrowserContext(parsed.context)) {
             throw new Error('Editor context message is invalid.');
@@ -244,7 +341,7 @@ export function createEditorHostSession(options: EditorHostSessionOptions) {
         notifyStandbyBrowsers();
     }
 
-    function contextResponse() {
+    function synchronizedContext() {
         if (!activeBrowser) {
             return jsonResponse({
                 ok: false,
@@ -297,12 +394,54 @@ export function createEditorHostSession(options: EditorHostSessionOptions) {
                 },
             }, 409);
         }
-        return jsonResponse(context);
+        return context;
+    }
+
+    function contextResponse() {
+        const result = synchronizedContext();
+        return result instanceof Response ? result : jsonResponse(result);
+    }
+
+    function screenshotResponse() {
+        const result = synchronizedContext();
+        if (result instanceof Response) return result;
+        if (result.scene.previewState !== 'ready') {
+            return jsonResponse({
+                ok: false,
+                error: 'Editor Scene preview is not ready.',
+                previewState: result.scene.previewState,
+            }, 409);
+        }
+        const browser = activeBrowser!;
+        const requestId = `screenshot-${++screenshotSequence}`;
+        const scene = {
+            path: result.scene.path,
+            revision: result.scene.revision,
+        };
+        return new Promise<Response>((resolve) => {
+            const timeout = setTimeout(() => {
+                settleScreenshot(requestId, jsonResponse({
+                    ok: false,
+                    error: 'Editor screenshot capture timed out.',
+                }, 504));
+            }, screenshotTimeoutMs);
+            pendingScreenshots.set(requestId, { browser, resolve, scene, timeout });
+            browser.send(JSON.stringify({
+                type: 'editorScreenshotRequested',
+                protocolVersion: editorSessionProtocolVersion,
+                requestId,
+                scene,
+            }));
+        });
     }
 
     function fetchRequest(request: Request) {
         const pathname = new URL(request.url).pathname;
-        if (pathname !== '/api/editor-session/health' && pathname !== '/api/editor-context') {
+        if (
+            pathname !== '/api/editor-session/health'
+            && pathname !== '/api/editor-context'
+            && pathname !== '/api/editor-screenshot'
+        ) {
             return undefined;
         }
         if (!authorizationMatches(request, options.token)) {
@@ -314,6 +453,12 @@ export function createEditorHostSession(options: EditorHostSessionOptions) {
                 projectRoot,
             });
         }
+        if (pathname === '/api/editor-screenshot') {
+            if (request.method !== 'POST') {
+                return jsonResponse({ ok: false, error: 'Editor screenshot requires POST.' }, 405);
+            }
+            return screenshotResponse();
+        }
         return contextResponse();
     }
 
@@ -488,3 +633,65 @@ export async function queryEditorContext(options: EditorSessionLookupOptions) {
         };
     }
 }
+
+export async function captureEditorScreenshot(
+    options: EditorSessionLookupOptions,
+): Promise<EditorScreenshotResult | { ok: false; error: string; [key: string]: unknown }> {
+    const projectRoot = fs.realpathSync(options.projectRoot);
+    const descriptor = readEditorSessionDescriptor(projectRoot, options.sessionsRoot);
+    if (!descriptor) {
+        return {
+            ok: false,
+            error: 'No Pixifact Editor Host is running for this project.',
+        };
+    }
+    if (descriptor.projectRoot !== projectRoot) {
+        return {
+            ok: false,
+            error: 'Pixifact Editor session belongs to a different project.',
+        };
+    }
+    const fetcher = options.fetch ?? fetch;
+    let response: Response;
+    try {
+        response = await fetcher(`${descriptor.origin}/api/editor-screenshot`, {
+            method: 'POST',
+            headers: { authorization: `Bearer ${descriptor.token}` },
+        });
+    } catch {
+        return {
+            ok: false,
+            error: 'Pixifact Editor Host is not reachable for this project.',
+        };
+    }
+    if (!response.ok) {
+        return await response.json() as { ok: false; error: string; [key: string]: unknown };
+    }
+    const sceneHeader = response.headers.get('x-pixifact-scene');
+    const revision = response.headers.get('x-pixifact-revision');
+    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'
+        || !sceneHeader
+        || !revision
+        || !Number.isInteger(width)
+        || width <= 0
+        || !Number.isInteger(height)
+        || height <= 0
+    ) {
+        return { ok: false, error: 'Pixifact Editor Host returned invalid screenshot metadata.' };
+    }
+    const data = new Uint8Array(await response.arrayBuffer());
+    if (!Buffer.from(data.subarray(0, 8)).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))) {
+        return { ok: false, error: 'Pixifact Editor Host did not return PNG screenshot data.' };
+    }
+    return {
+        ok: true,
+        scene: decodeURIComponent(sceneHeader),
+        revision,
+        width,
+        height,
+        data,
+    };
+}

package/src/pixifact-cli.ts

@@ -1,10 +1,14 @@
 #!/usr/bin/env bun
+import fs from 'node:fs';
+import path from 'node:path';
 import { createPixifactAutomation } from './automation';
 import { hintForCommandError } from 'pixifact';
 import { CompileSceneError, compileScenes } from 'pixifact/compiler-node';
 import type { SceneValidationDiagnostic } from 'pixifact/compiler';
 import { startEditorServer } from './editorServer';
-import { queryEditorContext } from './editorSession';
+import { captureEditorScreenshot, queryEditorContext } from './editorSession';
+import { queryRuntime, queryRuntimeList } from './runtimeSession';
+import type { RuntimeLogLevel, RuntimeRequest } from 'pixifact/runtime-dev';
 import {
     buildWechatTarget,
     devWechatTarget,
@@ -17,8 +21,11 @@ type Automation = ReturnType<typeof createPixifactAutomation>;
 
 interface CliOptions {
     automation?: Automation;
+    captureEditorScreenshot?: typeof captureEditorScreenshot;
     onWechatDevEvent?: (event: WechatDevEvent) => void;
     readEditorContext?: typeof queryEditorContext;
+    listRuntimes?: typeof queryRuntimeList;
+    queryRuntime?: typeof queryRuntime;
     startEditor?: typeof startEditorServer;
 }
 
@@ -82,6 +89,23 @@ function projectRootFlag(flags: Record<string, string | true>) {
     return requireFlag(flags, 'project-root');
 }
 
+function optionalFlag(flags: Record<string, string | true>, name: string) {
+    const value = flags[name];
+    return value === undefined ? undefined : requireFlag(flags, name);
+}
+
+function finiteNumberFlag(flags: Record<string, string | true>, name: string) {
+    const value = Number(requireFlag(flags, name));
+    if (!Number.isFinite(value)) throw new Error(`--${name} must be a finite number.`);
+    return value;
+}
+
+function nonNegativeInteger(value: string | undefined, error: string) {
+    const number = Number(value);
+    if (!Number.isInteger(number) || number < 0) throw new Error(error);
+    return number;
+}
+
 function jsonLine(value: unknown) {
     return `${JSON.stringify(value, null, 2)}\n`;
 }
@@ -92,6 +116,13 @@ function isFailedResult(value: unknown): value is CliJsonResult {
         && (value as CliJsonResult).ok === false;
 }
 
+function isRuntimeTreeResult(value: unknown): value is { runtimeId: string; root: unknown } {
+    return typeof value === 'object'
+        && value !== null
+        && typeof (value as { runtimeId?: unknown }).runtimeId === 'string'
+        && 'root' in value;
+}
+
 function compileScenesFailure(error: unknown): CliJsonResult {
     const message = error instanceof Error ? error.message : String(error);
     if (error instanceof CompileSceneError) {
@@ -228,10 +259,88 @@ async function executeFileCommand(
     onWechatDevEvent?: (event: WechatDevEvent) => void,
     startEditor: typeof startEditorServer = startEditorServer,
     readEditorContext: typeof queryEditorContext = queryEditorContext,
+    captureScreenshot: typeof captureEditorScreenshot = captureEditorScreenshot,
+    listRuntimes: typeof queryRuntimeList = queryRuntimeList,
+    sendRuntimeRequest: typeof queryRuntime = queryRuntime,
 ) {
     const [area, action] = positionals;
     const projectRoot = projectRootFlag(flags);
 
+    if (area === 'runtime' && action === 'list') {
+        return listRuntimes({ projectRoot });
+    }
+
+    if (area === 'runtime' && action !== undefined) {
+        const runtimeId = optionalFlag(flags, 'runtime');
+        let request: RuntimeRequest;
+        if (action === 'tree') {
+            request = { type: 'tree' };
+        } else if (action === 'node') {
+            request = {
+                type: 'node',
+                uid: nonNegativeInteger(
+                    positionals[2],
+                    'Runtime node uid must be a non-negative integer.',
+                ),
+            };
+        } else if (action === 'state') {
+            request = { type: 'state' };
+        } else if (action === 'logs') {
+            const after = flags.after === undefined
+                ? undefined
+                : nonNegativeInteger(requireFlag(flags, 'after'), '--after must be a non-negative integer.');
+            const level = optionalFlag(flags, 'level');
+            if (level && !['debug', 'log', 'info', 'warn', 'error'].includes(level)) {
+                throw new Error('--level must be debug, log, info, warn, or error.');
+            }
+            request = {
+                type: 'logs',
+                ...(after === undefined ? {} : { after }),
+                ...(level === undefined ? {} : { level: level as RuntimeLogLevel }),
+            };
+        } else if (action === 'input') {
+            const inputAction = positionals[2];
+            if (inputAction === 'click' || inputAction === 'move') {
+                request = {
+                    type: 'input',
+                    action: inputAction,
+                    x: finiteNumberFlag(flags, 'x'),
+                    y: finiteNumberFlag(flags, 'y'),
+                };
+            } else if (inputAction === 'key' || inputAction === 'keydown' || inputAction === 'keyup') {
+                const key = positionals[3];
+                if (!key) throw new Error(`runtime input ${inputAction} requires a key.`);
+                request = { type: 'input', action: inputAction, key };
+            } else {
+                throw new Error(`Unknown Pixifact Runtime input "${inputAction ?? ''}".`);
+            }
+        } else {
+            throw new Error(`Unknown Pixifact CLI command "${positionals.join(' ')}".`);
+        }
+        const result = await sendRuntimeRequest({ projectRoot, runtimeId, request });
+        if (action !== 'tree' || flags.output === undefined || isFailedResult(result)) {
+            return result;
+        }
+        if (!isRuntimeTreeResult(result)) {
+            throw new Error('Pixifact Runtime returned an invalid tree response.');
+        }
+        const output = path.resolve(requireFlag(flags, 'output'));
+        const capturedAt = new Date().toISOString();
+        fs.mkdirSync(path.dirname(output), { recursive: true });
+        fs.writeFileSync(output, jsonLine({
+            schemaVersion: 1,
+            capturedAt,
+            runtimeId: result.runtimeId,
+            root: result.root,
+        }), 'utf8');
+        return {
+            ok: true,
+            output,
+            runtimeId: result.runtimeId,
+            capturedAt,
+        };
+    }
+
     if (area === 'editor' && action === undefined) {
         const session = await startEditor({ projectRoot });
         return {
@@ -245,6 +354,22 @@ async function executeFileCommand(
         return readEditorContext({ projectRoot });
     }
 
+    if (area === 'editor' && action === 'screenshot') {
+        const output = path.resolve(requireFlag(flags, 'output'));
+        const screenshot = await captureScreenshot({ projectRoot });
+        if (!screenshot.ok) return screenshot;
+        fs.writeFileSync(output, screenshot.data);
+        return {
+            ok: true,
+            scene: screenshot.scene,
+            revision: screenshot.revision,
+            width: screenshot.width,
+            height: screenshot.height,
+            bytes: screenshot.data.byteLength,
+            output,
+        };
+    }
+
     if ((area === 'build' || area === 'dev' || area === 'validate') && action === undefined) {
         const target = requireFlag(flags, 'target');
         if (target !== 'wechat') {
@@ -392,12 +517,26 @@ export async function executePixifactCli(argv: string[], options: CliOptions = {
                     aiValidationAlternatives: [
                         'scene validate --all',
                     ],
+                    runtimeCommands: [
+                        'runtime list',
+                        'runtime tree [--output <json-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>]',
+                        'runtime input click --x <x> --y <y> [--runtime <runtime-id>]',
+                        'runtime input move --x <x> --y <y> [--runtime <runtime-id>]',
+                        'runtime input key <key> [--runtime <runtime-id>]',
+                        'runtime input keydown <key> [--runtime <runtime-id>]',
+                        'runtime input keyup <key> [--runtime <runtime-id>]',
+                    ],
                     auxiliaryCommands: [
                         'editor',
                         'editor context',
+                        'editor screenshot --output <png-path>',
                         'scene create --scene <scene-path> --name <SceneName>',
                         'node inspect --scene <scene-path> --node <locator>',
                     ],
+                    nodeLocatorSource: 'scene inspect --scene <scene-path> returns node locator values',
                     defaults: {
                         projectRoot: 'current working directory',
                     },
@@ -414,6 +553,9 @@ export async function executePixifactCli(argv: string[], options: CliOptions = {
             options.onWechatDevEvent,
             options.startEditor,
             options.readEditorContext,
+            options.captureEditorScreenshot,
+            options.listRuntimes,
+            options.queryRuntime,
         );
         if (isFailedResult(result)) {
             return {