@world-engines/project-host 0.1.0-alpha.0

package/dist/prepared-embedding-cache.js

@@ -0,0 +1,238 @@
+import { createHash, randomUUID } from "node:crypto";
+import { open, readFile, rename, rm } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { canonicalJson } from "@world-engines/scenario-review-snapshot";
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+import { sha256Hex } from "@world-engines/project-format";
+import { buildAuthoringRecallCorpus } from "./desktop-authoring-runtime.js";
+import { createCachedEmbeddingPort, readCachedEmbeddingVectors } from "./embedding-cache.js";
+import { assertSafeExistingProjectPath, assertSafeProjectParent, ensureSafeProjectDirectory, safeProjectPath } from "./safe-project-path.js";
+const PREPARED_PATH = ".worldengine/cache/embeddings/prepared-v1/current.json";
+const INDEX_PATH = "__derived__/embedding-index-v1.json";
+const MEDIA_TYPE = "application/vnd.chat.embedding-index.v1+json";
+function fail(message) {
+    throw new AuthoringBridgeError("E_VALIDATION_FAILED", `${message}；请先运行 worldengine recall prepare 或 review prepare 生成当前 revision 的冻结向量`);
+}
+function prepareRequired(message) {
+    throw new AuthoringBridgeError("E_VALIDATION_FAILED", `${message}；请先运行 worldengine recall prepare 或 review prepare 生成当前 revision 的冻结向量`, {
+        failure: "E_REVIEW_PREPARE_REQUIRED",
+    });
+}
+function sha256(value) {
+    return createHash("sha256").update(value, "utf8").digest("hex");
+}
+async function currentBinding(projectRoot, expectedProjectId) {
+    const manifest = JSON.parse(await readFile(await assertSafeExistingProjectPath(projectRoot, join(projectRoot, "worldengine.project.json")), "utf8"));
+    if (manifest.project_id !== expectedProjectId || !Number.isSafeInteger(manifest.project_revision) || manifest.project_revision < 0)
+        fail("prepared embedding project binding 无效");
+    const source = new Uint8Array(await readFile(await assertSafeExistingProjectPath(projectRoot, join(projectRoot, "scenario", "source.wes"))));
+    return { project_revision: manifest.project_revision, source_sha256: await sha256Hex(source) };
+}
+async function atomicWrite(projectRoot, path, text) {
+    await assertSafeProjectParent(projectRoot, path);
+    const temporary = join(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`);
+    const handle = await open(temporary, "wx");
+    try {
+        await handle.writeFile(text, "utf8");
+        await handle.sync();
+    }
+    catch (error) {
+        await handle.close();
+        await rm(temporary, { force: true });
+        throw error;
+    }
+    await handle.close();
+    try {
+        await rename(temporary, path);
+    }
+    catch (error) {
+        await rm(temporary, { force: true });
+        throw error;
+    }
+}
+/** 仅由显式 frozen-review embed 步骤写入；普通 search 不会生成 corpus vector。 */
+export function persistPreparedFrozenEmbeddingBatch(options) {
+    return async (request) => {
+        const before = await currentBinding(options.projectRoot, options.projectId);
+        const result = await options.runBatch(request);
+        const descriptorBase = {
+            provider: result.descriptor.provider,
+            model: result.descriptor.model,
+            dimension: result.descriptor.dimension,
+            source_revision: result.descriptor.source_revision,
+            source_revision_digest: result.descriptor.source_revision_digest,
+        };
+        if (result.descriptor.source_revision !== request.source.source_revision
+            || result.descriptor.source_revision_digest !== request.source.revision_digest
+            || result.descriptor.descriptor_sha256 !== sha256(canonicalJson(descriptorBase))
+            || result.entries.length !== request.entities.length
+            || new Set(result.entries.map((entry) => entry.entity_id)).size !== result.entries.length)
+            fail("prepared embedding batch 不完整或 identity 无效");
+        const expected = new Map(request.entities.map((entity) => [entity.entity_id, entity]));
+        for (const entry of result.entries) {
+            const source = expected.get(entry.entity_id);
+            if (source === undefined || source.source_kind !== entry.source_kind || source.source_text_sha256 !== entry.source_text_sha256
+                || entry.vector.length !== result.descriptor.dimension || entry.vector.some((value) => !Number.isFinite(value)))
+                fail("prepared embedding batch 绑定无效");
+        }
+        const binding = await currentBinding(options.projectRoot, options.projectId);
+        if (binding.project_revision !== before.project_revision || binding.source_sha256 !== before.source_sha256) {
+            fail("embedding 执行期间项目 source 已变化，拒绝持久化旧批次");
+        }
+        await ensureSafeProjectDirectory(options.projectRoot, ".worldengine/cache/embeddings/prepared-v1");
+        const path = await safeProjectPath(options.projectRoot, PREPARED_PATH);
+        const metadata = Object.freeze({
+            schema_version: 1,
+            project_id: options.projectId,
+            ...before,
+            source: Object.freeze({ ...request.source }),
+            descriptor: Object.freeze({ ...result.descriptor }),
+            entities: Object.freeze(request.entities.map((entity) => Object.freeze({ ...entity }))),
+        });
+        await atomicWrite(options.projectRoot, path, `${JSON.stringify(metadata)}\n`);
+        return result;
+    };
+}
+/**
+ * 只消费本地 WESP 的当前只读图投影并准备 corpus 向量；不依赖 review capture、远端
+ * source-ready 或结构化模型。写入前后的 revision/source CAS 仍由同一持久化模块检查。
+ */
+export async function prepareLocalRecallSnapshot(host, embedding, options = {}) {
+    const assertCurrentAccount = options.assertCurrentAccount ?? embedding.assertCurrentAccount;
+    await assertCurrentAccount?.();
+    const before = await host.readSourceReadback();
+    if (before.project_revision < 1)
+        fail("本地 recall corpus 尚无可绑定的 source revision");
+    const projection = await host.readGraphProjectionReadback();
+    if (projection.project_revision !== before.project_revision || projection.source_sha256 !== before.source_sha256) {
+        fail("本地 recall 图投影与 source identity 不一致");
+    }
+    const corpus = buildAuthoringRecallCorpus(projection.authoring).filter((entry) => {
+        if (options.scopeId === undefined)
+            return true;
+        const entity = projection.authoring.entities.find((candidate) => (candidate.entity_id ?? candidate.id) === entry.entity_id);
+        const props = entity?.props;
+        return typeof props === "object" && props !== null && !Array.isArray(props)
+            && (props.scope_id ?? props.scopeId) === options.scopeId;
+    });
+    if (corpus.length === 0)
+        fail("本地 recall corpus 为空");
+    const cachedEmbedding = await createCachedEmbeddingPort({ projectRoot: host.root, embedding, origin: embedding.origin });
+    const entities = await Promise.all(corpus.map(async (entry) => Object.freeze({
+        ...entry,
+        source_text_sha256: await sha256Hex(new TextEncoder().encode(entry.source_text)),
+    })));
+    const runBatch = persistPreparedFrozenEmbeddingBatch({
+        projectRoot: host.root,
+        projectId: before.project_id,
+        runBatch: async (request) => {
+            const vectors = await cachedEmbedding.embed(request.entities.map((entity) => entity.source_text), options.signal === undefined ? undefined : { signal: options.signal });
+            await assertCurrentAccount?.();
+            if (vectors.length !== request.entities.length
+                || vectors.some((vector) => vector.length !== cachedEmbedding.dimensions || vector.some((value) => !Number.isFinite(value)))) {
+                fail("本地 recall embedding provider result 无效");
+            }
+            const descriptorBase = Object.freeze({
+                provider: cachedEmbedding.providerId,
+                model: cachedEmbedding.modelId,
+                dimension: cachedEmbedding.dimensions,
+                source_revision: request.source.source_revision,
+                source_revision_digest: request.source.revision_digest,
+            });
+            return Object.freeze({
+                descriptor: Object.freeze({ ...descriptorBase, descriptor_sha256: sha256(canonicalJson(descriptorBase)) }),
+                entries: Object.freeze(request.entities.map((entity, index) => Object.freeze({
+                    entity_id: entity.entity_id,
+                    source_kind: entity.source_kind,
+                    source_text_sha256: entity.source_text_sha256,
+                    vector: Object.freeze([...vectors[index]]),
+                }))),
+            });
+        },
+    });
+    await runBatch(Object.freeze({
+        source: Object.freeze({
+            owner_id: `local:${before.project_id}`,
+            scenario_id: before.project_id,
+            source_revision: before.project_revision,
+            revision_digest: before.source_sha256,
+        }),
+        entities: Object.freeze(entities),
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+    }));
+    const current = await host.readSourceReadback();
+    if (current.project_id !== before.project_id || current.project_revision !== before.project_revision
+        || current.source_sha256 !== before.source_sha256)
+        fail("本地 recall prepare 完成后 source 已变化");
+    await assertCurrentAccount?.();
+    const prepared = await createPreparedEmbeddingSnapshotReader({
+        projectRoot: host.root,
+        projectId: before.project_id,
+        embedding: cachedEmbedding,
+        origin: cachedEmbedding.origin,
+        ...(assertCurrentAccount === undefined ? {} : { assertCurrentAccount }),
+    })({
+        project_id: before.project_id,
+        project_revision: before.project_revision,
+        source_sha256: before.source_sha256,
+        ...(options.scopeId === undefined ? {} : { scope_id: options.scopeId }),
+        entities,
+    });
+    if (prepared === null)
+        fail("本地 recall snapshot 无法读回");
+    return prepared;
+}
+/** 从 review prepare 已写入的 metadata + embedding cache 只读重建 formal snapshot。 */
+export function createPreparedEmbeddingSnapshotReader(options) {
+    return async (request) => {
+        const assertCurrentAccount = options.assertCurrentAccount ?? options.embedding.assertCurrentAccount;
+        await assertCurrentAccount?.();
+        let metadata;
+        try {
+            metadata = JSON.parse(await readFile(await assertSafeExistingProjectPath(options.projectRoot, join(options.projectRoot, ...PREPARED_PATH.split("/"))), "utf8"));
+        }
+        catch {
+            return prepareRequired("当前项目没有 prepared embedding snapshot");
+        }
+        if (metadata.schema_version !== 1 || metadata.project_id !== options.projectId || metadata.project_id !== request.project_id
+            || metadata.project_revision !== request.project_revision || metadata.source_sha256 !== request.source_sha256)
+            prepareRequired("prepared embedding snapshot 已过期");
+        const descriptor = metadata.descriptor;
+        if (descriptor.provider !== options.embedding.providerId || descriptor.model !== options.embedding.modelId || descriptor.dimension !== options.embedding.dimensions)
+            prepareRequired("prepared embedding provider identity 不匹配");
+        const available = new Map(metadata.entities.map((entity) => [entity.entity_id, entity]));
+        const selected = request.entities;
+        if (selected.length === 0)
+            prepareRequired("prepared embedding corpus 为空");
+        for (const entity of selected) {
+            const stored = available.get(entity.entity_id);
+            if (stored === undefined || stored.source_kind !== entity.source_kind || stored.source_text !== entity.source_text || stored.source_text_sha256 !== entity.source_text_sha256)
+                prepareRequired("prepared embedding corpus 与当前 source 不匹配");
+        }
+        const cachedVectors = await readCachedEmbeddingVectors({ projectRoot: options.projectRoot, embedding: options.embedding, origin: options.origin }, selected.map((entity) => entity.source_text_sha256));
+        if (cachedVectors === null)
+            prepareRequired("prepared embedding vector cache 不完整");
+        await assertCurrentAccount?.();
+        const entries = [];
+        for (const [index, entity] of selected.entries()) {
+            entries.push(Object.freeze({ entity_id: entity.entity_id, source_kind: entity.source_kind, source_text_sha256: entity.source_text_sha256, vector: cachedVectors[index] }));
+        }
+        const indexEntries = await Promise.all(entries.map(async (entry) => Object.freeze({
+            entity_id: entry.entity_id, source_kind: entry.source_kind, source_text_sha256: entry.source_text_sha256,
+            vector_sha256: await sha256Hex(new TextEncoder().encode(canonicalJson(entry.vector))),
+        })));
+        const vectors = new Map(entries.map((entry) => [entry.entity_id, entry.vector]));
+        return Object.freeze({
+            project_id: request.project_id, project_revision: request.project_revision, source_sha256: request.source_sha256,
+            scope_id: request.scope_id ?? "__all__",
+            snapshot: Object.freeze({
+                source: Object.freeze({ ...metadata.source }),
+                batch: Object.freeze({ descriptor: Object.freeze({ ...descriptor }), entries: Object.freeze(entries) }),
+                materialization: Object.freeze({ descriptor: Object.freeze({ ...descriptor }), vector_by_entity_id: vectors, index_resource: Object.freeze({
+                        path: INDEX_PATH, media_type: MEDIA_TYPE,
+                        bytes: new TextEncoder().encode(canonicalJson({ schema_version: 1, ...descriptor, entries: indexEntries })),
+                    }) }),
+            }),
+        });
+    };
+}

package/dist/preview-browser-adapter.d.ts

@@ -0,0 +1,53 @@
+import type { DesktopAuthoringCapabilities } from "./desktop-authoring-runtime.js";
+import type { PreviewSession } from "./preview-runtime.js";
+export declare const MAX_PREVIEW_DOM_CHARS: number;
+export declare const MAX_PREVIEW_TEXT_CHARS: number;
+export declare const MAX_PREVIEW_CONSOLE_ENTRIES = 100;
+export declare const MAX_PREVIEW_CONSOLE_CHARS: number;
+export declare const MAX_PREVIEW_SCREENSHOT_BYTES: number;
+export interface PreviewBrowserConsoleEntry {
+    readonly level: "debug" | "info" | "warning" | "error";
+    readonly text: string;
+}
+export interface PreviewBrowserScreenshot {
+    readonly bytes: Uint8Array;
+    readonly mimeType: "image/png" | "image/jpeg" | "image/webp";
+    readonly width?: number;
+    readonly height?: number;
+}
+export interface PreviewBrowserInspectCapture {
+    /** 浏览器实际看到的最终 URL；adapter 会重新做 session origin/base-path 绑定校验。 */
+    readonly url: string;
+    readonly ready: boolean;
+    readonly dom?: string;
+    readonly text?: string;
+    readonly console?: readonly PreviewBrowserConsoleEntry[];
+    readonly screenshot?: PreviewBrowserScreenshot;
+}
+export interface PreviewBrowserDriver {
+    inspect(request: Readonly<{
+        sessionId: string;
+        url: string;
+        selector?: string;
+        includeScreenshot: boolean;
+        includeConsole: boolean;
+    }>): Promise<PreviewBrowserInspectCapture>;
+    interact(request: Readonly<{
+        sessionId: string;
+        url: string;
+        action: "click" | "type" | "press" | "scroll" | "navigate";
+        target: string;
+        value?: string;
+    }>): Promise<Readonly<{
+        url: string;
+    }>>;
+}
+export interface PreviewBrowserAdapterOptions {
+    readonly inspectSession: () => PreviewSession | null;
+    readonly driver: PreviewBrowserDriver;
+}
+/**
+ * 把外部 harness 的真实浏览器端口收敛到 exact-21 Preview GUI hooks。
+ * 这里不实现浏览器，也不模拟 ChatPlay 握手或业务响应；driver 只能获得当前 session 的受控 URL。
+ */
+export declare function createPreviewBrowserCapabilities(options: PreviewBrowserAdapterOptions): Pick<DesktopAuthoringCapabilities, "preview_inspect" | "preview_interact">;

package/dist/preview-browser-adapter.js

@@ -0,0 +1,171 @@
+import { createHash } from "node:crypto";
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+export const MAX_PREVIEW_DOM_CHARS = 256 * 1024;
+export const MAX_PREVIEW_TEXT_CHARS = 64 * 1024;
+export const MAX_PREVIEW_CONSOLE_ENTRIES = 100;
+export const MAX_PREVIEW_CONSOLE_CHARS = 8 * 1024;
+export const MAX_PREVIEW_SCREENSHOT_BYTES = 4 * 1024 * 1024;
+function fail(code, message) {
+    throw new AuthoringBridgeError(code, message);
+}
+function validSession(options) {
+    const session = options.inspectSession();
+    if (session === null || session.state !== "running") {
+        return fail("E_CAPABILITY_UNAVAILABLE", "Preview 浏览器仅在已验证 running session 中可用");
+    }
+    let base;
+    try {
+        base = new URL(session.url);
+    }
+    catch {
+        return fail("E_CAPABILITY_UNAVAILABLE", "Preview session URL 无效");
+    }
+    if (base.protocol !== "http:"
+        || base.hostname !== "localhost"
+        || !/^\/_worldengine_preview\/[a-f0-9]{32}\/$/u.test(base.pathname)
+        || base.search !== ""
+        || base.hash !== "") {
+        return fail("E_CAPABILITY_UNAVAILABLE", "Preview session 未绑定到受控 loopback capability path");
+    }
+    return { session, base };
+}
+function boundedString(value, label, maxChars, allowEmpty = true) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" || (!allowEmpty && value.length === 0) || value.length > maxChars || /\0/u.test(value)) {
+        return fail("E_SCHEMA_INVALID", `${label} 无效或超过 ${maxChars} 字符`);
+    }
+    return value;
+}
+function assertBoundUrl(value, base, label) {
+    let url;
+    try {
+        url = new URL(value, base);
+    }
+    catch {
+        return fail("E_SCHEMA_INVALID", `${label} 不是有效 URL`);
+    }
+    if (url.origin !== base.origin || !url.pathname.startsWith(base.pathname)) {
+        return fail("E_SCHEMA_INVALID", `${label} 必须位于当前 Preview origin 与 capability path 内`);
+    }
+    return url;
+}
+function boundedOutput(value, maxChars) {
+    if (value === undefined)
+        return { truncated: false };
+    return value.length <= maxChars
+        ? { value, truncated: false }
+        : { value: value.slice(0, maxChars), truncated: true };
+}
+function boundedConsole(entries) {
+    if (entries === undefined)
+        return { entries: Object.freeze([]), truncated: false };
+    const selected = entries.slice(0, MAX_PREVIEW_CONSOLE_ENTRIES).map((entry) => {
+        const level = entry.level;
+        if (level !== "debug" && level !== "info" && level !== "warning" && level !== "error") {
+            return fail("E_SCHEMA_INVALID", "Preview console level 无效");
+        }
+        const text = boundedString(entry.text, "Preview console text", MAX_PREVIEW_CONSOLE_CHARS) ?? "";
+        return Object.freeze({ level, text });
+    });
+    return { entries: Object.freeze(selected), truncated: entries.length > selected.length };
+}
+function screenshotResult(value) {
+    if (value === undefined)
+        return undefined;
+    if (value.mimeType !== "image/png" && value.mimeType !== "image/jpeg" && value.mimeType !== "image/webp") {
+        return fail("E_SCHEMA_INVALID", "Preview screenshot MIME 无效");
+    }
+    if (value.bytes.byteLength === 0 || value.bytes.byteLength > MAX_PREVIEW_SCREENSHOT_BYTES) {
+        return fail("E_SCHEMA_INVALID", `Preview screenshot 必须在 1..${MAX_PREVIEW_SCREENSHOT_BYTES} bytes 内`);
+    }
+    const dimension = (candidate, label) => {
+        if (candidate === undefined)
+            return undefined;
+        if (!Number.isSafeInteger(candidate) || candidate <= 0 || candidate > 16_384) {
+            return fail("E_SCHEMA_INVALID", `${label} 无效`);
+        }
+        return candidate;
+    };
+    return Object.freeze({
+        mime_type: value.mimeType,
+        byte_length: value.bytes.byteLength,
+        sha256: createHash("sha256").update(value.bytes).digest("hex"),
+        ...(value.width === undefined ? {} : { width: dimension(value.width, "Preview screenshot width") }),
+        ...(value.height === undefined ? {} : { height: dimension(value.height, "Preview screenshot height") }),
+        data_base64: Buffer.from(value.bytes).toString("base64"),
+    });
+}
+/**
+ * 把外部 harness 的真实浏览器端口收敛到 exact-21 Preview GUI hooks。
+ * 这里不实现浏览器，也不模拟 ChatPlay 握手或业务响应；driver 只能获得当前 session 的受控 URL。
+ */
+export function createPreviewBrowserCapabilities(options) {
+    return Object.freeze({
+        preview_inspect: async (input) => {
+            const { session, base } = validSession(options);
+            const selector = boundedString(input.selector, "preview_inspect.selector", 4_096);
+            const includeScreenshot = input.include_screenshot === true;
+            const includeConsole = input.include_console === true;
+            const capture = await options.driver.inspect({
+                sessionId: session.session_id,
+                url: base.href,
+                ...(selector === undefined || selector === "" ? {} : { selector }),
+                includeScreenshot,
+                includeConsole,
+            });
+            const capturedUrl = assertBoundUrl(capture.url, base, "Preview 浏览器回读 URL");
+            const dom = boundedOutput(capture.dom, MAX_PREVIEW_DOM_CHARS);
+            const text = boundedOutput(capture.text, MAX_PREVIEW_TEXT_CHARS);
+            const consoleOutput = includeConsole ? boundedConsole(capture.console) : boundedConsole(undefined);
+            const screenshot = includeScreenshot ? screenshotResult(capture.screenshot) : undefined;
+            if (includeScreenshot && screenshot === undefined) {
+                return fail("E_CAPABILITY_UNAVAILABLE", "浏览器未返回请求的 Preview screenshot");
+            }
+            return Object.freeze({
+                schema_version: 1,
+                preview: Object.freeze({
+                    session_id: session.session_id,
+                    state: session.state,
+                    ready: capture.ready,
+                    url: capturedUrl.href,
+                    path: `${capturedUrl.pathname}${capturedUrl.search}${capturedUrl.hash}`,
+                }),
+                ...(selector === undefined || selector === "" ? {} : { selector }),
+                ...(dom.value === undefined ? {} : { dom: dom.value }),
+                ...(text.value === undefined ? {} : { text: text.value }),
+                output_truncated: dom.truncated || text.truncated || consoleOutput.truncated,
+                ...(includeConsole ? { console: consoleOutput.entries } : {}),
+                ...(screenshot === undefined ? {} : { screenshot }),
+            });
+        },
+        preview_interact: async (input) => {
+            const { session, base } = validSession(options);
+            const action = input.action;
+            if (action !== "click" && action !== "type" && action !== "press" && action !== "scroll" && action !== "navigate") {
+                return fail("E_SCHEMA_INVALID", "preview_interact.action 不在白名单中");
+            }
+            const rawTarget = boundedString(input.target, "preview_interact.target", 4_096, false);
+            const valueLimit = action === "type" ? 64 * 1024 : 512;
+            const value = boundedString(input.value, "preview_interact.value", valueLimit);
+            const target = action === "navigate"
+                ? assertBoundUrl(rawTarget, base, "Preview navigation target").href
+                : rawTarget;
+            const result = await options.driver.interact({
+                sessionId: session.session_id,
+                url: base.href,
+                action,
+                target,
+                ...(value === undefined ? {} : { value }),
+            });
+            const current = assertBoundUrl(result.url, base, "Preview 浏览器交互回读 URL");
+            return Object.freeze({
+                schema_version: 1,
+                session_id: session.session_id,
+                action,
+                url: current.href,
+                path: `${current.pathname}${current.search}${current.hash}`,
+            });
+        },
+    });
+}

package/dist/preview-runtime.d.ts

@@ -0,0 +1,67 @@
+import type { Readable } from "node:stream";
+/** 浏览器使用独立 hostname，避免 127.0.0.1 的 host-only GUI cookie 随 Preview 请求发送。 */
+export declare const LOCAL_PREVIEW_HOST = "localhost";
+/** Socket 始终绑定 IPv4 loopback，避免 localhost 的 IPv6 DNS 解析歧义。 */
+export declare const LOCAL_PREVIEW_BIND_HOST = "127.0.0.1";
+export declare const MAX_PREVIEW_OUTPUT_BYTES: number;
+export type PreviewSessionState = "starting" | "running" | "stopped" | "failed";
+export interface PreviewSession {
+    readonly session_id: string;
+    readonly project_root: string;
+    readonly cwd: string;
+    readonly url: string;
+    readonly port: number;
+    readonly state: PreviewSessionState;
+    readonly pid: number | null;
+    readonly started_at_ms: number;
+    readonly stopped_at_ms: number | null;
+    readonly exit_code: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly stdout_truncated: boolean;
+    readonly stderr_truncated: boolean;
+}
+export interface PreviewChildProcess {
+    readonly pid?: number | undefined;
+    readonly stdout: Readable;
+    readonly stderr: Readable;
+    once(event: "error", listener: (error: Error) => void): unknown;
+    once(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;
+    once(event: "close", listener: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;
+}
+export interface PreviewRuntimeDependencies {
+    readonly now?: () => number;
+    readonly newSessionId?: () => string;
+    readonly spawn?: (command: string, args: readonly string[], cwd: string) => PreviewChildProcess;
+    readonly findListeningPids?: (port: number) => Promise<readonly number[]>;
+    readonly getProcessCommandLine?: (pid: number) => Promise<string | null>;
+    readonly isProcessInTree?: (rootPid: number, pid: number) => Promise<boolean>;
+    readonly terminateProcessTree?: (pid: number) => Promise<void>;
+    readonly reserveLoopbackPort?: () => Promise<ReservedLoopbackPort>;
+}
+export interface ReservedLoopbackPort {
+    readonly port: number;
+    release(): Promise<void>;
+}
+export declare class PreviewRuntimeError extends Error {
+    readonly code: "E_PATH_OUTSIDE_PROJECT" | "E_PREVIEW_START_FAILED" | "E_PROJECT_BUSY";
+    constructor(code: PreviewRuntimeError["code"], message: string);
+}
+export declare function previewChildEnvironment(base?: NodeJS.ProcessEnv, nodeExecutable?: string): NodeJS.ProcessEnv;
+/** 跨进程只读 owner 探针；只返回 PID、listener 与 cwd 三者都能验证的 live ledger。 */
+export declare function readLivePreviewSessionOwner(projectRoot: string): Promise<Readonly<{
+    session_id: string;
+    pid: number;
+    port: number;
+    project_root: string;
+    cwd: string;
+    url: string;
+}> | null>;
+/** ProjectHost 的本地 Vite Preview 生命周期；每个 session 独占一个内核分配的 loopback 端口。 */
+export declare class LocalPreviewRuntime {
+    #private;
+    constructor(dependencies?: PreviewRuntimeDependencies);
+    start(projectRoot: string, parentOrigin?: string): Promise<PreviewSession>;
+    inspect(): PreviewSession | null;
+    stop(): Promise<PreviewSession | null>;
+}