@proteus-vue/render-backend 0.3.0-beta.21 → 0.3.0-beta.26

package/dist/native.d.ts

@@ -28,6 +28,69 @@ export interface MockNativeAdapter extends NativeViewAdapter {
     /** 操作日志（断言 create/insert/update/remove/setText 顺序） */
     ops: string[];
 }
+/**
+ * ★★C1：**宿主操作批次**（批量协议的元素）——一次跨边界调用携带整批变更。
+ *
+ * 【为什么必须有（Host ABI 的批处理红线）】`docs/Proteus_HostABI宿主抽象层设计方案.md` §3 原文：
+ *   「**所有跨边界调用必须是批处理的**」+ 红线「跨边界调用 = 帧数」。
+ *   而逐节点命令式适配器（`NativeViewAdapter`）在 4050 节点树上会产生
+ *   **数千次跨边界调用**（每节点 create + insert + ...）⇒ 直接违反该红线。
+ *
+ * 【真机链路本来就是这样做的（I6 评估的实测证据）】真机宿主协议是**批量**的：
+ *   `mount(treeJson)` / `updatePatches(patchesJson)` / `applyOps(bytesJson)` —— 每帧**一次**调用。
+ *   ⇒ 本类型把"真机已用的批量形态"**显式建模进 SPI**，让 NativeBackend 能表达它。
+ */
+export type NativeHostOp = 
+/** 建视图（宿主侧创建 UIView/View/ArkUI Node） */
+{
+    op: 'create';
+    id: number;
+    type: string;
+    props: Record<string, unknown>;
+}
+/** 插入子视图（anchor 可选——同批次内按序应用） */
+ | {
+    op: 'insert';
+    id: number;
+    parentId: number | null;
+    anchorId?: number;
+}
+/** 移除视图 */
+ | {
+    op: 'remove';
+    id: number;
+}
+/** 属性/样式变更 */
+ | {
+    op: 'patch';
+    id: number;
+    key: string;
+    prev: unknown;
+    next: unknown;
+}
+/** 文本同步 */
+ | {
+    op: 'text';
+    id: number;
+    text: string;
+};
+/**
+ * ★★C1：**批量宿主适配器**（与逐节点 `NativeViewAdapter` 并列的第二形态）。
+ *
+ * 【两者的分工（本评估的结论，勿混用）】
+ *   · `NativeViewAdapter`（逐节点）＝ **原型形态**：接口直观，适合简单宿主/测试；
+ *     但**不满足批处理红线** ⇒ 不能作为生产形态。
+ *   · `NativeBatchAdapter`（批量）＝ **生产形态**：一次 `commit` 携带整批 ⇒ 跨边界调用数 = flush 次数。
+ *
+ * 【与真机链路的对应】`commit(ops)` 即真机 `mount`/`updatePatches`/`applyOps` 的统一抽象：
+ *   宿主侧把批次翻译成自己的渲染调用（iOS CALayer / Android Canvas / ArkUI）。
+ */
+export interface NativeBatchAdapter {
+    /** 提交一批变更（★**一次跨边界调用**——调用方保证一批 = 一帧的变更） */
+    commit(ops: readonly NativeHostOp[]): void;
+    /** 已提交批次数（诊断/判据用——跨边界调用计数） */
+    commitCount?(): number;
+}
 /** 内置 mock 适配器（无宿主环境验证接线；真实平台 B4 后接 SDK 实现替换） */
 export declare function createMockNativeAdapter(): MockNativeAdapter;
 /** 原生平台（iOS UIKit / Android Jetpack / 鸿蒙 ArkUI） */
@@ -39,4 +102,7 @@ export type NativePlatform = 'ios' | 'android' | 'harmony';
  * - adapter 缺省 mock（ops 日志）；真实平台注入 SDK 桥
  * - platform：ios（UIKit 基准）/ android（Jetpack）/ harmony（ArkUI）——决定 id + semantic 映射表
  */
-export declare function createNativeBackend(adapter?: NativeViewAdapter, platform?: NativePlatform): ProteusRenderBackend;
+export declare function createNativeBackend(adapter?: NativeViewAdapter | NativeBatchAdapter, platform?: NativePlatform): ProteusRenderBackend & {
+    flush(): void;
+    hostCalls(): number;
+};

package/dist/quickjs-host.d.ts

@@ -0,0 +1,77 @@
+import type { HostRuntimeLike } from './host-conformance';
+/** 宿主原生调用通道（宿主壳注入：Android = proteusHost.* / iOS = JSExport；**同步**返回 JSON 串） */
+export interface NativeTransport {
+    /** 调用宿主（同步；返回 JSON 字符串；抛错 = 原生调用失败，语义与 JNI 异常对齐） */
+    call(name: string, argsJson: string): string;
+}
+/** 职责边界拒绝记录（G-39.1「唯一拥有」的机器证据——非法操作**被拒绝**而不是被静默吞掉） */
+export interface RuntimeRefusal {
+    op: string;
+    reason: string;
+    /** 拒绝时的状态（诊断用） */
+    state: string;
+}
+/** 能力自描述（G-39.3 诚实声明——框架据此决定降级，而不是运行时假装支持） */
+export interface QuickJsHostCapabilities {
+    threads: {
+        main: boolean;
+        background: boolean;
+        count: number;
+    };
+    engine: 'quickjs' | 'jsc' | 'node' | 'none';
+    nativeBridge: boolean;
+    lifecycle: 'full' | 'basic' | 'none';
+    /** 帧驱动源（诊断：谁在调 pumpFrame） */
+    frameDriver: string;
+}
+/** 逻辑 worker 域（**无真并行**——诚实声明；`real=false` 是"单线程宿主"的机器可读标记） */
+export interface LogicalWorkerHandle {
+    id: string;
+    thread: string;
+    /** ★恒为 false：本宿主无真并行（有真 Worker 的宿主见 web-host 的 WebWorkerHandle.raw） */
+    real: false;
+}
+export interface QuickJsHostRuntime extends HostRuntimeLike {
+    readonly id: string;
+    readonly capabilities: QuickJsHostCapabilities;
+    /** ★宿主帧驱动入口（Android Choreographer / iOS CADisplayLink 调用）——返回本帧执行的任务数 */
+    pumpFrame(): number;
+    /** 生命周期由宿主壳转发（Activity onPause/onResume → 这里）——事件流是治理证据 */
+    readonly lifecycleEvents: ReadonlyArray<'suspend' | 'resume' | 'destroy'>;
+    /** 职责边界拒绝日志（非法操作被拒绝的机器证据；不断言"我们不会犯错"，断言"犯错会被拒绝"） */
+    readonly refusals: ReadonlyArray<RuntimeRefusal>;
+    /** 注册 JS→原生方向的原生处理器（宿主壳也可以注册；业务不得绕过 runtime 直连宿主——G-39.1） */
+    registerNativeHandler(name: string, handler: (args: unknown) => unknown): void;
+    /** 调原生：注册的处理器优先，否则走 transport；未注册/未导出 ⇒ **拒绝并记账**（不静默） */
+    invokeNative(name: string, args?: unknown): Promise<unknown>;
+    /**
+     * 线程委派（G-39 计划面）：`'main'` ⇒ 入队（由 pumpFrame 消费）；
+     * `'background'` ⇒ **诚实拒绝**（capabilities.threads.background=false）——
+     * ★这正是 G-39 要治的病：「各 Backend 自己 pthread_create」在本宿主里**没有后门**，
+     *   要么查 capabilities 走降级，要么被 runtime 拒绝（记账可观测）。
+     */
+    runOnThread(thread: 'main' | 'background', task: () => void): void;
+    /** 已注册的原生处理器名（诊断） */
+    readonly nativeHandlers: string[];
+}
+export interface QuickJsHostOptions {
+    /** 宿主标识（'android' | 'ios' | 'harmony' | 诊断用） */
+    id?: string;
+    /** JS 引擎标识（诚实声明） */
+    engine?: QuickJsHostCapabilities['engine'];
+    /** 帧驱动源名（诊断：'Choreographer' / 'CADisplayLink' / 'manual'） */
+    frameDriver?: string;
+    /** 原生调用通道（缺省无桥：invokeNative 未命中处理器时**明确拒绝**） */
+    transport?: NativeTransport;
+}
+/**
+ * ★★G-39 B4：创建单线程 JS 引擎宿主运行时（Android QuickJS / iOS JSC 同族骨架）
+ *
+ * 职责边界（G-39.1「唯一拥有」在本实现的落点）：
+ *   · **生命周期**：只有 runtime 拥有状态机；宿主壳（Activity）只能**转发**事件；非法转换被拒绝并记账。
+ *   · **线程**：只有 runtime.createWorker 能产生新的执行域；`runOnThread('background')` 在本宿主
+ *     诚实拒绝（threads.background=false）——调用方应先查 capabilities（G-39.3）。
+ *   · **事件循环**：只有 runtime.pumpFrame 消费队列（宿主帧驱动）；destroy 清空队列（不悬空）。
+ *   · **原生桥**：唯一出口 invokeNative；未注册 ⇒ 拒绝 + 记账（不静默返回 undefined）。
+ */
+export declare function createQuickJsHostRuntime(opts?: QuickJsHostOptions): QuickJsHostRuntime;

package/dist/screen-executor-host.d.ts

@@ -0,0 +1,67 @@
+import type { ScreenAnimHost, ScreenTreeHost } from './screen-executor';
+/** 宿主通道（与 `capability-app.ts` 的 `invokeHost` 同形：同步请求/响应字符串） */
+export type HostInvokeChannel = (method: string, argsJson: string) => string;
+/** 完成回调的全局键（宿主回推用——与 `__proteusHostAppEvent` 同一"约定即接口"模式） */
+export declare const SCREEN_ANIM_DONE_KEY = "__proteusHostScreenAnimDone";
+export interface HostScreenPortsOptions {
+    /** 宿主通道（生产：`invokeHost`；测试：记录桩） */
+    invoke: HostInvokeChannel;
+    /**
+     * 是否安装完成回调钩子（缺省 true）。
+     * ★与 `installAppEventSource` 同一防御姿态：QuickJS 的全局可能不可写 ⇒ try + defineProperty 回退，
+     *   且**失败不阻断**（动画完成退化为"宿主不回调"——调用方需自行兜底）。
+     */
+    installAnimDoneHook?: boolean;
+}
+export interface HostScreenPorts {
+    /** 树操作端口（执行器用） */
+    tree: ScreenTreeHost;
+    /** 动画端口（执行器用） */
+    anim: ScreenAnimHost;
+    /**
+     * ★★**跨页面共享元素**（2026-10-01 收诚实边界）：两棵内核树之间的飞行。
+     *
+     * 与同树共享元素的差别：源几何由**调用方注入**（跨页面的稳态起点只有页面栈层知道——
+     * 内核只认识"当前树"）。
+     *
+     * 用法（页面栈层）：目标页 mount 后 → `rect(目标屏, 目标节点)` 取终点基准 →
+     *   以「源页当前矩形」为 `sourceRect` 调 `fly(...)` ⇒ 内核算 dx/dy/scale 并写首帧 ⇒
+     *   宿主帧循环推进（与转场**同一条**完成链）。
+     */
+    shared: {
+        /** 单节点绝对矩形（内核算；跨页面几何回传的入口） */
+        rect(screenId: string, nodeId: number): Promise<{
+            x: number;
+            y: number;
+            w: number;
+            h: number;
+        }>;
+        /** 启动跨页面飞行（源=系统坐标矩形；目标=目标屏的节点） */
+        fly(opts: {
+            targetScreenId: string;
+            targetNodeId: number;
+            sourceRect: {
+                x: number;
+                y: number;
+                w: number;
+                h: number;
+            };
+            durMs?: number;
+            curve?: number;
+            fadeIn?: boolean;
+        }): Promise<{
+            fromRect?: unknown;
+            toRect?: unknown;
+        }>;
+    };
+    /** 在途动画 promise 数（诊断：应回落到 0） */
+    readonly pendingAnimations: number;
+    /** 完成回调是否已装（判据读——未装时"动画播完"不可达） */
+    readonly animDoneHookInstalled: boolean;
+}
+/**
+ * 创建**生产端口**（执行器 ↔ 宿主通道）。
+ *
+ * ★返回值是端口对 + 读数；执行器照常 `createScreenExecutor({host: ports.tree, anim: ports.anim, plan})`。
+ */
+export declare function createHostScreenPorts(opts: HostScreenPortsOptions): HostScreenPorts;

package/dist/screen-executor-host.js

@@ -0,0 +1,151 @@
+// src/screen-executor-host.ts
+var SCREEN_ANIM_DONE_KEY = "__proteusHostScreenAnimDone";
+var instSeq = 0;
+function call(channel, method, args) {
+  const raw = channel(method, JSON.stringify(args ?? null));
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    throw new Error(`[screen-host] ${method} \u56DE\u6267\u975E JSON\uFF1A${String(raw).slice(0, 120)}`);
+  }
+  if (parsed && parsed.ok === false) {
+    throw new Error(`[screen-host] ${method} \u5931\u8D25${parsed.missing ? "\uFF08\u672A\u5B9E\u73B0\uFF09" : ""}\uFF1A${parsed.reason ?? "\u65E0\u539F\u56E0"}`);
+  }
+  return parsed && typeof parsed === "object" && "data" in parsed ? parsed.data : parsed;
+}
+function createHostScreenPorts(opts) {
+  const channel = opts.invoke;
+  const pending = /* @__PURE__ */ new Map();
+  let tokenSeq = 0;
+  let hookInstalled = false;
+  const INSTANCE_ID = `s${++instSeq}-`;
+  const resolveOne = (token, payload) => {
+    const r = pending.get(token);
+    if (!r) return false;
+    pending.delete(token);
+    r(payload);
+    return true;
+  };
+  if (opts.installAnimDoneHook !== false) {
+    const g = globalThis;
+    const REGISTRY_KEY = `${SCREEN_ANIM_DONE_KEY}__registry`;
+    let registry = g[REGISTRY_KEY];
+    if (!Array.isArray(registry)) {
+      registry = [];
+      g[REGISTRY_KEY] = registry;
+    }
+    const handler = (token, resultJson) => {
+      if (typeof token !== "string") return "bad-token";
+      const r = registry;
+      for (let i = 0; i < r.length; i++) {
+        if (r[i](token, resultJson)) return "ok";
+      }
+      return "unknown-token";
+    };
+    registry.push((token, payload) => resolveOne(token, payload));
+    try {
+      g[SCREEN_ANIM_DONE_KEY] = handler;
+      hookInstalled = true;
+    } catch {
+      try {
+        Object.defineProperty(g, SCREEN_ANIM_DONE_KEY, { value: handler, writable: true, configurable: true });
+        hookInstalled = true;
+      } catch {
+      }
+    }
+  }
+  const tree = {
+    mountScreen(screen) {
+      const d = call(channel, "screen.mount", {
+        screenId: screen.screenId,
+        name: screen.name,
+        path: screen.path,
+        params: screen.params,
+        rebuild: screen.rebuild,
+        // ★★★GP3-c：**三层容器计划**随 mount 下发（宿主照此建树——偏移量，宿主加到自己分配的根 id 上）。
+        //   执行器已按契约算好（见 screen-executor.ts）；本层只做**透传**（不再重复计算——
+        //   本仓纪律：同一件事两份实现 = 修一份等于没修）。
+        ...screen.layerContainers ? { layerContainers: screen.layerContainers } : {},
+        // ★★★阶段 1（2026-10-04 · App 三端对齐 B1+B2）：**屏内容**（真实页面渲染产物）透传。
+        //   执行器按 `contentOf` 提供者解析后放入 mountScreen 入参；本层只做转发（与上方同款纪律）。
+        ...screen.content ? { content: screen.content } : {}
+      });
+      const rootNodeId = Number(d?.rootNodeId ?? 0);
+      if (!rootNodeId) {
+        throw new Error(`[screen-host] screen.mount \u672A\u8FD4\u56DE rootNodeId\uFF08${JSON.stringify(d)}\uFF09\u2014\u2014\u5BBF\u4E3B\u5B9E\u73B0\u4E0D\u5B8C\u6574`);
+      }
+      return rootNodeId;
+    },
+    setScreenVisible(screenId, visible, rootNodeId) {
+      call(channel, "screen.visible", { screenId, visible, rootNodeId });
+    },
+    destroyScreen(screenId, reason, rootNodeId) {
+      call(channel, "screen.destroy", { screenId, reason, rootNodeId });
+    }
+  };
+  const anim = {
+    playRouteTransition(plan, ctx) {
+      const anims = [...plan.incoming.anims, ...plan.outgoing.anims];
+      if (anims.length === 0) return;
+      const token = `${INSTANCE_ID}screen-anim-${++tokenSeq}`;
+      const d = call(channel, "screen.anim", {
+        anims,
+        durationMs: plan.durationMs,
+        direction: ctx.direction,
+        transition: ctx.transition,
+        token
+      });
+      if (d?.immediate === true) return;
+      return new Promise((resolve) => {
+        pending.set(token, () => resolve());
+      });
+    }
+  };
+  return {
+    tree,
+    anim,
+    shared: {
+      async rect(screenId, nodeId) {
+        const d = call(channel, "screen.rect", { screenId, nodeId });
+        if (!d || typeof d.x !== "number") {
+          throw new Error(`[screen-host] screen.rect \u672A\u8FD4\u56DE\u51E0\u4F55\uFF08${JSON.stringify(d)}\uFF09`);
+        }
+        return { x: d.x, y: d.y ?? 0, w: d.width ?? 0, h: d.height ?? 0 };
+      },
+      fly(opts2) {
+        const token = `screen-shared-${++tokenSeq}`;
+        const d = call(channel, "screen.shared", { ...opts2, token });
+        if (!d || (d.started ?? 0) < 1) {
+          return Promise.reject(new Error(`[screen-host] screen.shared \u672A\u542F\u52A8\uFF08${JSON.stringify(d)}\uFF09`));
+        }
+        const geom = { fromRect: d.fromRect, toRect: d.toRect };
+        return new Promise((resolve) => {
+          pending.set(token, (v) => {
+            let extra = {};
+            if (typeof v === "string") {
+              try {
+                const o = JSON.parse(v);
+                if (o && typeof o === "object") extra = o;
+              } catch {
+              }
+            } else if (v && typeof v === "object") {
+              extra = v;
+            }
+            resolve({ ...geom, ...extra });
+          });
+        });
+      }
+    },
+    get pendingAnimations() {
+      return pending.size;
+    },
+    get animDoneHookInstalled() {
+      return hookInstalled;
+    }
+  };
+}
+export {
+  SCREEN_ANIM_DONE_KEY,
+  createHostScreenPorts
+};

package/dist/screen-executor.d.ts

@@ -0,0 +1,239 @@
+import { type MountLayerContainerPlan } from '@proteus-vue/contracts';
+/** 屏命令（**结构类型**——与 `@proteus-vue/router` 的 `ScreenCommand` 同形；本文件不 import router） */
+export interface ScreenCommandLike {
+    op: 'mount' | 'enter' | 'exit' | 'unmount';
+    screenId: string;
+    name?: string;
+    path?: string;
+    params?: unknown;
+    rebuild?: boolean;
+    transition?: unknown;
+    reason?: 'pop' | 'reset' | 'freeze';
+}
+/**
+ * 引擎动画指令的最小结构（与 `EngineAnim` **结构兼容**——执行器只透传 + 读少量字段）。
+ * ★不要加索引签名（`[k: string]: unknown`）：那会让 `EngineAnim`（无该签名）**不可赋值**
+ *   （真机装置编译期实测抓到）。按需字段显式列出即可。
+ */
+export interface AnimLike {
+    nodeId: number;
+    from?: number;
+    to?: number;
+}
+/** 转场批次计划（与 `routeTransitionBatches` 的产物结构兼容） */
+export interface RouteTransitionPlanLike {
+    incoming: {
+        anims: readonly AnimLike[];
+    };
+    outgoing: {
+        anims: readonly AnimLike[];
+    };
+    durationMs: number;
+    opaque: boolean;
+}
+/** 转场规划器（注入端口；生产 = `@proteus-vue/animation` 的 `routeTransitionBatches`） */
+export type RouteTransitionPlanner = (transition: unknown, targets: {
+    incoming?: number;
+    outgoing?: number;
+}, opts?: {
+    direction?: 'forward' | 'back';
+}) => RouteTransitionPlanLike;
+/**
+ * ★★★**屏内容节点**（2026-10-04 · App 三端对齐 阶段 1）：一页渲染产物的**内核节点描述**。
+ *
+ * 【字段名与内核契约同源】与 `@proteus-vue/renderer-app` 的 `SelfDrawNodeSpec` 结构兼容
+ *   （`id/parentId/width/height/text/flexDirection/justifyContent/alignItems/gap/display/position/…`），
+ *   也与 Rust 内核 `create` 请求的 `NodeDto`（camelCase）同形——**一处命名，三处消费**。
+ * 【为什么用宽松类型】本包**不 import renderer-app**（依赖方向：renderer-app → render-backend 的反向会成环）；
+ *   故按**结构**声明 `id`/`parentId` + 其余内核字段（`Record<string, unknown>`）。定义处的强类型在
+ *   `SelfDrawNodeSpec`（SSOT）——本处只承诺"这是能被宿主透传给内核的节点描述"。
+ */
+export interface ScreenContentNode extends Record<string, unknown> {
+    id: number;
+    parentId: number | null;
+}
+/**
+ * ★★★**屏内容**（一页的渲染产物）——`screen.mount` 的 `content` 字段载荷。
+ *
+ * 【它解决什么用户可见问题】此前屏 = 空壳容器（宿主塞占位几何节点）⇒「路由在走、页面没渲染」。
+ *   本载荷把**真实页面内容**（由页面渲染器从 SFC 产物产出）送到宿主建树路径 ⇒ 屏里真有页面。
+ * 【id 空间】`nodes[].id`/`parentId` 是**内容局部**空间；宿主建屏时重映射到屏 id 空间（见 mountScreen 注释）。
+ * 【viewport 可选】缺省用屏尺寸（宿主已知）；提供时用于内容按视口求解（如百分比基准）。
+ */
+export interface ScreenContent {
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    nodes: readonly ScreenContentNode[];
+}
+/**
+ * 屏内容提供者（执行器选项）：按屏名/路径取该页渲染产物。
+ *
+ * 【为什么是"提供者"而不是塞进屏注册表】屏注册表（`AppScreenSpec`）在 **router 包**——
+ *   若把它与"渲染产物"（render-backend 概念）耦合，会让 router 依赖渲染层（方向错）。
+ *   ⇒ 由**装配层**（宿主桥/应用入口）注入 `name → ScreenContent` 解析（缺省无内容 ⇒ 向后兼容老行为）。
+ */
+export type ScreenContentProvider = (screen: {
+    name: string;
+    path: string;
+}) => ScreenContent | undefined;
+/**
+ * ★★★**LayoutTemplate → ScreenContent**（2026-10-04 · App 三端对齐 阶段 1b · B5）：
+ *   把编译器产出的**页面布局模板**（`buildLayoutTemplate` 的 `LayoutTemplate`，来自 SFC）
+ *   转成宿主建树用的屏内容节点。
+ *
+ * 【为什么需要（把"链路证明"变成"真实页面"）】阶段 1a 的 `contentOf` 用**装置内联**内容
+ *   （手写 4 个节点）证明链路；生产形态必须让内容来自 **SFC 产物**。本函数是那条"从产物到内容"
+ *   的**唯一转换点**（一处实现，两端宿主 + 测试共用）。
+ *
+ * 【转换规则（LayoutNode → 内核节点）】
+ *   · `id`/`parentId`/`text` 直接搬（内容局部 id 空间——宿主会重映射到屏 id 空间）；
+ *   · `style`（嵌套引擎字段对象）**展平到节点顶层**（内核 `create` 的 NodeDto 是**顶层**键：
+ *     `width`/`flexDirection`/`padding`/`backgroundColor`…）——这是本函数存在的**关键**：
+ *     `LayoutNode.style` 是嵌套的，内核要顶层，直接搬会静默丢样式（本仓踩过同款"字段形态不对"坑）。
+ *   · `tag` → `semantic`（诊断用；内核不解析标签，只透传）。
+ *
+ * 【★结构类型（不 import 编译器/slot-runtime）】本包**不依赖** compiler/slot-runtime
+ *   （依赖方向纪律）⇒ 入参用**结构**描述 `LayoutTemplate` 的最小子集（`nodes` 的
+ *   `{id,parentId,style,text?,tag?}`）——编译器产物天然满足（多字段无妨）。
+ *
+ * 【诚实边界】本函数只做**结构转换**；`LayoutNode.style` 已由编译器折叠成**引擎字段**
+ *   （px/数值/比例——见 `parseStaticStyle`），本函数**不做 CSS 解析**（那是编译期 C1 的职责）。
+ *   即：CSS class → style 的展开**尚未**支持（见 App 三端对齐缺口 C1）——本函数吃的是
+ *   已折叠的 `style`（来自 inline style / 结构化 paint 声明）。
+ */
+export declare function screenContentFromLayoutTemplate(template: {
+    nodes: ReadonlyArray<{
+        id: number;
+        parentId: number | null;
+        style?: Record<string, unknown>;
+        text?: string;
+        tag?: string;
+    }>;
+}, viewport?: {
+    width: number;
+    height: number;
+}): ScreenContent;
+/**
+ * 树操作端口（宿主实现——Android/iOS 各自对接 Host ABI 的树接口）。
+ * ★三个方法都是"屏粒度"：宿主内部怎么落子树（load_tree / splice / 五原子销毁）不由本层约束。
+ */
+export interface ScreenTreeHost {
+    /** 建屏子树（首次挂载 rebuild=false；冻结后重建 rebuild=true）。返回**屏子树根节点 id**（转场动画的目标） */
+    mountScreen(screen: {
+        screenId: string;
+        name: string;
+        path: string;
+        params: unknown;
+        rebuild: boolean;
+        /**
+         * ★★★**屏内容**（2026-10-04 · App 三端对齐 阶段 1 · B1+B2）：该页**渲染产物**——内核节点描述列表。
+         *
+         * 【这是什么（消灭"屏 = 空壳容器"的关键）】此前 `screen.mount` 建的是**空子树**（宿主塞 3 个
+         *   占位几何节点）⇒ "路由在走、页面没渲染"（缺口 B2）。本字段携带**真实页面内容**：
+         *   由页面渲染器（`@proteus-vue/renderer-app` 的 selfdraw 适配器 `buildRequest`）从 SFC 产物
+         *   产出——`{ nodes: SelfDrawNodeSpec[] }`，字段名与内核 `create` 契约**同源**
+         *   （`id/parentId/width/text/flexDirection/...`）。
+         *
+         * 【★ id 空间（宿主职责）】content 里的 `id`/`parentId` 属**内容局部**空间（通常 1..N）。
+         *   宿主建屏时**必须重映射到屏 id 空间**（与层容器/屏根不冲突）——契约只承诺
+         *   "节点间的父子关系由 parentId 表达"，不约束宿主怎么分配最终 id（与
+         *   `mountLayerNodeId` 的"偏移量而非绝对 id"同一哲学）。`parentId === null` ⇒ 挂到
+         *   **page 内容容器**（层计划里的 page 层；无层计划则挂屏根）。
+         * 【诚实边界】本字段只保证"内容被下发"；内核对它建没建、建得对不对，由宿主读数
+         *   （`contentNodes` 数 / 几何探针）与判据证明——本层不声称。
+         */
+        content?: ScreenContent;
+        /**
+         * ★★★GP3-c（2026-10-03）：**三层挂载容器计划**（宿主据此在屏根下建三层容器）。
+         *
+         * 【为什么由执行器下发而不是宿主自造】层容器的偏移/树序/几何口径是**契约**
+         *   （`@proteus-vue/contracts` 的 `mountLayerContainerPlans`）；两端宿主各写一遍
+         *   = **同一件事两份实现**（本仓纪律：修一份等于没修）。⇒ 执行器（TS，两端同一份）
+         *   下发计划，宿主**只做"照此建树"**。
+         *
+         * 【宿主要做什么】对每项建一个容器：`id = rootId + nodeOffset`、`parentId = rootId`、
+         *   `position: absolute` + 宽高 = 屏尺寸 ⇒ **按数组顺序**加入 nodes（内核树序即层序）。
+         *   ★`global` 层容器**不随屏销毁**（见契约 `MOUNT_LAYER_HOST_CONTRACT.survivesRouteChange`）。
+         *   ★可选字段：宿主不认识它可忽略（向后兼容——老宿主照常工作，只是没有三层结构）。
+         */
+        layerContainers?: readonly MountLayerContainerPlan[];
+    }): number | Promise<number>;
+    /** 可见性切换（true = 显示；false = 隐藏但**树保留**——虚拟栈的核心语义） */
+    setScreenVisible(screenId: string, visible: boolean, rootNodeId: number | undefined): void | Promise<void>;
+    /** 销毁屏子树（reason 区分 pop/reset/freeze；五原子销毁由宿主实现负责） */
+    destroyScreen(screenId: string, reason: 'pop' | 'reset' | 'freeze', rootNodeId: number | undefined): void | Promise<void>;
+}
+/** 动画播放端口（宿主实现——内核 `anim_start` 或平台零参与提交路径） */
+export interface ScreenAnimHost {
+    /**
+     * 播放一次路由转场（**两页批次并发**——一次导航 = 一次跨边界提交）；
+     * promise resolve 时视为动画完成（无动画的宿主实现可同步返回）。
+     */
+    playRouteTransition(plan: RouteTransitionPlanLike, ctx: {
+        direction: 'forward' | 'back';
+        transition: string;
+    }): void | Promise<void>;
+}
+/** 执行器运行读数（判据/诊断读它——如"3 次导航 = 3 次转场提交"） */
+export interface ScreenExecutorStats {
+    /** 消费的命令总数 */
+    commands: number;
+    /** 实际播放的转场次数（空批次跳过的不计） */
+    transitions: number;
+    /** 方向分档计数 */
+    forward: number;
+    back: number;
+    /** 空规格（none/无动画）跳过的"转场"次数 */
+    skippedNone: number;
+    /** 被销毁的屏数（按 reason 计数） */
+    destroyed: {
+        pop: number;
+        reset: number;
+        freeze: number;
+    };
+    /** 可见性变更次数（true / false） */
+    visibility: {
+        shown: number;
+        hidden: number;
+    };
+    /** 建屏次数（含 rebuild） */
+    mounts: {
+        first: number;
+        rebuild: number;
+    };
+    /** 编排层错误（如 enter 的屏没有子树——不静默） */
+    errors: string[];
+}
+export interface ScreenExecutorOptions {
+    host: ScreenTreeHost;
+    anim: ScreenAnimHost;
+    plan: RouteTransitionPlanner;
+    /**
+     * ★★★（2026-10-04 · App 三端对齐 阶段 1）：**屏内容提供者**——按屏名/路径取该页渲染产物。
+     *   · 提供 ⇒ 屏里是**真实页面内容**（`screen.mount` 带 `content`）；
+     *   · 缺省（未提供）⇒ 向后兼容：不带 `content`，宿主按老行为建（空壳/占位）——
+     *     老宿主与老装置不受影响（零行为变化）。
+     *   ★诚实边界：本项只负责"把内容送到宿主建树路径"；内容**从哪来**（SFC 产物 → 节点描述）
+     *     由装配层（`@proteus-vue/renderer-app` 的 selfdraw `buildRequest`）决定，本层不声称。
+     */
+    contentOf?: ScreenContentProvider;
+    /** 建屏完成通知（接 `AppStack.markRebuilt`——契约要求"执行器建完调 markRebuilt"） */
+    onScreenMounted?: (screenId: string, rebuild: boolean) => void;
+    /** 诊断事件（记录端口调用顺序——真机判据/测试断言读它） */
+    onEvent?: (e: {
+        type: string;
+        screenId?: string;
+        detail?: unknown;
+    }) => void;
+}
+export interface ScreenExecutor {
+    /** 消费一批命令（一次 `stack.drainCommands()` 的产物）。★串行化：并发调用按调用序排队 */
+    applyCommands(commands: readonly ScreenCommandLike[]): Promise<void>;
+    /** 读数快照 */
+    stats(): ScreenExecutorStats;
+    /** 屏子树根节点（screenId → nodeId；诊断/转场目标查询） */
+    subtreeNode(screenId: string): number | undefined;
+}
+export declare function createScreenExecutor(opts: ScreenExecutorOptions): ScreenExecutor;