@xiongtao.xt/tau-plugins 0.31.1 → 0.33.0

package/docs/whiteboard.md

@@ -0,0 +1,290 @@
+# 白板扩展
+
+白板扩展让你在 Tau 的白板上添加自己的元素（如图形、图表、组件），以及创建它们的工具。白板扩展分为两部分：
+
+- **元素**：静态声明，描述元素长什么样、能怎么交互。没有打开任何画布时，Tau 也需要读取这些声明，例如生成预览图。
+- **交互贡献**：每块画布单独创建，提供工具、命令、属性面板、快捷键等。
+
+## 第一个元素：方块
+
+### 1. 在 manifest 中声明
+
+```json
+{
+  "whiteboard": true
+}
+```
+
+### 2. 定义扩展
+
+```tsx
+import { definePlugin } from "@tau/plugins";
+import { defineElement, defineWhiteboardExtension } from "@tau/plugins/whiteboard";
+
+declare const __PLUGIN_META__: { id: string; name: string; version: string };
+
+const BOX = `${__PLUGIN_META__.id}.box`;
+
+function BoxIcon({ className }: { className?: string }) {
+  return (
+    <svg
+      className={className}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+    >
+      <rect x="3" y="5" width="18" height="14" rx="2" />
+    </svg>
+  );
+}
+
+const boxExtension = defineWhiteboardExtension({
+  id: __PLUGIN_META__.id,
+  // 元素：静态声明
+  elements: [
+    defineElement({
+      type: BOX,
+      presentation: { label: "方块", icon: BoxIcon },
+      render: ({ element }) => (
+        <rect
+          x={element.x}
+          y={element.y}
+          width={element.width}
+          height={element.height}
+          rx={8}
+          fill="var(--tau-accent-soft)"
+          stroke="var(--tau-accent)"
+        />
+      ),
+      create: {
+        gesture: "drag",
+        defaultSize: [160, 90],
+        build: ({ rect }) => ({ id: crypto.randomUUID(), type: BOX, ...rect, data: {} }),
+      },
+    }),
+  ],
+  // 交互贡献：每块画布调用一次
+  create: () => ({
+    tools: [
+      {
+        id: `${__PLUGIN_META__.id}.box-tool`,
+        label: "方块",
+        icon: BoxIcon,
+        element: BOX,
+        group: "drawing",
+        order: 90,
+      },
+    ],
+  }),
+});
+
+export default definePlugin({ ...__PLUGIN_META__, whiteboardExtensions: [boxExtension] });
+```
+
+### 3. 构建、安装、重启
+
+白板扩展在 Tau 启动时装配，启用、停用和更新都要**完全退出并重新打开 Tau** 才生效。之后打开白板，在「扩展工具」菜单中就能找到「方块」。
+
+## 命名规则
+
+- 扩展 `id` 是你的插件 ID，或以插件 ID 加点开头（如 `yourname.shapes.box`）。
+- 元素 `type` 必须以插件 ID 加点开头（如 `yourname.shapes.box`）。
+- 工具、命令的 `id` 同样以插件 ID 作前缀。
+
+已经有白板用了某个元素类型，就不要再改名，否则已有的元素会显示为未知元素。
+
+## 元素
+
+元素的通用字段（`id`、`type`、`x`、`y`、`width`、`height` 等）在元素顶层，你自己的数据放在 `data` 里。
+
+### 元素声明
+
+| 字段                       | 说明                                                                                 |
+| -------------------------- | ------------------------------------------------------------------------------------ |
+| `type`                     | 元素类型                                                                             |
+| `render`                   | 渲染组件，收到 `element`，返回 SVG 内容                                              |
+| `presentation`             | 可选。`label`（类型名）、`icon`（图标）、`getName(element)`（列表中显示的名称）      |
+| `create`                   | 可选。创建方式，声明后才能注册创建型工具，见[创建工具](#创建工具)                    |
+| `interaction`              | 可选。缩放手柄与连接点，见下文                                                       |
+| `schema`                   | 可选。约束 `data` 结构的 [Standard Schema](https://standardschema.dev)，必须同步校验 |
+| `schemaVersion`、`migrate` | 可选。`data` 结构的版本号，以及从旧版本逐步升级的迁移函数                            |
+| `sketch`                   | 可选。为 `true` 时元素支持手绘画风，见[手绘画风](#手绘画风)                          |
+| `schematic`                | 可选。简略预览，见[简略预览](#简略预览)                                              |
+
+用 `defineElement<TData>` 声明 `data` 的类型，或者传入 `schema` 让类型自动推断：
+
+```ts
+interface StickyData {
+  text: string;
+}
+
+defineElement<StickyData>({
+  type: `${__PLUGIN_META__.id}.sticky`,
+  render: ({ element }) => <text x={element.x} y={element.y}>{element.data.text}</text>,
+});
+```
+
+### 缩放与连接
+
+```ts
+interaction: {
+  resize: { handles: "corners", preserveAspectRatio: true },
+  connect: "rect",
+},
+```
+
+- `resize.handles` 可选 `corners`（只有四角）或 `all`（默认，四角加四边）。`preserveAspectRatio` 默认 `false`，用户按住 Shift 时仍可等比缩放。
+- 缩放手柄、吸附、撤销都由 Tau 处理，不要在元素里自己画缩放手柄。
+- `connect: "rect"` 让元素有矩形连接点，可以用连线连接。不声明就没有连接点。
+
+### 显示名称
+
+`presentation.getName(element)` 返回元素在列表中显示的名称，例如便签显示它的文字。用户手动起的名字优先；返回空时显示 `label`。
+
+### 版本迁移
+
+`data` 的结构需要变化时，提高 `schemaVersion`，并在 `migrate` 中提供每一步升级：
+
+```ts
+schemaVersion: 2,
+migrate: {
+  // 从版本 1 升到版本 2
+  1: element => ({ ...element, data: { ...element.data, color: "accent" } }),
+},
+```
+
+`migrate` 必须覆盖从 1 到当前版本的每一步。
+
+## 创建工具
+
+### 创建型工具
+
+元素声明了 `create` 后，注册一个 `element` 指向它的工具，用户就能在画布上用手势创建元素。
+
+| `create` 字段 | 说明                                                                                                     |
+| ------------- | -------------------------------------------------------------------------------------------------------- |
+| `gesture`     | `"click"`（点击放置）或 `"drag"`（拖拽绘制）                                                             |
+| `build`       | 根据手势生成元素，收到 `rect`、`start`、`end`、`click`、`options` 等，返回 `null` 则不创建；可以是异步的 |
+| `defaultSize` | `click` 时必填，元素的默认尺寸；`drag` 时用于单击创建                                                    |
+| `minSize`     | 可选。`drag` 绘制的尺寸小于它时不创建                                                                    |
+| `constrain`   | 可选。`drag` 时按 Shift 的约束：`box`（等比，默认）或 `line`（45° 吸附）                                 |
+| `after`       | 可选。创建后 `select`（选中，默认）、`edit`（进入编辑）或 `none`                                         |
+| `stay`        | 可选。为 `true` 时创建后保持当前工具，可以连续创建                                                       |
+| `hint`        | 可选。工具激活时画布底部的提示文字                                                                       |
+
+### 工具
+
+| 工具字段         | 说明                                                   |
+| ---------------- | ------------------------------------------------------ |
+| `id`             | 工具 ID                                                |
+| `label`          | 名称，显示在菜单和提示中                               |
+| `icon`           | 图标组件                                               |
+| `element`        | 创建型工具：要创建的元素类型（与 `command` 二选一）    |
+| `command`        | 命令型工具：点击时执行的命令 ID（与 `element` 二选一） |
+| `group`、`order` | 分组与排序                                             |
+| `panel`          | 可选。参数面板，见下文                                 |
+
+插件的工具统一放在工具栏的「扩展工具」菜单里。
+
+### 创建前选择参数
+
+工具可以提供 `panel`，让用户先选好参数再执行：
+
+```tsx
+panel: ({ run }) => (
+  <div>
+    <button onClick={() => run({ color: "accent" })}>强调色</button>
+    <button onClick={() => run({ color: "neutral" })}>中性色</button>
+  </div>
+),
+```
+
+- 创建型工具在 `create.build` 的 `options` 中读到 `run` 传入的参数；命令型工具在命令的 `payload` 中读到。
+- 返回、关闭和面板卸载由 Tau 管理，`run` 执行后面板自动关闭。不要在面板里自己监听画布的指针事件。
+
+## 交互贡献
+
+`create(api)` 在每块画布上调用一次，返回这块画布上的交互贡献：
+
+| 字段         | 说明                                                                                                     |
+| ------------ | -------------------------------------------------------------------------------------------------------- |
+| `tools`      | 工具                                                                                                     |
+| `commands`   | 命令：`{ id, execute(api, payload), enabled?(api) }`                                                     |
+| `hotkeys`    | 快捷键：`{ key, command }`，键串格式如 `"mod+shift+b"`                                                   |
+| `menus`      | 菜单项：`{ id, label, command, order, when? }`                                                           |
+| `inspectors` | 属性面板：`{ [元素类型]: 组件 }`。选中单个该类型元素时显示在浮动属性栏，组件收到 `element` 和 `onChange` |
+| `activate`   | 可选。画布显示时调用，返回的清理函数在画布隐藏时执行                                                     |
+| `dispose`    | 可选。画布销毁时调用                                                                                     |
+
+- 每块画布的状态放在 `create` 的闭包里，不要放在模块顶层，否则会在多块画布之间共享。
+- `elements` 必须写在扩展顶层，不能放进 `create` 的返回值。
+- `mod+k`、`mod+p`、`mod+j`、Alt+方向键和 Esc 由 Tau 保留，不能声明。
+
+### 修改画布
+
+通过 `api` 修改画布，不要直接修改读到的元素对象：
+
+| 方法                                      | 用途                                           |
+| ----------------------------------------- | ---------------------------------------------- |
+| `api.updateElement(id, patch)`            | 修改一个元素的属性                             |
+| `api.submit(operations)`                  | 提交一组结构性操作（增删元素等），作为一步撤销 |
+| `api.select(ids)`                         | 设置选区                                       |
+| `api.getElement(id)`、`api.getSnapshot()` | 读取元素与画布快照                             |
+| `api.setActiveTool(id)`                   | 切换当前工具                                   |
+| `api.readonly`                            | 画布是否只读                                   |
+
+这些方法统一处理只读、撤销和生命周期。元素组件中可以用 `useWhiteboardAPI()` 拿到所属扩展的 `api`。
+
+## 手绘画风
+
+声明 `sketch: true` 后，元素可以跟随白板的手绘画风设置：
+
+- 在元素组件中调用 `useSketch(element)`，得到 `enabled`、`level`、`seed`，据此决定怎么绘制。页面画风变化时组件会自动更新。
+- `SketchPaths` 渲染手绘路径；`sketch` 命名空间提供手绘算法（`wobble`、`resample`、`inkOutline` 等），直接复用，不要自己复制实现。
+- `usePageSketch()` 读取所在页面的画风；`sketch.hashSeed(text)` 为预览生成稳定的随机种子。
+- 属性面板可以使用 `AttrPopover`、`AttrToggle`、`OptionGrid`、`Seg` 组件，`SketchPopover` 提供与 Tau 一致的笔触设置。
+
+## 简略预览
+
+`schematic(element, { dark })` 返回一组简单图元（矩形、路径等，类型见 `SchematicShape`），用于白板列表和导出弹窗里的缩略预览：
+
+```ts
+schematic: element => [
+  { kind: "rect", x: element.x, y: element.y, w: element.width, h: element.height, r: 3, fill: "var(--tau-accent)" },
+],
+```
+
+它必须是纯函数：只读元素数据，不调用 hook，也不依赖某块画布已经打开。真正导出图片时仍然使用完整的 `render`。
+
+## 记住用户的选择
+
+交互贡献需要保存用户偏好（如上次选的颜色）时，在扩展上声明依赖存储服务：
+
+```ts
+import { IPluginStorage, defineWhiteboardExtension } from "@tau/plugins/whiteboard";
+
+defineWhiteboardExtension({
+  id: __PLUGIN_META__.id,
+  requires: [IPluginStorage],
+  elements: [/* ... */],
+  create: api => {
+    const storage = api.getService(IPluginStorage);
+    // storage.get / set / delete，与 context.storage 相同
+    return { tools: [/* ... */] };
+  },
+});
+```
+
+- 存储按插件和工作区隔离，与 [`context.storage`](storage-and-network.md) 是同一份数据。
+- 只在交互贡献、工具面板、属性面板和 `create.build` 中使用。元素的 `render` 和 `schematic` 只能依据元素数据，不能读存储。
+- 读取失败时不要当成空数据再写回，否则会覆盖用户原有的偏好。
+
+## 样式
+
+- 颜色使用 Tau 的主题变量（如 `var(--tau-accent)`），这样会跟随明暗主题。
+- 需要 Tailwind 工具类时，可以导入 `@tau/plugins/tailwind.css`，它提供 Tau 语义类到主题变量的映射。
+
+## 停用与卸载
+
+插件停用或卸载后，白板里已有的元素会保留，显示为未知元素的占位；重新安装并启用后恢复显示。保存、复制白板时也会保留这些元素的数据。

package/package.js

@@ -14,7 +14,7 @@ import {
   isPluginPermission,
   validateBackendManifest,
   validatePluginManifest
-} from "./client/chunk-ECEBBIHP.js";
+} from "./client/chunk-SVY5LBAT.js";
 export {
   PLUGIN_AI_CAPABILITIES,
   PLUGIN_CATEGORIES,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiongtao.xt/tau-plugins",
-  "version": "0.31.1",
+  "version": "0.33.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/publish-artifacts.js

@@ -1,7 +1,37 @@
 import {
   PLUGIN_SHARED_MODULES,
   validatePluginManifest
-} from "./client/chunk-ECEBBIHP.js";
+} from "./client/chunk-SVY5LBAT.js";
+
+// packages/db-schema/content-resources.ts
+var CONTENT_RESOURCE_KINDS = [
+  "image",
+  "video",
+  "audio",
+  "file"
+];
+var UNSAFE_SEGMENTS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+var SEGMENT = /^[A-Za-z_$][\w$-]*(\[\])?$/;
+var FIELD = /^[A-Za-z_$][\w$-]*$/;
+var MAX_SPECS = 16;
+var MAX_PATH_LENGTH = 128;
+var isField = (value) => typeof value === "string" && FIELD.test(value) && !UNSAFE_SEGMENTS.has(value);
+function isValidPath(path) {
+  if (typeof path !== "string" || !path || path.length > MAX_PATH_LENGTH) return false;
+  const parts = path.split(".");
+  return parts.every(
+    (part, index) => SEGMENT.test(part) && !UNSAFE_SEGMENTS.has(part.replace(/\[\]$/, "")) && (index < parts.length - 1 || !part.endsWith("[]"))
+  );
+}
+function isContentResourceSpec(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const spec = value;
+  return isValidPath(spec.path) && CONTENT_RESOURCE_KINDS.includes(spec.kind) && ["preview", "alt", "caption"].every((key) => spec[key] === void 0 || isField(spec[key])) && Object.keys(spec).every((key) => ["path", "kind", "preview", "alt", "caption"].includes(key));
+}
+function assertContentResourceSpecs(value) {
+  if (!Array.isArray(value) || value.length > MAX_SPECS || !value.every(isContentResourceSpec))
+    throw new Error("\u8D44\u6E90\u58F0\u660E\u65E0\u6548");
+}
 
 // packages/plugins/src/rendering.ts
 var PLUGIN_RENDER_VERSION = 1;
@@ -49,6 +79,13 @@ function getPluginNodeTypes(definition) {
     for (const element of extension.elements ?? []) {
       if (!element.type || types.includes(element.type))
         throw new Error(`\u63D2\u4EF6\u8282\u70B9\u7C7B\u578B\u4E3A\u7A7A\u6216\u91CD\u590D\uFF1A${element.type}`);
+      if (element.resources !== void 0) {
+        try {
+          assertContentResourceSpecs(element.resources);
+        } catch {
+          throw new Error(`\u63D2\u4EF6\u8282\u70B9\u8D44\u6E90\u58F0\u660E\u65E0\u6548\uFF1A${element.type}`);
+        }
+      }
       types.push(element.type);
     }
   }

package/types/packages/db-schema/content-resources.d.ts

@@ -0,0 +1,76 @@
+export type ContentResourceKind = "image" | "video" | "audio" | "file";
+export declare const CONTENT_RESOURCE_KINDS: readonly ContentResourceKind[];
+export interface ContentResourceSpec {
+    /** 字段路径：`url`、`images[].url`；`[]` 表示数组的每一项 */
+    path: string;
+    kind: ContentResourceKind;
+    /** 同一资源的显示版本（如裁剪结果），与 path 末段同层的字段名，同样参与上传与改写 */
+    preview?: string;
+    /** 替代文字字段，与 path 末段同层 */
+    alt?: string;
+    /** 说明文字字段，与 path 末段同层 */
+    caption?: string;
+}
+/** 节点类型 → 资源字段 */
+export type ContentResourceDeclarations = Readonly<Record<string, readonly ContentResourceSpec[]>>;
+/** 宿主内置节点的资源字段 */
+export declare const BUILTIN_CONTENT_RESOURCES: {
+    readonly image: readonly [{
+        readonly path: "url";
+        readonly kind: "image";
+        readonly preview: "previewUrl";
+        readonly alt: "alt";
+        readonly caption: "description";
+    }];
+    readonly "inline-image": readonly [{
+        readonly path: "url";
+        readonly kind: "image";
+        readonly alt: "alt";
+    }];
+    readonly audio: readonly [{
+        readonly path: "src";
+        readonly kind: "audio";
+    }];
+    readonly video: readonly [{
+        readonly path: "src";
+        readonly kind: "video";
+    }];
+    readonly "file-attachment": readonly [{
+        readonly path: "filePath";
+        readonly kind: "file";
+    }, {
+        readonly path: "localFilePath";
+        readonly kind: "file";
+    }];
+};
+export declare function isContentResourceSpec(value: unknown): value is ContentResourceSpec;
+/** 校验来自插件或其他设备的声明；形状不对时抛错 */
+export declare function assertContentResourceSpecs(value: unknown): asserts value is readonly ContentResourceSpec[];
+/** 合并多份声明，后者覆盖同类型的前者 */
+export declare function mergeContentResources(...sources: readonly ContentResourceDeclarations[]): ContentResourceDeclarations;
+/** 资源所在的对象（字段的父对象）及字段名 */
+export interface ContentResourceSlot {
+    spec: ContentResourceSpec;
+    owner: Record<string, unknown>;
+    field: string;
+}
+/** 按声明列出一个节点里的资源位置（不深入子节点） */
+export declare function contentResourceSlots(node: unknown, specs: readonly ContentResourceSpec[] | undefined): ContentResourceSlot[];
+/** 资源位置上实际的地址：主地址与显示版本，空串跳过 */
+export declare function contentResourceValues(slot: ContentResourceSlot): string[];
+export interface ContentResourceEntry {
+    node: Record<string, unknown>;
+    slot: ContentResourceSlot;
+}
+/** 按文档顺序遍历节点树里所有声明了资源的位置 */
+export declare function forEachContentResource(nodes: readonly unknown[], declarations: ContentResourceDeclarations, visit: (entry: ContentResourceEntry) => void): void;
+/** 收集节点树里的资源地址（去重，保持首次出现的顺序） */
+export declare function collectContentResources(nodes: readonly unknown[], declarations: ContentResourceDeclarations): {
+    url: string;
+    kind: ContentResourceKind;
+}[];
+export type ContentResourceMapper = (url: string, kind: ContentResourceKind) => string | undefined;
+/** 不可变地改写一个节点里声明的资源（不深入子节点）；返回 undefined 表示保留原值 */
+export declare function mapNodeResources<T>(node: T, specs: readonly ContentResourceSpec[] | undefined, mapper: ContentResourceMapper): T;
+/** 不可变地改写整棵节点树里声明的资源 */
+export declare function mapContentResources<T>(nodes: readonly T[], declarations: ContentResourceDeclarations, mapper: ContentResourceMapper): T[];

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

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

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

@@ -1,4 +1,4 @@
-import type { ReactNode, ReactElement } from "react";
+import type { MouseEvent, ReactNode, ReactElement } from "react";
 import type { LucideIcon } from "lucide-react";
 import type { Editor, Element, Path } from "slate";
 import type { ElementBehaviors, ParagraphElement, BlockElement } from "./api";
@@ -35,6 +35,46 @@ export interface SourceEditorRuntime {
     insertSourceBlock(editor: Editor, element: BlockElement, line?: number): Path | undefined;
     sourceBlockParagraphBehavior(type: string): ElementBehaviors<ParagraphElement>;
 }
+export interface ElementAccess {
+    readOnly: boolean;
+    /** 外框里的块是否被点选；未声明外框时恒为 false */
+    selected: boolean;
+    /** 字段合并进节点，进入撤销记录并同步给协作者；只读、节点已被替换或卸载后不写入 */
+    update(properties: Record<string, unknown>): void;
+    remove(): void;
+    /** 选中外框里的块 */
+    select(): void;
+    /** 在指定位置打开块菜单；需要外框 */
+    openMenu(position: {
+        x: number;
+        y: number;
+    }): void;
+}
+export interface BlockToolbarProps {
+    /** 无障碍名称（如「画廊属性」） */
+    label: string;
+    className?: string;
+    children: ReactNode;
+}
+export interface BlockToolbarButtonProps {
+    /** 按钮名称：图标按钮的提示与无障碍名称 */
+    title: string;
+    shortcut?: string;
+    /** 显示在图标旁的文字（主操作用） */
+    label?: string;
+    icon?: ReactNode;
+    active?: boolean;
+    mono?: boolean;
+    onClick(event: MouseEvent<HTMLButtonElement>): void;
+}
+export interface ElementRuntime {
+    useElement(element: Element): ElementAccess;
+    /** 打开文档图片查看器，定位到该元素的第 index 个图片资源（按资源声明计） */
+    useMediaViewer(element: Element): (index?: number) => void;
+    BlockToolbar(props: BlockToolbarProps): ReactElement;
+    BlockToolbarButton(props: BlockToolbarButtonProps): ReactElement;
+    BlockToolbarGap(): ReactElement;
+}
 export interface InlineSourceRuntime {
     useInlineSource(element: Element): {
         readOnly: boolean;

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

@@ -9,6 +9,7 @@ import type { ElementDrag } from "./drag";
 import type { ElementIngestSpec } from "./ingest";
 import type { ElementCopy } from "./copy";
 import type { DecorationSpec, MarkSpec } from "./marks";
+import type { ContentResourceSpec } from "../../../../db-schema/content-resources";
 /**
  * 扩展 API v2（01 §5.1）：声明式描述「这个扩展贡献了什么」，内核负责装配、隔离与分发。
  * 所有扩展都是 defineExtension 的产物（旧 IExtension 适配层已删除，ER-019）。
@@ -35,6 +36,16 @@ export interface ElementEmptyContext {
     /** 使用当前编辑器已安装的声明判断子节点；未知或失败时保留。 */
     isEmpty(node: Descendant): boolean;
 }
+/**
+ * void 块的公共外框：点选描边、右键菜单、选中时 Delete / Backspace 删除与 Escape 取消、末尾「添加段落」。
+ * 声明后 render 只渲染内容（收到的 attributes 为空对象、children 为 null）。
+ */
+export interface ElementFrame {
+    /** 末尾的「添加段落」，默认显示 */
+    appendParagraph?: boolean;
+    /** 选中时的按键 → 命令 id（如 `{ Enter: "yourname.gallery.edit" }`），命令收到该元素 */
+    keys?: Readonly<Record<string, string>>;
+}
 export interface ElementSpec<E extends Element = Element> {
     /** 元素 type；内置类型沿用现有名字，兼容已有文档 */
     type: string;
@@ -53,6 +64,10 @@ export interface ElementSpec<E extends Element = Element> {
     drag?: ElementDrag;
     /** 内容注入声明（01 §5.4）：drop 与 paste 共用的认领规则；块组件不再改写 insertData */
     ingest?: ElementIngestSpec;
+    /** 节点里的资源字段：导出打包、协作上传、灯箱等只按它找图片、视频、音频与文件 */
+    resources?: readonly ContentResourceSpec[];
+    /** void 块的公共外框；只适用于 `kind: "block"` 且 `isVoid` 的元素 */
+    frame?: boolean | ElementFrame;
 }
 export interface ExtensionLayerProps {
     /** 根 UI 在 Editable 外，不能通过 Slate 的 useReadOnly 读取此状态。 */

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

@@ -4,7 +4,7 @@
  * 只放写扩展需要的东西：声明、服务、主题、少量工具。编辑器组件、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 { EXTENSION_API_VERSION, defineExtension, defineElement, type EditorExtension, type ExtensionDefinition, type ElementSpec, type ElementFrame, 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";
@@ -14,6 +14,10 @@ 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 { getElementResources } from "./resources";
+export { ELEMENT_SELECTED_OUTLINE_CLASS, useElementFrame, type ElementFrameState, } from "../components/ElementFrame/index";
+export { isOverlayTarget, isTextTarget, shouldIgnoreBlockKey } from "../utils/blockKeyTarget";
+export type { ContentResourceSpec, ContentResourceKind, ContentResourceDeclarations, } from "../../../../db-schema/content-resources";
 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";

package/types/packages/editor/src/core/api/resources.d.ts

@@ -0,0 +1,6 @@
+import type { Editor } from "slate";
+import type { ContentResourceDeclarations } from "../../../../db-schema/content-resources";
+/** 内核在创建编辑器时绑定当前装配的资源声明 */
+export declare function bindElementResources(editor: Editor, resources: ContentResourceDeclarations): void;
+/** 当前编辑器已安装的节点资源声明（节点类型 → 资源字段） */
+export declare function getElementResources(editor: Editor): ContentResourceDeclarations;

package/types/packages/editor/src/core/components/ElementFrame/index.d.ts

@@ -0,0 +1,25 @@
+import { type ReactNode } from "react";
+import { type RenderElementProps } from "slate-react";
+import type { ElementFrame as ElementFrameOptions } from "../../api/extension";
+/** 选中描边：外扩 3px，随内容圆角 */
+export declare const ELEMENT_SELECTED_OUTLINE_CLASS = "outline-solid outline-2 outline-offset-[3px] outline-[var(--ed-accent)]";
+export interface ElementFrameState {
+    selected: boolean;
+    select(): void;
+    deselect(): void;
+    /** 在指定位置打开块菜单（与右键、块手柄同一份条目） */
+    openMenu(position: {
+        x: number;
+        y: number;
+    }): void;
+}
+/** 外框里的块读取选中与菜单状态；不在外框里时为 null */
+export declare const useElementFrame: () => ElementFrameState | null;
+/**
+ * void 块的公共外框：点选与选中描边、右键菜单、选中时的删除与声明的按键、末尾「添加段落」。
+ * 块的 render 只渲染内容，attributes 与 children 由外框处理。
+ */
+export declare function ElementFrame({ attributes, element, children, options, content, }: RenderElementProps & {
+    options: ElementFrameOptions;
+    content: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;

package/types/packages/editor/src/core/utils/blockKeyTarget.d.ts

@@ -0,0 +1,9 @@
+/** 按键目标是文本输入（input / textarea / 可编辑区）：块级快捷键不拦截 */
+export declare const isTextTarget: (target: EventTarget | null) => boolean;
+/** 按键目标在浮层里（灯箱、裁剪编辑器、对话框）：交给浮层自己处理 */
+export declare const isOverlayTarget: (target: EventTarget | null) => boolean;
+/**
+ * 选中媒体块时的块级快捷键是否应忽略这次按键：输入法组合、浮层内、文本输入（如说明框）都不处理。
+ * 点选块后焦点通常留在外层编辑器根上——它包含这个块，不算文本输入，快捷键照常生效。
+ */
+export declare function shouldIgnoreBlockKey(event: KeyboardEvent, block: HTMLElement | null): boolean;

package/types/packages/plugins/src/categories.d.ts

@@ -20,6 +20,9 @@ export declare const PLUGIN_CATEGORIES: readonly [{
 }, {
     readonly id: "ai";
     readonly label: "AI";
+}, {
+    readonly id: "skill";
+    readonly label: "Skill";
 }, {
     readonly id: "voice";
     readonly label: "语音";

package/types/packages/plugins/src/contract.d.ts

@@ -1,5 +1,4 @@
 import type { PluginPages } from "./pages";
-import type { PluginSkill } from "./skills";
 import type { PluginAI, PluginAIFeature } from "./ai";
 import type { WhiteboardExtension } from "./whiteboard";
 import type { PluginServices } from "./services";
@@ -97,7 +96,6 @@ export interface PluginDefinition {
     readonly editorExtensions?: readonly PluginEditorExtension[];
     readonly whiteboardExtensions?: readonly WhiteboardExtension[];
     readonly editorCodecs?: readonly MarkdownCodec[];
-    readonly skills?: readonly PluginSkill[];
     readonly ai?: {
         readonly features: readonly PluginAIFeature[];
     };

package/types/packages/plugins/src/editor.d.ts

@@ -4,6 +4,7 @@ import type { Disposable } from "./index";
 export { defineElement as defineEditorElement } from "../../editor/contracts";
 export type { ElementRenderProps as EditorElementRenderProps } from "../../editor/contracts";
 export type { MarkdownCodec as EditorMarkdownCodec } from "../../markdown/src/index";
+export type { ContentResourceSpec as EditorResourceSpec, ContentResourceKind as EditorResourceKind, } from "../../db-schema/content-resources";
 /** 作者通过模块增强登记自定义节点，无需引用编辑器内部包。 */
 declare const elementMapBrand: unique symbol;
 declare const inlineMapBrand: unique symbol;

package/types/packages/plugins/src/element.d.ts

@@ -0,0 +1,11 @@
+import type { ElementRuntime } from "../../editor/source-contracts";
+export type { ElementAccess, BlockToolbarProps, BlockToolbarButtonProps, ElementRuntime, } from "../../editor/source-contracts";
+export type { ElementFrame as EditorElementFrame } from "../../editor/contracts";
+export declare function configureElement(value: ElementRuntime): void;
+/** 读写当前节点：只读状态、外框选中、合并字段、删除、打开块菜单 */
+export declare const useElement: ElementRuntime["useElement"];
+/** 打开文档图片查看器，定位到该节点的第 index 个图片资源 */
+export declare const useMediaViewer: ElementRuntime["useMediaViewer"];
+export declare const BlockToolbar: ElementRuntime["BlockToolbar"];
+export declare const BlockToolbarButton: ElementRuntime["BlockToolbarButton"];
+export declare const BlockToolbarGap: ElementRuntime["BlockToolbarGap"];