@xiongtao.xt/tau-plugins 0.32.0 → 0.33.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 更新记录
 
+## 0.33.0
+
+- 新增媒体组件 `MediaImage`、`MediaVideo`、`MediaAudio`：节点里的本地路径、远程地址和共享文档资源按 Tau 自带图片、视频、音频块的方式解析和缓存。
+- 新增 `useResource(url, { kind })`，自己绘制媒体时取得可加载的地址；`useResourceUpload()` 把文件存进用户当前的资源存储并返回地址，只读编辑器与博客中为 `undefined`。
+- 新增 `useMediaAppearance()`，读取用户设置（博客中为发布设置）的媒体默认圆角与阴影。
+- 新增 `useElement(element)`：读写当前节点（`readOnly`、`update`、`remove`），外框里的块还能取得 `selected`、`select()`、`openMenu(position)`。`useInlineSource` 建在它之上。
+- 节点声明新增 `frame`：void 块的公共外框，提供点选描边、右键菜单、选中时删除与声明的按键命令、末尾「添加段落」；声明后 `render` 只渲染内容。
+- 新增块属性条 `BlockToolbar`、`BlockToolbarButton`、`BlockToolbarGap`，外观与自带图片块一致。
+- 新增 `useMediaViewer(element)`，打开文档图片查看器并定位到该节点的第几张图。
+- `@tau/ui` 新增 `Sortable`，用指针事件拖动排序，手柄支持方向键。
+- 节点声明新增 `resources`：写明节点里哪些字段是图片、视频、音频或文件。导出打包、共享给协作者时上传本地文件、灯箱与 EPUB 取图都只按这份声明找资源；声明随笔记库保存。
+
 ## 0.32.0
 
 - 插件 Skill 改为包内目录：在插件项目根目录放 `skills/<id>/SKILL.md`，可附带参考资料和脚本，构建时打进插件包并写入 manifest 的 `skills` 与文件摘要。名称、描述与调用方式取自 SKILL.md 的 front matter。

package/docs/editor.md

@@ -134,6 +134,7 @@ export default definePlugin({
 | `drag`      | 可选。为 `true` 时显示拖动手柄，用户可以拖动这个块。不声明就不能拖动                      |
 | `isEmpty`   | 可选。判断节点是否为空。内容保存在自定义字段（如源码）里时，用它告诉 Tau 什么情况下算空块 |
 | `behaviors` | 可选。光标在节点内时，接管回车、退格、输入等行为，见[行为](#行为)                         |
+| `resources` | 可选。节点里哪些字段是图片、视频、音频或文件，见[声明资源字段](#声明资源字段)             |
 
 ### 渲染组件
 
@@ -154,13 +155,13 @@ render: ({ attributes, element, children }) => (
 
 ### 修改节点字段
 
-组件里需要修改节点数据（例如保存用户调整后的参数）时，使用 `useSourceBlock` 返回的 `update`：
+组件里需要修改节点数据（例如保存用户调整后的参数）时，使用 `useElement` 返回的 `update`：
 
 ```tsx
-import { useSourceBlock } from "@tau/plugins";
+import { useElement } from "@tau/plugins";
 
 function Counter({ element }: { element: CounterElement }) {
-  const { update } = useSourceBlock(element);
+  const { update } = useElement(element);
   return (
     <button
       onMouseDown={event => event.preventDefault()}
@@ -174,6 +175,78 @@ function Counter({ element }: { element: CounterElement }) {
 
 `update` 把传入的字段合并进节点，这次修改会进入撤销记录并同步给协作者。
 
+`useElement(element)` 返回：
+
+| 字段                 | 说明                                                               |
+| -------------------- | ------------------------------------------------------------------ |
+| `readOnly`           | 编辑器是否只读。只读时 `update`、`remove` 不会写入                 |
+| `update(properties)` | 把字段合并进节点                                                   |
+| `remove()`           | 删除节点                                                           |
+| `selected`           | 声明了[外框](#块的外框)的块是否被点选                              |
+| `select()`           | 选中外框里的块                                                     |
+| `openMenu(position)` | 在指定位置（视口坐标）打开块菜单，条目与右键、块手柄相同；需要外框 |
+
+请始终传入当前渲染拿到的 `element`。节点被替换或组件卸载后，旧对象上的写入会被忽略，不会改到别的块。
+
+### 块的外框
+
+图表、画廊这类整块由组件渲染的节点（`isVoid: true` 的块），在节点声明上加 `frame` 即可得到 Tau 块的公共交互：点击选中并描边、点到别处取消、右键打开块菜单、选中时 Delete / Backspace 删除块并留下空段落、Esc 取消选中，以及块末尾的「添加段落」。
+
+```tsx
+defineEditorElement({
+  type: "yourname.chart",
+  kind: "block",
+  isVoid: true,
+  frame: { keys: { Enter: "yourname.chart.edit" } },
+  render: Chart,
+});
+```
+
+| 字段              | 说明                                                                |
+| ----------------- | ------------------------------------------------------------------- |
+| `keys`            | 可选。选中时的按键对应的命令 id，命令收到这个节点（同菜单里的命令） |
+| `appendParagraph` | 可选。为 `false` 时不显示末尾的「添加段落」                         |
+
+声明外框后，`render` 只渲染内容：收到的 `attributes` 是空对象、`children` 为空，交给外框处理。组件里用 `useElement(element).selected` 决定是否显示属性条。
+
+### 块的属性条
+
+选中块后浮在块上方的属性条，用 `BlockToolbar`、`BlockToolbarButton`、`BlockToolbarGap` 组成，外观和 Tau 自带的图片块一致。上方放不下时自动翻到下方，点击按钮不会让编辑器失去光标。
+
+```tsx
+import { BlockToolbar, BlockToolbarButton, BlockToolbarGap, useElement } from "@tau/plugins";
+
+function Chart({ element }: { element: ChartElement }) {
+  const { selected, readOnly, update, openMenu } = useElement(element);
+  return (
+    <div className="relative">
+      {selected && !readOnly && (
+        <BlockToolbar label="图表属性">
+          <BlockToolbarButton
+            title="柱状图"
+            active={element.kind === "bar"}
+            icon={<BarChart3 size={15} />}
+            onClick={() => update({ kind: "bar" })}
+          />
+          <BlockToolbarGap />
+          <BlockToolbarButton
+            title="更多"
+            icon={<MoreHorizontal size={15} />}
+            onClick={event => {
+              const rect = event.currentTarget.getBoundingClientRect();
+              openMenu({ x: rect.left, y: rect.bottom + 6 });
+            }}
+          />
+        </BlockToolbar>
+      )}
+      <ChartView data={element.data} />
+    </div>
+  );
+}
+```
+
+`BlockToolbarButton` 的 `title` 是按钮名称（纯图标按钮悬停时显示），`label` 是显示在图标旁的文字，`shortcut` 在提示里显示快捷键，`active` 表示当前选中的选项。
+
 ## 扩展能声明的内容
 
 `defineEditorExtension` 接收：
@@ -420,6 +493,66 @@ function DiagramBlock({ element, children }: { element: DiagramElement; children
 
 行内的源码输入弹层由你用 `@tau/ui` 组件实现。只读时只显示预览，不打开编辑弹层；只读状态下 `update` 和 `remove` 不会写入文档。
 
+## 图片、视频与音频
+
+节点里存的图片、视频、音频地址可能是本地路径、远程地址或共享文档里的资源，不能直接交给 `<img>`。用宿主的媒体组件显示，解析方式与 Tau 自带的图片块相同：本地路径转成可加载的地址，远程资源按用户的缓存设置下载，共享文档里的资源经协作服务解析。
+
+```tsx
+import { MediaImage, useMediaAppearance } from "@tau/plugins";
+
+function Photo({ element }: { element: PhotoElement }) {
+  const appearance = useMediaAppearance();
+  return (
+    <figure contentEditable={false} data-radius={element.borderRadius ?? appearance?.borderRadius}>
+      <MediaImage url={element.url} alt={element.caption} />
+    </figure>
+  );
+}
+```
+
+| 接口                         | 用途                                                                                                                   |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `MediaImage`                 | 显示图片，参数为 `url`、`alt`、`className`、`style`、`loading`、`onLoadError` 等                                       |
+| `MediaVideo` / `MediaAudio`  | 宿主的视频、音频播放器，参数为 `src` 与原生媒体属性                                                                    |
+| `useResource(url, { kind })` | 自己绘制时使用：返回 `src`、`status`（`loading` / `ready` / `error`）与 `retry()`，元素加载失败时调用 `retry` 重新解析 |
+| `useResourceUpload()`        | 返回上传函数，把用户选的文件存进当前的资源存储并返回可写入节点的地址；只读编辑器和博客里为 `undefined`                 |
+| `useMediaAppearance()`       | 用户设置的媒体默认圆角与阴影（`none` / `sm` / `md` / `lg`）；博客里取发布设置。节点自己有设置时以节点为准              |
+
+`kind` 取 `image`、`video`、`audio`、`file`，决定远程资源的缓存方式。上传的文件不需要自己判断本地还是远端存储，也不要把文件内容写进节点。
+
+### 查看图片
+
+`useMediaViewer(element)` 返回一个函数，调用后打开 Tau 的图片查看器，浏览文档里的全部图片，并定位到这个节点的第 `index` 张（按[声明的资源字段](#声明资源字段)计，从 0 开始）。
+
+```tsx
+const openViewer = useMediaViewer(element);
+<MediaImage url={item.url} onDoubleClick={() => openViewer(index)} />;
+```
+
+### 声明资源字段
+
+节点里存了图片、视频、音频或文件地址时，在节点声明上用 `resources` 写明是哪些字段。Tau 只按这份声明找资源：导出打包、共享给协作者时上传本地文件、灯箱里浏览图片、EPUB 取图，都靠它。没有声明的字段按普通文字原样保留，本地图片不会随内容导出，也不会上传给协作者。
+
+```tsx
+defineEditorElement({
+  type: "yourname.gallery",
+  kind: "block",
+  isVoid: true,
+  render: Gallery,
+  resources: [{ path: "images[].url", kind: "image", alt: "desc", caption: "desc" }],
+});
+```
+
+| 字段      | 说明                                                                                     |
+| --------- | ---------------------------------------------------------------------------------------- |
+| `path`    | 资源字段的路径。`url` 是节点上的字段，`images[].url` 表示 `images` 数组每一项的 `url`    |
+| `kind`    | `image`、`video`、`audio` 或 `file`                                                      |
+| `preview` | 可选。同一资源的显示版本（如裁剪结果）所在的字段，与 `path` 末段同层，同样会被导出和上传 |
+| `alt`     | 可选。替代文字所在的字段，与 `path` 末段同层，灯箱里显示                                 |
+| `caption` | 可选。说明文字所在的字段，与 `path` 末段同层，灯箱里显示                                 |
+
+声明会随笔记库保存，插件停用或在没装插件的设备上，这些资源照样能导出和共享。已经有文档用了的字段不要改名；新增资源字段时补进声明即可。
+
 ## 动态 Tailwind 样式
 
 如果节点的源码里写了 Tailwind 类名（比如用户写的组件演示），在扩展上声明哪个字段是源码：

package/docs/ui.md

@@ -318,12 +318,13 @@ export function Help() {
 }
 ```
 
-| 组件         | 常用属性                                                                                                                         |
-| ------------ | -------------------------------------------------------------------------------------------------------------------------------- |
-| `Button`     | `onClick`、`disabled`、`loading`、`loadingText`；`variant` 可选 `primary`、`secondary`、`soft`、`ghost`、`danger`、`danger-soft` |
-| `Panel`      | 内容容器                                                                                                                         |
-| `Dialog`     | `open`、`onOpenChange`、`title`，`footer` 放操作按钮                                                                             |
-| `DialogBody` | 弹窗正文                                                                                                                         |
+| 组件         | 常用属性                                                                                                                                          |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Button`     | `onClick`、`disabled`、`loading`、`loadingText`；`variant` 可选 `primary`、`secondary`、`soft`、`ghost`、`danger`、`danger-soft`                  |
+| `Panel`      | 内容容器                                                                                                                                          |
+| `Dialog`     | `open`、`onOpenChange`、`title`，`footer` 放操作按钮                                                                                              |
+| `DialogBody` | 弹窗正文                                                                                                                                          |
+| `Sortable`   | 拖动排序：`items`、`getKey`、`onMove(from, to)`、`renderItem(item, state)`，把 `state.handleProps` 展开到拖动手柄上；手柄获得焦点时方向键前后移动 |
 
 完整的组件列表和属性见 `@tau/ui` 的类型提示。
 

package/package.json

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

package/publish-artifacts.js

@@ -3,6 +3,36 @@ import {
   validatePluginManifest
 } 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;
 function evaluatePluginPackage(artifact, modules) {
@@ -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/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"];

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

@@ -12,6 +12,10 @@ export { SourceBlockEditor, useSourceBlock, useReportPreviewError, insertSourceB
 export type { SourceBlockEditorProps, PluginRuntimeStyleCompiler } from "./source-editor";
 export { useInlineSource, insertInlineSource, InlineSourceBoundary } from "./inline-source";
 export { ContentEditor, ContentPreview } from "./components";
+export { useElement, useMediaViewer, BlockToolbar, BlockToolbarButton, BlockToolbarGap, } from "./element";
+export type { ElementAccess, BlockToolbarProps, BlockToolbarButtonProps, EditorElementFrame, } from "./element";
+export { MediaImage, MediaVideo, MediaAudio, useResource, useResourceUpload, useMediaAppearance, } from "./media";
+export type { ResourceKind, ResourceState, ResourceUpload, MediaAppearance, MediaAppearancePreset, MediaImageProps, MediaVideoProps, MediaAudioProps, MediaRuntime, } from "./media";
 export type { ContentEditorProps, ContentPreviewProps } from "./components";
 export * from "./sidebar";
 export type * from "./icons";

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

@@ -0,0 +1,69 @@
+import type { CSSProperties, ImgHTMLAttributes, MouseEventHandler, ReactElement, ReactNode, Ref, SyntheticEvent, VideoHTMLAttributes } from "react";
+import type { ContentResourceKind } from "../../db-schema/content-resources";
+export type ResourceKind = ContentResourceKind;
+export interface ResourceState {
+    /** 可直接给 img / video / audio 的地址；解析中或失败时为 undefined */
+    src: string | undefined;
+    status: "loading" | "ready" | "error";
+    /** 元素加载失败时调用：作废宿主缓存后重新解析 */
+    retry(): void;
+}
+/** 上传到用户当前的资源存储（本地库、远端或共享文档），返回可写入节点的地址 */
+export type ResourceUpload = (file: File) => Promise<string>;
+export type MediaAppearancePreset = "none" | "sm" | "md" | "lg";
+/** 用户设置（发布站为发布设置）里的媒体默认外观；节点自身的设置优先 */
+export interface MediaAppearance {
+    borderRadius?: MediaAppearancePreset;
+    shadow?: MediaAppearancePreset | boolean;
+}
+export interface MediaImageProps {
+    url: string;
+    alt?: string;
+    className?: string;
+    style?: CSSProperties;
+    onClick?: MouseEventHandler<HTMLImageElement>;
+    onDoubleClick?: MouseEventHandler<HTMLImageElement>;
+    onLoad?: (event: SyntheticEvent<HTMLImageElement>) => void;
+    /** 宿主的回退地址也加载失败后回调 */
+    onLoadError?: () => void;
+    crossOrigin?: ImgHTMLAttributes<HTMLImageElement>["crossOrigin"];
+    /** 默认懒加载 */
+    loading?: "eager" | "lazy";
+    draggable?: boolean;
+    ref?: Ref<HTMLImageElement>;
+}
+export type MediaVideoProps = VideoHTMLAttributes<HTMLVideoElement> & {
+    src: string;
+    playbackRate?: number;
+    onPlaybackRateChange?: (rate: number) => void;
+    /** 播放器底栏信息位，宿主播放器不支持时忽略 */
+    info?: ReactNode;
+    ref?: Ref<HTMLVideoElement>;
+};
+export interface MediaAudioProps {
+    src: string;
+    controls?: boolean;
+    label?: string;
+    labelSlot?: ReactNode;
+    className?: string;
+    ref?: Ref<HTMLAudioElement>;
+}
+/** 宿主注入的实现；在编辑器内按当前文档的作用域生效（共享文档走协作资源），编辑器外用应用默认实现。 */
+export interface MediaRuntime {
+    useResource(url: string, options: {
+        kind: ResourceKind;
+    }): ResourceState;
+    /** 只读编辑器与没有资源存储的宿主（发布站）返回 undefined */
+    useResourceUpload(): ResourceUpload | undefined;
+    useMediaAppearance(): MediaAppearance | undefined;
+    MediaImage(props: MediaImageProps): ReactElement | null;
+    MediaVideo(props: MediaVideoProps): ReactElement | null;
+    MediaAudio(props: MediaAudioProps): ReactElement | null;
+}
+export declare function configureMedia(value: MediaRuntime): void;
+export declare const useResource: MediaRuntime["useResource"];
+export declare const useResourceUpload: MediaRuntime["useResourceUpload"];
+export declare const useMediaAppearance: MediaRuntime["useMediaAppearance"];
+export declare const MediaImage: (props: MediaImageProps) => ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | null;
+export declare const MediaVideo: (props: MediaVideoProps) => ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | null;
+export declare const MediaAudio: (props: MediaAudioProps) => ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | null;

package/types/packages/ui/src/index.d.ts

@@ -44,6 +44,7 @@ export * from "./primitives/datepicker/DateRangePicker";
 export * from "./primitives/ImagePreview";
 export * from "./primitives/Tabs";
 export * from "./primitives/FileDropZone";
+export * from "./primitives/Sortable";
 export * from "./primitives/LoadingOverlay";
 export { lockBodyScroll } from "./hooks/lockBodyScroll";
 export { mergeRefs } from "./primitives/mergeRefs";

package/types/packages/ui/src/primitives/Sortable.d.ts

@@ -0,0 +1,32 @@
+import { type KeyboardEvent, type PointerEvent, type ReactNode } from "react";
+export interface SortableHandleProps {
+    onPointerDown(event: PointerEvent<HTMLElement>): void;
+    onKeyDown(event: KeyboardEvent<HTMLElement>): void;
+    tabIndex: number;
+    "aria-roledescription": string;
+}
+export interface SortableItemState {
+    index: number;
+    /** 正在被拖动的那一项 */
+    dragging: boolean;
+    /** 拖动经过、松手后会放到这里 */
+    over: boolean;
+    /** 展开到拖动手柄上；也可以展开到整项上，整项都能拖 */
+    handleProps: SortableHandleProps;
+}
+export interface SortableProps<T> {
+    items: readonly T[];
+    getKey(item: T): string;
+    /** 把 from 位置的项移到 to 位置 */
+    onMove(from: number, to: number): void;
+    renderItem(item: T, state: SortableItemState): ReactNode;
+    className?: string;
+    /** 每一项外层容器的类名 */
+    itemClassName?: string;
+    disabled?: boolean;
+}
+/**
+ * 列表与网格排序：按住手柄拖到另一项上松手即移到那里；手柄获得焦点时方向键前后移动一位，Esc 取消拖动。
+ * 用指针事件实现，不依赖拖放 API，任何容器（含编辑器里的块）都能用。
+ */
+export declare function Sortable<T>({ items, getKey, onMove, renderItem, className, itemClassName, disabled, }: SortableProps<T>): import("react/jsx-runtime").JSX.Element;