weifuwu 0.85.0 → 0.87.0

package/dist/{layout → client/layout}/weifuwu-layout.css

@@ -160,9 +160,13 @@
   /* 浮层面板底色（surface-2/3：浮层/模态——亮色同 bg 靠阴影区分，暗色抬升一级见 _dark.css） */
   --wf-color-bg-elevated: var(--wf-color-bg);
 
-  /* ── 字体 ── */
-  --wf-font-sans: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
-  --wf-font-mono: 'SF Mono', 'Fira Code', 'JetBrains Mono', monospace;
+  /* ── 字体 ──
+   * 西文优先（拉丁字形平台最优），CJK 显式回退（中文原生：PingFang/苹方、
+   * Hiragino/冬青、雅黑、思源 Noto Sans SC——三平台中文渲染一致） */
+  --wf-font-sans: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto,
+    'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', 'Noto Sans SC', sans-serif;
+  --wf-font-mono: 'SF Mono', 'Fira Code', 'JetBrains Mono',
+    'PingFang SC', 'Microsoft YaHei', monospace;
 
   --wf-font-size-xs: 12px;
   --wf-font-size-sm: 13px;
@@ -196,9 +200,11 @@
      变暗不可见，primary 是亮蓝——明暗主题聚焦均可见） ── */
   --wf-focus-ring: 0 0 0 2px var(--wf-color-primary-bg), 0 0 0 1px var(--wf-color-primary);
 
-  /* ── 动效 ── */
-  --wf-transition-duration: 150ms;
-  --wf-transition-timing: ease;
+  /* ── 动效 ──
+   * --wf-transition 为派生别名（hover 类过渡统一走 dur-fast + ease-out——微流明标准节奏）。
+   * 旧 --wf-transition-duration/timing 保留为兼容（不建议新引用——新代码直接用 --wf-dur-* 系列） */
+  --wf-transition-duration: var(--wf-dur-fast);
+  --wf-transition-timing: var(--wf-ease-out);
   --wf-transition: var(--wf-transition-duration) var(--wf-transition-timing);
 
   /* ── 动效语言：时长阶梯 + 缓动曲线 + 位移量（组件动效统一引用，不各自硬编码） ── */
@@ -217,6 +223,12 @@
   --wf-motion-md: 8px;
   --wf-motion-lg: 24px;                                /* drawer 全幅位移 */
 
+  /* 循环动效族（旋转/呼吸/闪烁/进度——时长阶梯之外的循环节拍——S5 审计强制引用） */
+  --wf-dur-spin: 0.6s;                 /* 旋转（spinner/loading/折叠） */
+  --wf-dur-pulse: 1.2s;                /* 呼吸脉冲（在线点/骨架/思考） */
+  --wf-dur-blink: 1.1s;                /* 光标闪烁（流式光标/AI 回复） */
+  --wf-dur-progress: 1.4s;             /* 不确定进度循环（indeterminate） */
+
   /* ── 色彩 — 信息（补充） ── */
   --wf-color-info: var(--wf-sky-500);
   --wf-color-info-bg: var(--wf-sky-50);
@@ -274,6 +286,7 @@
   --wf-letter-spacing: normal;
   --wf-letter-spacing-wide: 0.5px;
   --wf-letter-spacing-wider: 1px;
+  --wf-heading-display-tracking: -0.5px; /* 顶级标题 display 档窄字距（PageHeader display——CJK 可覆盖） */
 
   /* ── 数字 ── */
   --wf-nums: 'tabular-nums'; /* 数字等宽（统计/表格数值防抖动） */
@@ -721,6 +734,34 @@ body.wf-dragging {
   user-select: none;
   -webkit-user-select: none;
 }
+
+/* ── 微流明 · 进行态语言：stream-in 内容渐显（AI 回复/流式列表/hero 元素） ──
+ * 微流明设计语言三支柱之二（design/design-language.md）——"进行中"是可见的流
+ * 用法：元素加 wf-stream-in 类（opacity 0→1 + 上移 4px）
+ */
+@keyframes wf-stream-in {
+  from { opacity: 0; transform: translateY(4px); }
+  to { opacity: 1; transform: translateY(0); }
+}
+.wf-stream-in {
+  animation: wf-stream-in var(--wf-dur-base) var(--wf-ease-out) both;
+}
+@media (prefers-reduced-motion: reduce) {
+  .wf-stream-in {
+    animation-duration: 0.01ms;
+  }
+}
+
+/* ── 首页 hero 打字机光标（微流明·进行态——reduced-motion 由下方降级块处理） ── */
+.wf-hero-cursor {
+  animation: wf-hero-blink 1s step-end infinite;
+  color: var(--wf-color-primary);
+}
+
+@keyframes wf-hero-blink {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0; }
+}
 }
 
 @layer layout {
@@ -1004,6 +1045,11 @@ body.wf-dragging {
   background: var(--wf-surface-bg);
 }
 
+/* 平面表面（M4 表面语言——静态卡片/面板组合 wf-border 用：阴影仅抬升语义） */
+.wf-surface--flat {
+  box-shadow: none;
+}
+
 /* ── 背景色工具 — 引用语义 Token，免自定义 CSS ── */
 .wf-bg-secondary { background: var(--wf-color-bg-secondary); }
 .wf-bg-tertiary { background: var(--wf-color-bg-tertiary); }
@@ -1494,6 +1540,14 @@ body.wf-dragging {
   /* 内容高于视口时在主区内滚动（壳固定视口高度后的唯一滚动出口） */
   overflow-y: auto;
   background: var(--wf-color-bg);
+  /* 行宽约束（P5）：默认 none 全宽（聊天/表格等全宽应用零影响）；
+     文档站/长文本场景设 --wf-main-max: 900px——直接子元素限宽居中 */
+  --wf-main-max: none;
+}
+
+.wf-main > * {
+  max-width: var(--wf-main-max);
+  margin-inline: auto;
 }
 
 /* ── 触屏：导航项 44px 命中区 ── */

package/dist/client/office/docx.d.ts

@@ -0,0 +1,33 @@
+/**
+ * weifuwu/office/docx — docx ↔ ODES DocState 双向转换（前端/服务端通用——零依赖）
+ *
+ * 参考算法：office2json（unzip → XML 树 → 路径提取 w:body → w:p → w:r → w:t），
+ * 增强提取到 ODES IR（design/office-events-plan.md）：
+ * - 段落属性：pStyle → h1/h2/h3、jc → 对齐（裁剪：样式名映射子集）
+ * - 内联格式：rPr b/i/u → marks（区间）
+ * - 表格：w:tbl → Editor 表格 embed 快照（HTML 复用现有模型）
+ * - 图片：w:drawing r:embed → rels → media → data url → img embed
+ *
+ * 导出（DocState → minimal docx）：VNode 组件化（OOXML 也是 VNode——与前端
+ * "VNode → DOM"同构）→ vnodeToXml → store ZIP。块级 embed（pre/hr）打断段落。
+ *
+ * 前端可用（无需后端）：ZIP 解压走 DecompressionStream（浏览器/Node 18+）；
+ * base64 跨环境（Buffer 守卫/atob）。诚实裁剪：分节/页眉页脚/域代码/批注
+ * 不导入；http 图片导出裁剪（warning）。
+ */
+import type { DocState } from '../components/Editor/model/types.ts';
+/** base64 → Uint8Array（跨环境——浏览器 atob / Node Buffer） */
+export declare function base64ToBytes(b64: string): Uint8Array;
+/** Uint8Array → base64（跨环境） */
+export declare function bytesToBase64(u8: Uint8Array): string;
+export interface DocxImportResult {
+    doc: DocState;
+    /** 裁剪提示（不可映射内容——诚实不静默） */
+    warnings: string[];
+}
+export declare function docxToDoc(u8: Uint8Array): Promise<DocxImportResult>;
+export interface DocxExportResult {
+    data: Uint8Array;
+    warnings: string[];
+}
+export declare function docToDocx(doc: DocState): DocxExportResult;

package/dist/client/office/pptx.d.ts

@@ -0,0 +1,24 @@
+/**
+ * weifuwu/office/pptx — pptx ↔ ODES DeckState 双向转换（前端/服务端通用——零依赖）
+ *
+ * 参考算法：office2json（ppt/slides/slideN.xml → p:sld → p:cSld → p:spTree →
+ * p:sp → p:txBody → a:p → a:r → a:t），增强提取到 ODES IR：
+ * - 多幻灯片：slideN.xml 全量（office2json 只取文本——ODES 保留结构）
+ * - shape 几何：p:xfrm（a:off x/y + a:ext cx/cy——EMU → px：/9525）
+ * - shape 类型：p:sp（文本/图形——p:prstGeom prst）/ p:pic（图片）
+ * - 文本：txBody → 段落拼接（a:br 换行）
+ *
+ * 导出（DeckState → minimal pptx）：slideN.xml（spTree 结构）+ presentation.xml
+ * + rels + contentTypes——store ZIP（VNode 组件化）。裁剪：动画/母版/备注/主题。
+ */
+import type { DeckState } from '../components/OfficeEditor/model/types.ts';
+export interface PptxImportResult {
+    deck: DeckState;
+    warnings: string[];
+}
+export declare function pptxToDeck(u8: Uint8Array): Promise<PptxImportResult>;
+export interface PptxExportResult {
+    data: Uint8Array;
+    warnings: string[];
+}
+export declare function deckToPptx(deck: DeckState): PptxExportResult;

package/dist/client/office/xlsx.d.ts

@@ -0,0 +1,25 @@
+/**
+ * weifuwu/office/xlsx — xlsx ↔ ODES WorkbookState 双向转换（前端/服务端通用——零依赖）
+ *
+ * 参考算法：office2json（sheet1.xml → sheetData → row → c{t,v} + sharedStrings），
+ * 增强提取到 ODES IR（design/office-events-plan.md）：
+ * - 多 sheet：workbook.xml（sheet 名 + rId）→ rels → 各 sheetN.xml
+ * - 单元格引用：c@r（A1——office2json 丢弃——ODES 必须）
+ * - 类型：c@t（s=shared/n=number/b=bool/f=formula）→ SheetCell.kind
+ * - 公式：f 元素（公式字符串保留——不计算——服务端导出重算）
+ * - 行高/列宽/样式索引：裁剪（v1——诚实：不读不写）
+ *
+ * 导出（WorkbookState → minimal xlsx）：共享字符串表去重 + sheetData XML +
+ * store ZIP（VNode 组件化——OOXML 也是 VNode）。
+ */
+import type { WorkbookState } from '../components/OfficeEditor/model/types.ts';
+export interface XlsxImportResult {
+    workbook: WorkbookState;
+    warnings: string[];
+}
+export declare function xlsxToWorkbook(u8: Uint8Array): Promise<XlsxImportResult>;
+export interface XlsxExportResult {
+    data: Uint8Array;
+    warnings: string[];
+}
+export declare function workbookToXlsx(wb: WorkbookState): XlsxExportResult;

package/dist/client/office/xml-serialize.d.ts

@@ -0,0 +1,18 @@
+/**
+ * weifuwu/office/xml-serialize — VNode 树 → XML 字符串（服务端 OOXML 生成）
+ *
+ * 架构（与前端 "VNode → DOM" 同构——"OOXML 也是写 VNode"）：
+ *   DocState → VNode 树（h()——vdom3 纯数据结构，零 DOM 依赖）
+ *   → vnodeToXml（本模块）→ ZIP 打包
+ *
+ * 序列化约定（仅输出 XML 子集——与 vdom3 渲染管线解耦）：
+ * - type: string = 元素名（含命名空间前缀——w:p、a:graphic 等原样输出）
+ * - props: 字符串值 = XML 属性；number/boolean 字符串化；key/children 排除
+ * - children: 字符串 = 文本（转义）；VNode = 子元素；数组 = 序列
+ * - 空元素 → 自闭合 <w:b/>（OOXML 合法——MS Word 接受）
+ * - 函数/symbol type、事件 props（on*）→ 抛错（诚实——序列化器不支持）
+ */
+import type { VNode, VNodeChild } from '../vdom/index.ts';
+export declare function vnodeToXml(v: VNode | VNodeChild, xmlDecl?: boolean): string;
+/** 便捷：把 VNode 树序列化为 OOXML 部件 XML（名称检查由调用方保证） */
+export declare function vnodeToXmlDecl(v: VNode): string;

package/dist/client/office/xml.d.ts

@@ -0,0 +1,21 @@
+/**
+ * weifuwu/office/xml — 自研轻量 XML 解析（零 npm 依赖）
+ *
+ * 参考算法：office2json（@xmldom/xmldom → { name, attrs, children } 树）。
+ * OOXML 是规整 XML——只做元素树 + 文本；裁剪：DTD/实体展开（除内建五实体）/
+ * 命名空间处理（前缀保留原名——w:p 等）。解析失败抛错（诚实——不静默）。
+ */
+export interface XmlNode {
+    name: string;
+    attrs: Record<string, string>;
+    children: XmlNode[];
+    /** 直接文本内容（子元素外的文本） */
+    text: string;
+}
+/** 手写扫描器：<name attrs>...</name> / <name/> / 文本 / 指令 / 注释 / CDATA */
+export declare function parseXml(xml: string): XmlNode;
+/** 便捷：找子元素（按名字——含命名空间前缀匹配） */
+export declare function child(el: XmlNode, name: string): XmlNode | null;
+export declare function children(el: XmlNode, name: string): XmlNode[];
+/** 全部后代文本（拼接） */
+export declare function allText(el: XmlNode): string;

package/dist/client/office/zip.d.ts

@@ -0,0 +1,21 @@
+/**
+ * weifuwu/office/zip — 自研 ZIP 容器读写（零 npm 依赖）
+ *
+ * 参考算法：office2json（unzip 结构——EOCD → central directory → local header）。
+ * 实现取舍：
+ * - 读：EOCD（尾部扫描）→ central directory → local header offset 取数据；
+ *   压缩方法 0（store）/ 8（deflate——Node 内置 zlib.inflateRawSync）
+ * - 写：store（无压缩——合法 ZIP，文件较大但零依赖正确性优先）；
+ *   CRC32 自研查表
+ * - 裁剪：ZIP64/加密/数据描述符（flags bit3）/多盘——不支持（诚实——读到即抛错）
+ */
+export interface ZipEntry {
+    name: string;
+    data: Uint8Array;
+}
+export declare function crc32(buf: Uint8Array): number;
+/** inflate（ZIP method 8）——跨环境：浏览器 DecompressionStream / Node 18+（同 API）。
+ *  老环境无 DecompressionStream → 抛错（诚实裁剪：OOXML 必用 deflate）。 */
+export declare function inflateRaw(data: Uint8Array): Promise<Uint8Array>;
+export declare function readZip(u8: Uint8Array): Promise<Map<string, Uint8Array>>;
+export declare function writeZip(files: Map<string, Uint8Array>): Uint8Array;

package/dist/client/vdom/browser/Browser.d.ts

@@ -0,0 +1,73 @@
+/**
+ * vdom browser — 浏览器环境接口（依赖注入——uiServe 显式接收）
+ *
+ * 设计（2026-12）：uiServe(router, { root, browser })——**无全局依赖**——
+ * 注入 window/document 两字段为基座 + **组件消费面方法**（设计规则 §5.5——
+ * 组件禁止直接访问 DOM 全局——一律经 ctx.browser 唯一入口——46 处迁移
+ * 基线）。接口按组件库消费面扩展（P2 组件迁移——activeElement/byId/
+ * copyText/scrollTop/storage 等）。
+ *
+ * 三态实现：客户端 createClientBrowser（惰性 typeof 防御）· SSR shim
+ * （null/0/false/no-op——组件 SSR 安全）· 测试 testBrowser()/jsdom。
+ */
+/** 浏览器环境（基座 window/document + 组件消费面方法） */
+export interface Browser {
+    /** 浏览器窗口（location/事件/媒体查询/定时器——完整环境面） */
+    window: Window;
+    /** 文档（元素创建/查询——渲染 DOM 面） */
+    document: Document;
+    /** 复制文本 */
+    copyText(text: string): void;
+    /** 下载文件（dataURL/blob） */
+    downloadFile(filename: string, content: string, mime?: string): boolean;
+    /** 当前聚焦元素 */
+    activeElement(): HTMLElement | null;
+    /** 按 id 查询 */
+    byId(id: string): HTMLElement | null;
+    /** 查询元素（CSS 选择器） */
+    query(sel: string): HTMLElement | null;
+    queryAll(sel: string): NodeListOf<Element> | null;
+    /** 创建元素/片段/注释/文本 */
+    createElement<K extends keyof HTMLElementTagNameMap>(tag: K): HTMLElementTagNameMap[K] | null;
+    createElementNS(ns: string, tag: string): Element | null;
+    createDocumentFragment(): DocumentFragment | null;
+    createComment(text: string): Comment | null;
+    createTextNode(text: string): Text | null;
+    /** 事件监听（全局——组件层统一入口） */
+    addEventListener(type: string, fn: (e: any) => void, options?: any): void;
+    removeEventListener(type: string, fn: (e: any) => void, options?: any): void;
+    /** 滚动 */
+    scrollTo(y: number): void;
+    /** 当前滚动量（scrollingElement 优先——headless 漂移防护） */
+    scrollTop(): number;
+    /** 媒体查询（matchMedia——headless 无 → null） */
+    matchMedia(query: string): MediaQueryList | null;
+    /** 可视视口（visualViewport——键盘弹起/缩放） */
+    visualViewport(): VisualViewport | null;
+    /** 滚动根元素 */
+    scrollingElement(): Element | null;
+    bodyElement(): HTMLElement | null;
+    bodyAppend(el: Node): void;
+    bodyRemove(el: Node): void;
+    clearBody(): void;
+    /** 事件构造（jsdom 兼容——跨 realm 安全） */
+    event(type: string, init?: any): Event;
+    /** 主题根元素 */
+    rootElement(): HTMLElement | null;
+    /** 选区 */
+    getSelection(): Selection | null;
+    selectionText(): string;
+    /** 存储（SSR/隐私模式安全） */
+    storageGet(key: string): string | null;
+    storageSet(key: string, value: string): void;
+    /** 定时器（SSR no-op） */
+    timeout(fn: () => void, ms: number): number;
+    /** 当前路径 */
+    pathname(): string;
+    /** 设置 hash（锚点滚动——Anchor 用） */
+    setHash(hash: string): void;
+    /** 视口高度 */
+    viewportHeight(): number;
+    /** 表单恢复回调（ui-dom 兼容——Slider/Form 字段恢复） */
+    onFormRestore?(fn: () => void): void;
+}

package/dist/client/vdom/browser/create-client-browser.d.ts

@@ -0,0 +1,11 @@
+/**
+ * vdom browser — createClientBrowser（生产浏览器环境工厂）
+ *
+ * 设计：Browser 接口 = window/document 基座 + 组件消费面方法（设计规则 §5.5
+ * 能力映射表——copyText/query/storage/scrollTop 等唯一入口——组件禁止
+ * 直接访问 DOM 全局）。**惰性环境**（对齐 ui-dom——模块加载时可能无
+ * window（SSR/测试 setup 前）——方法内 typeof 检查——setupJsdom/浏览器
+ * 就绪后可用——不捕获创建时的 null）。
+ */
+import type { Browser } from './Browser.ts';
+export declare function createClientBrowser(): Browser;

package/dist/client/vdom/commands.d.ts

@@ -0,0 +1,19 @@
+/**
+ * vdom — commands（命令式 API——toast/confirm/notification——P4 apps 迁移）
+ *
+ * 设计：vdom 无 createRoot（UIRouter 唯一入口——用户决策）——命令式
+ * 浮层经 **vdom 引擎直接渲染**（renderToStream + CommandApplier 到 body
+ * 容器——独立 mini-root——不依赖应用路由）——事件代理在 applier 内。
+ *
+ * 对应组件库：Toast/Confirm/Notification 组件（声明式）+ 本模块命令式
+ * 入口（showcase 等应用用 ctx.toast/confirm/notification）。
+ *
+ * 使用：应用装配（main.tsx）注入 ctx——`ctx.toast('...')` 任意位置调用。
+ */
+export type ToastType = 'success' | 'error' | 'info' | 'warning';
+/** 命令式轻提示（vdom 引擎渲染——自动消失——独立容器） */
+export declare function toast(message: string, type?: ToastType, duration?: number): void;
+/** 命令式注入（应用装配——ctx.toast） */
+export declare function injectCommands<C extends Record<string, unknown>>(ctx: C): C & {
+    toast: typeof toast;
+};

package/dist/client/vdom/context/UIContext.d.ts

@@ -0,0 +1,61 @@
+/**
+ * vdom context — 组件 ctx 类型（独立实现——零引用 ui-dom）
+ *
+ * 形状对齐契约（vdom-x X-A~G + 设计规则 §4）：
+ * - render(ids?) 返回 Promise（X-A7——await 精确等待含补跑——契约 §4.2）
+ * - data = 数据管道（唯一异步边界——三场景：SSR 真 fetch / hydration 种子 /
+ *   SPA fetch——缓存 + 并发合并 + 失败显式 invalidate）
+ * - onUnmount（卸载清理注册）
+ * - browser / ui 由 browser/ hooks/ 模块提供实现——类型在此引用（形状细化
+ *   随模块实现推进——当前 unknown 占位——实现后替换为具体接口）
+ * - params（路由页面组件参数——UIRouter 注入）
+ * - 中间件注入面（api/auth/ws/i18n...——索引签名——可选链消费）
+ */
+/** 数据管道（唯一异步边界——缓存/并发合并/错误/超时由管道管理） */
+export interface DataPipe {
+    /** 取数：命中同步返回——未命中调 fetcher 缓存并发合并；
+     *  未命中且无 fetcher（SPA 默认 fetch）——管道管理——不挂起 */
+    get<T = unknown>(key: string, fetcher?: () => Promise<T>): Promise<T>;
+    /** 写缓存（手动失效/预置） */
+    set<T = unknown>(key: string, value: T): void;
+    /** 数据是否已就绪（渲染期判断——未就绪输出加载态——管线不等待） */
+    has(key: string): boolean;
+    /** 种子注入（hydration——SSR 收集的数据预热——命中同步——零二次 fetch） */
+    preload(seed: Record<string, unknown>): void;
+    /** 失败重试（清除缓存中 reject 的 promise——显式入口——默认失败缓存不重试） */
+    invalidate(key: string): void;
+    /** 收集已解析数据（SSR——渲染后取种子——序列化进 __DATA__） */
+    seed(): Record<string, unknown>;
+}
+import type { Browser } from '../browser/Browser.ts';
+import type { Ui } from '../hooks/env.ts';
+export type { Ui };
+/** 组件 ctx（类型增强方案——对齐后端 Context：
+ *  - 内建面：render/data/ui/browser/onUnmount/params——具体类型
+ *  - 中间件注入面：`[key: string]: unknown` 索引签名 + **declare module 合并**
+ *    （应用/中间件作者扩展——同后端 `declare module 'weifuwu' { interface Context }`）：
+ *    ```ts
+ *    declare module 'weifuwu/vdom' { interface UIContext { api: ApiClient } }
+ *    ```
+ *  - 组件泛型：Component<P, C = UIContext>——默认增强后的 UIContext） */
+export interface UIContext {
+    /** 统一渲染原语（组件级闭包绑定——root/comp/语义 id 同一入口——串行调度；
+     *  返回 Promise——await 精确等待（含渲染中触发的补跑——X-A7） */
+    render(ids?: string[]): Promise<void>;
+    /** 数据管道（唯一异步边界——工厂层取数） */
+    data: DataPipe;
+    /** 卸载清理注册（ref cleanup/监听退订——unmount 时执行） */
+    onUnmount(fn: () => void): void;
+    /** 渲染完成回调注册（hook 挂载后动作——元素已挂载——serve 提供） */
+    afterRender?(fn: () => void): void;
+    /** 浏览器环境 API（注入的 window/document） */
+    browser: Browser;
+    /** hooks 注入面（usePopup/useControlled/useExternal 等 14 个——类型安全） */
+    ui: Ui;
+    /** 路由参数（页面组件——UIRouter 注入） */
+    params?: Record<string, string>;
+    /** 国际化（middlewares i18n 注入——可选——组件读组件文案面） */
+    i18n?: import('../middlewares/auth-i18n.ts').I18nState;
+    /** 中间件注入面（api/auth/ws/i18n...——可选链消费） */
+    [key: string]: unknown;
+}

package/dist/client/vdom/context/data.d.ts

@@ -0,0 +1,17 @@
+/**
+ * vdom context — DataPipe 实现（数据管道——组件工厂取数的唯一异步边界）
+ *
+ * 契约（设计规则 §3.4——ctx.data）：
+ * - **缓存 + 并发合并**：同 key 并发 get → 同一 promise（重复执行零成本——
+ *   组件工厂 N 实例同 key 取数合并）
+ * - **key 约定即 URL**（`/api/posts/1`）——天然唯一——key 必须含数据维度
+ *   （route params、userId）
+ * - **三场景**（SSR 真 fetch / hydration 种子同步命中 / SPA 未命中触发
+ *   fetcher——**无 hydration 决策后**：preload/seed 保留为 SSR 种子通道——
+ *   客户端接管时同步命中避免二次 fetch）
+ * - **失败缓存**：reject 的 promise 缓存——显式 invalidate(key) 重试
+ *   （默认失败不重试——诚实语义）
+ * - 未命中且无 fetcher → 默认 fetch(key)（key = URL——JSON 解析）
+ */
+import type { DataPipe } from './UIContext.ts';
+export declare function createDataPipe(timeoutMs?: number): DataPipe;

package/dist/client/vdom/core/async-guard.d.ts

@@ -0,0 +1,20 @@
+/**
+ * vdom core — async guard（异步超时防御——R2 挂起/饿死防御——零依赖）
+ *
+ * 背景（design/vdom-core-robustness-round4.md R2）：DataPipe 缓存 pending
+ * promise 无超时——fetcher 永不 resolve（网络挂起/用户 promise 泄漏）→
+ * `await renderFn` 永不完成 → 渲染队列饿死——应用冻结。
+ *
+ * 语义：
+ * - **管道级放弃**（不杀底层异步）：超时 → reject（显式错误——不再永久
+ *   pending——诚实语义）——底层 promise 继续跑（完成后结果丢弃——
+ *   缓存语义由调用方决定：fail 缓存→invalidate 重试）
+ * - 配置：createDataPipe(timeoutMs) / registry.asyncTimeout——生产默认
+ *   DEFAULT_ASYNC_TIMEOUT_MS（15s）——测试注入短值（假时钟零依赖）
+ * - 原生 AbortController 不可用于纯 promise 放弃（fetcher 无 signal 面）——
+ *   定时器方案——零依赖契约不变
+ */
+/** 默认异步超时（毫秒——生产——高于移动端慢网络阈值，低于"挂起感知"阈值） */
+export declare const DEFAULT_ASYNC_TIMEOUT_MS = 15000;
+/** 超时包装（ms ≤ 0 = 不超时——测试/本地禁用） */
+export declare function withTimeout<T>(p: Promise<T>, ms: number, label: string): Promise<T>;

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

@@ -0,0 +1,36 @@
+/**
+ * vdom core — build 阶段（vnode → 全量命令事件流）
+ *
+ * 四阶段管线（route → build → diff → patch）：build 是「新树渲染」——
+ * vnode → 命令事件流（create/insert/close...——done.full 全量标记——
+ * patch 据此清理旧树多余节点）。
+ *
+ * **共享渲染分发器**（createRenderDispatcher——build/diff 共用——单一
+ * 规则源）：kindOf 分类 → 各 node/ 文件渲染（text/hole/array/fragment/
+ * element/component/invalid）——diff 的新侧渲染复用本分发器——
+ * **消除重复**（diff 只做对照决策——新侧渲染走这里）。
+ */
+import type { VNode, VNodeChild } from './vnode.ts';
+import { type ComponentRegistry } from './node/component.ts';
+import type { UIContext } from '../context/UIContext.ts';
+import type { Command } from './command/index.ts';
+/** 渲染 sink（子节点递归出口——build/diff 共用） */
+export type RenderSink = (v: VNodeChild, parent: string, index: number, ref: string | null) => Promise<void>;
+/**
+ * 创建渲染分发器（**共享——build 首帧/diff 新侧渲染同一实现**）：
+ * emit(v, parent, index, ref)——kindOf 分类 → 各 node/ 文件渲染
+ */
+/** 生成端 emit 状态机（**维度 6——2026-XX**）：
+ *  本流内 id 类型表（id → 节点形态）——验证：
+ *  ① create 类型冲突：同 id 先 el 后 text（或反）→ 违例（投影错位）
+ *  ② insert parent 容器性：parent 是已生成的锚/文本 → 违例（id 空间
+ *     错位——组件 fuzz an:root.0(div) 类在生成时暴露——而非消费/终态）
+ *  宽容项：parent 不在类型表（组件 compId——sink 特判子空间）→ 合法
+ *    （段回退由消费端处理）；create 同 id 同类型重复（幂等复用）→ 合法
+ *  报告：console.error（不中断生成——生成端产物仍由对账器裁决） */
+export declare function createRenderDispatcher(emitCommand: (cmd: Command) => void, ctx: UIContext, registry: ComponentRegistry): RenderSink;
+/**
+ * vnode → 全量命令事件流（首帧/导航——done.full——patch 清理旧树多余）
+ * ctx：组件共享上下文（serve 创建）；registry：组件实例注册表
+ */
+export declare function renderToStream(root: VNode, ctx?: UIContext, registry?: ComponentRegistry): ReadableStream<Command>;

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

@@ -0,0 +1,25 @@
+/**
+ * vdom command — create（节点创建命令）
+ *
+ * create 携带 attrs = 可序列化面（class/id/style/data-*——服务端 create 即吐
+ * 完整开标签——不依赖后续 setProp）；运行时面（事件/ref）走 setProp。
+ */
+/** 创建元素（attrs 序列化面——服务端吐 HTML 开标签） */
+export type CreateCommand = {
+    op: 'create';
+    id: string;
+    tag: string;
+    attrs: Record<string, unknown>;
+};
+/** 创建文本节点 */
+export type CreateTextCommand = {
+    op: 'createText';
+    id: string;
+    value: string;
+};
+/** 创建占位锚（空洞槽——childNodes 同构——detail 诊断信息） */
+export type CreateAnchorCommand = {
+    op: 'createAnchor';
+    id: string;
+    detail?: string;
+};

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

@@ -0,0 +1,15 @@
+/**
+ * vdom command — index（命令汇总——统一导出 + 判定）
+ *
+ * 命令集 = 修改 DOM 的全部动作（流元素——纯数据——自足不依赖 vn 引用——
+ * 可序列化/可流——NDJSON 传输）。
+ */
+import type { CreateCommand, CreateTextCommand, CreateAnchorCommand } from './create.ts';
+import type { InsertCommand, MoveCommand, RemoveCommand } from './insert.ts';
+import type { SetPropCommand, SetTextCommand } from './props.ts';
+import type { RefCommand, UnrefCommand, MountCommand, UnmountCommand, CloseCommand, DoneCommand } from './lifecycle.ts';
+export type { CreateCommand, CreateTextCommand, CreateAnchorCommand, InsertCommand, MoveCommand, RemoveCommand, SetPropCommand, SetTextCommand, RefCommand, UnrefCommand, MountCommand, UnmountCommand, CloseCommand, DoneCommand, };
+/** 渲染指令（流元素——修改 DOM 的最小操作集） */
+export type Command = CreateCommand | CreateTextCommand | CreateAnchorCommand | InsertCommand | MoveCommand | RemoveCommand | SetPropCommand | SetTextCommand | RefCommand | UnrefCommand | MountCommand | UnmountCommand | CloseCommand | DoneCommand;
+/** 命令名（调试/审计——op 类型收窄） */
+export type CommandOp = Command['op'];

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

@@ -0,0 +1,32 @@
+/**
+ * vdom command — insert/remove（挂载与移除命令）
+ *
+ * insert 的 ref = 已插入的**前一个兄弟**（流式渲染——后一个尚未插入）——
+ * apply 侧插到 prev 之后（insertBefore(el, prev.nextSibling)）；ref null =
+ * 追加尾部。
+ */
+/** 挂载节点（parent/ref 均为节点 id） */
+export type InsertCommand = {
+    op: 'insert';
+    id: string;
+    parent: string;
+    ref: string | null;
+};
+/** 移动节点（keyed 重排——**DOM 不重建**——子树 id 重映射——
+ *  id = 旧 id；ref = 前一个兄弟（insertAfter 语义——null = 尾部）；
+ *  first = 移到父最前（首位标记）；newId = 新位置 id（子树前缀迁移）） */
+export type MoveCommand = {
+    op: 'move';
+    id: string;
+    parent: string;
+    ref: string | null;
+    newId: string;
+    first?: boolean;
+    /** 顺移 remap-only（相对顺序一致——DOM 位置自然到位——只做 id 前缀迁移） */
+    noMove?: boolean;
+};
+/** 移除节点（含子树——事件监听随元素 GC） */
+export type RemoveCommand = {
+    op: 'remove';
+    id: string;
+};

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

@@ -0,0 +1,47 @@
+/**
+ * vdom command — lifecycle（生命周期命令——显式指令化）
+ *
+ * 设计（2026-12——用户决策）：生命周期动作**显式指令**——patch 读取指令
+ * 时处理：
+ * - ref / unref —— **DOM 节点生命周期**：
+ *   ref = 节点挂载完成（insert 后——ref(el) 回调——el 已连接）；
+ *   unref = 节点卸载（ref(null) 回调——子树清理）
+ * - mount / unmount —— **组件生命周期**：
+ *   mount = 组件实例初始化完成（工厂执行后——实例已注册）；
+ *   unmount = 组件卸载（onUnmounts 清理——逆序执行——实例注册表消费）
+ *
+ * close = 离开子树（服务端闭合标签时机——客户端 no-op）；
+ * done = 流结束 = 渲染完成。
+ */
+/** 节点挂载完成（DOM 生命周期——ref(el)——fn 经函数表引用） */
+export type RefCommand = {
+    op: 'ref';
+    id: string;
+    fn: unknown;
+};
+/** 节点卸载（DOM 生命周期——ref(null)） */
+export type UnrefCommand = {
+    op: 'unref';
+    id: string;
+};
+/** 组件实例初始化完成（组件生命周期——工厂已执行——实例已注册） */
+export type MountCommand = {
+    op: 'mount';
+    compId: string;
+};
+/** 组件卸载（组件生命周期——onUnmounts 清理——逆序执行） */
+export type UnmountCommand = {
+    op: 'unmount';
+    compId: string;
+};
+/** 离开子树——服务端闭合标签——客户端 no-op */
+export type CloseCommand = {
+    op: 'close';
+    id: string;
+};
+/** 流结束 = 渲染完成（full = 全量流标记——patch 据此清理旧树多余节点；
+ *  增量流（diff）不清理——旧节点都是存活） */
+export type DoneCommand = {
+    op: 'done';
+    full?: boolean;
+};