@xiongtao.xt/tau-plugins 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LastKnightCoder
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# Tau plugins 作者契约
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+通过 npm 别名安装为 `@tau/plugins`。运行时由 Tau 桌面宿主提供，构建时必须 external；不可在普通 Node.js 程序中直接执行。
+
+模板与使用说明：https://github.com/LastKnightCoder/tau-plugin-template

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@xiongtao.xt/tau-plugins",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LastKnightCoder/editor.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "type": "module",
+  "description": "Tau 桌面开发插件契约；运行时由宿主提供",
+  "exports": {
+    ".": {
+      "types": "./types/packages/plugins/src/index.d.ts",
+      "default": "./runtime.js"
+    }
+  },
+  "dependencies": {
+    "@types/react": "19.2.0",
+    "@types/react-dom": "19.2.0",
+    "slate": "0.126.2",
+    "slate-react": "0.126.4",
+    "clsx": "2.1.1",
+    "lucide-react": "0.399.0",
+    "slate-history": "0.113.1"
+  },
+  "peerDependencies": {
+    "react": "19.2.0",
+    "react-dom": "19.2.0"
+  }
 }

package/runtime.js

@@ -0,0 +1 @@
+throw new Error("Tau 插件模块由桌面宿主提供，请在插件构建中设为 external");

package/types/packages/editor/api.d.ts

@@ -0,0 +1,10 @@
+export * from "./src/api/index";
+/** 扩展包通过模块增强登记元素；不要求内核知道包名或实现文件。 */
+declare const extensionElementMapBrand: unique symbol;
+declare const extensionInlineElementMapBrand: unique symbol;
+export interface ExtensionElementMap {
+    [extensionElementMapBrand]: never;
+}
+export interface ExtensionInlineElementMap {
+    [extensionInlineElementMapBrand]: never;
+}

package/types/packages/editor/contracts.d.ts

@@ -0,0 +1,3 @@
+/** 无 React/DOM 运行时代码的声明入口，供应用 SDK 适配现有扩展协议。 */
+export { defineExtension, defineElement } from "./src/api/extension";
+export type { EditorExtension, ElementSpec, ElementRenderProps } from "./src/api/extension";

package/types/packages/editor/src/api/command.d.ts

@@ -0,0 +1,61 @@
+import type { Editor, Element, Path } from "slate";
+/**
+ * 命令注册表（01 §5.1）：命令是编辑器的唯一动词层——热键、菜单、块面板、宿主
+ * 都引用命令 id 触发动作，enablement（when）与错误隔离（按贡献扩展熔断）只有一份。
+ */
+export interface EditorCommandContext {
+    /** 经热键触发时的键盘事件 */
+    event?: React.KeyboardEvent<HTMLDivElement>;
+    /** 调用方传参（如待插入的类型） */
+    payload?: unknown;
+    /** 入口针对的目标元素（块菜单打开的块）；热键路径没有 */
+    element?: Element;
+    /** 目标元素的路径（与 element 成对出现），命令省一次 ReactEditor.findPath */
+    path?: Path;
+}
+export interface EditorCommand {
+    /** 全局唯一；内置用 `tau.*`，宿主 `host.*`，第三方将来用作者命名空间 */
+    id: string;
+    /** 展示名（菜单 / 命令面板用），可省 */
+    title?: string;
+    /** enablement：false 时热键跳过、菜单灰显 */
+    when?: (editor: Editor) => boolean;
+    /** 异步动作应返回 Promise，交给 dispatcher 隔离失败 */
+    run: (editor: Editor, ctx: EditorCommandContext) => void;
+}
+/** 热键只绑命令 id，不绑函数 */
+export interface EditorHotkey {
+    key: string | string[];
+    command: string;
+    /** 普通扩展热键未消费时才尝试，仍早于内核通用兜底；同段保持声明顺序。 */
+    fallback?: boolean;
+}
+export interface RegisteredCommand {
+    readonly command: EditorCommand;
+    /** 贡献者（扩展 id 或内核 "editor"）；熔断与上报按它计 */
+    readonly owner: string;
+}
+export declare class CommandRegistry {
+    private readonly commands;
+    register(owner: string, commands: readonly EditorCommand[]): void;
+    get(id: string): RegisteredCommand | undefined;
+    list(): readonly RegisteredCommand[];
+}
+/** 命令执行的最小守卫接口（ExtensionCircuitBreaker 结构兼容） */
+export interface CommandGuard {
+    isDisabled(owner: string): boolean;
+    record(owner: string, phase: "command", error: unknown): void;
+}
+export interface CommandDispatcher {
+    /**
+     * 执行命令。返回 false 表示未执行（没有这个命令会告警；when 不满足静默跳过），
+     * 调用方据此决定要不要回落到别的处理；异步命令返回 true 表示已启动。
+     */
+    execute(editor: Editor, id: string, ctx?: EditorCommandContext): boolean;
+}
+export declare function createCommandDispatcher(registry: CommandRegistry, guard: CommandGuard): CommandDispatcher;
+/** 程序化执行命令的句柄，挂在 editor 实例上（热键、菜单与宿主统一入口） */
+export interface EditorCommandsHandle {
+    /** payload 仅传领域参数；目标 element/path 单独传入，run 会收到组合后的上下文。 */
+    execute(id: string, payload?: unknown, element?: Element, path?: Path): boolean;
+}

package/types/packages/editor/src/api/copy.d.ts

@@ -0,0 +1,23 @@
+import type { Descendant, Element } from "slate";
+export type CopyDecision = "keep" | "unwrap";
+type DeepReadonly<T> = T extends object ? {
+    readonly [K in keyof T]: DeepReadonly<T[K]>;
+} : T;
+type CopiedElement<E extends Element> = E extends Element ? Omit<DeepReadonly<E>, "children"> & {
+    /** 解包后的片段子节点可能不再满足原元素的完整文档 schema。 */
+    readonly children: readonly DeepReadonly<Descendant>[];
+} : never;
+export interface CopyContext<E extends Element = Element> {
+    /** 子节点已处理的冻结片段，不是原文档节点。 */
+    readonly element: CopiedElement<E>;
+    readonly fullySelected: boolean;
+    /** 原节点的祖先类型，从外到内，不含自身。 */
+    readonly ancestorTypes: readonly string[];
+}
+export type ElementCopy<E extends Element = Element> = (context: CopyContext<E>) => CopyDecision;
+/** 装配后的有效元素策略；同类型覆盖时连同 owner 一起替换。 */
+export interface RegisteredCopy {
+    readonly owner: string;
+    readonly copy: ElementCopy;
+}
+export {};

package/types/packages/editor/src/api/drag.d.ts

@@ -0,0 +1,24 @@
+import type { Element } from "slate";
+/**
+ * 拖拽声明（01 §5.4）：知识归属容器——块自己声明可拖性与放置谓词，
+ * 内核（BlockDragHost）统一渲染手柄 / 插入线 / 悬停标记，块组件只渲染内容。
+ */
+export interface ElementDragSpec {
+    /** 自身可拖（显示手柄）；false 时本块仅作为放置目标参与 */
+    self: boolean;
+    /** 内部子内容是否参与块级拖拽；false 时更深的子块不显示手柄（如勾选项里的段落） */
+    children: boolean;
+    /**
+     * 放置谓词：拖动元素能否落到本块（含本块内部）。缺省接受任何块。
+     * 「拖到本块内部的子块前后」也经过本谓词——容器不必认识子块的类型细节。
+     */
+    accepts?: (dragElement: Element) => boolean;
+    /**
+     * 手柄位置微调（经 cn 合并，可覆盖默认 left / top / 尺寸；如标题让出折叠箭头的位置）。
+     * 手柄挂在 chrome wrapper 上，em 按 wrapper（正文）字号计算；需随元素属性变化（如标题级别）时传函数。
+     */
+    handleClassName?: string | ((element: Element) => string | undefined);
+}
+/** `true` 是 `{ self: true, children: true }` 的简写；未声明的类型没有拖拽 chrome */
+export type ElementDrag = boolean | ElementDragSpec;
+export declare const normalizeDragSpec: (drag: ElementDrag | undefined) => ElementDragSpec | undefined;

package/types/packages/editor/src/api/extension.d.ts

@@ -0,0 +1,100 @@
+import type { ComponentType, ReactNode } from "react";
+import type { Descendant, Editor, Element, NodeEntry, TextUnit } from "slate";
+import type { RenderElementProps } from "slate-react";
+import type { Plugin } from "../utils/plugin";
+import type { IBlockPanelListItem, IConfigItem } from "../types";
+import type { EditorCommand, EditorHotkey } from "./command";
+import type { EditorMenuContribution } from "./menu";
+import type { ElementDrag } from "./drag";
+import type { ElementIngestSpec } from "./ingest";
+import type { ElementCopy } from "./copy";
+import type { DecorationSpec, MarkSpec } from "./marks";
+/**
+ * 扩展 API v2（01 §5.1）：声明式描述「这个扩展贡献了什么」，内核负责装配、隔离与分发。
+ * 所有扩展都是 defineExtension 的产物（旧 IExtension 适配层已删除，ER-019）。
+ */
+export declare const EXTENSION_API_VERSION = 1;
+/** 元素渲染组件的 props；`attributes` 与 `children` 必须原样交给最外层元素 */
+export interface ElementRenderProps<E extends Element = Element> {
+    attributes: RenderElementProps["attributes"];
+    element: E;
+    children: ReactNode;
+}
+/**
+ * 元素的行为：只在选区落在该类型的元素内时调用（从最内层元素往外找），
+ * 不再全局改写 `editor.insertBreak`。返回 `true` 表示已处理；`false` 交给外层元素，最后回到默认行为。
+ */
+export interface ElementBehaviors<E extends Element = Element> {
+    insertBreak?(editor: Editor, entry: NodeEntry<E>): boolean;
+    deleteBackward?(editor: Editor, entry: NodeEntry<E>, unit: TextUnit): boolean;
+    insertText?(editor: Editor, entry: NodeEntry<E>, text: string): boolean;
+    /** 规范化该类型的节点；做了修改返回 `true`（Slate 会再规范化一轮） */
+    normalize?(editor: Editor, entry: NodeEntry<E>): boolean;
+}
+export interface ElementEmptyContext {
+    /** 使用当前编辑器已安装的声明判断子节点；未知或失败时保留。 */
+    isEmpty(node: Descendant): boolean;
+}
+export interface ElementSpec<E extends Element = Element> {
+    /** 元素 type；内置类型沿用现有名字，兼容已有文档 */
+    type: string;
+    kind: "block" | "inline";
+    isVoid?: boolean;
+    /** 后代的方向键/退格导航由领域接管，核心不执行默认相邻块导航。 */
+    isolateBlockNavigation?: boolean;
+    /** 判定源码等非 children 内容是否为空；未声明时内核不推断扩展私有字段 */
+    isEmpty?: (element: E, context: ElementEmptyContext) => boolean;
+    /** 渲染组件，可以是 `lazy()`：加载期间内核显示保留结构的空壳 */
+    render: ComponentType<ElementRenderProps<E>>;
+    behaviors?: ElementBehaviors<E>;
+    /** 选区复制的包装策略；未声明时保留整棵片段子树。仅非 void 块生效。 */
+    copy?: ElementCopy<E>;
+    /** 拖拽声明（01 §5.4）：未声明的类型没有拖拽 chrome；块组件不再自己接手柄 */
+    drag?: ElementDrag;
+    /** 内容注入声明（01 §5.4）：drop 与 paste 共用的认领规则；块组件不再改写 insertData */
+    ingest?: ElementIngestSpec;
+}
+export interface ExtensionLayerProps {
+    /** 根 UI 在 Editable 外，不能通过 Slate 的 useReadOnly 读取此状态。 */
+    readonly readOnly: boolean;
+}
+export interface EditorExtension {
+    /** 全局唯一；内置用 `tau.*`，第三方将来用作者命名空间 */
+    readonly id: string;
+    readonly apiVersion: typeof EXTENSION_API_VERSION;
+    readonly elements?: readonly ElementSpec[];
+    readonly marks?: readonly MarkSpec[];
+    /** 暂态装饰（不进文档）；外观由本扩展 marks 里 keys 对应的声明渲染 */
+    readonly decorations?: readonly DecorationSpec[];
+    /** 在编辑器的 Slate/Kit 上下文挂载辅助 UI，组件自行接宿主浮层仲裁。 */
+    readonly layers?: readonly ComponentType<ExtensionLayerProps>[];
+    /** 块菜单条目；给函数时每次打开菜单求值 */
+    readonly blockPanel?: readonly IBlockPanelListItem[] | ((editor: Editor) => readonly IBlockPanelListItem[]);
+    /** 悬浮工具条条目 */
+    readonly toolbar?: readonly IConfigItem[];
+    /** 贡献的命令：菜单、块面板、宿主都引用命令 id 触发动作 */
+    readonly commands?: readonly EditorCommand[];
+    /** 热键只绑命令 id（不绑函数）；同一键位允许多条声明按顺序匹配（沿用旧语义） */
+    readonly hotkeys?: readonly EditorHotkey[];
+    /** 手柄菜单与右键菜单的特有条目（01 §5.4）；条目只引用命令 id */
+    readonly menu?: EditorMenuContribution;
+    /** 贡献到指定源类型的菜单；不改变 menu 默认归属自身元素的规则。 */
+    readonly menuFor?: Readonly<Record<string, EditorMenuContribution>>;
+    /**
+     * 挂到**其他**元素类型上的行为，给「在别的元素里触发、产出本元素」的场景，
+     * 典型是快捷语法（段落里输入 `---` 回车变分割线）。与该类型自身的行为按扩展顺序一起分发。
+     */
+    readonly behaviorsFor?: Readonly<Record<string, ElementBehaviors>>;
+    /**
+     * @internal 受信任层（ER-005）：原始 Slate 插件，只给内核内置扩展表达声明式写不出的跨节点逻辑。
+     * 将来开放第三方时不进公开类型。
+     */
+    readonly plugins?: readonly Plugin[];
+}
+export type ExtensionDefinition = Omit<EditorExtension, "apiVersion"> & {
+    apiVersion?: typeof EXTENSION_API_VERSION;
+};
+export declare function defineExtension(definition: ExtensionDefinition): EditorExtension;
+/** 按元素类型收窄 render / behaviors 的参数类型；运行时原样返回 */
+export declare function defineElement<E extends Element>(spec: ElementSpec<E>): ElementSpec;
+export declare const isEditorExtension: (value: unknown) => value is EditorExtension;

package/types/packages/editor/src/api/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * `@tau/editor/api`：扩展作者的渲染入口；纯服务契约经 /api/services（ER-021）。
+ *
+ * 只放写扩展需要的东西：声明、服务、主题、少量工具。编辑器组件、kit 工厂等宿主用的留在包根入口。
+ * 未标注过渡用途的导出按稳定 API 维护；过渡导出只供现有内部消费者迁移使用。
+ */
+export { EXTENSION_API_VERSION, defineExtension, defineElement, type EditorExtension, type ExtensionDefinition, type ElementSpec, type ElementEmptyContext, type ElementBehaviors, type ElementRenderProps, type ExtensionLayerProps, } from "./extension";
+export type { AnyExtension } from "./legacy";
+export type { CopyDecision, CopyContext, ElementCopy } from "./copy";
+export type { MarkSpec, MarkRenderProps, DecorationSpec } from "./marks";
+export { useToolbarState } from "./toolbar";
+export { default as ToolbarSubmenu } from "../components/HoveringToolbar/FloatingSubmenu";
+export { Tooltip as EditorTooltip } from "../ui/Tooltip";
+export { CaretRight as EditorCaretRight } from "../ui/CaretRight";
+export { getParagraphShortcutEntry } from "../utils/paragraphShortcut";
+export type { IngestContext, ElementIngestSpec } from "./ingest";
+export { CommandRegistry, createCommandDispatcher, type EditorCommand, type EditorCommandContext, type EditorHotkey, type RegisteredCommand, type CommandDispatcher, type CommandGuard, } from "./command";
+export { type EditorMenuEntry, type EditorMenuContext, type EditorMenuContribution, type MenuValue, } from "./menu";
+export { createServiceId, IThemeService, IExtensionErrorReporter, IEditorNotifier, type ServiceIdentifier, } from "../services/tokens";
+export { useService, useOptionalService, useNotifier } from "../services/hooks";
+export { notifierOf } from "../services/editorNotifier";
+export type { EditorNotifier, EditorFeedback, EditorLoadingHandle, EditorConfirmOptions, EditorPromptOptions, } from "../services/notifier";
+export { useEditorTheme, type EditorTheme } from "../theme/context";
+export type { ThemeService, EditorThemeMode } from "../theme/ThemeService";
+export type { IBlockPanelListItem, IConfigItem } from "../types";
+export type { CustomElement, InlineElement, BlockElement } from "../types/custom-element";
+export { setOrInsertNode, canSetOrInsertNode, focusInsertedPreviewElement, } from "../utils/insertElement";
+export { default as ElementMenu, type ElementMenuProps } from "../components/ElementMenu/index";
+export { default as InlineChromiumBugfix } from "../components/InlineChromiumBugFix/index";
+export { default as useIsLastElement } from "../hooks/useIsLastElement";
+export { registerBlockNavigation, hasBlockNavigation, unregisterBlockNavigation, focusPreviousBlock, focusNextBlock, type BlockNavigationHandler, } from "../utils/blockNavigation";
+export { isCollapsed, getCurrentTextNode } from "../utils/editor";
+export { deleteVoidBlock } from "../utils/nodeOperations";
+export { getSelectionSnapshot, isSelectionSnapshotUnchanged } from "../utils/selectionSnapshot";
+export { createParagraph, isParagraphElement, type ParagraphElement } from "../model/paragraph";
+export { insertParagraphAndFocus } from "../utils/editor";
+export { isAtParagraphStart, isParagraphAndEmpty } from "../utils/editor";
+export { isNodeEmpty } from "../kit/elementEmpty";
+export { createBlockConversionMenu } from "../menu/conversion";
+export { getCommandElementPath } from "../utils/commandTarget";
+export { captureEditorSubmission, captureElementSubmission, captureInsertionSubmission, type Submission, type SubmissionOutcome, type SubmissionDiscardReason, } from "./submission";
+export { default as AddParagraph, type AddParagraphRef } from "../components/AddParagraph/index";
+export { IOverlayBackDismiss, type OverlayBackDismissProps, type OverlayBackDismissAdapter, } from "../services/overlayBackDismiss";
+export { default as OverlayBackDismiss } from "../components/OverlayBackDismiss/index";
+export { getElementParent, getClosestCurrentElement } from "../utils/editor";
+export { getParentNodeByNode, getPreviousSiblingNode } from "../utils/element";
+export { getPrevPath } from "../utils/path";
+export { hitEmptyOrInlineChild, exitContainerOnEmptyParagraph } from "../utils/container";
+export { replaceNode } from "../utils/editor";
+export { findPathSafely } from "../utils/path";
+export type { Plugin } from "../utils/plugin";
+export { BLOCK_DRAG_GROUP, DragHandle, type DragHandleProps } from "../components/BlockDrag/index";
+export { panAroundAnchor, pointFromCenter, type Point as ZoomPanPoint } from "../utils/zoomPan";
+export { FloatingToolbar, ToolbarDivider, ToolbarIconButton } from "../components/FloatingToolbar/index";

package/types/packages/editor/src/api/ingest.d.ts

@@ -0,0 +1,39 @@
+import type { Editor, Point } from "slate";
+/**
+ * 内容注入声明（01 §5.4）：drop 与 paste 归并为一条认领式管线（共同形状是 DataTransfer）。
+ * 扩展声明自己认领什么（files 的 MIME / text 的谓词），内核负责分桶、隔离与熔断；
+ * drop 与 paste 共用同一个 run，经 ctx.source 区分来源。
+ */
+export interface IngestContext {
+    editor: Editor;
+    /** 认领到的文件（files 侧）；drop 与 paste 都可能是多个 */
+    files?: readonly File[];
+    /** 原始剪贴板 / 拖拽数据（text 侧认领与兜底读取用） */
+    data: DataTransfer;
+    /** 拖放落点（source 为 drop 时有；粘贴跟随当前选区） */
+    point?: Point;
+    source: "drop" | "paste";
+}
+export interface IngestFilesRule {
+    /** MIME 认领（`image/*` 前缀通配或 `application/pdf` 精确）；完全相同 accept 重复声明建 kit 抛错 */
+    accept: string;
+    /** 认领到的整批文件一次处理；抛错按贡献扩展熔断 */
+    run: (ctx: IngestContext) => void | Promise<void>;
+}
+export interface IngestTextRule {
+    /** 文本侧认领谓词；求值在 markdown 导入之前 */
+    when: (data: DataTransfer) => boolean;
+    run: (ctx: IngestContext) => void | Promise<void>;
+}
+export interface ElementIngestSpec {
+    files?: IngestFilesRule;
+    text?: IngestTextRule;
+}
+/** 一个扩展的内容注入声明（装配产出的形态）；owner 用于隔离熔断与日志 */
+export interface IngestSource {
+    readonly owner: string;
+    readonly files?: IngestFilesRule;
+    readonly text?: IngestTextRule;
+}
+/** accept 匹配：`*` 全收、`type/*` 前缀、其余精确 */
+export declare const ingestAccepts: (accept: string, mimeType: string) => boolean;

package/types/packages/editor/src/api/legacy.d.ts

@@ -0,0 +1,10 @@
+import type { EditorExtension } from "./extension";
+/**
+ * kit 接受的扩展。旧 `IExtension` 适配层已随三端迁移完成而删除（2026-09-30，
+ * docs/editor-refactor DECISIONS）：所有扩展都是 defineExtension 的产物。
+ * `AnyExtension` 保留为 `EditorExtension` 的别名，等全仓标注自然更替后再收。
+ */
+export type AnyExtension = EditorExtension;
+export declare const toEditorExtension: (extension: AnyExtension) => EditorExtension;
+/** 扩展贡献的元素类型 */
+export declare const elementTypesOf: (extension: EditorExtension) => string[];

package/types/packages/editor/src/api/marks.d.ts

@@ -0,0 +1,35 @@
+import type { ComponentType, ReactNode } from "react";
+import type { Editor, NodeEntry, Range, Text } from "slate";
+export interface MarkRenderProps {
+    readonly leaf: Readonly<Text>;
+    children: ReactNode;
+}
+export interface MarkSpec {
+    id: string;
+    keys: readonly string[];
+    /** 只包装 children；Slate 属性及文本承载由核心持有。 */
+    render: ComponentType<MarkRenderProps>;
+    /**
+     * 非包含标记：光标落到这些标记的边缘时默认停在标记外侧（如行内代码）。
+     * 其余标记默认沿用光标左侧的格式；用户可用左右键切换偏向。
+     */
+    nonInclusiveKeys?: readonly string[];
+}
+export interface RegisteredMark {
+    readonly owner: string;
+    readonly spec: MarkSpec;
+}
+/**
+ * 暂态装饰：按节点算出带属性的 Range，属性只出现在渲染用的叶子上，不进文档、不被保存。
+ * 配合同一扩展声明的 MarkSpec（keys 取装饰属性名）渲染外观。与宿主的 decorate 合并执行。
+ */
+export interface DecorationSpec {
+    id: string;
+    decorate(editor: Editor, entry: NodeEntry): Range[];
+    /** 外部数据变化时使装饰重算，订阅随实例及服务作用域清理。 */
+    subscribe?(editor: Editor, invalidate: () => void): (() => void) | undefined;
+}
+export interface RegisteredDecoration {
+    readonly owner: string;
+    readonly spec: DecorationSpec;
+}

package/types/packages/editor/src/api/menu.d.ts

@@ -0,0 +1,37 @@
+import type { ReactNode } from "react";
+import type { Editor, Element, Path } from "slate";
+/**
+ * 菜单贡献点（01 §5.4）：手柄菜单与右键菜单统一的数据来源。
+ * 条目只引用命令 id（不写内联函数），执行、enablement 与熔断与热键共用命令注册表。
+ */
+/** 菜单声明的求值上下文：菜单针对的目标元素及其路径（打开时求一次） */
+export interface EditorMenuContext {
+    editor: Editor;
+    element: Element;
+    path: Path;
+}
+/** `T | ((ctx) => T)`：静态声明或打开菜单时求值（如「收起 / 展开」的动态标题） */
+export type MenuValue<T> = T | ((ctx: EditorMenuContext) => T);
+export interface EditorMenuEntry {
+    /** 条目 id，同一份菜单内唯一；内核默认条目直接用命令 id */
+    id: string;
+    title: MenuValue<string>;
+    icon?: MenuValue<ReactNode>;
+    /** 引用的命令 id；只有 `children` 的父条目可省 */
+    command?: string;
+    /** 命令的静态参数（如 `{ level: 2 }`），与目标元素一起进命令上下文 */
+    payload?: unknown;
+    /** `false` 时条目（连同 children）不出现：条目对目标元素的适用范围 */
+    when?: (ctx: EditorMenuContext) => boolean;
+    /** `false` 时灰显（enablement），打开菜单时求值 */
+    disabled?: (ctx: EditorMenuContext) => boolean;
+    /** 分组；缺省 `"actions"`（扩展特有条目）。组间画分隔线，组内按 `order` 与声明顺序 */
+    group?: string;
+    order?: number;
+    danger?: boolean;
+    children?: readonly EditorMenuEntry[];
+    /** 同名顶层无命令菜单均声明时合并子项；未声明仍整项覆盖。 */
+    mergeChildren?: boolean;
+}
+/** 扩展贡献的菜单：静态数组，或需要按 editor 求值的工厂（如过滤服务提供的动作） */
+export type EditorMenuContribution = readonly EditorMenuEntry[] | ((editor: Editor) => readonly EditorMenuEntry[]);

package/types/packages/editor/src/api/submission.d.ts

@@ -0,0 +1,38 @@
+import { Editor, Element, Path, type BaseRange } from "slate";
+import type { ServiceIdentifier } from "../services/tokens";
+interface SubmissionOptions {
+    signal?: AbortSignal;
+    /** 只跟踪本操作依赖的服务；无关主题或插槽派生不取消操作。 */
+    services?: readonly ServiceIdentifier<unknown>[];
+}
+export type SubmissionDiscardReason = "cancelled" | "scope-ended" | "readonly" | "target-lost" | "target-changed";
+export type SubmissionOutcome = {
+    status: "committed";
+} | {
+    status: "discarded";
+    reason: SubmissionDiscardReason;
+};
+export interface Submission<T> {
+    readonly signal: AbortSignal;
+    /** 失效时终结操作并释放引用；不能放进要求纯判断的表单 validate。 */
+    check(): SubmissionDiscardReason | undefined;
+    /** 只提交一次；回调必须同步，异常向上传播，不能依赖事务回滚。 */
+    commit(write: (target: T) => undefined): SubmissionOutcome;
+    dispose(): void;
+}
+/** 无元素目标的输入请求只绑定编辑会话和调用方取消信号。 */
+export declare const captureEditorSubmission: (editor: Editor, options?: SubmissionOptions) => Submission<void>;
+export declare function captureElementSubmission<E extends Element>(editor: Editor, options: SubmissionOptions & {
+    element: E;
+    path?: Path;
+    accept?: (current: E) => boolean;
+}): Submission<{
+    element: E;
+    path: Path;
+}>;
+/** 段落内的原始折叠落点；后续选区变化不会改写该落点。 */
+export declare function captureInsertionSubmission(editor: Editor, signal?: AbortSignal): Submission<{
+    range: BaseRange;
+    path: Path;
+}>;
+export {};

package/types/packages/editor/src/api/toolbar.d.ts

@@ -0,0 +1,3 @@
+import { type IHoveringBarContext } from "../components/HoveringToolbar/context";
+/** 工具条贡献读取当前展示状态，不取得 Provider 或内部可写状态。 */
+export declare function useToolbarState(): Readonly<IHoveringBarContext>;

package/types/packages/editor/src/components/AddParagraph/index.d.ts

@@ -0,0 +1,11 @@
+import React from "react";
+import type { Element } from "slate";
+interface IAddParagraphProps {
+    element: Element;
+    onAddParagraph?: () => void;
+}
+export interface AddParagraphRef {
+    addParagraph: () => void;
+}
+declare const AddParagraph: React.ForwardRefExoticComponent<IAddParagraphProps & React.RefAttributes<AddParagraphRef>>;
+export default AddParagraph;

package/types/packages/editor/src/components/BlockDrag/index.d.ts

@@ -0,0 +1,35 @@
+import type { ComponentType, MouseEvent, ReactNode, Ref } from "react";
+/**
+ * 块的拖拽手柄与放置指示，所有块共用。
+ *
+ * 显示逻辑按块隔离：块的外层容器加 `BLOCK_DRAG_GROUP`，带 `data-block-reveal` 的元素（手柄、标题折叠箭头）
+ * 只在**最内层**被悬停的块里出现，规则见 `theme/editor.css`。
+ * 不用 Tailwind 命名 group：`group-hover/x` 匹配的是「任意同名祖先被悬停」，嵌套块会一起亮。
+ */
+export declare const BLOCK_DRAG_GROUP = "ed-block";
+export interface DragHandleProps {
+    /** useDragAndDrop 返回的 drag 连接器 */
+    dragRef: Ref<HTMLDivElement> | ((node: HTMLDivElement | null) => void);
+    canDrag: boolean;
+    onClick?: (event: MouseEvent) => void;
+    /** 位置微调（经 cn 合并，可覆盖 top / left / height） */
+    className?: string;
+    /** 手柄图标；传 null 渲染无图标的热区 */
+    icon?: ComponentType<{
+        className?: string;
+    }> | null;
+    iconClassName?: string;
+}
+export declare function DragHandle({ dragRef, canDrag, onClick, className, icon: Icon, iconClassName, }: DragHandleProps): import("react/jsx-runtime").JSX.Element;
+export interface DropIndicatorProps {
+    /** 当前是否有可放置的拖拽经过本块 */
+    active: boolean;
+    /** 插入到本块之前（上方）还是之后（下方） */
+    before: boolean;
+    /** 位置微调（经 cn 合并，可覆盖 top / bottom） */
+    className?: string;
+}
+/** 拖拽经过时的 accent 插入线；父元素需 position: relative */
+export declare function DropIndicator({ active, before, className }: DropIndicatorProps): ReactNode;
+/** 拖拽源 / 放置目标的半透明（原 .dragging / .drop 的 opacity: 0.5） */
+export declare const dimWhileDragging: (dragging: boolean) => "opacity-50" | undefined;

package/types/packages/editor/src/components/ElementMenu/index.d.ts

@@ -0,0 +1,11 @@
+import type { Element } from "slate";
+export interface ElementMenuProps {
+    element: Element;
+    position: {
+        x: number;
+        y: number;
+    };
+    onClose: () => void;
+}
+/** 在指定位置打开目标元素已注册的菜单，不接受绕过命令协议的条目。 */
+export default function ElementMenu({ element, position, onClose }: ElementMenuProps): import("react/jsx-runtime").JSX.Element;

package/types/packages/editor/src/components/FloatingToolbar/index.d.ts

@@ -0,0 +1,23 @@
+import type { ReactNode } from "react";
+import type { LucideIcon } from "lucide-react";
+/**
+ * 块右上角的悬浮操作条（代码块、源码预览块共用）：浅色实底 + 描边 + 浮起投影，随主题。
+ * 显隐交给调用方的 group-hover 类（Tailwind 需要静态类名），例如
+ * `group-hover/code:pointer-events-auto group-hover/code:translate-y-0 group-hover/code:opacity-100`。
+ * 定位取 min(右上角, 垂直居中)：块较矮（如单行）时居中，较高时贴右上角。
+ */
+export declare const FloatingToolbar: ({ className, children, }: {
+    className?: string;
+    children: ReactNode;
+}) => import("react/jsx-runtime").JSX.Element;
+export declare const ToolbarDivider: () => import("react/jsx-runtime").JSX.Element;
+export declare const ToolbarIconButton: ({ icon: Icon, title, onClick, disabled, tone, active, className, }: {
+    icon: LucideIcon;
+    title: string;
+    onClick?: () => void;
+    disabled?: boolean;
+    tone?: "default" | "danger" | "ok";
+    /** 按下态（开关类按钮） */
+    active?: boolean;
+    className?: string;
+}) => import("react/jsx-runtime").JSX.Element;

package/types/packages/editor/src/components/HoveringToolbar/FloatingSubmenu.d.ts

@@ -0,0 +1,19 @@
+import React from "react";
+import type { HoveringSubmenuTrigger } from "./context";
+import { type FloatingPlacement } from "./floatingPosition";
+interface FloatingSubmenuProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    trigger: HoveringSubmenuTrigger;
+    isHoveringBarShow: boolean;
+    children: React.ReactNode;
+    content: React.ReactNode;
+    preferredPlacement?: FloatingPlacement;
+    gap?: number;
+    zIndex?: number;
+    triggerClassName?: string;
+    panelClassName?: string;
+    panelStyle?: React.CSSProperties;
+}
+declare const FloatingSubmenu: (props: FloatingSubmenuProps) => import("react/jsx-runtime").JSX.Element;
+export default FloatingSubmenu;

package/types/packages/editor/src/components/HoveringToolbar/context.d.ts

@@ -0,0 +1,8 @@
+import React from "react";
+export type HoveringSubmenuTrigger = "hover" | "click";
+export interface IHoveringBarContext {
+    isHoveringBarShow: boolean;
+    isCompact: boolean;
+    submenuTrigger: HoveringSubmenuTrigger;
+}
+export declare const HoveringBarContext: React.Context<IHoveringBarContext>;