weifuwu 0.84.0 → 0.86.0

package/README.md

@@ -1,6 +1,6 @@
 # weifuwu
 
-**自托管全栈框架** — 一个 npm 包 = 后端 HTTP + 前端 VDOM + 115 组件 + CSS 设计系统 + SaaS 地基（认证 / 消息 / 队列 / AI）。全自研、零构建、消灭样板。
+**自托管全栈框架** — 一个 npm 包 = 后端 HTTP + 前端 VDOM + 118 组件 + CSS 设计系统 + SaaS 地基（认证 / 消息 / 队列 / AI）。全自研、零构建、消灭样板。
 
 ```bash
 npm install weifuwu      # 一个依赖，完整应用栈
@@ -29,7 +29,7 @@ npm install weifuwu      # 一个依赖，完整应用栈
 |----|------|------|
 | 后端 | `weifuwu` | Trie 路由 / 中间件链 / serve / 自研 PG+Redis / SSR / GraphQL / WebSocket |
 | 前端 | `weifuwu/ui-dom` | **vdom3 精准事件流引擎**——createRouter（路由）+ createRoot（挂载）+ 事件流（渲染本体：`entity:action` 统一命名、DOM = fold、可回放可断言）+ SSR（事件流序列化）；组件=两阶段异步组件 / ctx.params 对齐后端；**weifuwu/components 直接复用**（VNode 契约唯一来源 ui-dom，见 `docs/frontend-ui-dom.md`） |
-| 组件 | `weifuwu/components` | 115 个 HTML 原语组件（表单/表格/弹层/AiChat…），引用 `--wf-*` 主题变量 |
+| 组件 | `weifuwu/components` | 118 个 HTML 原语组件（表单/表格/弹层/AiChat…），引用 `--wf-*` 主题变量 |
 | 样式 | `weifuwu/layout` | 66 布局原语 + 156 工具类 + 177 主题 Token，零自定义 CSS 文件 |
 | SaaS 地基 | 随包内置 | rateLimit / email / userSystem / messager / queue / ai → `ctx.*` 一行接入 |
 
@@ -116,7 +116,7 @@ npm install weifuwu      # 一个依赖，完整应用栈
 
 **自研数据层** — `ctx.sql`（PG v3 协议）与 `ctx.redis`（RESP2 协议）为**自研客户端**：确定性输出、行为可预测、统一错误模型。jsonb 自动解码、TTL 安全 API、schema 写前校验——高频痛点（双重编码/parseRow 样板/`'EX'` 参数顺序）从根上消除。
 
-> **实践验证**：多租户 AI 平台（`apps/agent-platform`——14 页 + 部门聊天 + 知识库 + HITL 审批）已完全运行在框架上：auth（userSystem）/ AI 引擎（ai）/ 实时消息（messager）/ UI（115 组件）/ 数据管道（ctx.api）零自研替代。框架哲学（中间件注入、诚实裁剪、机制与策略分离）经受住了真实复杂应用的检验——这也是我们确定「哪些进框架、哪些留应用层」的依据。
+> **实践验证**：多租户 AI 平台（`apps/agent-platform`——14 页 + 部门聊天 + 知识库 + HITL 审批）已完全运行在框架上：auth（userSystem）/ AI 引擎（ai）/ 实时消息（messager）/ UI（118 组件）/ 数据管道（ctx.api）零自研替代。框架哲学（中间件注入、诚实裁剪、机制与策略分离）经受住了真实复杂应用的检验——这也是我们确定「哪些进框架、哪些留应用层」的依据。
 
 ---
 
@@ -232,7 +232,7 @@ createRouter(routes, root)                                  // 之后正常交
 ### 30 秒体验（跑现有 demo）
 
 ```bash
-# ① 组件 cheatsheet——115 组件全部可交互预览（零依赖，5 秒起）
+# ① 组件 cheatsheet——118 组件全部可交互预览（零依赖，5 秒起）
 cd apps/components-demo && node server.ts
 # 打开 http://localhost:3000
 
@@ -321,7 +321,7 @@ cd apps/agent-platform && npm run seed && npm run dev
 | 资源 | CDN 地址 | 说明 |
 |------|---------|------|
 | `weifuwu/ui-dom` | `https://unpkg.com/weifuwu@latest/dist/ui-dom/index.js` | 前端运行时（createRouter, createRoot, h, 事件流, 状态管理等） |
-| `weifuwu/components` | `https://unpkg.com/weifuwu@latest/dist/components/index.js` | 115 个 UI 组件（Button, Card, Table, Modal, Icon 等） |
+| `weifuwu/components` | `https://unpkg.com/weifuwu@latest/dist/components/index.js` | 118 个 UI 组件（Button, Card, Table, Modal, Icon 等） |
 | `weifuwu/components` | `https://unpkg.com/weifuwu@latest/dist/components/style.css` | 组件 CSS + 177 个主题 Token + 66 个布局原语 + 156 个工具类 |
 | 独立布局系统 | `https://unpkg.com/weifuwu@latest/dist/layout/weifuwu-layout.css` | 仅 CSS 布局，不依赖 JS |
 

package/dist/components/Editor/Editor.d.ts

@@ -1,13 +1,14 @@
 /**
- * weifuwu/components — Editor
+ * weifuwu/components/Editor — 富文本编辑器（事件流事务层，阶段 1）
  *
- * 富文本编辑器组件，基于 contentEditable + _browser?.execCommand。
- * 零外部依赖，纯函数 (props, ctx) => VNode。
- *
- * 使用两阶段模型 + VDOM innerHTML 支持。
- * 状态管理：闭包变量 + ctx.ui.render()
+ * 架构（design/editor-events-plan.md）：文档 = fold(edit 事件流)。
+ * - 模型真相：DocState（contentEditable DOM 是渲染）
+ * - 语义操作（工具栏/快捷键）→ edit:commit（before 快照 + 事件）→ undo/redo 精确
+ * - 用户输入（键盘/IME/粘贴）暂由浏览器直写 DOM → onInput 同步回模型
+ *   （输入入流是阶段 2——阶段 1 撤销分流：语义操作走自建栈，输入退浏览器）
+ * - 受控 value 契约保留：onChange 发 serializeHtml(doc)
  */
 import type { Component } from '../../ui-dom/vnode.ts';
 import type { EditorProps } from './tools/types.ts';
-export type { EditorProps, ToolbarItem } from './tools/types.ts';
+export type { EditorProps, ToolbarItem, EditorAiAction, EditorAiOptions } from './tools/types.ts';
 export declare const Editor: Component<EditorProps>;

package/dist/components/Editor/edit-events.d.ts

@@ -0,0 +1,27 @@
+/**
+ * weifuwu/components/Editor/edit-events — 编辑事件流（第四端）
+ *
+ * 与 ai/sandbox 事件流同构（design/ai-events-plan.md / sandbox-events-plan.md）：
+ * 环形缓冲 + 查询（按动作过滤）+ 订阅 + 全局调试工具。
+ *
+ * 桥接（跨层一条链）：
+ * - vdom3 stream：每 commit 一条摘要（降频——细粒度事件只在本缓冲）
+ * - ai：edit:ai-apply 事件带 messageId 关联键（↔ ai 事件流 wf:token/done）
+ * - sandbox：source: 'sandbox' 的 commit 带 toolCallId（↔ sandbox exec 事件）
+ */
+export type EditAction = 'text-insert' | 'text-delete' | 'mark-apply' | 'block-set' | 'embed-insert' | 'embed-delete' | 'ai-apply' | 'ai-accept' | 'ai-reject' | 'commit' | 'undo' | 'redo' | 'clear' | 'preview' | 'office';
+export interface EditStreamEvent {
+    entity: 'edit';
+    action: EditAction;
+    ts: number;
+    target?: string;
+    payload?: Record<string, unknown>;
+}
+export declare function editEmit(action: EditAction, payload?: Record<string, unknown>, target?: string): void;
+/** 查询（倒序返回——最新在前；filter 按 action 过滤） */
+export declare function editEvents(n?: number, filter?: {
+    action?: EditAction | EditAction[];
+}): EditStreamEvent[];
+export declare function subscribeEditEvents(fn: (e: EditStreamEvent) => void): () => void;
+/** 测试隔离 */
+export declare function resetEditEvents(): void;

package/dist/components/Editor/model/apply.d.ts

@@ -0,0 +1,23 @@
+/**
+ * weifuwu/components/Editor/model/apply — 事件应用（文档 = fold(事件流)）
+ *
+ * applyEdit(doc, ev) 纯函数：任意事件 → 新 DocState（不可变）。
+ * 所有 offset 平移在单一入口维护（marks/blockProps/embeds/caret 同步——
+ * 防止各路径各自修补的漂移）。段结构查找用二分（undo/redo 高频路径）。
+ */
+import type { DocState, EditEvent, BlockProp } from './types.ts';
+/** 所有段起点（升序；空文档 = [0]——单空段） */
+export declare function segmentStarts(text: string): number[];
+/** 最后一个 <= pos 的段起点（二分——O(log n)） */
+export declare function segmentStartAt(text: string, pos: number, starts?: number[]): number;
+/** 位置 pos 所属段的块属性（默认 p/null） */
+export declare function blockPropAt(doc: DocState, pos: number): BlockProp | null;
+export declare function applyEdit(doc: DocState, ev: EditEvent): DocState;
+/** 应用事件并记录实际效果（ai-apply 返回带 original 校验后的事件——供历史审计） */
+export declare function applyEditChecked(doc: DocState, ev: EditEvent): {
+    doc: DocState;
+    ev: EditEvent;
+};
+/** 删除区间内/边界段起点被覆盖的段属性（含边界——段起点恰在 at+len 时合并吞属性；
+ *  逆操作按原段起点恢复——文本恢复后起点仍有效，幂等安全） */
+export declare function removedBlocksOf(doc: DocState, at: number, end: number): BlockProp[];

package/dist/components/Editor/model/diff.d.ts

@@ -0,0 +1,25 @@
+/**
+ * weifuwu/components/Editor/model/diff — 文本 diff（AI 建议对比用）
+ *
+ * 零依赖：公共前缀/后缀剪枝 + 中间 LCS（滚动数组 O(m) 空间）。
+ * 裁剪：总长度超 DIFF_MAX_LEN 退化为整体替换（诚实裁剪——大文本不追求
+ * 精细 diff，AI 选区级文本通常 < 4k）。
+ */
+export type DiffOp = {
+    type: 'equal';
+    text: string;
+} | {
+    type: 'insert';
+    text: string;
+} | {
+    type: 'delete';
+    text: string;
+};
+export declare const DIFF_MAX_LEN = 4000;
+/** a → b 的文本 diff（公共前后缀剪枝——编辑两端不动的场景零 DP） */
+export declare function textDiff(a: string, b: string): DiffOp[];
+/** diff 统计（AI 面板摘要：+N/-M） */
+export declare function diffStats(ops: DiffOp[]): {
+    added: number;
+    removed: number;
+};

package/dist/components/Editor/model/dom.d.ts

@@ -0,0 +1,27 @@
+/**
+ * weifuwu/components/Editor/model/dom — offset ↔ DOM 桥
+ *
+ * doc.text 的 offset 与 contentEditable DOM 的双向映射：
+ * - 文本节点：按 nodeValue.length 累加
+ * - 嵌入元素（IMG/TABLE/HR）：占位符 1 个 offset（与模型 embeds 对应）
+ * - **块级元素边界：计 1 个 \n**（模型段分隔——serialize 输出块标签，
+ *   \n 无 DOM 文本节点——不计数则 offset 偏 1（真实事故：AI 选区替换错位））
+ *
+ * 前提：DOM 内容 = serialize(doc) 的渲染（文本 + 嵌入 + 块结构对应）。
+ */
+/** 嵌入元素判定（与 html.ts EMBED_TAGS 一致） */
+export declare function isEmbedElement(el: Element): boolean;
+/** Range → 文档 offset（相对 root 内容起点） */
+export declare function rangeToOffsets(root: HTMLElement, range: Range): {
+    start: number;
+    end: number;
+};
+/** 当前选区 → offsets（编辑器内/无 DOM 时返回 null） */
+export declare function selectionOffsets(root: HTMLElement | null): {
+    start: number;
+    end: number;
+} | null;
+/** offset 区间 → Range（恢复选区；越界时 clamp 到内容末尾） */
+export declare function offsetsToRange(root: HTMLElement, start: number, end: number): Range | null;
+/** offsets → 选区（focus + 设置） */
+export declare function setSelectionOffsets(root: HTMLElement | null, start: number, end: number): void;

package/dist/components/Editor/model/history.d.ts

@@ -0,0 +1,21 @@
+/**
+ * weifuwu/components/Editor/model/history — undo/redo 栈（commit 粒度）
+ *
+ * 撤销粒度 = commit 粒度（AI 流式接受 = 1 个 commit = 1 个撤销步）。
+ * 栈本身只存事件——状态折叠由调用方（Editor 层）执行 applyEdit。
+ */
+import type { Commit } from './types.ts';
+export interface HistoryState {
+    undoStack: Commit[];
+    redoStack: Commit[];
+}
+export declare function createHistory(maxDepth?: number): HistoryState;
+/** 压入新 commit（清空 redo 栈——新分支；超深丢弃最旧） */
+export declare function pushCommit(h: HistoryState, commit: Commit, maxDepth?: number): void;
+/** 弹出 undo 栈顶（不动 redo——由调用方折叠后决定；返回 null = 无可撤销） */
+export declare function popUndo(h: HistoryState): Commit | null;
+/** 弹出 redo 栈顶（同时收回 undo——撤销后重做路径一致） */
+export declare function popRedo(h: HistoryState): Commit | null;
+export declare function canUndo(h: HistoryState): boolean;
+export declare function canRedo(h: HistoryState): boolean;
+export declare function clearHistory(h: HistoryState): void;

package/dist/components/Editor/model/html.d.ts

@@ -0,0 +1,16 @@
+/**
+ * weifuwu/components/Editor/model/html — HTML ⇄ DocState 序列化
+ *
+ * 只认 Editor 格式子集（诚实裁剪）：p/div/h1-3/blockquote/ul/ol（块）、
+ * b/strong/i/em/u/a（内联）、img/table/hr（embed 快照——内部不解析）、
+ * text-align（inline style 或 wf-text-* class）。未知标签降级取文本。
+ *
+ * parse 需要 DOM（DOMParser）——浏览器环境全局可用；测试注入 jsdom document。
+ */
+import type { DocState } from './types.ts';
+/** HTML → DocState（doc 可注入——jsdom 测试；浏览器默认全局） */
+export declare function parseHtml(html: string, doc?: Document): DocState;
+/** DocState → HTML（块标签 + 对齐 + marks + embeds；相邻 ul/ol 段合并列表） */
+export declare function serializeHtml(doc: DocState): string;
+/** 往返幂等校验辅助：parse → serialize → parse 不再变化 */
+export declare function normalizeHtml(html: string, doc?: Document): string;

package/dist/components/Editor/model/inverse.d.ts

@@ -0,0 +1,20 @@
+/**
+ * weifuwu/components/Editor/model/inverse — 事件逆操作（undo 基元）
+ *
+ * 任意事件 → 逆事件（与 vdom3 events.ts inverse() 同构）。不变量：
+ * applyEdit(applyEdit(doc, ev), inverseEdit(ev)) === doc。
+ */
+import type { DocState, EditEvent, EmbedSpan } from './types.ts';
+import { EMBED_CHAR } from './types.ts';
+/** 逆操作可能产生多个事件（text-delete 覆盖 embed → 恢复条目需补 embed-insert） */
+export type InverseResult = EditEvent | EditEvent[];
+/**
+ * 逆操作（undo 审计/验证用——生产 undo 走 commit 快照）。
+ * doc 可选：text-insert/ai-apply 的逆需要操作后文档提取区间内段属性
+ * （text-delete 校验要求——无 doc 时跳过（不精确——仅审计场景））。
+ */
+export declare function inverseEdit(ev: EditEvent, doc?: DocState): InverseResult;
+/** commit 的逆（事件逆序 + 各自逆操作展开——undo 应用顺序） */
+export declare function inverseCommit(events: EditEvent[]): EditEvent[];
+export { EMBED_CHAR };
+export type { EmbedSpan };

package/dist/components/Editor/model/types.d.ts

@@ -0,0 +1,116 @@
+/**
+ * weifuwu/components/Editor/model — 文档模型（事件流底座）
+ *
+ * 核心不变量（design/editor-events-plan.md）：文档状态 = fold(edit 事件流)。
+ * 本文档模型是纯 TS 数据结构 + 纯函数（无 DOM、无 UI）——阶段 0 验收：
+ * 折叠不变量（fuzz）/ 逆操作 / HTML 往返。
+ *
+ * 模型设计：
+ * - text 为全文纯文本，`\n` 为段落分隔符（offset 连续——选区/diff/提示词天然）
+ * - blockProps：非默认块属性（按段起点 offset 记录；段结构由 text 派生）
+ * - marks：内联格式区间（左闭右开；b/i/u/link 可重叠）
+ * - embeds：img/table/hr 用占位符 `\uFFFC` 占 1 个字符位（标准对象替换字符）
+ */
+/** 块类型（p 为默认——不记录） */
+export type BlockKind = 'p' | 'h1' | 'h2' | 'h3' | 'ul' | 'ol' | 'quote';
+export type Align = 'left' | 'center' | 'right';
+export type MarkType = 'b' | 'i' | 'u' | 'link';
+/** 非默认块属性（段起点 offset → 块格式） */
+export interface BlockProp {
+    start: number;
+    kind: BlockKind;
+    align?: Align;
+}
+/** 内联格式区间 */
+export interface MarkSpan {
+    start: number;
+    end: number;
+    type: MarkType;
+    href?: string;
+}
+/** 嵌入（占位符 \uFFFC 占据 text 1 字符位；id 唯一——删除按 id 精确匹配） */
+export interface EmbedSpan {
+    id: string;
+    at: number;
+    type: 'img' | 'table' | 'hr' | 'pre';
+    html: string;
+}
+/** 文档状态（不可变——applyEdit 返回新对象；undo/redo 快照对比免费） */
+export interface DocState {
+    text: string;
+    blockProps: BlockProp[];
+    marks: MarkSpan[];
+    embeds: EmbedSpan[];
+}
+export declare const EMPTY_DOC: DocState;
+/** 嵌入占位符（OBJECT REPLACEMENT CHARACTER——业界标准） */
+export declare const EMBED_CHAR = "\uFFFC";
+export type EditEvent = {
+    type: 'text-insert';
+    at: number;
+    text: string;
+} | {
+    type: 'text-delete';
+    at: number;
+    len: number;
+    removed: string;
+    removedEmbeds: EmbedSpan[];
+    /** 被完整删除的段属性（起点在区间内）——逆操作恢复段格式（合并段继承丢失） */
+    removedBlocks: BlockProp[];
+} | {
+    type: 'mark-apply';
+    start: number;
+    end: number;
+    mark: MarkType;
+    on: boolean;
+    href?: string;
+    prev: MarkSpan[];
+}
+/** 绝对恢复（mark 逆操作——区间表示不可逆，undo 用快照精确还原） */
+ | {
+    type: 'mark-restore';
+    mark: MarkType;
+    spans: MarkSpan[];
+    prev: MarkSpan[];
+} | {
+    type: 'block-set';
+    start: number;
+    kind: BlockKind;
+    align?: Align | null;
+    prev: BlockProp | null;
+} | {
+    type: 'embed-insert';
+    at: number;
+    embed: EmbedSpan;
+} | {
+    type: 'embed-delete';
+    at: number;
+    embed: EmbedSpan;
+}
+/** 快照式：AI 替换（original 由创建者提供——diff 面板直接读；原子撤销一步；
+ *  removedEmbeds/removedBlocks：区间内嵌入与被删段属性——逆操作恢复） */
+ | {
+    type: 'ai-apply';
+    start: number;
+    end: number;
+    original: string;
+    revised: string;
+    removedEmbeds: EmbedSpan[];
+    removedBlocks: BlockProp[];
+};
+/** 事务边界：N 个事件 = 1 个撤销步（AI 流式接受 = 1 个 commit）
+ *  before：操作前状态快照——undo 精确恢复（mark 区间表示不可逆——
+ *  收缩/合并后无法从逆事件还原；快照 + 重放混合：undo=恢复 before，
+ *  redo=从 before 重放 events——vdom3 remove 逆操作存快照同款先例） */
+export interface Commit {
+    label: string;
+    events: EditEvent[];
+    before: DocState;
+    /** 操作时间（历史面板显示；缺省 = 记录时） */
+    ts?: number;
+    /** 操作前光标（undo 恢复位置；可选——默认不恢复） */
+    caret?: {
+        start: number;
+        end: number;
+    };
+}

package/dist/components/Editor/tools/table.d.ts

@@ -1,7 +1,10 @@
 /**
  * weifuwu/components/Editor/tools — 表格工具
+ *
+ * 事件流事务层（design/editor-events-plan.md 阶段 1）：表格 = embed 事件——
+ * 本模块只生成 HTML（不再操作 DOM/execCommand）。
  */
-/** 在光标处插入表格 HTML */
-export declare function insertTable(rows: number, cols: number): void;
+/** 生成表格 HTML（表头行加粗——模型 embed 快照） */
+export declare function tableHtml(rows: number, cols: number): string;
 /** 渲染 6×6 表格选择网格 */
 export declare function renderTableGrid(hoverRow: number, hoverCol: number, onSelect: (rows: number, cols: number) => void, onHover: (row: number, col: number) => void, onLeave: () => void): any;

package/dist/components/Editor/tools/toolbar.d.ts

@@ -6,4 +6,4 @@ import type { FormatState, ToolbarItem } from './types.ts';
 export declare const DEFAULT_TOOLBAR: ToolbarItem[];
 export declare const TOOLBAR_LABELS: Record<ToolbarItem, string>;
 export declare const TOOLBAR_TITLES: Record<ToolbarItem, string>;
-export declare function renderToolbar(items: ToolbarItem[], active: FormatState, isSource: boolean, onItem: (item: ToolbarItem) => void, customRender?: Record<string, (item: ToolbarItem) => VNode>): VNode;
+export declare function renderToolbar(items: ToolbarItem[], active: FormatState, isSource: boolean, onItem: (item: ToolbarItem, anchor?: HTMLElement | null) => void, customRender?: Record<string, (item: ToolbarItem) => VNode>, extra?: VNode[]): VNode;

package/dist/components/Editor/tools/types.d.ts

@@ -11,5 +11,30 @@ export interface EditorProps {
     toolbar?: ToolbarItem[];
     /** 图片上传回调 — 接收 File 返回图片 URL。不传时弹出 URL 输入框 */
     onUpload?: (file: File) => Promise<string>;
+    /** AI 协作（可选——不传则无 AI 能力）：选区操作 → wf: 流式端点 → 建议浮层 →
+     *  接受 = edit:ai-apply commit（原子撤销一步） */
+    ai?: EditorAiOptions;
+    /** 草稿持久化 key（可选）：传入时内容自动保存/恢复（ctx.browser.storage*——
+     *  SSR 无害 no-op）。挂载时 value 为空且存在草稿 → 恢复草稿。 */
+    draftKey?: string;
+}
+/** AI 动作（选区文本 → 提示词 → 建议） */
+export interface EditorAiAction {
+    id: string;
+    /** 按钮标签（如 '润色'） */
+    label: string;
+    /** 提示词模板（选区文本注入 {selection} 由调用方替换） */
+    prompt: (ctx: {
+        selection: string;
+    }) => string;
+}
+export interface EditorAiOptions {
+    /** wf: SSE 端点（POST——协议 docs/ai-contract.md） */
+    url: string;
+    headers?: Record<string, string>;
+    /** 自定义动作（缺省 = 内置 5 个：润色/翻译/缩写/扩写/纠错） */
+    actions?: EditorAiAction[];
+    /** x:* 自定义事件透传 */
+    onEvent?: (name: string, data: unknown) => void;
 }
 export type FormatState = Record<string, boolean>;

package/dist/components/FilePreview/FilePreview.d.ts

@@ -0,0 +1,42 @@
+/**
+ * weifuwu/components/FilePreview — 文件预览（office/pdf/md/html/text）
+ *
+ * 架构（design/file-preview-plan.md）：
+ * - md 预览：复用 `<Markdown>` 组件（安全 token 渲染——表格/任务列表/URL 白名单）
+ * - md/text 编辑：复用 `<Editor>`（事件流事务层——撤销/时光机/AI 全继承）——
+ *   编辑闭环：md → markdownToHtml → Editor（DocState 模型）→ serializeMarkdown 回写
+ * - html 预览：iframe sandbox（安全隔离——untrusted HTML 不直插 DOM）
+ * - pdf/office：浏览器原生/服务端转换 URL（只读）
+ *
+ * 事件流：预览加载 `editEmit('preview')`（__edit_tail 可审计）；编辑 = Editor
+ * commit 事件流（同一时间线）。sandbox 集成：url 加载 + onSave 回写由消费方接。
+ */
+import type { Component } from '../../ui-dom/vnode.ts';
+import type { EditorAiOptions } from '../Editor/Editor.ts';
+export type FileType = 'md' | 'html' | 'pdf' | 'office' | 'text';
+/** 从文件名/URL 推断类型（type 未传时自动探测） */
+export declare function detectType(fileName?: string, url?: string): FileType;
+export interface FilePreviewProps {
+    /** 文件类型（缺省按 fileName/url 扩展名自动探测） */
+    type?: FileType;
+    /** md/html/text 内容（直接传入）；pdf/office 用 url */
+    content?: string;
+    /** pdf/office 文件 URL（或 html 远程加载） */
+    url?: string;
+    fileName?: string;
+    /** md/text：切换 Editor（复用事件流事务层——编辑/撤销/时光机/AI） */
+    editable?: boolean;
+    /** 编辑模式 AI 协作（透传 Editor） */
+    ai?: EditorAiOptions;
+    /** 编辑保存回调（md/text 序列化回写） */
+    onSave?: (content: string, type: 'md' | 'text') => void;
+    /** 加载完成（解析成功） */
+    onLoad?: (info: {
+        type: FileType;
+        chars: number;
+        blocks: number;
+    }) => void;
+    /** 内容高度 */
+    height?: string;
+}
+export declare const FilePreview: Component<FilePreviewProps>;

package/dist/components/FilePreview/markdown.d.ts

@@ -0,0 +1,23 @@
+/**
+ * weifuwu/components/FilePreview/markdown — Markdown 转换（编辑桥）
+ *
+ * 复用现有 Markdown 组件（src/components/Markdown/parser.ts——安全子集 token 树：
+ * 表格/任务列表/删除线/安全 URL 白名单——不重复造轮子）。
+ *
+ * 本模块只提供两个编辑桥转换：
+ * - markdownToHtml(md)：md → HTML 字符串（Editor 编辑入口——Editor 是 HTML 模型）
+ * - serializeMarkdown(doc)：DocState → md（编辑保存回写）
+ *
+ * 编辑闭环（事件流）：md → markdownToHtml → Editor（DocState 模型——撤销/时光机/
+ * AI 全继承）→ serializeMarkdown → 保存。
+ */
+import type { DocState } from '../Editor/model/types.ts';
+import { safeUrl, type MdBlock, type MdInline } from '../Markdown/parser.ts';
+/** md → HTML（Editor 模型子集内：标题/段落/引用/列表/代码块/分割线/图片——
+ *  表格/任务列表/删除线超出 Editor 模型——裁剪为段落（编辑时降级——诚实）） */
+export declare function markdownToHtml(md: string): string;
+/** DocState → Markdown（编辑保存回写——格式子集内语义等价）
+ *  块间空行分隔（md 规范）；相邻列表项单换行（保持列表连续） */
+export declare function serializeMarkdown(doc: DocState): string;
+export { safeUrl };
+export type { MdBlock, MdInline };

package/dist/components/OfficeEditor/ai/ai-bridge.d.ts

@@ -0,0 +1,39 @@
+/**
+ * weifuwu/components/OfficeEditor/ai — ODES × AI 事件流对接
+ *
+ * 设计（design/office-events-plan.md §9）：AI 落地 = 普通 op + ai 元数据。
+ * 本模块：AI 回复 → OfficeOp[] 默认解析（按 mode）+ 事件流桥接发射。
+ *
+ * xlsx formula 模式解析：
+ * - 回复含 `=...` → 公式单元格（kind:'f'——值 + formula 字符串保留——不计算）
+ * - 纯数字 → kind:'n'；true/false → kind:'b'；其余 → kind:'s'
+ * - 位置：回复内嵌 ref（`A1:` 前缀 / `B2=...`）优先，否则 ctx.ref（活动单元格）
+ */
+import type { AiContext, OfficeOp, OfficeStreamPayload } from '../model/types.ts';
+import type { DocType } from '../model/types.ts';
+export interface ParseResult {
+    ops: OfficeOp[];
+    /** 解析说明（UI 展示；不可解析时建议） */
+    note?: string;
+}
+/** AI 回复 → cell-set ops（formula 模式） */
+export declare function parseFormulaReply(text: string, ctx: AiContext): ParseResult;
+/** AI 回复 → shape-set op（pptx text 模式——选中 shape 文本替换） */
+export declare function parseShapeTextReply(text: string, ctx: AiContext): ParseResult;
+/** docx/text 模式：回复即正文——Editor ai-apply 语义由 Editor 层处理（本模块不产生 op） */
+export declare function parseTextReply(_text: string, _ctx: AiContext): ParseResult;
+export declare function parseReplyByMode(text: string, ctx: AiContext): ParseResult;
+/**
+ * 发射 office 事件（AI 关联——payload.ai.messageId + target = messageId——
+ * editEvents ↔ aiEvents 一条链：`__edit_tail(50,'office')` ↔ `__ai_events(n,{messageId})`）
+ */
+export declare function officeAiEmit(payload: Omit<OfficeStreamPayload, 'ai'> & {
+    ai: {
+        messageId: string;
+        status: 'suggested' | 'accepted' | 'rejected';
+    };
+}): void;
+/** 便捷：AI 建议接受 = 普通 op 落地（ai 元数据——接受状态） */
+export declare function emitAiApply(docType: DocType, op: OfficeOp, messageId: string): void;
+/** 便捷：AI 建议拒绝（不产生 op——状态记录审计） */
+export declare function emitAiReject(docType: DocType, messageId: string, reason?: string): void;

package/dist/components/OfficeEditor/model/apply.d.ts

@@ -0,0 +1,25 @@
+/**
+ * weifuwu/components/OfficeEditor/model/apply — ODES 折叠（fold）纯函数
+ *
+ * 核心不变量：snapshot = fold(全部事件)——apply 每个 op 得到新状态（不可变）。
+ * - docx：委托 Editor applyEdit（EditEvent 全量复用——零新逻辑）
+ * - xlsx/pptx：各自 apply（纯函数——Map 复制、数组复制）
+ */
+import type { DeckState, DocType, OfficeCheckpoint, OfficeOp, OfficeSnapshot, SheetOp, SlideOp, WorkbookState } from './types.ts';
+export declare function emptySnapshot(docType: DocType): OfficeSnapshot;
+/** 'A1' → { row: 0, col: 0 }（col 字母段、row 数字段） */
+export declare function parseRef(ref: string): {
+    row: number;
+    col: number;
+};
+export declare function toRef(row: number, col: number): string;
+/** 行列插入后引用平移（单元格重定位；公式字符串不重算——裁剪登记） */
+export declare function shiftCellRef(ref: string, atRow: number, atCol: number, dRow: number, dCol: number): string | null;
+export declare function applySheetOp(wb: WorkbookState, op: SheetOp): WorkbookState;
+export declare function applySlideOp(deck: DeckState, op: SlideOp): DeckState;
+/** 单 op 应用（docx 委托 applyEdit——EditEvent 全量复用） */
+export declare function applyOfficeOp(snapshot: OfficeSnapshot, op: OfficeOp): OfficeSnapshot;
+/** checkpoint 折叠：snapshot + apply tail 全部 op（不变量：结果 = 全部事件 fold） */
+export declare function foldOffice(cp: OfficeCheckpoint): OfficeSnapshot;
+/** 校验 op 是否属于 docType 命名空间（跨类型 op 拒绝——诚实裁剪） */
+export declare function opBelongsTo(op: OfficeOp, docType: DocType): boolean;