weifuwu 0.86.0 → 0.87.0

package/dist/client/vdom/core/patch/processors.d.ts

@@ -0,0 +1,75 @@
+/**
+ * vdom core/patch — processors（命令处理器——独立文件）
+ *
+ * 职责：各命令的消费逻辑（细节）——CommandApplier（index.ts）只做
+ * 中转（apply switch → 本模块分发）。
+ *
+ * 生命周期语义：
+ * - ref（挂载完成——insert 后——el 已连接）；unref/remove/done（ref(null)）
+ * - mount（组件初始化标记）；unmount（onUnmounts 逆序）
+ * - move（顺移 remap / 移动 + 重映射）
+ * - done.full（全量流清理旧树多余节点——资源释放完整）
+ */
+import type { Command } from '../command/index.ts';
+import { RefRegistry } from '../field/ref.ts';
+import type { CommandApplier } from './index.ts';
+export type WfNode = HTMLElement | Text | Comment;
+export declare function procCreate(applier: CommandApplier, cmd: Extract<Command, {
+    op: 'create';
+}>): void;
+/** createText 处理器（幂等） */
+export declare function procCreateText(applier: CommandApplier, cmd: Extract<Command, {
+    op: 'createText';
+}>): void;
+/** createAnchor 处理器（占位锚——幂等） */
+export declare function procCreateAnchor(applier: CommandApplier, cmd: Extract<Command, {
+    op: 'createAnchor';
+}>): void;
+/** insert 处理器（挂载——ref 查表触发）
+ *  **ref=null 语义 = 容器头部**（diff 逐槽对照首项/新增首项——位置 0
+ *  ——append 会把位置 0 的新项追加到末尾——错位——真实 bug） */
+export declare function procInsert(applier: CommandApplier, cmd: Extract<Command, {
+    op: 'insert';
+}>): void;
+/** move 处理器（顺移 remap / 移动 + 重映射） */
+export declare function procMove(applier: CommandApplier, cmd: Extract<Command, {
+    op: 'move';
+}>): void;
+/** remove 处理器（卸载——ref(null) + 事件表 + 节点移除） */
+export declare function procRemove(applier: CommandApplier, cmd: Extract<Command, {
+    op: 'remove';
+}>): void;
+/** setText 处理器（就地更新）
+ *  防御审计（P2）：!t / 非文本 = setText Pre 违例（生成层 bug——Sim 状态机
+ *  验证器在测试层显式 Reject（setText Pre 违例 throw）——生产保留静默防御
+ *  （真实浏览器环境差异兜底——不中断渲染管线） */
+export declare function procSetText(applier: CommandApplier, cmd: Extract<Command, {
+    op: 'setText';
+}>): void;
+/** setProp 处理器（ref 生命周期 / 事件代理 / 三通道） */
+export declare function procSetProp(applier: CommandApplier, cmd: Extract<Command, {
+    op: 'setProp';
+}>): void;
+/** ref 指令（挂载完成——insert 后） */
+export declare function procRef(applier: CommandApplier, cmd: Extract<Command, {
+    op: 'ref';
+}>): void;
+/** unref 指令（ref(null)） */
+export declare function procUnref(applier: CommandApplier, cmd: Extract<Command, {
+    op: 'unref';
+}>): void;
+/** mount 指令（组件初始化完成——审计标记） */
+export declare function procMount(applier: CommandApplier, cmd: Extract<Command, {
+    op: 'mount';
+}>): void;
+export declare function procUnmount(applier: CommandApplier, cmd: Extract<Command, {
+    op: 'unmount';
+}>): void;
+/** done 处理器（full 清理——旧树多余节点——资源释放完整） */
+export declare function procDone(applier: CommandApplier, cmd: Extract<Command, {
+    op: 'done';
+}>): void;
+/** 命令分发（中转——switch → 处理器） */
+export declare function dispatch(applier: CommandApplier, cmd: Command): void;
+/** RefRegistry 内部访问（procSetProp 的 prev 查询——同包约定） */
+export type { RefRegistry };

package/dist/client/vdom/core/patch/state-machine.d.ts

@@ -0,0 +1,38 @@
+/**
+ * vdom core/patch — 状态机规格（单一实现源——P3c）
+ *
+ * 目标：NodeState 迁移 + Post 验证的**唯一规格源**——Sim（契约层对账器）
+ * 与 createDevVerifier（生产 dev 检查）共用——消灭双实现漂移（isConnected
+ * 类误报的根治——规格只有一份——两边行为恒等）。
+ *
+ * 规格（design/vdom-state-machine-plan.md §2.1/§3）：
+ *   ABSENT → CREATED → INSERTED → ACTIVE（close）→ REMOVED
+ *   - create 族：ABSENT → CREATED（同形复用不变）
+ *   - insert：CREATED → INSERTED（INSERTED/ACTIVE = 幂等 skip）
+ *   - close：INSERTED → ACTIVE（ACTIVE = 幂等 skip——重建路径）
+ *   - remove：任意 → REMOVED（记录前缀清除——Post：无残留）
+ *   - setText/setProp/move：节点存在性 Post（类型检查由调用方——
+ *     Sim 查 SimNode.kind / devVerify 查 nodeType——各层有各自数据面）
+ *
+ * 迁移返回违例数组（不 throw）——调用方决定：Sim throw（测试红）/
+ * devVerify console.error（dev 报告）。
+ */
+import type { Command } from '../command/index.ts';
+export type NodeState = 'created' | 'inserted' | 'active';
+/** 状态跟踪器（id → NodeState——调用方数据面无关） */
+export interface StateTracker {
+    get(id: string): NodeState | undefined;
+    set(id: string, s: NodeState): void;
+    /** 前缀清除（remove/done 的子树记录） */
+    removePrefix(id: string): void;
+    /** 前缀残留检查（remove Post） */
+    hasPrefix(id: string): boolean;
+    /** 前缀重映射（move——id 空间跟随——nodes/事件/ref 同规则） */
+    remapPrefix(oldPrefix: string, newPrefix: string): void;
+    /** 全量重置（done——渲染流结束——与 touched.clear() 对齐） */
+    clear(): void;
+}
+/** Map 实现（Sim/devVerify 共用） */
+export declare function createStateTracker(): StateTracker;
+/** 状态迁移 + Post 验证（纯逻辑——单一规格源——违例返回数组） */
+export declare function transition(tracker: StateTracker, cmd: Command): string[];

package/dist/client/vdom/core/patch/verify.d.ts

@@ -0,0 +1,17 @@
+/**
+ * vdom core/patch — dev 验证器（状态机 Post 断言——dev only）
+ *
+ * 机制（P3b/P3c）：CommandApplier 可选注入 devVerify——每个命令消费后
+ * 断言 Post——**状态机规格单一实现源**：patch/state-machine.ts（transition
+ * ——与 Sim（契约层对账器）共用——消灭双实现漂移）——数据面类型检查
+ * （nodeType）与挂载性（isConnected）在此补充（规格的类型维度由各数据面
+ * 承担——Sim 查 SimNode.kind / devVerify 查 nodeType）。
+ *
+ * 报告方式：console.error（不中断渲染管线——dev 可见性）——
+ * 违例 = 生成层 bug 或 Sim 与浏览器语义差异（isConnected 类问题落验）。
+ *
+ * 生产零开销：仅 window.__WF_DEV__ 开启时注入（serve.ts）。
+ */
+import type { Command } from '../command/index.ts';
+import type { CommandApplier } from './index.ts';
+export declare function createDevVerifier(): (cmd: Command, applier: CommandApplier) => void;

package/dist/client/vdom/core/router.d.ts

@@ -0,0 +1,31 @@
+/**
+ * vdom core — route 阶段（UIRouter——应用唯一入口——公共面）
+ *
+ * 设计（design/vdom-plan.md §2）：Handler 签名字面同构后端——
+ * `(req: Request, ctx) => Response`——原生 Request/Response——
+ * 路由核心 = shared Trie（src/shared/router/trie.ts——前后端共用）——
+ * 静态段优先 → :param → * 通配——params 注入 req。
+ */
+import type { UIContext } from '../context/UIContext.ts';
+import type { Command } from './command/index.ts';
+/** 页面 handler——返回原生 Response（body = 命令流字节——NDJSON）——
+ *  与后端 Handler 签名字面同构：(req, ctx) => Response——req 为**标准
+ *  Request**（零扩展——params/query 经 ctx 注入） */
+export type PageHandler = (req: Request, ctx: UIContext) => Response | Promise<Response>;
+/** 渲染入口封装：命令流 → 原生 Response（body = NDJSON 字节流——
+ *  HTTP 传输层即字节——命令纯数据可序列化——服务端同源解析） */
+export declare function commandResponse(stream: ReadableStream<Command>, init?: ResponseInit): Response;
+/** 构造前端请求（纯标准 Request——零扩展——URL 基于 http://localhost） */
+export declare function frontRequest(path: string): Request;
+export declare class UIRouter {
+    private root;
+    private notFoundHandler;
+    /** 注册路由（shared Trie——静态/:param/*——params 注入 req） */
+    get(path: string, handler: PageHandler): this;
+    /** 404 兜底 */
+    notFound(handler: PageHandler): this;
+    /** 解析请求 → 响应（Trie 匹配 + **params/query 注入 ctx**——对齐后端
+     *  `ctx = { params, query }`——`Object.fromEntries(searchParams)`——
+     *  不修改原始 Request） */
+    resolve(req: Request, ctx: UIContext): Promise<Response>;
+}

package/dist/client/vdom/core/serve.d.ts

@@ -0,0 +1,75 @@
+/**
+ * vdom core — uiServe（渲染落地——公共面——双端一体）
+ *
+ * 设计（design/vdom-plan.md §3/§4）：
+ * - UIRouter 唯一应用入口——uiServe(router, { root }) 收养渲染（真实浏览器全局
+ *   document/window——2026-12 删除 browser 注入——测试与生产同环境）
+ * - 渲染循环：初始 URL resolve → Response（command 事件流）→ patch
+ * - **ctx.render() = 重新渲染**（事件触发/fetch 结束/定时器回调的唯一入口）：
+ *   重新 resolve（handler 重跑——registry 复用——组件工厂不重跑——
+ *   renderFn 重调读最新状态）→ **新的 Response command 事件流** → 消费
+ *   （patch 对照现有 DOM 节点——幂等——就地更新）
+ * - 函数面传输：同进程共享函数表——编码时函数 → {$fn: n} 标记——
+ *   解码时查表还原（事件绑定跨 Response 保持）
+ *
+ * 服务端面（SSR——同一 handler 同一 Response——body 经 commandToHtml()
+ * TransformStream 流式吐 HTML）后续实现。
+ */
+import { UIRouter } from './router.ts';
+import type { VNode } from './vnode.ts';
+import type { UIContext } from '../context/UIContext.ts';
+import type { Command } from './command/index.ts';
+/** 函数表还原（$fn 标记 → 函数——编码/解码同进程共享） */
+export declare function reviveFn(fnTable: Map<number, unknown>): (k: string, v: unknown) => unknown;
+/** NDJSON 命令流解析（行缓冲——命令可能跨 chunk——函数表还原——
+ * 导出（测试——跨 chunk 边界/畸形行合规断言）） */
+export declare function commandReader(reader: ReadableStreamDefaultReader<Uint8Array>, fnTable: Map<number, unknown>): AsyncGenerator<Command>;
+/** 命令流编码（函数面 → {$fn: n}——函数表——同进程共享） */
+export declare function encodeCommands(stream: ReadableStream<Command>, fnTable: Map<number, unknown>): ReadableStream<Uint8Array>;
+/** 函数表（serve 级共享——编码/解码同进程） */
+export declare function createFnTable(): Map<number, unknown>;
+export interface UiServeOptions {
+    /** 根容器（选择器或元素——'#root'） */
+    root: string | HTMLElement;
+    /** 中间件注入面（ctx.api/auth/ws/i18n——组件/页面可用——可选） */
+    api?: import('../middlewares/api.ts').ApiClient;
+    auth?: import('../middlewares/auth-i18n.ts').AuthClient;
+    ws?: import('../middlewares/ws.ts').WsClient;
+    i18n?: import('../middlewares/auth-i18n.ts').I18nState;
+    /** 命令式轻提示（ctx.toast——应用装配） */
+    toast?: (message: string, type?: 'success' | 'error' | 'info' | 'warning', duration?: number) => void;
+    /** 命令式确认（ctx.confirm——应用装配——返回 Promise<boolean>） */
+    confirm?: (message: string, options?: Record<string, unknown>) => Promise<boolean>;
+    /** 命令式通知（ctx.notification——应用装配） */
+    notification?: unknown;
+    /**
+     * 渲染错误回退 UI（R1 熔断——连续渲染错误达阈值后显示——应用可配置——
+     * 缺省内置：错误文案 + 重试按钮（独立于应用路由——不依赖 router.resolve））
+     */
+    errorFallback?: (error: Error, ctx: UIContext) => VNode;
+}
+export interface UiServeHandle {
+    /** 首帧渲染完成 Promise（await 精确等待） */
+    ready: Promise<void>;
+    /** 编程式导航（URL 变化 → 重新 resolve → 新命令事件流 → 消费——
+     *   root 异类型 = 整树替换；同类型 = diff 精准） */
+    navigate(path: string): Promise<void>;
+    /** 卸载（清理 DOM/监听） */
+    unmount(): void;
+}
+/** serve 生命周期状态机（**全部状态机化——2026-XX**）：
+ *  active → unmounted（unmount 消费——迁移后 render/navigate 违例报错） */
+export type ServePhase = 'active' | 'unmounted';
+/** 渲染队列状态机（**替代裸 rendering boolean**）：
+ *  idle → rendering（render 启动）→ idle（runRender 完成/错误/队列空）
+ *  - rendering 中 render() → 入队（合法——FIFO 确定性——非违例）
+ *  - unmounted 中 render()/navigate() → 违例报错（DOM 已清——静默渲染
+ *    是隐藏错误——审计 2026-XX） */
+export type RenderPhase = 'idle' | 'rendering';
+/** 页面作者渲染入口（ctx 面——vnode → Response command 事件流——
+ *  公共面仍只有 h/jsx/uiServe/UIRouter——本入口经 ctx 提供） */
+export interface RenderCtx extends UIContext {
+    /** vnode → Response（command 事件流——函数表编码——事件绑定跨流保持） */
+    stream(vnode: VNode, init?: ResponseInit): Response;
+}
+export declare function uiServe(router: UIRouter, opts: UiServeOptions): UiServeHandle;

package/dist/client/vdom/core/ssr/absorb.d.ts

@@ -0,0 +1,53 @@
+/**
+ * vdom core/ssr — absorb（SSR 结构吸收状态机）
+ *
+ * 首帧结构对齐：SSR 输出静态 HTML → 客户端 uiServe 接管——create 命令
+ * 按 DFS 序消费 SSR 节点（类型匹配复用——焦点/状态保持——零重建）。
+ *
+ * 职责边界（中转——命令分发细节在 processors——本文件只持有状态 +
+ * 匹配判定）：
+ * - begin（DFS 序快照——不消费 root 自身）
+ * - next（匹配消费——元素按 tag 匹配 / 文本 / 注释锚——不匹配跳过）
+ * - end（done.full 收尾——剩余节点 = SSR 输出多于命令 → mismatch）
+ * - failed（serve 检测回退清空重建——原子性）
+ *
+ * 确定性前提（诚实裁剪）：SSR 与客户端首帧必须同构（同路由同组件——
+ * 渲染期非确定（Date/Math.random）→ mismatch → 回退重建——dev 检测）。
+ */
+/** 吸收状态机（**状态机化——非法调用顺序显式 Reject**）：
+ *  inactive → begin → consuming →（end/next 耗尽）→ inactive/failed
+ *  - begin：inactive → consuming（DFS 序快照）
+ *  - next：consuming → consuming（消费）/ failed（队列耗尽）
+ *  - end：consuming → inactive（无剩余）/ failed（剩余 = mismatch）
+ *  - reset：任意 → inactive（回退重建）
+ *  违例（静默路径歼灭——审计 2026-XX）：next/end 在 inactive 调用 →
+ *  显式 console.error（不再静默返回 null——非法顺序是 bug）
+ */
+import type { WfNode } from '../patch/processors.ts';
+/** 吸收阶段（状态机枚举） */
+export type AbsorbPhase = 'inactive' | 'consuming' | 'failed';
+/** 吸收状态（CommandApplier 持有——apply 层消费） */
+export declare class AbsorbState {
+    /** DFS 序快照（root 后代——create 按序消费） */
+    queue: Node[] | null;
+    /** 吸收失败（SSR 与命令流不匹配——serve 回退清空重建） */
+    failed: boolean;
+    /** 状态机阶段（迁移：begin→consuming；end/reset→inactive；耗尽→failed） */
+    phase: AbsorbPhase;
+    /** 启动吸收（root 有 SSR 内容——DFS 序快照——不消费 root 自身） */
+    begin(container: HTMLElement): void;
+    /** 吸收结束（done.full）——剩余节点 = SSR 输出多于命令——mismatch
+     *  **inactive 时 = 合法 no-op**（procDone 无条件调用——非 SSR 客户端
+     *  渲染未 begin——end 无意义——不报错）；consuming 时 = 正常收尾 */
+    end(): void;
+    /** 重置（回退重建后——恢复非吸收态） */
+    reset(): void;
+    /** 吸收消费（create 族——匹配下一个 SSR 节点——类型不符/耗尽 → 失败）
+     *  **文本分裂（2026-08——SSR 相邻文本合流实战）**：HTML 序列化会把
+     *  相邻 createText 合并成一个 DOM 文本节点（如 ` › ` + `InputNumber`
+     *  → `" › InputNumber"`）——但客户端命令流是两条 createText——按整节点
+     *  消费会吞掉后缀（后续 next 找不到文本 → 耗尽 failed）→ 前缀匹配 +
+     *  splitText 分裂：剩余部分 unshift 回队列头部——命令流 1:1 对齐
+     *  （procCreateText 传目标 value——prefix 判定） */
+    next(kind: 'element' | 'text' | 'comment', tag?: string, value?: string): WfNode | null;
+}

package/dist/client/vdom/core/ssr/html.d.ts

@@ -0,0 +1,32 @@
+/**
+ * vdom core — commandToHtml（命令事件流 → HTML——流式 SSR 核心）
+ *
+ * 设计（design/vdom-plan.md §3）：服务端消费同一 handler 的 Response——
+ * `res.body.pipeThrough(commandToHtml())` → HTTP 流式响应（边构建边吐
+ * HTML——React Fizz 同模式）：
+ * - create（attrs 序列化面）→ 开标签（属性转义——style 对象 → CSS 文本）
+ * - createText → 转义文本；createAnchor → 注释占位
+ * - close → 闭标签（tag 栈——void 元素不闭合）
+ * - insert/remove/setProp（事件/运行时面）/done → 无输出（HTML 无交互面）
+ * - setText → 转义文本（增量流场景）
+ *
+ * 与客户端同构：同一命令流——客户端 apply DOM / 服务端吐 HTML——
+ * 精准增量流 → 增量 HTML（服务端驱动更新后续）。
+ */
+import type { Command } from '../command/index.ts';
+/** HTML 转义（文本/属性值） */
+export declare function escapeHtml(s: string): string;
+/** void 元素（自闭——close 不吐闭标签） */
+export declare const VOID_ELEMENTS: Set<string>;
+/** camelCase → kebab-case（style 对象序列化） */
+export declare function kebab(s: string): string;
+/** create attrs → HTML 属性字符串（转义——style 对象 → CSS 文本——boolean 空串） */
+export declare function attrsToHtml(attrs: Record<string, unknown>): string;
+/** 命令事件流 → HTML 字符串流（TransformStream——tag 栈闭合） */
+export declare function commandToHtml(): TransformStream<Command, string>;
+/** 完整 HTML 文档包装（SSR 页面——<!DOCTYPE html> + root 容器） */
+export declare function htmlDocument(html: string, opts?: {
+    title?: string;
+    rootId?: string;
+    data?: Record<string, unknown>;
+}): string;

package/dist/client/vdom/core/ssr/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * vdom core/ssr — index（SSR 中转站——自身不处理细节逻辑）
+ *
+ * 职责：服务端渲染入口（uiSsr——同一 UIRouter 同一 handler）——
+ * 具体功能交由独立文件：
+ * - html.ts（commandToHtml 流式序列化 + htmlDocument 文档包装）
+ * - absorb.ts（客户端结构吸收状态机——首帧复用 SSR DOM）
+ *
+ * 与客户端同构：同一命令流——客户端 apply DOM / 服务端吐 HTML——
+ * 首帧吸收（结构对齐）——接管原子性（mismatch → 回退清空重建）。
+ */
+export { escapeHtml, attrsToHtml, htmlDocument, commandToHtml, VOID_ELEMENTS, kebab } from './html.ts';
+export { AbsorbState } from './absorb.ts';
+import { UIRouter } from '../router.ts';
+/** 服务端渲染选项 */
+export interface SsrOptions {
+    title?: string;
+    /** __DATA__ 种子（ctx.data 预取结果——序列化进文档） */
+    data?: Record<string, unknown>;
+}
+/** 服务端渲染（SSR——同一 router 同一 handler——命令流 → HTML 文档）
+ *  **无 hydration**（客户端接管结构吸收——SSR = 首屏/SEO + 吸收种子）；
+ *  函数面（事件）经空函数表编码为 $fn 标记——解码 undefined——
+ *  commandToHtml 的 setProp no-op——HTML 无运行时面 */
+export declare function uiSsr(router: UIRouter, url: string, opts?: SsrOptions): Promise<string>;

package/dist/client/vdom/core/transform/component.d.ts

@@ -0,0 +1,23 @@
+/**
+ * vdom transform — component（组件转换——component ↔ X）
+ *
+ * 场景（条件渲染主场景——组件类型切换）：
+ *   component <-> null（{cond && <Comp/>}——卸载/挂载）
+ *   component <-> fragment（组件输出多根 ↔ 展开项）
+ *   component <-> element（组件 ↔ 原生元素）
+ *
+ * 同类型 component → component 不在本表（diff 层复用——工厂不重跑——
+ *  renderFn 重新调用——let/ref 状态保持）；异类型组件（A <-> B）同样
+ * 走本表（旧组件卸载 + 新组件由 diff mount）。
+ *
+ * 转换职责（old=component → new=X）：
+ * 1. unmountComp（onUnmounts 清理——ctx.onUnmount 注册的回调——逆序执行）
+ * 2. 旧组件输出节点移除——**区间完整移除（G2——终态等价违例）**：
+ *    组件输出多根 = 隐式 Fragment（展开槽位 parent.i+1...）——只移除首锚
+ *    会让第二节点起 DOM 残留（fuzz 实证）——经 registry 查 lastOutput
+ *    → removeVNodeTree 递归（数组全形态 + 组件项 unmount）
+ * 3. 新节点由 diff 渲染到同一位置（首锚位置）
+ */
+import type { TransitionFn } from './index.ts';
+/** component → X：组件卸载（onUnmounts）+ 输出区间移除（让位） */
+export declare const transitionComponent: TransitionFn;

package/dist/client/vdom/core/transform/element.d.ts

@@ -0,0 +1,21 @@
+/**
+ * vdom transform — element（元素转换——element ↔ X）
+ *
+ * 场景：类型切换（<div/> <-> 组件 / <div/> <-> 文本 / <div/> <-> null）。
+ * 同态 element → element 不在本表（就地 patch——diff 层：属性/事件/children）。
+ *
+ * 转换职责（old=element → new=X）：
+ * 1. 旧元素移除（remove oldId——含子树——事件监听随元素 GC）
+ * 2. 新节点由 diff 渲染到同一位置
+ * —— 旧元素若为组件输出根（组件卸载语义）——组件侧先 unmount
+ */
+import type { TransitionFn } from './index.ts';
+/** element → X：旧元素移除（含子树——让位）
+ *  **根本修复（C2——统一区间移除）**：单锚 remove 只删元素自身——子树内
+ *  组件实例（unkeyed compId = DOM 槽位 id）残留（onUnmounts 不执行——
+ *  S_INST 面——组件树 fuzz 实证）——removeVNodeTree 递归：声明子树槽位 +
+ *  组件项 unmount + 组件输出区间（registry 查 lastOutput）——与
+ *  transitionComponent/transitionFragment 统一——消费端零猜测
+ *  （procRemove 前缀卸载因 id 空间重叠误删——deep-tour 回归——回退——
+ *  卸载信息由 diff 层完整生成） */
+export declare const transitionElement: TransitionFn;

package/dist/client/vdom/core/transform/fragment.d.ts

@@ -0,0 +1,21 @@
+/**
+ * vdom transform — fragment（Fragment/数组转换——fragment ↔ X）
+ *
+ * 场景（隐式 Fragment——数组/`<></>`/组件输出多根）：
+ *   fragment <-> null（空数组 ↔ 条件渲染）
+ *   fragment <-> element（展开项 ↔ 单元素）
+ *   fragment <-> component（展开项 ↔ 组件）
+ *
+ * 同态 fragment → fragment 不在本表（diff 层逐项转换——keyed/unkeyed
+ * 列表 diff——按位置/key 逐项对比）。
+ *
+ * 转换职责（old=fragment → new=X）：**旧展开区间完整清理**（数组/多节点
+ * 递归 remove——不是只清首锚——数组多项残留事故的根治）——新侧经
+ * emitNode 渲染到同一位置。
+ */
+import type { TransitionFn } from './index.ts';
+/** fragment → X：旧展开区间完整清理（数组逐项递归——非只清首锚）+
+ *  新侧渲染到同一位置（展开位置连续——pathId(parent, index + ci)）
+ *  **单一实现源**：区间移除统一 removeVNodeTree（cleanup.ts——FRAG 展开
+ *  到父级槽位/数组全形态/组件 unmount——与 diff 各路径共享——防双实现漂移） */
+export declare const transitionFragment: TransitionFn;

package/dist/client/vdom/core/transform/hole.d.ts

@@ -0,0 +1,13 @@
+/**
+ * vdom transform — hole（空洞转换——null <-> X 主场景）
+ *
+ * 条件渲染核心（设计规则 §6.3——占位法）：`{cond && <X/>}` = false 占位锚——
+ * cond 翻转时 **占位锚 ↔ 真实节点互换**（禁止 removeChild 塌缩 childNodes——
+ * 长度恒定则预捕获索引全有效——提交按钮消失事故的根治）。
+ *
+ * 转换职责（old=hole → new=X）：旧占位锚移除（让位）——新节点由 diff
+ * 主循环渲染到同一位置（parent/ref）——childNodes 长度不变（1:1 互换）。
+ */
+import type { TransitionFn } from './index.ts';
+/** hole → X：旧占位锚移除（让位——新节点 diff 渲染到同一位置） */
+export declare const transitionHole: TransitionFn;

package/dist/client/vdom/core/transform/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * vdom transform — 节点转换状态机（节点类型之间的转换渲染）
+ *
+ * 场景（diff 重渲染——旧节点 × 新节点类型不同）：
+ *   null <-> component / null <-> fragment / component <-> fragment /
+ *   element <-> component / hole <-> element / text <-> element ...
+ *
+ * 核心不变量（设计规则 §4.0/§6.3——占位法）：
+ * - **childNodes 长度恒等于 children 数组长度**——任何转换保持节点数 1:1
+ *   （空洞占位锚是 DOM 里的真实节点——转换 = 锚 ↔ 真实节点 replaceChild 互换——
+ *   禁止 removeChild 塌缩）
+ * - 组件输出多根 = 隐式 Fragment——锚点管理（首/尾锚——_childAnchors 语义）
+ * - 组件卸载 = unmountComp（onUnmounts 清理）+ 输出节点移除
+ *
+ * 转换表（table.ts）：oldKind × newKind → 策略函数（各状态文件实现）
+ *   text.ts / hole.ts / element.ts / component.ts / fragment.ts
+ */
+import type { VNodeChild } from '../vnode.ts';
+import type { ComponentRegistry } from '../node/component.ts';
+export type NodeState = 'text' | 'hole' | 'element' | 'component' | 'fragment' | 'array';
+/** 转换上下文（diff 调用——命令发射 + 新侧渲染 + 位置信息） */
+export interface TransformContext {
+    /** 命令发射（旧侧让位：remove/unmountComp——diff 生成的命令序列） */
+    emit(cmd: unknown): void;
+    /** 新侧渲染（sink——共享分发器——转换函数内部完成完整转换） */
+    emitNode(v: VNodeChild, parent: string, index: number, ref: string | null): Promise<void>;
+    /** 旧节点锚/元素 id（旧树 id——diff 的 oldId 空间） */
+    oldId: string;
+    /** 新节点 id（新树 id——diff 的 newId 空间） */
+    newId: string;
+    /** 父节点 id（'root' = 根容器） */
+    parent: string;
+    /** 新侧位置 index（emitNode 用） */
+    index: number;
+    /** 前一个兄弟 id（插入位置——null = 尾部） */
+    ref: string | null;
+    /** 旧组件实例 id（component 转换时——卸载/复用） */
+    oldCompId?: string;
+    /** 组件实例注册表（区间清理查 lastOutput——组件多根完整移除——G2） */
+    registry?: ComponentRegistry | null;
+}
+/** 新侧渲染 sink（与 build 的 RenderSink 同形——transform 不依赖 build） */
+export type TransformSink = (v: VNodeChild, parent: string, index: number, ref: string | null) => Promise<void>;
+/** 转换策略函数（各状态文件实现——**完整转换**：旧侧让位命令 + ctx.emitNode
+ *  新侧渲染——返回 Promise 支持异步组件） */
+export type TransitionFn = (oldNode: unknown, nextNode: VNodeChild, ctx: TransformContext) => Promise<void> | void;

package/dist/client/vdom/core/transform/states.d.ts

@@ -0,0 +1,22 @@
+/**
+ * vdom transform — states（节点状态定义与判定）
+ *
+ * 状态 = 节点类别（转换状态机的维度）：
+ *   text      —— string/number（文本节点）
+ *   hole      —— null/undefined/boolean（空洞占位锚——DOM 有真实注释节点）
+ *   element   —— string type（原生元素）
+ *   component —— 函数 type（两阶段组件——输出多根 = 隐式 Fragment）
+ *   fragment  —— Fragment 符号/数组（隐式 Fragment——多节点展开）
+
+ *   array     —— VNodeChild[]（childrenOf 已展开的防御态）
+ *
+ * 判定复用 node.ts kindOf（唯一判定点）——状态是 kindOf 的转换语义面。
+ */
+import type { VNodeChild } from '../vnode.ts';
+import type { NodeState } from './index.ts';
+/** 节点状态判定（kindOf → NodeState——语义别名——invalid 归 hole 占位） */
+export declare function stateOf(v: VNodeChild | null | undefined): NodeState;
+/** 是否「同态」（旧新状态相同——可走就地 patch 而非重建） */
+export declare function isSameState(oldState: NodeState, newState: NodeState): boolean;
+/** 是否组件输出态（组件/fragment——多节点锚点管理） */
+export declare function isMultiNode(state: NodeState): boolean;

package/dist/client/vdom/core/transform/table.d.ts

@@ -0,0 +1,28 @@
+/**
+ * vdom transform — table（转换表——状态机核心）
+ *
+ * 转换表：oldState × newState → 策略函数（各状态文件实现）——
+ * 同态（对角）走「就地 patch」（text→setText / element→就地 diff /
+ * component→同类型复用 / hole→no-op）；异态走「转换」——
+ * 占位法核心：**锚 ↔ 真实节点 replaceChild 互换**（childNodes 长度恒定——
+ * 同构不变量——禁止 removeChild 塌缩）。
+ *
+ * 转换策略（各文件实现）：
+ *   text.ts      —— text ↔ element/component/fragment（文本节点 ↔ 结构）
+ *   hole.ts      —— hole ↔ element/component/fragment/text
+ *                  （**null <-> component / null <-> fragment 主场景**——
+ *                  条件渲染 cond ? <X/> : null 的类型切换）
+ *   element.ts   —— element ↔ component/fragment/hole/text
+ *   component.ts —— component ↔ element/fragment/hole（同类型复用——
+ *                   异类型卸载 + 重建）
+ *   fragment.ts  —— fragment ↔ element/component/hole（多节点展开 ↔ 单节点）
+
+ */
+import type { VNodeChild } from '../vnode.ts';
+import type { NodeState, TransformContext, TransitionFn } from './index.ts';
+/** 转换表（old × new → 策略）——同态 = 就地 patch（diff 层处理——表中为 null） */
+export declare const TRANSITIONS: Record<NodeState, Record<NodeState, TransitionFn | null>>;
+/** 转换调度（old × next → 策略）——同态返回 null（diff 就地 patch——不重建） */
+export declare function transitionOf(oldState: NodeState, newState: NodeState): TransitionFn | null;
+/** 执行转换（diff 调用——自动降级：同态/null 策略 → no-op） */
+export declare function runTransition(oldState: NodeState, newState: NodeState, oldNode: unknown, nextNode: VNodeChild, ctx: TransformContext): Promise<void> | void;

package/dist/client/vdom/core/transform/text.d.ts

@@ -0,0 +1,10 @@
+/**
+ * vdom transform — text（文本转换——text ↔ X）
+ *
+ * 场景：条件渲染/列表项类型切换（'a' <-> <div/> <-> 组件...）。
+ * 转换职责（old=text → new=X）：旧文本节点移除（让位）——新节点由 diff
+ * 渲染到同一位置。同态 text → text 不在本表（就地 setText——diff 层）。
+ */
+import type { TransitionFn } from './index.ts';
+/** text → X：旧文本节点移除（让位） */
+export declare const transitionText: TransitionFn;

package/dist/client/vdom/core/vnode.d.ts

@@ -0,0 +1,45 @@
+/**
+ * vdom core — vnode 纯数据面（独立实现——零引用 ui-dom）
+ *
+ * 设计（对齐 vdom-x 契约 + 设计规则 §4.0/§6.3）：
+ * ① vnode 纯数据——零回填字段（el/_render/_id 等全部在影子层——可自由克隆/
+ *    比较/序列化——用户写 JSX 就能推导 vnode 形状）
+ * ② h() 除 key 剥离外零转换——children 原样（false/嵌套数组保留——不 filter）
+ * ③ key 业务身份声明协议：key 从 props 剥离进 vnode.key（组件 props 不见 key）
+ * ④ children 值域协议：vnode/string/number/boolean/空洞(null/undefined)/嵌套数组
+ *    （数组 = 隐式 Fragment——递归展开统一在 childrenOf——单一规则源——
+ *    空洞保留——占位法保长度恒定）
+ * ⑤ 组件两阶段：工厂 = mount（一次——初始化状态/订阅/数据预取）；
+ *    renderFn = 每次渲染（同步或 async——异步边界 = ctx.data 管道——不挂起）
+ * ⑥ Fragment 内部符号——公共面不导出（数组 = 隐式 Fragment；
+ *    `<></>` 经 jsx-runtime 子路径）
+ */
+import type { UIContext } from '../context/UIContext.ts';
+/** vnode——纯数据 */
+export interface VNode {
+    /** 标签名 / 组件 / 内部符号（Fragment） */
+    type: string | symbol | Component;
+    props: Record<string, unknown>;
+    /** 业务身份声明（无自动生成——无 key = 位置身份） */
+    key: string | null;
+    children?: VNodeChild[];
+}
+/** children 值域：vnode/string/number/boolean/空洞/嵌套数组（数组 = 隐式 Fragment） */
+export type VNodeChild = VNode | string | number | boolean | null | undefined | VNodeChild[];
+/** renderFn——每次渲染（读最新 props——同步或 async——异步边界 = ctx.data） */
+export type RenderFn<P = Record<string, unknown>> = (props: P) => VNode | null | (VNode | null)[] | Promise<VNode | null | (VNode | null)[]>;
+/** 组件（两阶段）：
+ *  工厂 = mount（一次——初始化状态/订阅/数据预取（await ctx.data——管道保证））
+ *  renderFn = 每次渲染（ctx.render()/props 变化触发） */
+export type Component<P = Record<string, unknown>, C = UIContext> = (initProps: P, ctx: C) => RenderFn<P> | Promise<RenderFn<P>>;
+type HType = string | symbol | Component<any, any>;
+/** h()——创建 vnode（纯数据——除 key 剥离外零转换）
+ *  children 原样：单子节点直接存、多子节点存数组、无子节点不存——false/嵌套
+ *  数组保留（不 filter——空洞占位法在消费侧） */
+export declare function h(type: HType, props?: Record<string, unknown> | null, ...children: VNodeChild[]): VNode;
+/** jsx 运行时（自动导入——`<div/>` 编译目标——React 兼容签名 jsx(type, props, key)——
+ *  props 内 key 同样剥离；jsxs/jsxDEV 同形状（children 已在 props.children） */
+export declare function jsx(type: HType, props: Record<string, unknown> | null, key?: string | null): VNode;
+export declare const jsxs: typeof jsx;
+export declare const jsxDEV: typeof jsx;
+export {};

package/dist/client/vdom/dev/effect-guard.d.ts

@@ -0,0 +1,8 @@
+/** renderFn 执行窗口（begin/end——渲染路径副作用检测） */
+export declare function beginRender(): void;
+export declare function endRender(): void;
+/** 安装守卫（幂等——patch 一次）：
+ *  @param target 浏览器 window / node globalThis（SSR 端）
+ *  @param ssrOnly SSR 端——warn + noop（timer 不执行——unhandledRejection
+ *  崩溃链阻断——服务器进程保护）；浏览器端 warn-only */
+export declare function installEffectGuard(target: unknown, ssrOnly?: boolean): void;