weifuwu 0.85.0 → 0.87.0

package/dist/client/vdom/core/command/props.d.ts

@@ -0,0 +1,22 @@
+/**
+ * vdom command — props（属性/文本更新命令）
+ *
+ * setProp = 运行时面（事件/ref/property——不可序列化——服务端 no-op——
+ * 客户端 apply 三通道分发：on[A-Z] → events / PROPERTY_KEYS → props /
+ * ref → ref.ts / 其余 → attributes）。
+ * prev = 旧值（diff 提供——事件解绑/属性还原——引用变化重绑正确性）。
+ */
+/** 运行时属性/事件/ref（prev = 旧值——diff 提供） */
+export type SetPropCommand = {
+    op: 'setProp';
+    id: string;
+    key: string;
+    value: unknown;
+    prev?: unknown;
+};
+/** 文本更新 */
+export type SetTextCommand = {
+    op: 'setText';
+    id: string;
+    value: string;
+};

package/dist/client/vdom/core/diff/attrs.d.ts

@@ -0,0 +1,10 @@
+/**
+ * vdom core/diff — attrs（属性精准 diff——值比较——最小命令集）
+ *
+ * 职责（diff 层的细节模块）：静态面值比较（只发变化键 + 旧有新的没有 →
+ * undefined 移除）；函数面引用比较（prev !== next 才发——prev 传递）。
+ */
+import type { VNode } from '../vnode.ts';
+import type { Command } from '../command/index.ts';
+/** 属性精准 diff（值比较——只发变化的键；函数面引用比较——prev 传递） */
+export declare function diffAttrs(oldV: VNode, newV: VNode, id: string, emitCommand: (cmd: Command) => void): void;

package/dist/client/vdom/core/diff/children.d.ts

@@ -0,0 +1,29 @@
+/**
+ * vdom core/diff — children（children 对照 + keyed 列表策略——细节模块）
+ *
+ * 职责：children 列表对照——A 级检测（长度变化 + 无 key 组件 warn）、
+ * 列表分类（all-keyed/含 keyed/unkeyed）、diffSlot 单槽对照（位置身份——
+ * 含 null ↔ null 空洞保持）、diffKeyedChildren（相对顺序检测——顺移
+ * noMove remap / 交换重建 / 实例复用）、emitWithKey（keyed 项渲染）。
+ *
+ * diff/same 只做中转——本文件为列表策略细节。
+ */
+import type { VNode, VNodeChild } from '../vnode.ts';
+import { type ComponentRegistry } from '../node/component.ts';
+import type { Command } from '../command/index.ts';
+import type { RenderSink } from '../build.ts';
+import type { UIContext } from '../../context/UIContext.ts';
+/** children 对照（列表分类：全 unkeyed 位置身份 / 全 keyed 身份复用 / 混合） */
+export declare function diffChildren(oldV: VNode, newV: VNode, id: string, emit: RenderSink, emitCommand: (cmd: Command) => void, ctx: UIContext, registry: ComponentRegistry): Promise<void>;
+/** children 项对照（列表分类：全 unkeyed 位置身份 / 全 keyed 身份复用 / 混合——
+ *  组件数组输出（隐式 Fragment）同用——旧项移除清理） */
+export declare function diffChildrenItems(oldCs: VNodeChild[], newCs: VNodeChild[], id: string, emit: RenderSink, emitCommand: (cmd: Command) => void, ctx: UIContext, registry: ComponentRegistry, shapeChanged?: boolean): Promise<void>;
+export declare function hasKeyed(items: VNodeChild[]): boolean;
+/** keyed 列表对照（身份映射——增删/重排状态跟随 key）
+ *  **move 版**（2026-12）：复用项位置变化 → **move 命令**（DOM 不重建——
+ *  节点移动 + 子树 id 重映射——焦点保持）；位置不变 → 组件输出对照（精准）；
+ *  真移除 → unmount + remove；新增 → 新侧渲染 */
+export declare function diffKeyedChildren(oldCs: VNodeChild[], newCs: VNodeChild[], parent: string, emit: RenderSink, emitCommand: (cmd: Command) => void, ctx: UIContext, registry: ComponentRegistry): Promise<void>;
+/** keyed 项渲染（compId = 位置路径 + .k{key}——身份稳定——增删/重排复用）
+ *  组件输出对照（lastOutput → diffSame 精准——move 后节点已在新位置） */
+export declare function emitWithKey(v: VNodeChild, parent: string, index: number, ref: string | null, key: string, emit: RenderSink, emitCommand: (cmd: Command) => void, ctx: UIContext, registry: ComponentRegistry): Promise<void>;

package/dist/client/vdom/core/diff/cleanup.d.ts

@@ -0,0 +1,44 @@
+/**
+ * vdom core/diff — cleanup（旧输出递归清理——纯逻辑）
+ *
+ * 职责（diff 层的细节模块）：组件类型切换/数组 ↔ 单节点转换——旧输出
+ * 按 vnode 结构递归 remove（同构保持）。
+ *
+ * **数组安全（G1——终态等价违例）**：lastOutput 可为数组（组件输出多根）
+ * ——childrenOf 对数组读 v.props 崩溃（TypeError 中断渲染管线——fuzz 实证）
+ * ——VNodeChild 全形态递归（数组逐项按展开槽位 id）。
+ * **组件项 unmount（G5/G7 区间语义）**：组件 vnode 项 → unmount——compId
+ * 与渲染路径一致：keyed → `${parent}.k{key}`（parent = 项所在容器 id）；
+ * unkeyed → 项槽位 id（base）。
+ */
+import type { VNodeChild } from '../vnode.ts';
+import type { Command } from '../command/index.ts';
+import { type ComponentRegistry } from '../node/component.ts';
+/** **组件输出清理基线（C2——outIsComponent 特判的 id 空间统一）**：
+ *  renderComponent 输出组件时 sink 用 compId 作 parent（特判——防 compId
+ *  冲突）——输出 DOM 的 id 空间：
+ *  - 单 vnode 组件 → pathId(compId, 0)（首槽）
+ *  - 数组首项组件 → compId（数组展开 pathId(compId, i)）
+ *  - 普通输出 → 槽位 id（slotId——锚点法）
+ *  清理递归必须以**同一基线**计算——否则组件项 unmount compId 错位
+ *  （unmount 外层实例/内层残留——组件 fuzz 89% 不等价实证——S_INST 面
+ *  错乱） */
+export declare function outputBase(out: VNodeChild, compId: string, slotId: string): string;
+/** 组件输出清理的 parent 语义（**证明审计——sink 特判对齐——单一实现源**）：
+ *  顶层/递归调用 removeVNodeTree 的 parent 参数 = 渲染时 sink 的 parent：
+ *  - 输出组件（keyed）→ compId（outIsCompNode 特判——sink(组件, compId, 0)——
+ *    内层 keyed 组件 compId = keyedId(compId, key)——传槽位父则错位
+ *    （root.0.0.kk1 渲染 vs root.0.kk1 清理——实证））
+ *  - 输出数组 → compId（数组展开容器——数组分支内部已用 base——顶层
+ *    parent 不参与——但保持 compId 语义一致）
+ *  - 输出 Fragment → 槽位父（sink parent 分支——展开挂槽位父——index
+ *    推导 + 内项 keyedId(槽位父) 依赖）
+ *  - 元素/文本/空洞 → 不依赖 parent（children 递归用 base）——槽位父安全 */
+export declare function removalParent(child: VNodeChild, compId: string, slotParent: string): string;
+/** 旧输出递归清理（组件类型切换——remove 命令——同构保持）
+ *  @param v       旧输出（VNodeChild 全形态——数组 = 组件输出多根）
+ *  @param base    当前项 id（顶层 = outputBase 计算；递归 = pathId(base, i)）
+ *  @param parent  当前容器 id（keyed 组件项 compId 用——渲染 sink 的 parent）
+ *  @param registry 组件实例注册表（可选——组件项输出区间递归清理——
+ *  嵌套组件 A > B > C 的 B 多根展开——C2） */
+export declare function removeVNodeTree(v: VNodeChild, base: string, parent: string, emitCommand: (cmd: Command) => void, registry?: ComponentRegistry | null): void;

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

@@ -0,0 +1,22 @@
+/**
+ * vdom core/diff — index（diff 阶段中转站）
+ *
+ * 职责：**中转站——自身不处理细节逻辑**——root 级对照决策
+ * （transitionOf 查表——异态交 transform / 同态交 diffSame）——细节
+ * 下沉独立模块：
+ * - same.ts：同态对照决策（组件/元素分支——再中转）
+ * - attrs.ts：属性值比较（精准命令）
+ * - children.ts：children 对照 + keyed 列表策略
+ * - output.ts：组件输出对照（null ↔ vnode/数组对照）
+ * - cleanup.ts：旧输出递归清理
+ * - transform/：类型转换状态机（异态执行）
+ */
+import type { VNode } from '../vnode.ts';
+import type { ComponentRegistry } from '../node/component.ts';
+import type { UIContext } from '../../context/UIContext.ts';
+import type { Command } from '../command/index.ts';
+/**
+ * diff：旧树 → 新树——精准增量命令事件流
+ * ctx：组件共享上下文；registry：组件实例注册表（跨渲染保持）
+ */
+export declare function diffStream(oldTree: VNode, newTree: VNode, ctx: UIContext, registry: ComponentRegistry): ReadableStream<Command>;

package/dist/client/vdom/core/diff/output.d.ts

@@ -0,0 +1,30 @@
+/**
+ * vdom core/diff — output（组件输出对照——细节模块）
+ *
+ * 职责：组件 renderFn 输出的对照决策——输出级空值转换（null ↔ vnode——
+ * transform 状态机）、单节点对照（diffSame）、数组输出对照（逐项 diffSlot）、
+ * 数组 ↔ 单节点（transform——旧展开区间递归清理）、类型切换（卸载重建）。
+ *
+ * diffSame 组件分支的 sink 在此实现——diff/same 只做中转。
+ */
+import type { VNode, VNodeChild } from '../vnode.ts';
+import type { Command } from '../command/index.ts';
+import type { RenderSink } from '../build.ts';
+import type { ComponentRegistry, CompOutput } from '../node/component.ts';
+import type { UIContext } from '../../context/UIContext.ts';
+/** 组件输出对照（组件分支 sink——细节集中在此）
+ *  **方案 3——判别联合穷尽**：oldOut 为 CompOutput（null 结构性消除）——
+ *  switch(kind) 编译器强制——hole（空洞锚）与真实输出同等处理——
+ *  undefined = 未渲染（首帧——全量渲染） */
+export declare function diffComponentOutput(oldOut: CompOutput | undefined, out: VNodeChild, p: string, i: number, r: string | null, emit: RenderSink, emitCommand: (cmd: Command) => void, ctx: UIContext, registry: ComponentRegistry, diffSame: (oldV: VNode, newV: VNode, parent: string, index: number, ref: string | null, emit: RenderSink, emitCommand: (cmd: Command) => void, ctx: UIContext, registry: ComponentRegistry) => Promise<void>, 
+/** 组件实例 compId（**证明审计——输出形态 id 空间**）：组件输出单元素
+ *  挂槽位（锚点法——id = compId）；空洞/数组/组件输出挂 compId 子空间
+ *  （compId.0 起）——转换的 oldId 必须按**旧输出形态**计算（p/i 是
+ *  新输出的 sink 参数——数组/空洞输出时 p=compId、i=0——outId 对新
+ *  输出正确对旧输出错位——可变输出 div→数组/收缩/展开实证——旧 div
+ *  保留 + 锚插入 + 实例残留）
+ *  @param slotId 组件槽位（单元素/文本输出挂载点——= pathId(渲染父,
+ *  渲染索引)——keyed 组件 compId ≠ 槽位——必须由调用点提供）
+ *  @param keyedOut keyed 组件输出回调（对照分支——keyed 输出组件的
+ *  rec 在 keyedId(p, key)——diffSame 按槽位查落空——递归 emitWithKey） */
+compId: string, slotId: string, keyedOut?: (out: VNodeChild, p: string, i: number, r: string | null, key: string) => Promise<void>): Promise<void>;

package/dist/client/vdom/core/diff/same.d.ts

@@ -0,0 +1,22 @@
+/**
+ * vdom core/diff — same（同态对照决策——中转）
+ *
+ * 职责：同位置同类型的对照决策——组件分支（类型比较/复用——输出对照
+ * 细节在 output.ts）、元素分支（diffAttrs + diffChildren——细节在
+ * attrs.ts/children.ts）。
+ *
+ * 本文件是「对照决策的中转站」——具体命令生成下沉 attrs/children/output/
+ * cleanup——自身不处理细节逻辑。
+ */
+import type { VNode } from '../vnode.ts';
+import { type ComponentRegistry } from '../node/component.ts';
+import type { Command } from '../command/index.ts';
+import type { RenderSink } from '../build.ts';
+import type { UIContext } from '../../context/UIContext.ts';
+/**
+ * 同态对照（同位置同类型——**精准命令生成**）：
+ * 组件 → renderComponent 复用（工厂不重跑——lastOutput 对照递归）；
+ * 元素 → 属性值比较（只发变化）+ 函数面引用比较 + children 递归（列表分类）
+ */
+export declare function diffSame(oldV: VNode, newV: VNode, parent: string, index: number, ref: string | null, emit: RenderSink, emitCommand: (cmd: Command) => void, ctx: UIContext, registry: ComponentRegistry): Promise<void>;
+/** 属性精准 diff（值比较——只发变化的键；函数面引用比较——prev 传递） */

package/dist/client/vdom/core/field/attributes.d.ts

@@ -0,0 +1,15 @@
+/**
+ * vdom core — attribute 通道（可序列化面——create 携带的 attrs / setProp 兜底）
+ *
+ * 规则（设计规则 §4.0 属性三通道——attribute/property/event）：
+ * - class/className → setAttribute('class')
+ * - style → style.ts（对象应用/数字单位/undefined 清空——独立复杂面）
+ * - enumerated 白名单（draggable/contenteditable/spellcheck）——**空字符串解析
+ *   为 false**（Kanban 教训）——显式 'true'/'false'
+ * - boolean attribute（disabled/hidden 等）→ setAttribute(key, '')
+ * - 其余字符串化 setAttribute；null/undefined/false → removeAttribute
+ */
+/** enumerated 属性白名单（HTML 规范——空字符串语义非 true） */
+export declare const ENUMERATED_KEYS: Set<string>;
+/** attribute 通道——单键应用 */
+export declare function applyAttribute(el: HTMLElement, key: string, value: unknown): void;

package/dist/client/vdom/core/field/events.d.ts

@@ -0,0 +1,54 @@
+/**
+ * vdom core/field — events（事件通道——**事件代理**）
+ *
+ * 设计（2026-12 用户决策——事件代理）：
+ * - **事件表**（EventRegistry——nodeId → event → handler）——setProp 事件
+ *   写入表（**不直接 addEventListener**——prev 解绑由表替换取代——
+ *   重复绑定根治天然）
+ * - **根代理**：document 捕获阶段监听（动态注册——首次绑定某事件类型）——
+ *   portal（#__wf_portal 在 body 下）可达——不冒泡事件（scroll/
+ *   mouseenter）捕获可达
+ * - **分发**（模拟冒泡语义——vdom3 同款）：e.target 向上祖先链——
+ *   data-wf-id 查表——currentTarget 还原绑定元素（组件库依赖）——
+ *   handler 内 stopPropagation（cancelBubble）停止向上——与原生冒泡一致
+ * - **监听器数量 O(事件类型)** vs O(N)（列表/表格场景）——动态节点天然
+ *   （增删无需绑定/解绑——查表）
+ * - 生命周期：remove/done 清理表（子树前缀）；dispose 移除全部根监听
+ *
+ * 规则（设计规则 §6.4）：on + 大写判定（once/only 不误判）；事件名小写化；
+ * 非函数值 warn + 跳过。
+ */
+/** 事件注册表 + 根代理（per serve 实例——document 捕获监听） */
+export declare class EventRegistry {
+    private table;
+    private rootTypes;
+    private doc;
+    private dispatchBound;
+    /** 容器过滤（命令式弹窗独立 applier——事件仅分发容器内 target——
+     *  独立 applier 的节点 id 与主树同路径（root.0.x）——document 捕获时
+     *  主树按钮祖先链命中独立表（onRemove 误触发——toast 多条 bug 实证）） */
+    private container?;
+    /** 生命周期状态机（**全部状态机化——2026-XX**）：active → disposed
+     *  （dispose 消费——之后 set/remove 违例报错——不再静默写死表） */
+    private phase;
+    constructor(doc: Document, container?: HTMLElement | null);
+    /** 事件注册（代理写入——不直接绑定） */
+    set(nodeId: string, event: string, handler: unknown): void;
+    get(nodeId: string, event: string): EventListener | undefined;
+    /** 单事件删除（差集对称——setProp undefined 消费——G4）——
+     *  与 remove(nodeId)（全子树删除）区分——只删一个 (nodeId, event) 对 */
+    removeEvent(nodeId: string, event: string): void;
+    /** 子树清理（id 前缀匹配——remove/done 卸载指令） */
+    remove(nodeId: string): void;
+    /** 根监听动态注册（document 捕获——首次绑定某事件类型——容器过滤可达） */
+    private ensureRoot;
+    /** 分发（模拟冒泡——target 向上祖先链查表——currentTarget 还原——
+     *  handler 内 stopPropagation 停止向上） */
+    private dispatch;
+    /** 卸载清理（移除全部根监听 + 清表）——状态机迁移：active → disposed */
+    dispose(): void;
+}
+/** 事件 prop 判定（on + 大写——`once`/`only` 不误判） */
+export declare const EVENT_RE: RegExp;
+/** 事件名解析（onClick → click；非事件返回 null） */
+export declare function eventName(key: string): string | null;

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

@@ -0,0 +1,19 @@
+/**
+ * vdom core/field — 属性三通道 + key/ref/style（字段处理统一出口）
+ *
+ * 规则（设计规则 §4.0——属性三通道）：setProp 按通道分发——
+ *   on[A-Z] → events（事件绑定——on + 大写判定——once/only 不误判）
+ *   PROPERTY_KEYS → props（DOM property——value/checked 白名单——
+ *     setAttribute 不更新输入值）
+ *   ref → ref（挂载 el/卸载 null——同引用幂等——设计规则 §5.1 纪律）
+ *   style → style（对象/字符串/数字 px/UNITLESS/--var/清空防残留）
+ *   key → key（业务身份声明协议——h/jsx 剥离——props 不泄漏）
+ *   其余 → attributes（attribute 通道——enumerated 白名单显式 true/false——
+ *     boolean 空字符串=存在——null/undefined/false removeAttribute）
+ */
+export { applyAttribute, ENUMERATED_KEYS } from './attributes.ts';
+export { applyProperty, isPropertyKey, PROPERTY_KEYS } from './props.ts';
+export { applyRef, REF_KEY } from './ref.ts';
+export { applyStyle, applyStyleValue, UNITLESS_KEYS } from './style.ts';
+export { EventRegistry, eventName, EVENT_RE } from './events.ts';
+export { extractKey, stripKey, KEY } from './key.ts';

package/dist/client/vdom/core/field/key.d.ts

@@ -0,0 +1,16 @@
+/**
+ * vdom core — key 字段（业务身份声明协议——独立文件）
+ *
+ * 规则（设计规则 §4.0/§5.7——key 业务身份声明）：
+ * - 框架**不生成身份 key**——数组项 key 只由业务声明（数据 id → keyBy /
+ *   组件内部生成 / 用户显式 key）；无 key = 位置身份（unkeyed 按位置 patch）
+ * - h()/jsx 剥离 key 进 vnode.key（**props 不泄漏 key**——组件不见 key）
+ * - key 必须是 string|number（其余类型 warn + 忽略——不静默）
+ * - keyed 列表 diff（身份跟随内容——增删/重排复用正确）与 A 级检测
+ *   （数组长度变化 + 无 key 组件项 → dev error）在 diff 层消费
+ */
+export declare const KEY = "key";
+/** key 提取（props → vnode.key——string|number 有效——其余 warn + null） */
+export declare function extractKey(props: Record<string, unknown> | null | undefined): string | null;
+/** 从 props 拷贝中剥离 key（h/jsx 用——props 不泄漏 key） */
+export declare function stripKey(props: Record<string, unknown> | null | undefined): Record<string, unknown>;

package/dist/client/vdom/core/field/props.d.ts

@@ -0,0 +1,15 @@
+/**
+ * vdom core — property 通道（DOM property——setAttribute 无法表达的面）
+ *
+ * 规则（设计规则 §4.0 属性三通道）：
+ * - value/checked/selected/disabled 等 → `el[key] = value`（property——
+ *   setAttribute('value') 不更新输入值/勾选态）
+ * - 白名单判断（PROPERTY_KEYS）——其余走 attribute 通道
+ * - ref 特殊通道 → ref.ts（独立文件——挂载/卸载回调）
+ */
+/** property 白名单（DOM 节点属性——非 HTML attribute 语义） */
+export declare const PROPERTY_KEYS: Set<string>;
+/** 是否走 property 通道 */
+export declare function isPropertyKey(key: string): boolean;
+/** property 应用（值直接赋给 DOM 节点属性） */
+export declare function applyProperty(el: HTMLElement, key: string, value: unknown): void;

package/dist/client/vdom/core/field/ref.d.ts

@@ -0,0 +1,38 @@
+/**
+ * vdom core/field — ref 通道（**全局注册表管理**——对齐事件代理模式）
+ *
+ * 纪律（设计规则 §5.1）：带清理逻辑的 ref 必须定义在 mount 作用域——
+ * ref 函数引用变化时旧 ref(null) 被调用（diff 重绑定）。
+ *
+ * **RefRegistry**（全局注册表——统一管理——与 EventRegistry 同构）：
+ * - set(id, fn, prev?)：注册（prev 旧引用先退 null——diff 重绑）
+ * - mount(id, el)：**挂载完成触发**（insert 后/ref 指令——查表 fn(el)——
+ *   未挂载注册自动挂起（insert 时查表触发——无需独立 pending 表））
+ * - unmount(id)：**卸载**（ref(null) 子树——前缀匹配——表删除）
+ * - remap(oldPrefix, newPrefix)：move 前缀重映射
+ * - dispose：卸载清理
+ *
+ * 生命周期整合：ref 指令（insert 后——已挂载——set + mount）；
+ * setProp ref（diff 更新——已挂载立即——未挂载等 insert）；remove/done →
+ * unmount（ref(null)）；move → remap。
+ */
+export declare const REF_KEY = "ref";
+/** ref 应用（el 挂载 / null 卸载——prev 引用变化先退旧） */
+export declare function applyRef(el: HTMLElement | null, value: unknown, prev?: unknown): void;
+/** ref 全局注册表（per serve 实例——挂载/卸载查表触发） */
+export declare class RefRegistry {
+    private refs;
+    /** 生命周期状态机（**全部状态机化——2026-XX**）：active → disposed
+     *  （dispose 消费——之后 set/mount/unmount 违例报错——不再静默） */
+    private phase;
+    /** 注册（prev 旧引用先退 null——diff 重绑；已注册同 id 覆盖——不重复触发） */
+    set(id: string, fn: unknown, prev?: unknown): void;
+    /** 挂载完成触发（insert 后/ref 指令——查表 fn(el)） */
+    mount(id: string, el: HTMLElement): void;
+    /** 卸载（ref(null) 子树——前缀匹配——表删除） */
+    unmount(id: string): void;
+    /** move 前缀重映射（节点移动——id 路径变化——表跟随） */
+    remap(oldPrefix: string, newPrefix: string): void;
+    /** 卸载清理（serve unmount）——状态机迁移：active → disposed */
+    dispose(): void;
+}

package/dist/client/vdom/core/field/style.d.ts

@@ -0,0 +1,17 @@
+/**
+ * vdom core — style 通道（复杂面独立处理）
+ *
+ * 规则（设计规则 §4.0/§6.4——style diff 只设不删已修）：
+ * - 对象应用：el.style[k] = v——**undefined/null/false → 清空**（防残留——
+ *   条件显隐组件 display: undefined 残留旧 none）
+ * - 字符串直通：setAttribute('style', str)
+ * - 数字自动单位：width/height/margin... → px（UNITLESS 白名单无单位——
+ *   zIndex/opacity/lineHeight/fontWeight/flex 系）
+ * - CSS 变量（--x 前缀）→ setProperty（el.style['--x'] 赋值无效）
+ */
+/** 无单位属性白名单（数字原样——React 同规则） */
+export declare const UNITLESS_KEYS: Set<string>;
+/** 单值应用（kebab/camelCase 键——CSS 变量走 setProperty） */
+export declare function applyStyleValue(el: HTMLElement, key: string, value: unknown): void;
+/** style 应用（对象/字符串——整体替换语义） */
+export declare function applyStyle(el: HTMLElement, style: unknown): void;

package/dist/client/vdom/core/node/children.d.ts

@@ -0,0 +1,20 @@
+/**
+ * vdom core — children（数组节点处理——隐式 Fragment——独立文件）
+ *
+ * 规则（设计规则 §4.0——单一规则源）：
+ * - 数组/`<></>`/嵌套数组 = 隐式 Fragment——childrenOf 递归展开为同一
+ *   children 序列（纯函数一次到位——路径按展开后位置——深度不漂移）
+ * - 空洞（false/null/undefined）**保留不滤除**（占位法——长度恒定——
+ *   对齐从结构上保证——filter(Boolean) 是红线）
+ * - 五消费方共用（buildVNode/renderValue/patchChildren/renderSsr/hydrate）
+ */
+import type { VNode, VNodeChild } from '../vnode.ts';
+/** children 读取（单一规则源）：统一 children 序列——任意嵌套递归展开 */
+export declare function childrenOf(v: VNode): VNodeChild[];
+/** 数组节点遍历（隐式 Fragment——按展开后位置 emit）——递归覆盖任意嵌套 */
+export declare function forEachChild<T>(cs: VNodeChild[], fn: (c: VNodeChild, i: number) => T): void;
+/** 槽位计数（**投影维度——单一实现源**）：FRAG vnode → 递归展开槽位数；
+ *  其他项 = 1——build 的 fragment/array 展开用槽位推进（嵌套 FRAG 展开
+ *  占 N 连续槽位——按数组项数 +1 推进会覆盖后续项——fuzz seed=42/7/2026
+ *  实证——build(new) 参考树 3 项 vs diff 4 项——build 覆盖 c2） */
+export declare function slotCount(c: VNodeChild): number;

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

@@ -0,0 +1,93 @@
+/**
+ * vdom core — component（组件渲染——两阶段工厂 + renderFn——独立文件）
+ *
+ * 模型（设计规则 §3——两阶段组件）：
+ * ```ts
+ * Component<P, C> = (initProps, ctx) => RenderFn<P> | Promise<RenderFn<P>>
+ * RenderFn<P> = (props) => VNode | null | Promise<VNode | null>
+ * ```
+ * - 工厂 = mount（一次——初始化状态/订阅/数据预取（await ctx.data——管道保证））
+ * - renderFn = 每次渲染（读最新 props——同步或 async——异步边界 = ctx.data）
+ *
+ * 渲染流集成（render.ts 消费）：
+ * - 工厂调用（可 await）→ renderFn 调用（可 await）→ 输出 vnode 递归 emit
+ *   （null → 空洞占位；数组 → 隐式 Fragment；元素/组件嵌套）
+ * - per-instance ctx：Object.create(shared) + onUnmount 覆盖——收集回调
+ *   到实例记录（组件卸载时执行——unmount 命令由 diff 发出）
+ * - 实例记录注册表（compId → { renderFn, onUnmounts }）——同位置同类型
+ *   组件复用（工厂不重跑——let/ref 状态保持——diff 消费）
+ */
+import type { VNode, VNodeChild } from '../vnode.ts';
+import type { Component, RenderFn } from '../vnode.ts';
+import type { UIContext } from '../../context/UIContext.ts';
+import type { Command } from '../command/index.ts';
+/** 组件输出判别联合（**方案 3——null 结构性消除——编译器穷尽**）：
+ *  - vnode：单节点输出（元素/组件/文本——挂槽位 id——锚点法）
+ *  - hole：空洞输出（原 null——锚——挂 compId.0 子空间）
+ *  - array：多根输出（挂 compId 子空间——与兄弟槽位隔离）
+ *  消费点 switch(kind) 穷尽——遗漏分支 = 编译错误（而非运行时静默）——
+ *  lastOutput 条件判断只用 `!== undefined`（hole 与真实输出同等处理——
+ *  4 处 `!== null` 遗漏实证——an:root.0(div) 幽灵/锚残留） */
+export type CompOutput = {
+    kind: 'vnode';
+    v: VNode;
+} | {
+    kind: 'hole';
+} | {
+    kind: 'array';
+    items: VNodeChild[];
+};
+/** 组件输出归一化（VNodeChild → CompOutput——null/undefined/boolean → hole） */
+export declare function normalizeOutput(out: VNodeChild): CompOutput;
+/** CompOutput → VNodeChild（清理/转换路径消费——outputBase 兼容） */
+export declare function outputToChild(out: CompOutput): VNodeChild;
+/** 组件实例记录（跨渲染保持——diff 复用） */
+export interface ComponentRecord {
+    /** 组件函数引用（类型比较——同位置不同类型 → 卸载重建） */
+    type: Component;
+    /** renderFn（工厂产物——每次渲染调用——读最新 props） */
+    renderFn: RenderFn;
+    /** 卸载清理回调（ctx.onUnmount 收集——unmount 时执行） */
+    onUnmounts: (() => void)[];
+    /** 上次渲染输出（**判别联合 CompOutput**——diff 对照——同实例更新就地
+     *  patch——不重建——undefined = 未渲染（首帧）；hole = 空洞锚——同等处理） */
+    lastOutput?: CompOutput;
+    /** hook 调用顺序（渲染期重置——状态按 index 缓存） */
+    hookSeq: {
+        n: number;
+    };
+    /** 渲染期 hook 基准（mount 阶段 hook 计数——渲染 hook 用其后空间——
+     *  与 mount 的 usePopup 等分离——索引冲突根治） */
+    renderBase: number;
+    /** hook 状态缓存（per-instance——useOpen 等渲染期 hooks） */
+    hookStates: Map<number, unknown>;
+    /** 组件状态机阶段（**MOUNTING 补全——审计 2026-XX**）：工厂 await 期间
+     *  = 'mounting'（rec 已注册——防御异步工厂重复执行/循环引用——重复
+     *  引用显式报错）；mount 命令消费后 = 'mounted' */
+    phase: 'mounting' | 'mounted';
+}
+/** 组件实例注册表（uiServe 持有——renderToStream 写入——diff/unmount 消费） */
+export interface ComponentRegistry {
+    get(id: string): ComponentRecord | undefined;
+    set(id: string, rec: ComponentRecord): void;
+    delete(id: string): void;
+    /** 全部实例 id（整树替换遍历卸载） */
+    keys(): string[];
+    /** 异步超时（R2——mount 工厂/renderFn await 上限——测试可注入短值） */
+    asyncTimeout: number;
+}
+/** 创建注册表（per serve 实例）——asyncTimeout 默认 15s（async-guard） */
+export declare function createComponentRegistry(): ComponentRegistry;
+/** 整树替换：全部组件实例卸载（**LIFO——后挂载先卸载**——导航/root
+ *  类型变化——与单组件 onUnmounts 逆序一致——栈语义） */
+export declare function disposeAllComponents(registry: ComponentRegistry): void;
+/** 组件渲染 sink（render.ts 的 emit——子节点递归出口） */
+export type ComponentSink = (v: VNodeChild, parent: string, index: number, ref: string | null) => Promise<void>;
+/** 渲染一个组件（mount + renderFn——可 await——输出经 sink 递归 emit） */
+export declare function renderComponent(vn: VNode, parent: string, index: number, ref: string | null, compId: string, sharedCtx: UIContext, registry: ComponentRegistry, sink: ComponentSink, emitCommand?: (cmd: Command) => void): Promise<boolean>;
+/** 执行组件卸载（unmount 命令消费——onUnmounts 逆序执行）
+ *  **递归清理子实例（G8——终态等价违例）**：组件 vnode 的 compId（parent.i）
+ *  ≠ 其子树内子组件实例 id（parent.i.0 / parent.i.k{key} / compId.0 特判）——
+ *  单实例删除会残留子实例（onUnmounts 不执行——订阅/监听泄漏——fuzz 实证）
+ *  ——按 compId 前缀递归（LIFO——与 disposeAllComponents 同语义——先子后父） */
+export declare function disposeComponent(id: string, registry: ComponentRegistry): void;

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

@@ -0,0 +1,14 @@
+/**
+ * vdom core — Fragment（隐式——数组 = Fragment——独立文件）
+ *
+ * 设计（设计规则 §4.0——结构符号内化）：
+ * - Fragment 为内部符号——公共面不导出（数组 = 隐式 Fragment；`<></>` 经
+ *   jsx-runtime 子路径自动导入——编译目标即本符号）
+ * - 数组节点处理 → children.ts（childrenOf 单一规则源——递归展开）
+ * - 单节点分类 → node.ts（kindOf——fragment 分支判定）
+ */
+import type { VNode } from '../vnode.ts';
+/** Fragment 内部符号（`<></>` 编译目标——数组 = 隐式 Fragment） */
+export declare const Fragment: unique symbol;
+/** Fragment vnode 判定 */
+export declare function isFragment(v: VNode): boolean;

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

@@ -0,0 +1,22 @@
+/**
+ * vdom core — hole（特殊值渲染——空洞占位 + 非法输入诊断——独立文件）
+ *
+ * 规则（设计规则 §4.0/§6.3——占位法）：
+ * - 空洞（null/undefined/boolean——无渲染值）→ 占位锚节点
+ *   （<!--wf-hole: xxx-->）——**childNodes 长度恒等于 children 数组长度**
+ *   （数组第 i 项 ⟷ childNodes 第 i 个节点——同构不变量——对齐从结构上
+ *   保证——不靠消费侧猜测）——filter(Boolean) 是红线（消除空洞破坏长度）
+ * - 非法输入（对象/数字 type/未知 Symbol）→ 诊断占位 + warn（不崩溃不静默）
+ * - 占位是静态的零 resolve 回调——≠ 动态挂载占位——不触发任何补渲染
+ */
+import type { Command } from '../command/index.ts';
+/** 空洞判定（无渲染值——false/null/undefined/true——占位法保同构） */
+export declare function isHole(v: unknown): boolean;
+/** 非法输入判定（对象/数字 type/未知 Symbol——诊断占位 + warn） */
+export declare function isInvalid(v: unknown): boolean;
+/** 非法输入诊断信息（warn 提示——不崩溃） */
+export declare function invalidDiagnostic(v: unknown): string;
+/** 占位锚命令对（createAnchor + insert——同构长度恒定） */
+export declare function holeCommands(id: string, parent: string, ref: string | null, detail?: string): Command[];
+/** 占位锚入队（emitCommand 直发——render/hydrate 共用） */
+export declare function emitHole(emit: (cmd: Command) => void, id: string, parent: string, ref: string | null, detail?: string): void;

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

@@ -0,0 +1,35 @@
+/**
+ * vdom core — node（单节点处理——类型判定/分类——独立文件）
+ *
+ * 规则（设计规则 §4.0——children 值域协议 + 非法输入分类）：
+ * - text：string/number → 文本节点
+ * - hole：null/undefined/boolean → 空洞占位锚（hole.ts——占位法——长度恒定）
+ * - array：VNodeChild[] → 隐式 Fragment（children.ts 展开）
+ * - element：string type → 元素节点
+ * - fragment：Fragment 符号（`<></>`——与数组同义）
+ * - component：函数 type → 两阶段组件（工厂 + renderFn）
+ * - invalid：对象/数字 type/未知 Symbol → 诊断占位 + warn（hole.ts——不崩溃不静默）
+ */
+import type { VNodeChild } from '../vnode.ts';
+export type NodeKind = 'text' | 'hole' | 'array' | 'element' | 'fragment' | 'component' | 'invalid';
+/** 单节点分类（唯一判定点——各消费方共用）
+ *  **空字符串 = 空洞（2026-08——编码唯一性——映射歧义歼灭）**：'' 文本
+ *  节点在 DOM 可见性上 = 无——但客户端 createText('') 生成空文本节点、
+ *  HTML 序列化（commandToHtml escapeHtml('') → 空串）不产任何节点——
+ *  同一 children 值两套物理表示——SSR 吸收文本流错位（实证：
+ *  `{cond ? 'x' : ''}` 的 '' 槽位——吸收把整个 demo 面 div 当多余节点
+ *  跳过——inputnumber 页吸收耗尽 failed）——统一归空洞（锚注释——
+ *  双端同构——与 false/null/undefined 同类） */
+export declare function kindOf(v: VNodeChild): NodeKind;
+/** 文本值提取（text kind——string/number 统一字符串化） */
+export declare function textOf(v: VNodeChild): string | null;
+/** **渲染级空洞判定（2026-08——判定点收敛——单一实现源）**：
+ *  null/undefined/boolean/''（'' 归 kindOf hole——编码唯一性）——
+ *  build/diff/transform/SSR 四端渲染分类唯一判定点——禁止模块内手写
+ *  `=== null || === undefined || typeof === 'boolean'`（''→hole 曾只改
+ *  kindOf——diffSlot typeof 快路径分裂——双 bug 实证）——渲染空洞语义
+ *  一律经本函数 */
+export declare function isHoleKind(v: VNodeChild): boolean;
+/** **渲染级文本判定**（kindOf 语义——'' 是 hole 不是文本——文本快路径
+ *  与 setText 目标判定统一——diffSlot ''↔text 转换回归的机制防线） */
+export declare function isTextKind(v: VNodeChild): boolean;

package/dist/client/vdom/core/node/keyed.d.ts

@@ -0,0 +1,64 @@
+/**
+ * vdom core/node — keyed（keyed 列表语义——业务身份声明协议）
+ *
+ * 规则（设计规则 §4.0/§5.7——key 业务身份声明）：
+ * - **框架不生成身份 key**——数组项 key 只由业务声明（数据 id → keyBy /
+ *   组件内部生成 / 用户显式 key）；无 key = 位置身份（unkeyed 按位置 patch）
+ * - **全 keyed**：key 身份映射——增删/重排复用正确（身份跟随内容——
+ *   状态不漂移）
+ * - **全 unkeyed**：按位置对照（静态/无状态列表正确零噪音）
+ * - **混合数组**（部分 key）：无 key 项由位置接管——`pos:{i}` 位置 key——
+ *   命名空间隔离（pos: 前缀——**永不与用户 key 冲突**）
+ * - **A 级检测**（dev）：数组长度变化 + 无 key 组件项 → warn 引导声明 key
+ *
+ * 消费方：diff.ts（keyed 列表 diff——身份映射/复用决策）。
+ */
+import type { VNodeChild } from '../vnode.ts';
+/** 位置 key 前缀（混合数组——无 key 项位置接管——命名空间隔离） */
+export declare const POS_KEY_PREFIX = "pos:";
+/** keyed 组件实例 id（**key 转义——id 空间注入防御**）：compId =
+ *  `{parent}.k{key}`——'.' 是路径分隔符——用户 key 可含任意字符（数据
+ *  id——如 'a.b'）——直接拼接则 'root.0.ka' 与 'root.0.ka.b'（key='a.b'）
+ *  产生前缀关系——disposeComponent/remapSubtree/procRemove 的 startsWith
+ *  前缀匹配误删兄弟 keyed 实例（key 注入实证——unmount root.0.ka 误删
+ *  root.0.ka.b——实例状态丢失 + onUnmounts 错乱）——'%' 先行转义（防
+ *  '.' 转义后 '%' 二次歧义：'a.b'→'a%2Eb'，'a%2Eb'→'a%252Eb'——互不碰撞）
+ *  ——build/diff/cleanup 全部生成点统一走本函数（单一实现源） */
+export declare function keyedId(parent: string, key: string): string;
+/** 数组项 key（vnode.key——纯数据面——非 vnode 项 = null） */
+export declare function keyOf(v: VNodeChild): string | null;
+/** 数组项是否显式 keyed（业务声明——vnode.key 非 null） */
+export declare function isKeyed(v: VNodeChild): boolean;
+/** 列表分类：全 keyed / 全 unkeyed / 混合 */
+export type KeyedKind = 'all-keyed' | 'all-unkeyed' | 'mixed';
+/** 列表 keyed 分类（空列表 = all-unkeyed——无身份可言） */
+export declare function listKind(items: VNodeChild[]): KeyedKind;
+/** 位置 key（混合数组——无 key 项的位置接管——pos: 前缀永不与用户 key 冲突） */
+export declare function positionKey(i: number): string;
+/** 是否为位置 key（pos: 前缀——命名空间识别） */
+export declare function isPositionKey(k: string): boolean;
+/** 统一身份键（keyed 项用业务 key——unkeyed 项用位置 key——混合数组同一映射） */
+export declare function identityKey(items: VNodeChild[], i: number): string;
+/** keyed 列表身份映射（key → 项索引——增删/重排决策用） */
+export declare function keyIndex(items: VNodeChild[]): Map<string, number>;
+/** keyed 复用决策（旧列表 × 新列表——key 交集 → 复用；旧有新无 → 移除；
+ *  旧无新有 → 新建）——diff 消费 */
+export interface KeyedDiffPlan {
+    /** 复用的 key（身份保持——节点移动/就地更新） */
+    reused: string[];
+    /** 移除的旧 key（不在新列表） */
+    removed: string[];
+    /** 新建的新 key（不在旧列表） */
+    added: string[];
+}
+export declare function planKeyedDiff(oldItems: VNodeChild[], newItems: VNodeChild[]): KeyedDiffPlan;
+/** A 级检测（dev——重复 key → warn 引导修正——重复 key 是非法输入：
+ *  身份映射无唯一语义——diffKeyedChildren 按首现优先处理（与 keyIndex
+ *  对齐——确定性）——但列表本身应修正（fuzz 实证：重复 key 导致 move
+ *  映射错位——旧节点残留/新节点错位——终态不等价）） */
+export declare function detectDuplicateKey(items: VNodeChild[], context: string): void;
+/** A 级检测（dev——数组长度变化 + 无 key 组件项 → warn 引导声明 key——
+ *  用户层引导；豁免：单子节点条件渲染的 null 空洞）——**实槽翻转语义**：
+ *  仅当组件占据/让出「非空洞非组件」的实槽（位置被占用——后续组件按位置
+ *  移位 → 重挂 → 状态丢失）才 warn——尾部/空洞槽条件渲染零漂移不报 */
+export declare function detectMissingKey(items: VNodeChild[], context: string): void;