pixifact 0.5.0 → 0.6.0

package/dist/compiler/pixiNodeSchema.d.ts

@@ -4,6 +4,7 @@ export type PixiSceneFieldType = 'string' | 'number' | 'boolean' | 'color' | 'en
 export type PixiScenePropGroup = 'transform' | 'display' | 'sprite' | 'nineSlice' | 'tiling' | 'text' | 'graphics' | 'stack' | 'props';
 export interface PixiSceneFieldSchema {
     key: string;
+    resource?: 'image';
     type: PixiSceneFieldType;
     options?: readonly (string | number)[];
 }

package/dist/compiler/pixiNodeSchema.js

@@ -218,7 +218,7 @@ const pixiSceneFieldSchemas = {
     eventMode: { key: 'eventMode', type: 'enum', options: ['none', 'passive', 'auto', 'static', 'dynamic'] },
     cursor: { key: 'cursor', type: 'enum', options: ['default', 'pointer', 'text', 'grab', 'grabbing'] },
     label: { key: 'label', type: 'string' },
-    texture: { key: 'texture', type: 'string' },
+    texture: { key: 'texture', type: 'string', resource: 'image' },
     fit: { key: 'fit', type: 'enum', options: ['stretch', 'contain', 'cover', 'none'] },
     anchorX: { key: 'anchorX', type: 'number' },
     anchorY: { key: 'anchorY', type: 'number' },

package/dist/compiler-node/index.d.ts

@@ -2,4 +2,5 @@ export * from '../compiler/compileScenes.js';
 export * from './builtinSceneAssets.js';
 export * from './builtinSceneInterfaces.js';
 export * from './scriptInterfaceExtractor.js';
+export * from './runtimeVite.js';
 export * from './vite.js';

package/dist/compiler-node/index.js

@@ -2,4 +2,5 @@ export * from '../compiler/compileScenes.js';
 export * from './builtinSceneAssets.js';
 export * from './builtinSceneInterfaces.js';
 export * from './scriptInterfaceExtractor.js';
+export * from './runtimeVite.js';
 export * from './vite.js';

package/dist/compiler-node/runtimeVite.d.ts

@@ -0,0 +1,89 @@
+import type { IncomingMessage, Server, ServerResponse } from 'node:http';
+export declare const runtimeSessionProtocolVersion = 1;
+export interface RuntimeSessionDescriptor {
+    protocolVersion: typeof runtimeSessionProtocolVersion;
+    projectRoot: string;
+    pid: number;
+    origin: string;
+    token: string;
+}
+export interface RuntimeHostBrowserSocket {
+    send(event: string, data: unknown): void;
+}
+interface RuntimeHostSessionOptions {
+    projectRoot: string;
+    requestTimeoutMs?: number;
+    token: string;
+    now?: () => Date;
+}
+interface RuntimeSessionLookupOptions {
+    projectRoot: string;
+    sessionsRoot?: string;
+    fetch?: typeof fetch;
+}
+interface ClaimRuntimeSessionOptions extends RuntimeSessionLookupOptions {
+    descriptor: RuntimeSessionDescriptor;
+}
+export interface PixifactRuntimePluginOptions {
+    projectRoot?: string | URL;
+}
+interface RuntimeViteClient extends RuntimeHostBrowserSocket {
+    socket: {
+        once(event: 'close', listener: () => void): void;
+    };
+}
+interface RuntimeViteServer {
+    config: {
+        server: {
+            https?: unknown;
+        };
+        logger: {
+            error(message: string): void;
+        };
+    };
+    httpServer: Server | null;
+    middlewares: {
+        use(handler: (request: IncomingMessage, response: ServerResponse, next: (error?: unknown) => void) => void): void;
+    };
+    ws: {
+        on(event: string, listener: (data: unknown, client: RuntimeViteClient) => void): void;
+    };
+}
+export declare function createRuntimeHostSession(options: RuntimeHostSessionOptions): {
+    open: (socket: RuntimeHostBrowserSocket) => void;
+    close: (socket: RuntimeHostBrowserSocket) => void;
+    message: (socket: RuntimeHostBrowserSocket, event: string, data: unknown) => void;
+    fetch: (request: Request) => Promise<Response | undefined>;
+};
+export declare function defaultRuntimeSessionsRoot(): string;
+export declare function runtimeSessionDescriptorPath(projectRoot: string, sessionsRoot?: string): string;
+export declare function readRuntimeSessionDescriptor(projectRoot: string, sessionsRoot?: string): RuntimeSessionDescriptor | undefined;
+export declare function writeRuntimeSessionDescriptor(descriptor: RuntimeSessionDescriptor, sessionsRoot?: string): void;
+export declare function removeRuntimeSessionDescriptor(descriptor: RuntimeSessionDescriptor, sessionsRoot?: string): void;
+export declare function findActiveRuntimeSession(options: RuntimeSessionLookupOptions): Promise<RuntimeSessionDescriptor | undefined>;
+export declare function claimRuntimeSession(options: ClaimRuntimeSessionOptions): Promise<{
+    descriptor: RuntimeSessionDescriptor;
+    owned: false;
+} | {
+    descriptor: RuntimeSessionDescriptor;
+    owned: true;
+}>;
+export declare function pixifactRuntimePlugin(options?: PixifactRuntimePluginOptions): {
+    name: string;
+    apply: string;
+    configResolved(config: {
+        root: string;
+    }): void;
+    resolveId(id: string): "\0virtual:pixifact-runtime-client" | undefined;
+    load(id: string): string | undefined;
+    transformIndexHtml(): {
+        tag: string;
+        attrs: {
+            type: string;
+            src: string;
+        };
+        injectTo: "head-prepend";
+    }[];
+    configureServer(server: RuntimeViteServer): void;
+};
+export {};

package/dist/compiler-node/runtimeVite.js

@@ -0,0 +1,420 @@
+import { createHash, randomBytes } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { pixifactRuntimeProtocolVersion, } from '../runtime-dev/protocol.js';
+export const runtimeSessionProtocolVersion = pixifactRuntimeProtocolVersion;
+const runtimeAnnounceEvent = 'pixifact:runtime:announce';
+const runtimeRequestEvent = 'pixifact:runtime:request';
+const runtimeResponseEvent = 'pixifact:runtime:response';
+const runtimeApiRoot = '/__pixifact_runtime__';
+const virtualRuntimeClientId = 'virtual:pixifact-runtime-client';
+const resolvedVirtualRuntimeClientId = `\0${virtualRuntimeClientId}`;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function jsonResponse(value, status = 200) {
+    return Response.json(value, { status });
+}
+function authorizationMatches(request, token) {
+    return request.headers.get('authorization') === `Bearer ${token}`;
+}
+function isRuntimePageDescriptor(value) {
+    return isRecord(value)
+        && typeof value.runtimeId === 'string'
+        && value.runtimeId.length > 0
+        && typeof value.url === 'string'
+        && typeof value.title === 'string'
+        && typeof value.ready === 'boolean';
+}
+function isRuntimeHmrResponse(value) {
+    if (!isRecord(value)
+        || typeof value.requestId !== 'string'
+        || typeof value.runtimeId !== 'string'
+        || typeof value.ok !== 'boolean') {
+        return false;
+    }
+    return value.ok ? 'result' in value : typeof value.error === 'string';
+}
+function isRuntimeRequest(value) {
+    if (!isRecord(value) || typeof value.type !== 'string')
+        return false;
+    if (value.type === 'tree' || value.type === 'state')
+        return true;
+    if (value.type === 'node')
+        return Number.isInteger(value.uid) && Number(value.uid) >= 0;
+    if (value.type === 'logs') {
+        return (value.after === undefined || (Number.isInteger(value.after) && Number(value.after) >= 0))
+            && (value.level === undefined || ['debug', 'log', 'info', 'warn', 'error'].includes(String(value.level)));
+    }
+    if (value.type !== 'input' || typeof value.action !== 'string')
+        return false;
+    if (value.action === 'click' || value.action === 'move') {
+        return typeof value.x === 'number' && typeof value.y === 'number';
+    }
+    return ['key', 'keydown', 'keyup'].includes(value.action)
+        && typeof value.key === 'string'
+        && value.key.length > 0;
+}
+export function createRuntimeHostSession(options) {
+    const requestTimeoutMs = options.requestTimeoutMs ?? 5_000;
+    const now = options.now ?? (() => new Date());
+    const sockets = new Set();
+    const runtimeIdBySocket = new Map();
+    const runtimes = new Map();
+    const pending = new Map();
+    let requestSequence = 0;
+    function settle(requestId, response) {
+        const current = pending.get(requestId);
+        if (!current)
+            return;
+        pending.delete(requestId);
+        clearTimeout(current.timeout);
+        current.resolve(response);
+    }
+    function removeSocketRuntime(socket) {
+        const runtimeId = runtimeIdBySocket.get(socket);
+        if (!runtimeId)
+            return;
+        runtimeIdBySocket.delete(socket);
+        if (runtimes.get(runtimeId)?.socket === socket)
+            runtimes.delete(runtimeId);
+    }
+    function open(socket) {
+        sockets.add(socket);
+    }
+    function close(socket) {
+        sockets.delete(socket);
+        removeSocketRuntime(socket);
+        for (const [requestId, current] of pending) {
+            if (current.socket === socket) {
+                settle(requestId, jsonResponse({
+                    ok: false,
+                    error: 'Pixifact Runtime page disconnected during the request.',
+                }, 409));
+            }
+        }
+    }
+    function message(socket, event, data) {
+        if (!sockets.has(socket))
+            return;
+        if (event === runtimeAnnounceEvent) {
+            if (!isRuntimePageDescriptor(data)) {
+                throw new Error('Pixifact Runtime page descriptor is invalid.');
+            }
+            const previousId = runtimeIdBySocket.get(socket);
+            const previous = runtimes.get(data.runtimeId);
+            if (previousId && previousId !== data.runtimeId)
+                runtimes.delete(previousId);
+            if (previous && previous.socket !== socket)
+                runtimeIdBySocket.delete(previous.socket);
+            runtimeIdBySocket.set(socket, data.runtimeId);
+            runtimes.set(data.runtimeId, {
+                ...data,
+                connectedAt: previous?.connectedAt ?? now().toISOString(),
+                socket,
+            });
+            return;
+        }
+        if (event !== runtimeResponseEvent || !isRuntimeHmrResponse(data))
+            return;
+        const current = pending.get(data.requestId);
+        if (!current || current.socket !== socket || current.runtimeId !== data.runtimeId)
+            return;
+        settle(data.requestId, data.ok
+            ? jsonResponse(data.result)
+            : jsonResponse({ ok: false, error: data.error }, 422));
+    }
+    async function fetchRequest(request) {
+        const pathname = new URL(request.url).pathname;
+        if (!pathname.startsWith(`${runtimeApiRoot}/`))
+            return undefined;
+        if (!authorizationMatches(request, options.token)) {
+            return jsonResponse({
+                ok: false,
+                error: 'Pixifact Runtime session token is invalid.',
+            }, 401);
+        }
+        if (pathname === `${runtimeApiRoot}/health`) {
+            return jsonResponse({
+                protocolVersion: runtimeSessionProtocolVersion,
+                projectRoot: options.projectRoot,
+            });
+        }
+        if (pathname === `${runtimeApiRoot}/list`) {
+            return jsonResponse({
+                ok: true,
+                runtimes: [...runtimes.values()]
+                    .map(({ socket: _socket, ...runtime }) => runtime)
+                    .sort((left, right) => left.connectedAt.localeCompare(right.connectedAt)),
+            });
+        }
+        if (pathname !== `${runtimeApiRoot}/request`)
+            return undefined;
+        if (request.method !== 'POST') {
+            return jsonResponse({ ok: false, error: 'Pixifact Runtime requests require POST.' }, 405);
+        }
+        const body = await request.json();
+        if (!isRecord(body) || typeof body.runtimeId !== 'string' || !isRuntimeRequest(body.request)) {
+            return jsonResponse({ ok: false, error: 'Pixifact Runtime request is invalid.' }, 400);
+        }
+        const runtime = runtimes.get(body.runtimeId);
+        if (!runtime) {
+            return jsonResponse({
+                ok: false,
+                error: `Pixifact Runtime "${body.runtimeId}" is not connected.`,
+            }, 404);
+        }
+        const requestId = `runtime-${++requestSequence}`;
+        return new Promise((resolve) => {
+            const timeout = setTimeout(() => {
+                settle(requestId, jsonResponse({
+                    ok: false,
+                    error: 'Pixifact Runtime request timed out.',
+                }, 504));
+            }, requestTimeoutMs);
+            pending.set(requestId, {
+                resolve,
+                runtimeId: runtime.runtimeId,
+                socket: runtime.socket,
+                timeout,
+            });
+            runtime.socket.send(runtimeRequestEvent, {
+                requestId,
+                runtimeId: runtime.runtimeId,
+                request: body.request,
+            });
+        });
+    }
+    return {
+        open,
+        close,
+        message,
+        fetch: fetchRequest,
+    };
+}
+export function defaultRuntimeSessionsRoot() {
+    return path.join(os.tmpdir(), 'pixifact', 'runtime-sessions');
+}
+export function runtimeSessionDescriptorPath(projectRoot, sessionsRoot = defaultRuntimeSessionsRoot()) {
+    const canonicalRoot = fs.realpathSync(projectRoot);
+    const projectHash = createHash('sha256').update(canonicalRoot).digest('hex');
+    return path.join(sessionsRoot, `${projectHash}.json`);
+}
+function isLoopbackOrigin(origin) {
+    const hostname = new URL(origin).hostname;
+    return hostname === 'localhost' || hostname === '::1' || hostname.startsWith('127.');
+}
+function validateRuntimeSessionDescriptor(value) {
+    if (!isRecord(value)
+        || value.protocolVersion !== runtimeSessionProtocolVersion
+        || typeof value.projectRoot !== 'string'
+        || typeof value.pid !== 'number'
+        || typeof value.origin !== 'string'
+        || typeof value.token !== 'string'
+        || !isLoopbackOrigin(value.origin)) {
+        throw new Error('Pixifact Runtime session descriptor is invalid.');
+    }
+    return value;
+}
+export function readRuntimeSessionDescriptor(projectRoot, sessionsRoot = defaultRuntimeSessionsRoot()) {
+    const descriptorPath = runtimeSessionDescriptorPath(projectRoot, sessionsRoot);
+    if (!fs.existsSync(descriptorPath))
+        return undefined;
+    return validateRuntimeSessionDescriptor(JSON.parse(fs.readFileSync(descriptorPath, 'utf8')));
+}
+export function writeRuntimeSessionDescriptor(descriptor, sessionsRoot = defaultRuntimeSessionsRoot()) {
+    const canonicalRoot = fs.realpathSync(descriptor.projectRoot);
+    const stored = validateRuntimeSessionDescriptor({ ...descriptor, projectRoot: canonicalRoot });
+    fs.mkdirSync(sessionsRoot, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(runtimeSessionDescriptorPath(canonicalRoot, sessionsRoot), `${JSON.stringify(stored, null, 2)}\n`, { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+}
+export function removeRuntimeSessionDescriptor(descriptor, sessionsRoot = defaultRuntimeSessionsRoot()) {
+    const descriptorPath = runtimeSessionDescriptorPath(descriptor.projectRoot, sessionsRoot);
+    if (!fs.existsSync(descriptorPath))
+        return;
+    const current = readRuntimeSessionDescriptor(descriptor.projectRoot, sessionsRoot);
+    if (current?.token === descriptor.token)
+        fs.unlinkSync(descriptorPath);
+}
+function validateRuntimeHealth(value) {
+    if (!isRecord(value)
+        || value.protocolVersion !== runtimeSessionProtocolVersion
+        || typeof value.projectRoot !== 'string') {
+        throw new Error('Pixifact Runtime Host health response is invalid.');
+    }
+    return value;
+}
+export async function findActiveRuntimeSession(options) {
+    const projectRoot = fs.realpathSync(options.projectRoot);
+    const descriptor = readRuntimeSessionDescriptor(projectRoot, options.sessionsRoot);
+    if (!descriptor)
+        return undefined;
+    if (descriptor.projectRoot !== projectRoot) {
+        throw new Error('Pixifact Runtime session belongs to a different project.');
+    }
+    const fetcher = options.fetch ?? fetch;
+    try {
+        const response = await fetcher(`${descriptor.origin}${runtimeApiRoot}/health`, {
+            headers: { authorization: `Bearer ${descriptor.token}` },
+        });
+        if (!response.ok)
+            return undefined;
+        const health = validateRuntimeHealth(await response.json());
+        if (health.projectRoot !== projectRoot) {
+            throw new Error('Pixifact Runtime Host health check returned a different project.');
+        }
+        return descriptor;
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.includes('different project'))
+            throw error;
+        return undefined;
+    }
+}
+export async function claimRuntimeSession(options) {
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        const current = readRuntimeSessionDescriptor(options.projectRoot, options.sessionsRoot);
+        const active = await findActiveRuntimeSession(options);
+        if (active)
+            return { descriptor: active, owned: false };
+        if (current)
+            removeRuntimeSessionDescriptor(current, options.sessionsRoot);
+        try {
+            writeRuntimeSessionDescriptor(options.descriptor, options.sessionsRoot);
+            return { descriptor: options.descriptor, owned: true };
+        }
+        catch (error) {
+            if (!isRecord(error) || error.code !== 'EEXIST')
+                throw error;
+        }
+    }
+    throw new Error('Pixifact Runtime session could not be registered.');
+}
+function projectRootPath(projectRoot, viteRoot) {
+    if (typeof projectRoot === 'string')
+        return projectRoot;
+    if (projectRoot)
+        return fileURLToPath(projectRoot);
+    return viteRoot;
+}
+function serverOrigin(server) {
+    const address = server.httpServer?.address();
+    if (!address || typeof address === 'string') {
+        throw new Error('Pixifact Runtime requires a listening Vite HTTP server.');
+    }
+    if (!(address.address === '::1' || address.address.startsWith('127.'))) {
+        throw new Error('Pixifact Runtime requires the Vite server to bind to a loopback address.');
+    }
+    const hostname = address.address === '::1' ? '[::1]' : address.address;
+    const protocol = server.config.server.https ? 'https' : 'http';
+    return `${protocol}://${hostname}:${address.port}`;
+}
+async function webRequestFromNode(request, origin) {
+    const chunks = [];
+    for await (const chunk of request) {
+        chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+    }
+    const body = chunks.length > 0 ? Buffer.concat(chunks) : undefined;
+    return new Request(new URL(request.url ?? '/', origin), {
+        method: request.method,
+        headers: request.headers,
+        ...(body ? { body } : {}),
+    });
+}
+async function writeNodeResponse(response, result) {
+    response.statusCode = result.status;
+    result.headers.forEach((value, name) => response.setHeader(name, value));
+    response.end(Buffer.from(await result.arrayBuffer()));
+}
+export function pixifactRuntimePlugin(options = {}) {
+    let projectRoot = '';
+    const token = randomBytes(32).toString('hex');
+    return {
+        name: 'pixifact-runtime',
+        apply: 'serve',
+        configResolved(config) {
+            projectRoot = fs.realpathSync(projectRootPath(options.projectRoot, config.root));
+        },
+        resolveId(id) {
+            return id === virtualRuntimeClientId ? resolvedVirtualRuntimeClientId : undefined;
+        },
+        load(id) {
+            if (id !== resolvedVirtualRuntimeClientId)
+                return undefined;
+            return [
+                "const runtimeHotKey = Symbol.for('pixifact.runtime.hot');",
+                'globalThis[runtimeHotKey] = import.meta.hot;',
+                "await import('pixifact/runtime-dev');",
+                'delete globalThis[runtimeHotKey];',
+            ].join('\n');
+        },
+        transformIndexHtml() {
+            return [{
+                    tag: 'script',
+                    attrs: {
+                        type: 'module',
+                        src: `/@id/${virtualRuntimeClientId}`,
+                    },
+                    injectTo: 'head-prepend',
+                }];
+        },
+        configureServer(server) {
+            const host = createRuntimeHostSession({ projectRoot, token });
+            const openedClients = new WeakSet();
+            function openClient(client) {
+                if (openedClients.has(client))
+                    return;
+                openedClients.add(client);
+                host.open(client);
+                client.socket.once('close', () => host.close(client));
+            }
+            server.ws.on(runtimeAnnounceEvent, (data, client) => {
+                openClient(client);
+                host.message(client, runtimeAnnounceEvent, data);
+            });
+            server.ws.on(runtimeResponseEvent, (data, client) => {
+                openClient(client);
+                host.message(client, runtimeResponseEvent, data);
+            });
+            server.middlewares.use((request, response, next) => {
+                void (async () => {
+                    const webRequest = await webRequestFromNode(request, serverOrigin(server));
+                    const result = await host.fetch(webRequest);
+                    if (!result) {
+                        next();
+                        return;
+                    }
+                    await writeNodeResponse(response, result);
+                })().catch(next);
+            });
+            const httpServer = server.httpServer;
+            if (!httpServer)
+                throw new Error('Pixifact Runtime requires the Vite HTTP server.');
+            let descriptor;
+            httpServer.once('listening', () => {
+                void (async () => {
+                    const candidate = {
+                        protocolVersion: runtimeSessionProtocolVersion,
+                        projectRoot,
+                        pid: process.pid,
+                        origin: serverOrigin(server),
+                        token,
+                    };
+                    const claim = await claimRuntimeSession({ projectRoot, descriptor: candidate });
+                    if (!claim.owned) {
+                        throw new Error('Another Pixifact Runtime Vite server is already running for this project.');
+                    }
+                    descriptor = candidate;
+                })().catch((error) => {
+                    server.config.logger.error(error instanceof Error ? error.message : String(error));
+                });
+            });
+            httpServer.once('close', () => {
+                if (descriptor)
+                    removeRuntimeSessionDescriptor(descriptor);
+            });
+        },
+    };
+}

package/dist/errors.d.ts

@@ -1 +1 @@
-export declare function hintForCommandError(error: string): "Use a project-relative scene path that stays inside projectRoot." | "Choose a different scene path or inspect the existing file before writing." | "Use one of: button, progressBar, scrollView, loginForm." | "Re-run scene get or node inspect to refresh locators before regenerating the command." | "Choose a container node as the parent, or create a container template before adding children." | "Verify that the field belongs to the target node or component schema before retrying." | "Check the target schema and send a value with the expected type." | undefined;
+export declare function hintForCommandError(error: string): "Use a project-relative scene path that stays inside projectRoot." | "Choose a different scene path or inspect the existing file before writing." | "Use one of: button, progressBar, scrollView, loginForm." | "Run scene inspect --scene <scene-path> and pass one of the returned node locator values." | "Inspect the current project state again before regenerating the command." | "Choose a container node as the parent, or create a container template before adding children." | "Verify that the field belongs to the target node or component schema before retrying." | "Check the target schema and send a value with the expected type." | undefined;

package/dist/errors.js

@@ -8,8 +8,11 @@ export function hintForCommandError(error) {
     if (error.includes('Unknown template kind')) {
         return 'Use one of: button, progressBar, scrollView, loginForm.';
     }
+    if (error.includes('Node locator') && error.includes('was not found')) {
+        return 'Run scene inspect --scene <scene-path> and pass one of the returned node locator values.';
+    }
     if (error.includes('was not found')) {
-        return 'Re-run scene get or node inspect to refresh locators before regenerating the command.';
+        return 'Inspect the current project state again before regenerating the command.';
     }
     if (error.includes('Only container nodes')) {
         return 'Choose a container node as the parent, or create a container template before adding children.';

package/dist/runtime-dev/index.d.ts

@@ -0,0 +1,5 @@
+import type { Application } from 'pixi.js';
+import { type RegisterPixiRuntimeOptions } from './runtimeClient.js';
+export declare function registerPixiRuntime(app: Application, options?: RegisterPixiRuntimeOptions): void;
+export type { RegisterPixiRuntimeOptions } from './runtimeClient.js';
+export type { RuntimeJsonValue, RuntimeLogLevel, RuntimePageDescriptor, RuntimeRequest, } from './protocol.js';

package/dist/runtime-dev/index.js

@@ -0,0 +1,22 @@
+import { createPixifactRuntimeClient, } from './runtimeClient.js';
+const runtimeHotKey = Symbol.for('pixifact.runtime.hot');
+const runtimeClientKey = Symbol.for('pixifact.runtime.client');
+const runtimeGlobal = globalThis;
+const injectedHot = runtimeGlobal[runtimeHotKey];
+const existingRuntimeClient = runtimeGlobal[runtimeClientKey];
+const runtimeClient = existingRuntimeClient ?? (injectedHot
+    ? createPixifactRuntimeClient({
+        runtimeId: crypto.randomUUID(),
+        hot: injectedHot,
+        console,
+        window,
+    })
+    : undefined);
+if (runtimeClient && !existingRuntimeClient)
+    runtimeGlobal[runtimeClientKey] = runtimeClient;
+export function registerPixiRuntime(app, options = {}) {
+    if (!runtimeClient) {
+        throw new Error('registerPixiRuntime requires pixifactRuntimePlugin in the Vite development server.');
+    }
+    runtimeClient.register(app, options);
+}

package/dist/runtime-dev/protocol.d.ts

@@ -0,0 +1,58 @@
+export declare const pixifactRuntimeProtocolVersion = 1;
+export type RuntimeJsonPrimitive = boolean | number | string | null;
+export type RuntimeJsonValue = RuntimeJsonPrimitive | RuntimeJsonValue[] | {
+    [key: string]: RuntimeJsonValue;
+};
+export type RuntimeLogLevel = 'debug' | 'log' | 'info' | 'warn' | 'error';
+export interface RuntimeLogEntry {
+    seq: number;
+    time: string;
+    level: RuntimeLogLevel;
+    message: string;
+    args: RuntimeJsonValue[];
+    stack?: string;
+}
+export type RuntimeInputRequest = {
+    type: 'input';
+    action: 'click' | 'move';
+    x: number;
+    y: number;
+} | {
+    type: 'input';
+    action: 'key' | 'keydown' | 'keyup';
+    key: string;
+};
+export type RuntimeRequest = {
+    type: 'tree';
+} | {
+    type: 'node';
+    uid: number;
+} | {
+    type: 'state';
+} | {
+    type: 'logs';
+    after?: number;
+    level?: RuntimeLogLevel;
+} | RuntimeInputRequest;
+export interface RuntimePageDescriptor {
+    runtimeId: string;
+    url: string;
+    title: string;
+    ready: boolean;
+}
+export interface RuntimeHmrRequest {
+    requestId: string;
+    runtimeId: string;
+    request: RuntimeRequest;
+}
+export type RuntimeHmrResponse = {
+    requestId: string;
+    runtimeId: string;
+    ok: true;
+    result: RuntimeJsonValue;
+} | {
+    requestId: string;
+    runtimeId: string;
+    ok: false;
+    error: string;
+};

package/dist/runtime-dev/protocol.js

@@ -0,0 +1 @@
+export const pixifactRuntimeProtocolVersion = 1;

package/dist/runtime-dev/runtimeClient.d.ts

@@ -0,0 +1,22 @@
+import { type Application } from 'pixi.js';
+import { type RuntimeJsonValue, type RuntimeRequest } from './protocol.js';
+export interface RegisterPixiRuntimeOptions {
+    getState?: () => RuntimeJsonValue;
+}
+export interface PixifactRuntimeHotContext {
+    on(event: string, listener: (data: unknown) => void): void;
+    send(event: string, data: unknown): void;
+}
+interface RuntimeClientOptions {
+    runtimeId: string;
+    hot: PixifactRuntimeHotContext;
+    console: Console;
+    window: Window;
+    now?: () => Date;
+}
+export declare function createPixifactRuntimeClient(options: RuntimeClientOptions): {
+    register(application: Application, registerOptions?: RegisterPixiRuntimeOptions): void;
+    handleRequest: (request: RuntimeRequest) => Promise<RuntimeJsonValue>;
+    dispose: () => void;
+};
+export {};

package/dist/runtime-dev/runtimeClient.js

@@ -0,0 +1,382 @@
+import { BitmapText, Graphics, Sprite, Text, } from 'pixi.js';
+const maxRetainedLogs = 500;
+const runtimeRequestEvent = 'pixifact:runtime:request';
+const runtimeResponseEvent = 'pixifact:runtime:response';
+const runtimeAnnounceEvent = 'pixifact:runtime:announce';
+function pointSnapshot(point) {
+    return { x: point.x, y: point.y };
+}
+function boundsSnapshot(bounds) {
+    return {
+        x: bounds.x,
+        y: bounds.y,
+        width: bounds.width,
+        height: bounds.height,
+    };
+}
+function basicNodeSnapshot(node, childIndex) {
+    return {
+        uid: node.uid,
+        type: node.constructor.name,
+        label: node.label,
+        childIndex,
+        position: pointSnapshot(node.position),
+        scale: pointSnapshot(node.scale),
+        rotation: node.rotation,
+        alpha: node.alpha,
+        visible: node.visible,
+        renderable: node.renderable,
+        zIndex: node.zIndex,
+        eventMode: node.eventMode ?? null,
+        children: node.children.map((child, index) => basicNodeSnapshot(child, index)),
+    };
+}
+function supportedFill(fill) {
+    return typeof fill === 'number' || typeof fill === 'string' ? fill : null;
+}
+function specificNodeSnapshot(node) {
+    if (node instanceof Sprite) {
+        return {
+            kind: 'sprite',
+            anchor: pointSnapshot(node.anchor),
+            texture: {
+                uid: node.texture.uid,
+                label: node.texture.label ?? null,
+                width: node.texture.width,
+                height: node.texture.height,
+            },
+            tint: node.tint,
+        };
+    }
+    if (node instanceof BitmapText || node instanceof Text) {
+        return {
+            kind: node instanceof BitmapText ? 'bitmapText' : 'text',
+            text: node.text,
+            anchor: pointSnapshot(node.anchor),
+            style: {
+                align: node.style.align,
+                fill: supportedFill(node.style.fill),
+                fontFamily: Array.isArray(node.style.fontFamily)
+                    ? [...node.style.fontFamily]
+                    : node.style.fontFamily,
+                fontSize: node.style.fontSize,
+                fontStyle: node.style.fontStyle,
+                fontWeight: node.style.fontWeight,
+            },
+        };
+    }
+    if (node instanceof Graphics) {
+        return { kind: 'graphics' };
+    }
+    return undefined;
+}
+function findStageNode(stage, uid) {
+    if (stage.uid === uid)
+        return stage;
+    for (const child of stage.children) {
+        const result = findStageNode(child, uid);
+        if (result)
+            return result;
+    }
+    return undefined;
+}
+function detailedNodeSnapshot(node) {
+    const childIndex = node.parent ? node.parent.children.indexOf(node) : null;
+    const specific = specificNodeSnapshot(node);
+    return {
+        uid: node.uid,
+        type: node.constructor.name,
+        label: node.label,
+        parentUid: node.parent?.uid ?? null,
+        childIndex,
+        childCount: node.children.length,
+        position: pointSnapshot(node.position),
+        scale: pointSnapshot(node.scale),
+        pivot: pointSnapshot(node.pivot),
+        skew: pointSnapshot(node.skew),
+        rotation: node.rotation,
+        angle: node.angle,
+        width: node.width,
+        height: node.height,
+        localBounds: boundsSnapshot(node.getLocalBounds()),
+        globalBounds: boundsSnapshot(node.getBounds()),
+        alpha: node.alpha,
+        worldAlpha: node.getGlobalAlpha(),
+        visible: node.visible,
+        renderable: node.renderable,
+        zIndex: node.zIndex,
+        tint: node.tint,
+        blendMode: String(node.blendMode),
+        eventMode: node.eventMode ?? null,
+        cursor: node.cursor === undefined ? null : String(node.cursor),
+        ...(specific ? { specific } : {}),
+    };
+}
+function snapshotLogValue(value, seen = new WeakSet(), depth = 0) {
+    if (value === null || typeof value === 'boolean' || typeof value === 'number' || typeof value === 'string') {
+        return value;
+    }
+    if (typeof value === 'bigint')
+        return `${value}n`;
+    if (typeof value === 'undefined')
+        return '[undefined]';
+    if (typeof value === 'symbol')
+        return String(value);
+    if (typeof value === 'function')
+        return `[Function ${value.name || 'anonymous'}]`;
+    if (value instanceof Error) {
+        return {
+            name: value.name,
+            message: value.message,
+            stack: value.stack ?? '',
+        };
+    }
+    if (value instanceof Date)
+        return value.toISOString();
+    if (depth >= 4)
+        return `[${value.constructor?.name ?? 'Object'}]`;
+    if (seen.has(value))
+        return '[Circular]';
+    seen.add(value);
+    if (Array.isArray(value)) {
+        return value.map((item) => snapshotLogValue(item, seen, depth + 1));
+    }
+    const snapshot = {};
+    for (const key of Object.keys(value)) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        snapshot[key] = descriptor && 'value' in descriptor
+            ? snapshotLogValue(descriptor.value, seen, depth + 1)
+            : '[Getter]';
+    }
+    return snapshot;
+}
+function logMessage(args) {
+    const first = args[0];
+    if (typeof first === 'string')
+        return first;
+    if (first instanceof Error)
+        return first.message;
+    return JSON.stringify(snapshotLogValue(first));
+}
+function createRuntimeLogCapture(targetConsole, targetWindow, now) {
+    const retained = [];
+    const originals = new Map();
+    let sequence = 0;
+    function append(level, args, explicitStack) {
+        const stack = explicitStack ?? args.find((value) => value instanceof Error)?.stack;
+        retained.push({
+            seq: ++sequence,
+            time: now().toISOString(),
+            level,
+            message: logMessage(args),
+            args: args.slice(typeof args[0] === 'string' ? 1 : 0).map((value) => snapshotLogValue(value)),
+            ...(stack ? { stack } : {}),
+        });
+        if (retained.length > maxRetainedLogs)
+            retained.splice(0, retained.length - maxRetainedLogs);
+    }
+    for (const level of ['debug', 'log', 'info', 'warn', 'error']) {
+        const original = targetConsole[level];
+        originals.set(level, original);
+        targetConsole[level] = ((...args) => {
+            original.apply(targetConsole, args);
+            append(level, args);
+        });
+    }
+    const onWindowError = (event) => {
+        append('error', [event.message, event.error ?? null], event.error instanceof Error ? event.error.stack : undefined);
+    };
+    const onUnhandledRejection = (event) => {
+        const reason = event.reason;
+        append('error', ['Unhandled promise rejection', reason], reason instanceof Error ? reason.stack : undefined);
+    };
+    targetWindow.addEventListener('error', onWindowError);
+    targetWindow.addEventListener('unhandledrejection', onUnhandledRejection);
+    return {
+        entries: () => retained,
+        latestSeq: () => sequence,
+        dispose() {
+            for (const [level, original] of originals) {
+                targetConsole[level] = original;
+            }
+            targetWindow.removeEventListener('error', onWindowError);
+            targetWindow.removeEventListener('unhandledrejection', onUnhandledRejection);
+        },
+    };
+}
+function pointerEvent(targetWindow, type, point, buttons) {
+    const eventWindow = targetWindow;
+    return new eventWindow.PointerEvent(type, {
+        bubbles: true,
+        cancelable: true,
+        pointerId: 1,
+        pointerType: 'mouse',
+        isPrimary: true,
+        button: 0,
+        buttons,
+        ...point,
+    });
+}
+function clientPoint(app, x, y) {
+    if (!Number.isFinite(x) || !Number.isFinite(y)) {
+        throw new Error('Runtime pointer coordinates must be finite numbers.');
+    }
+    if (x < 0 || y < 0 || x > app.screen.width || y > app.screen.height) {
+        throw new Error(`Runtime pointer coordinates must stay inside ${app.screen.width} x ${app.screen.height}.`);
+    }
+    const bounds = app.canvas.getBoundingClientRect();
+    return {
+        clientX: bounds.left + (x / app.screen.width) * bounds.width,
+        clientY: bounds.top + (y / app.screen.height) * bounds.height,
+    };
+}
+function keyboardIdentity(key) {
+    if (key === 'Space')
+        return { key: ' ', code: 'Space' };
+    if (/^Key[A-Z]$/.test(key))
+        return { key: key.slice(3).toLowerCase(), code: key };
+    if (/^Digit[0-9]$/.test(key))
+        return { key: key.slice(5), code: key };
+    return { key, code: key };
+}
+function dispatchRuntimeInput(targetWindow, app, request) {
+    const eventWindow = targetWindow;
+    if (request.action === 'move' || request.action === 'click') {
+        const point = clientPoint(app, request.x, request.y);
+        app.canvas.dispatchEvent(pointerEvent(targetWindow, 'pointermove', point, 0));
+        if (request.action === 'click') {
+            app.canvas.dispatchEvent(pointerEvent(targetWindow, 'pointerdown', point, 1));
+            app.canvas.dispatchEvent(pointerEvent(targetWindow, 'pointerup', point, 0));
+            app.canvas.dispatchEvent(new eventWindow.MouseEvent('click', {
+                bubbles: true,
+                cancelable: true,
+                button: 0,
+                ...point,
+            }));
+        }
+        return;
+    }
+    if (!('key' in request))
+        throw new Error('Runtime keyboard input requires a key.');
+    const identity = keyboardIdentity(request.key);
+    const dispatchKey = (type) => {
+        targetWindow.dispatchEvent(new eventWindow.KeyboardEvent(type, {
+            bubbles: true,
+            cancelable: true,
+            ...identity,
+        }));
+    };
+    if (request.action === 'key' || request.action === 'keydown')
+        dispatchKey('keydown');
+    if (request.action === 'key' || request.action === 'keyup')
+        dispatchKey('keyup');
+}
+function cloneState(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function isHmrRequest(value) {
+    return typeof value === 'object'
+        && value !== null
+        && typeof value.requestId === 'string'
+        && typeof value.runtimeId === 'string'
+        && typeof value.request === 'object'
+        && value.request !== null;
+}
+export function createPixifactRuntimeClient(options) {
+    const now = options.now ?? (() => new Date());
+    const logs = createRuntimeLogCapture(options.console, options.window, now);
+    let app;
+    let getState;
+    function descriptor() {
+        return {
+            runtimeId: options.runtimeId,
+            url: options.window.location.href,
+            title: options.window.document.title,
+            ready: app !== undefined,
+        };
+    }
+    function announce() {
+        options.hot.send(runtimeAnnounceEvent, descriptor());
+    }
+    function requireApplication() {
+        if (!app)
+            throw new Error('PixiJS Application has not been registered in this runtime.');
+        return app;
+    }
+    async function handleRequest(request) {
+        if (request.type === 'logs') {
+            return {
+                runtimeId: options.runtimeId,
+                latestSeq: logs.latestSeq(),
+                entries: logs.entries()
+                    .filter((entry) => request.after === undefined || entry.seq > request.after)
+                    .filter((entry) => request.level === undefined || entry.level === request.level)
+                    .map((entry) => ({ ...entry })),
+            };
+        }
+        const currentApp = requireApplication();
+        if (request.type === 'tree') {
+            return {
+                runtimeId: options.runtimeId,
+                root: basicNodeSnapshot(currentApp.stage, null),
+            };
+        }
+        if (request.type === 'node') {
+            const node = findStageNode(currentApp.stage, request.uid);
+            if (!node)
+                throw new Error(`PixiJS node uid ${request.uid} is not in app.stage.`);
+            return {
+                runtimeId: options.runtimeId,
+                node: detailedNodeSnapshot(node),
+            };
+        }
+        if (request.type === 'state') {
+            return getState
+                ? {
+                    runtimeId: options.runtimeId,
+                    available: true,
+                    state: cloneState(getState()),
+                }
+                : {
+                    runtimeId: options.runtimeId,
+                    available: false,
+                    state: null,
+                };
+        }
+        if (request.type === 'input') {
+            dispatchRuntimeInput(options.window, currentApp, request);
+            return {
+                runtimeId: options.runtimeId,
+                dispatched: true,
+            };
+        }
+        throw new Error('Unknown Pixifact Runtime request.');
+    }
+    options.hot.on(runtimeRequestEvent, (data) => {
+        if (!isHmrRequest(data) || data.runtimeId !== options.runtimeId)
+            return;
+        void handleRequest(data.request).then((result) => options.hot.send(runtimeResponseEvent, {
+            requestId: data.requestId,
+            runtimeId: options.runtimeId,
+            ok: true,
+            result,
+        }), (error) => options.hot.send(runtimeResponseEvent, {
+            requestId: data.requestId,
+            runtimeId: options.runtimeId,
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+        }));
+    });
+    announce();
+    return {
+        register(application, registerOptions = {}) {
+            if (app)
+                throw new Error('This page already has a registered PixiJS Application.');
+            app = application;
+            getState = registerOptions.getState;
+            announce();
+        },
+        handleRequest,
+        dispose: logs.dispose,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixifact",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Pixifact 2D UI 和轻量游戏 Scene 语义框架。",
   "packageManager": "bun@1.3.13",
   "main": "./dist/index.js",
@@ -42,6 +42,11 @@
       "import": "./dist/runtime/index.js",
       "require": "./dist/runtime/index.js"
     },
+    "./runtime-dev": {
+      "types": "./dist/runtime-dev/index.d.ts",
+      "import": "./dist/runtime-dev/index.js",
+      "require": "./dist/runtime-dev/index.js"
+    },
     "./scene": {
       "types": "./dist/scene/index.d.ts",
       "import": "./dist/scene/index.js",