@xiongtao.xt/tau-plugins 0.7.0 → 0.8.0

package/WHITEBOARD.md

@@ -0,0 +1,115 @@
+# 白板插件
+
+白板作者接口需要 SDK 0.8.0 及包含白板扩展支持的 Tau 客户端。SDK 0.7.0 不提供此能力。
+
+插件定义中声明 `whiteboardExtensions`，manifest 增加 `whiteboard: true`。使用 `@tau/plugins/whiteboard` 导入定义函数和类型，并将该模块保留为构建 external，由宿主提供实现。一个 main.js 同时包含声明、渲染与交互，不生成另一个渲染入口。
+
+```tsx
+import { definePlugin } from "@tau/plugins";
+import { defineElement, defineWhiteboardExtension } from "@tau/plugins/whiteboard";
+
+declare const __PLUGIN_META__: { id: string; name: string; version: string };
+const type = `${__PLUGIN_META__.id}.box`;
+const extension = defineWhiteboardExtension({
+  id: __PLUGIN_META__.id,
+  elements: [
+    defineElement({
+      type,
+      render: ({ element }) => (
+        <rect
+          x={element.x}
+          y={element.y}
+          width={element.width}
+          height={element.height}
+          fill="var(--tau-accent)"
+        />
+      ),
+      create: {
+        gesture: "click",
+        defaultSize: [160, 90],
+        after: "select",
+        build: ({ rect }) => ({ id: crypto.randomUUID(), type, ...rect, data: {} }),
+      },
+    }),
+  ],
+  create: () => ({
+    tools: [
+      {
+        id: `${__PLUGIN_META__.id}.create`,
+        element: type,
+        label: "插入方块",
+        order: 90,
+        group: "drawing",
+        icon: () => (
+          <svg viewBox="0 0 24 24">
+            <rect x={3} y={5} width={18} height={14} fill="currentColor" />
+          </svg>
+        ),
+      },
+    ],
+  }),
+});
+export default definePlugin({ ...__PLUGIN_META__, whiteboardExtensions: [extension] });
+```
+
+## 契约
+
+- `elements` 在扩展顶层静态声明，禁止放到 `create` 返回值中。元素类型必须以完整插件 ID 加点开头，扩展 ID 为插件 ID 或其子命名空间。
+- `create(api)` 每个画布单独执行，返回 `tools`、`inspectors`、`commands` 等交互贡献。状态放在实例闭包，不能放在模块顶层跨画布共享。
+- 元素私有字段放在 `data`，通过 `defineElement<TData>` 和可选同步 Standard Schema 校验约束；通用位置和尺寸仍在元素顶层。
+- 属性修改走 `api.updateElement`，结构操作走 `api.submit`；这些入口统一处理只读、历史及生命周期。不要修改返回的快照。
+- 元素组件可用 `useWhiteboardAPI()` 获取所属扩展的受控 API，不接触内部 Board。声明求值阶段不得读取 DOM。
+- `activate` 随画布显示运行，停驻会清理；`dispose` 在真正销毁时运行。插件整体启用/停用/更新在重启后改变静态装配，不热替换打开中的画布。
+- 找不到插件时保留节点并显示未知元素占位，重新安装并启用后恢复。保存、复制不能丢弃未知节点。
+
+## 通用展示与交互
+
+### 创建前选择参数
+
+第三方工具集中在「扩展工具」菜单；可选的 `panel` 让用户先选择参数，再调用 `run(payload)`。面板可以通过 `useWhiteboardAPI()` 获取所属扩展的 API。
+
+```tsx
+panel: ({ run }) => (
+  <button onClick={() => run({ label: "新方块" })}>创建新方块</button>
+),
+```
+
+创建工具在 `element.create.build` 的 `options` 中读取这些参数，命令工具在命令的 `payload` 中读取。宿主管理返回、关闭与面板卸载，执行后自动关闭；返回或关闭不会执行工具。关闭后的迟到 `run` 调用被忽略。面板抛错时显示错误并保留返回入口。没有 `panel` 的工具仍点击即执行；不要用只供内置工具栏使用的 `component` 代替它，也不要在面板内创建第二套画布指针监听。
+
+### 元素声明
+
+以下声明放在 `defineElement` 内，仍使用同一个插件入口：
+
+```ts
+interaction: {
+  resize: { handles: "corners", preserveAspectRatio: true },
+  connect: "rect",
+},
+presentation: {
+  label: "我的图形",
+  getName: element => element.data.label,
+},
+sketch: true,
+schematic: element => [{
+  kind: "rect", x: element.x, y: element.y,
+  w: element.width, h: element.height, r: 3, fill: "var(--tau-accent)",
+}],
+```
+
+- `resize.handles` 可选 corners 或 all，默认 all；`preserveAspectRatio` 默认为 false，Shift 仍可启用等比。内核生成手柄，负责吸附、单步撤销、取消和生命周期，不要再给元素额外画一套缩放手柄。
+- `connect: "rect"` 使用矩形连接点，包括相对位置绑定；不声明则不生成连接控件。
+- `presentation.icon` 为可选图标组件，接收 className、size、strokeWidth。`getName` 接收只读快照，手动 name 优先；无法生成时回退 label。
+- 声明 `sketch:true` 后，在元素组件调用 `useSketch(element)` 获取 enabled/level/seed；页面切换会更新组件，元素覆盖仍由宿主解析。不要自行维护全局画风状态。
+- `SketchPaths` 渲染已有手绘路径；`sketch` 命名空间提供 createRandom、distance、polylineToD、resample、wobble、inkOutline、inkSize、loopStroke、handTextClass。复用宿主纯算法，不从白板内部目录复制实现。
+- `usePageSketch()` 读取所属页面的画风；`sketch.hashSeed(text)` 为预览图生成稳定种子。`AttrPopover`、`AttrToggle`、`OptionGrid`、`Seg` 供属性面板使用，`SketchPopover` 提供与宿主相同的元素笔触设置。
+- `schematic(element, { dark })` 返回纯图元数组，用于列表与导出弹窗的简略预览；字段类型见 SchematicShape。不能调用 hook、修改元素或依赖某个画布已打开。实际图像导出仍使用完整画布渲染，不使用简略投影替代。
+
+构建 Tailwind 工具类时可导入 `@tau/plugins/tailwind.css`，其中仅包含语义类名映射，主题变量由客户端提供。不要引入未公开的宿主主题包。
+
+## 私有偏好
+
+需要记住用户选择时，在扩展中声明 `requires: [IPluginStorage]`，通过 `api.getService(IPluginStorage)` 获取存储。`IPluginStorage` 从 `@tau/plugins/whiteboard` 导入，接口与 `PluginContext.storage` 相同：异步 `get(key)`、`set(key, JSON值)`、`delete(key)`。
+
+宿主按插件真实归属与当前工作区绑定存储，插件不能传入其他插件 ID。画布隐藏、关闭或只读时拒绝交互存储操作；插件失活、工作区切换后，旧实例也不能继续写入。异步读写应捕获错误，并在面板卸载后忽略迟到结果。重新打开白板后绑定当前激活实例。
+
+只在 `create(api)`、工具面板、属性交互和 `element.create.build` 中使用这项服务。静态渲染与 `schematic` 必须只依据元素数据及明确输入，不依赖存储、DOM 或插件 activate 时序。读取不存在的偏好时使用默认值；读取失败不能伪装成空数据后覆盖原值。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xiongtao.xt/tau-plugins",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -16,15 +16,20 @@
     ".": {
       "types": "./types/packages/plugins/src/index.d.ts",
       "default": "./runtime.js"
+    },
+    "./tailwind.css": "./tailwind.css",
+    "./whiteboard": {
+      "types": "./types/packages/plugins/src/whiteboard.d.ts",
+      "default": "./runtime.js"
     }
   },
   "dependencies": {
     "@types/react": "19.2.0",
     "@types/react-dom": "19.2.0",
+    "lucide-react": "0.399.0",
+    "clsx": "2.1.1",
     "slate": "0.126.2",
     "slate-react": "0.126.4",
-    "clsx": "2.1.1",
-    "lucide-react": "0.399.0",
     "slate-history": "0.113.1"
   },
   "peerDependencies": {

package/tailwind.css

@@ -0,0 +1,101 @@
+/*
+ * Tailwind v4 语义类名映射：组件写 bg-page / text-ink-1 / border-line-1 等，主题无关。
+ * 取值来自 tokens.css 的 --tau-*，使用方需同时引入 @tau/themes/tokens.css。
+ *
+ * Tailwind 词一律用 tau 命名空间（rounded-tau-* / text-tau-*），不覆盖
+ * legacy 页面在用的 Tailwind 默认刻度（D-001）；一次性展示字号允许
+ * text-[24px] 类任意值。
+ */
+@theme inline {
+  --color-page: var(--tau-bg-page);
+  --color-surface: var(--tau-bg-surface);
+  --color-surface-hover: var(--tau-bg-surface-hover);
+  --color-sunken: var(--tau-bg-sunken);
+  --color-track: var(--tau-bg-track);
+  --color-hover: var(--tau-bg-hover);
+  --color-press: var(--tau-bg-press);
+  --color-selected: var(--tau-bg-selected);
+
+  --color-ink-1: var(--tau-ink-1);
+  --color-ink-2: var(--tau-ink-2);
+  --color-ink-3: var(--tau-ink-3);
+  --color-ink-inverse: var(--tau-ink-inverse);
+
+  --color-line-1: var(--tau-line-1);
+  --color-line-2: var(--tau-line-2);
+
+  --color-overlay: var(--tau-overlay);
+
+  --color-accent: var(--tau-accent);
+  --color-accent-hover: var(--tau-accent-hover);
+  --color-accent-soft: var(--tau-accent-soft);
+  --color-accent-text: var(--tau-accent-text);
+
+  --color-ok: var(--tau-ok);
+  --color-ok-soft: var(--tau-ok-soft);
+  --color-warn: var(--tau-warn);
+  --color-warn-soft: var(--tau-warn-soft);
+  --color-danger: var(--tau-danger);
+  --color-danger-soft: var(--tau-danger-soft);
+  --color-info: var(--tau-info);
+  --color-info-soft: var(--tau-info-soft);
+
+  --color-tag-1: var(--tau-tag-1);
+  --color-tag-1-soft: var(--tau-tag-1-soft);
+  --color-tag-2: var(--tau-tag-2);
+  --color-tag-2-soft: var(--tau-tag-2-soft);
+  --color-tag-3: var(--tau-tag-3);
+  --color-tag-3-soft: var(--tau-tag-3-soft);
+  --color-tag-4: var(--tau-tag-4);
+  --color-tag-4-soft: var(--tau-tag-4-soft);
+  --color-tag-5: var(--tau-tag-5);
+  --color-tag-5-soft: var(--tau-tag-5-soft);
+
+  --font-tau: var(--tau-font);
+  --font-tau-mono: var(--tau-font-mono);
+  --font-tau-hand: var(--tau-font-hand);
+
+  /* ── 尺度词（D-001，tau 命名空间，见 02 规范 §3/§4）── */
+
+  /* 字号：A2 定稿取值（经 :root 字面值层 --tau-text-* 桥接，支持运行时整体缩放——
+     @theme inline 对字面值会内联进工具类导致不可覆盖，必须走 var 引用） */
+  --text-tau-hero: var(--tau-text-hero);
+  --text-tau-title-lg: var(--tau-text-title-lg);
+  --text-tau-title: var(--tau-text-title);
+  --text-tau-body-lg: var(--tau-text-body-lg);
+  --text-tau-body: var(--tau-text-body);
+  --text-tau-body--line-height: 1.65;
+  --text-tau-meta: var(--tau-text-meta);
+  --text-tau-sm: var(--tau-text-sm);
+  --text-tau-micro: var(--tau-text-micro);
+  --text-tau-tiny: var(--tau-text-tiny);
+
+  /* 圆角三档 */
+  --radius-tau-sm: var(--tau-radius-sm);
+  --radius-tau-md: var(--tau-radius-md);
+  --radius-tau-lg: var(--tau-radius-lg);
+
+  /* 阴影（tokenContract float 组词）：card 静止 / lift 卡片 hover 轻抬 / float 浮层 / paper 画布上浮起的文档纸 */
+  --shadow-card: var(--tau-shadow-card);
+  --shadow-lift: var(--tau-shadow-lift);
+  --shadow-float: var(--tau-shadow-float);
+  --shadow-paper: var(--tau-shadow-paper);
+
+  /* 缓动 */
+  --ease-tau-out: var(--tau-ease-out);
+
+  /* 域内动效（keyframes 与词表同处声明，hover:animate-hm-pulse 消费） */
+  --animate-hm-pulse: hmPulse 0.5s linear alternate infinite;
+
+  @keyframes hmPulse {
+    0% {
+      transform: scale(1.18);
+    }
+    50% {
+      transform: scale(1);
+    }
+    100% {
+      transform: scale(0.85);
+    }
+  }
+}

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

@@ -1,6 +1,7 @@
 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";
 import type { PluginEditor } from "./editor";
 import type { PluginEditorExtension } from "./editor";
@@ -56,6 +57,7 @@ export interface PluginDefinition {
     readonly apiVersion: 1;
     /** 静态声明，桌面与博客均装配同一份扩展；模块加载不得依赖桌面激活。 */
     readonly editorExtensions?: readonly PluginEditorExtension[];
+    readonly whiteboardExtensions?: readonly WhiteboardExtension[];
     readonly editorCodecs?: readonly MarkdownCodec[];
     readonly skills?: readonly PluginSkill[];
     readonly ai?: {

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

@@ -0,0 +1,7 @@
+export { defineElement, defineWhiteboardExtension, useWhiteboardAPI, useSketch, usePageSketch, AttrPopover, AttrToggle, OptionGrid, Seg, SketchPopover, sketch, SketchPaths, } from "../../whiteboard/src/author";
+export type { SketchPath, Vec } from "../../whiteboard/src/author";
+export type { SchematicShape, SchematicFill, ResolvedSketch, ElementSketch, PageSketch, SketchLevel, } from "../../whiteboard/src/author";
+export type { WhiteboardAPI, WhiteboardExtension, WhiteboardElementDefinition, WhiteboardContributions, TypedBoardElement, ElementCreateSpec, WhiteboardSnapshot, BoardElement, WhiteboardToolProps, } from "../../whiteboard/src/author";
+import type { PluginStorage } from "./contract";
+/** 由宿主按插件和工作区绑定，交互扩展通过 requires 声明后获取。 */
+export declare const IPluginStorage: import("../../shared/service-contract").ServiceIdentifier<PluginStorage>;

package/types/packages/shared/entity-ref.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 统一实体地址：跨模块指向「一份正文的某个身份」（卡片、文章、项目文档、日记）。
+ *
+ * 纯 TypeScript，桌面端与移动端共用。存量各处的类型写法（question_link 的 project_item、
+ * content-link / 索引的 project-item）经 normalizeEntityRefKind 收口；
+ * 日记正文身份为 diary-moment + 片段 id，存量日级引用在开库时转换。
+ */
+export declare const ENTITY_REF_KINDS: readonly ["card", "article", "project-item", "diary-moment"];
+export type EntityRefKind = (typeof ENTITY_REF_KINDS)[number];
+export interface EntityRef {
+    kind: EntityRefKind;
+    id: number;
+}
+/** 各处存量写法 → EntityRefKind；不认识的返回 null，由调用方丢弃 */
+export declare function normalizeEntityRefKind(raw: unknown): EntityRefKind | null;
+export declare const entityRefKey: (ref: EntityRef) => string;
+export declare const isSameEntityRef: (a: EntityRef, b: EntityRef) => boolean;
+/** 同一份正文被多个实体共用时，选哪个身份作代表：卡片 > 文章 > 项目文档 > 日记 */
+export declare const ENTITY_REF_PRIORITY: Record<EntityRefKind, number>;

package/types/packages/whiteboard/src/author.d.ts

@@ -0,0 +1,14 @@
+/** 白板作者入口保持无 DOM 副作用，定义可在纯数据宿主中求值。 */
+export { defineElement, defineWhiteboardExtension } from "./extensions/api";
+export type { WhiteboardAPI, WhiteboardExtension, WhiteboardElementDefinition, WhiteboardContributions, TypedBoardElement, ElementCreateSpec, WhiteboardSnapshot, WhiteboardToolProps, } from "./extensions/api";
+export type { BoardElement } from "./types/element";
+export { useWhiteboardAPI } from "./extensions/context";
+export { useSketch, usePageSketch } from "./extensions/authorHooks";
+export { AttrPopover, AttrToggle, OptionGrid, Seg } from "./chrome/index";
+export { default as SketchPopover } from "./components/SketchPopover";
+export * as sketch from "./authorSketch";
+export { default as SketchPaths } from "./components/SketchPaths/index";
+export type { SketchPath } from "./utils/sketch/types";
+export type { Vec } from "./utils/sketch/geometry";
+export type { SchematicShape, SchematicFill } from "./types/schematic";
+export type { ResolvedSketch, ElementSketch, PageSketch, SketchLevel } from "./types/sketch";

package/types/packages/whiteboard/src/authorSketch.d.ts

@@ -0,0 +1,6 @@
+export { createRandom, hashSeed } from "./utils/sketch/random";
+export { distance, polylineToD, resample, wobble } from "./utils/sketch/geometry";
+export { inkOutline } from "./utils/sketch/ink";
+export { inkSize } from "./utils/sketch/levels";
+export { loopStroke } from "./utils/sketch/shape";
+export { handTextClass } from "./utils/sketch/handText";

package/types/packages/whiteboard/src/chrome/index.d.ts

@@ -0,0 +1,189 @@
+/**
+ * 画布 chrome 公共件（D-049）：
+ * 工具条 / 属性浮动条 / 状态栏 / 元素树等浮动件共用一套主题语言——
+ * 实底 surface + shadow-lift + 1px 细描边，不用毛玻璃与蓝调；激活 = accent-soft，悬停 = bg-hover；
+ * 组内分隔靠留白（ChromeGap），不画竖线。
+ *
+ * 属性控件（色板 / 滑杆 / 图示选项 / 分区头）是 setter 弹层的内容：色板与派生描边承载用户数据色
+ * （完整保留），外壳装饰阴影用黑色 alpha——二者不另设 token，其余一律走主题变量。
+ */
+import { type ComponentProps, type ReactNode, type SyntheticEvent } from "react";
+import { type TooltipPlacement } from "../../../ui/src/index";
+/**
+ * 浮动件内的指针 / 右键 / 按键不落到画布（画布容器在祖先上监听这些事件）。
+ * wheel 必须走捕获：画布的滚轮缩放/平移挂在容器上的原生 addEventListener，
+ * 先于 React root 的冒泡委托触发，冒泡期的合成事件 stopPropagation 到不了它前面；
+ * 捕获阶段（React root）stopPropagation 会截断整条剩余传播路径，原生监听才收不到。
+ */
+export declare const stopCanvasEvents: {
+    onPointerDown: (e: SyntheticEvent) => void;
+    onPointerUp: (e: SyntheticEvent) => void;
+    onMouseDown: (e: SyntheticEvent) => void;
+    onMouseUp: (e: SyntheticEvent) => void;
+    onClick: (e: SyntheticEvent) => void;
+    onDoubleClick: (e: SyntheticEvent) => void;
+    onWheelCapture: (e: SyntheticEvent) => void;
+    onKeyDown: (e: SyntheticEvent) => void;
+    onContextMenu: (e: SyntheticEvent) => void;
+};
+export declare function ChromeBar({ className, children, ...rest }: ComponentProps<"div">): import("react/jsx-runtime").JSX.Element;
+/** 组间留白（替代竖分隔线） */
+export declare function ChromeGap({ className }: {
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element;
+/**
+ * 工具栏语境：激活态由滑动指示块承载底色，按钮只改文字色（悬停不加背景）；
+ * 工具栏以外的 ChromeButton（属性条 / 状态栏）保持 accent-soft 底色的原激活态。
+ */
+export declare const ToolbarContext: import("react").Context<boolean>;
+export interface ChromeButtonProps extends ComponentProps<"button"> {
+    /** 提示与无障碍名 */
+    label: string;
+    /** 激活态（当前工具 / 开关已开） */
+    active?: boolean;
+    /** 带子菜单：右下角固定小三角（占位固定，悬停不改尺寸） */
+    sub?: boolean;
+    kbd?: string;
+    tooltipPlacement?: TooltipPlacement;
+}
+/**
+ * 浮动件图标按钮：30px，Tooltip 包在 button 外、ref 与注入的 props 透传到 button——
+ * 所以可以直接作为 Menu / Popover 的 trigger。展开时（aria-expanded）按下态、并暂停提示。
+ */
+export declare function ChromeButton({ label, active, sub, kbd, tooltipPlacement, className, children, ref, ...rest }: ChromeButtonProps): import("react/jsx-runtime").JSX.Element;
+/** 属性条的弹层方向：条在元素上方 → 向上展开；翻到元素下方 → 向下展开 */
+export declare const AttrBarContext: import("react").Context<{
+    side: "top" | "bottom";
+}>;
+export interface AttrPopoverProps {
+    label: string;
+    /** 条目图标；与 swatch 二选一 */
+    icon?: ReactNode;
+    /** 颜色条目用当前色的小圆点代替通用图标（数据色） */
+    swatch?: SwatchLook;
+    /** 分区头右侧的开关（开关型属性：开关放标题右侧，下面不再写同名开关） */
+    toggle?: {
+        checked: boolean;
+        onChange: (v: boolean) => void;
+    };
+    children?: ReactNode;
+    /** 弹层宽度，默认 280 */
+    width?: number;
+}
+export declare function AttrPopover({ label, icon, swatch, toggle, children, width, }: AttrPopoverProps): import("react/jsx-runtime").JSX.Element;
+/** 纯开关项：点一下直接切换，按钮本身显示开 / 关 */
+export declare function AttrToggle({ label, icon, checked, onChange, }: {
+    label: string;
+    icon: ReactNode;
+    checked: boolean;
+    onChange: (v: boolean) => void;
+}): import("react/jsx-runtime").JSX.Element;
+/** 动作项：直接执行（适应内容 / 解散 / 对齐…） */
+export declare function AttrAction({ label, icon, onClick, disabled, }: {
+    label: string;
+    icon: ReactNode;
+    onClick: () => void;
+    disabled?: boolean;
+}): import("react/jsx-runtime").JSX.Element;
+/** 弹层内的子字段：小标题 + 控件（纵向从属，不做左右两列） */
+export declare function Field({ label, value, children, className, }: {
+    label?: ReactNode;
+    value?: ReactNode;
+    children: ReactNode;
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element;
+export interface SwatchLook {
+    fill: string;
+    stroke?: string;
+    /** default = 「默认」（墨色环）；none = 无 / 透明（斜线） */
+    kind?: "default" | "none";
+}
+export declare function SwatchDot({ look }: {
+    look: SwatchLook;
+}): import("react/jsx-runtime").JSX.Element;
+export interface SwatchOption extends SwatchLook {
+    key: string;
+    label: string;
+}
+/** 色板：22px 圆色块，选中 = surface 间隙 + accent 外环 */
+export declare function SwatchRow({ options, value, onChange, custom, }: {
+    options: SwatchOption[];
+    value: string | null | undefined;
+    onChange: (key: string) => void;
+    /** 末尾「自定义颜色」 */
+    custom?: {
+        value?: string;
+        onChange: (hex: string) => void;
+    };
+}): import("react/jsx-runtime").JSX.Element;
+/** 滑杆：accent 轨道 + 右侧数值 */
+export declare function Slider({ value, min, max, step, unit, onChange, onCommit, format, label, }: {
+    value: number;
+    min: number;
+    max: number;
+    step?: number;
+    unit?: string;
+    onChange: (v: number) => void;
+    /** 拖动结束（需要合并为一次历史记录的调用方用） */
+    onCommit?: (v: number) => void;
+    format?: (v: number) => string;
+    label?: string;
+}): import("react/jsx-runtime").JSX.Element;
+/**
+ * 步进器：− 按钮 / 数值输入 / + 按钮（档位按钮之外的精确微调）。
+ * 单位后缀走 unit 文字：NumberInput 事前拦截只放行数字，后缀进输入框会被剥掉。
+ */
+export declare function Stepper({ value, min, max, step, onChange, label, unit, }: {
+    value: number;
+    min: number;
+    max: number;
+    step?: number;
+    onChange: (v: number) => void;
+    label: string;
+    /** 输入框右侧紧贴的单位字（如 "%"） */
+    unit?: string;
+}): import("react/jsx-runtime").JSX.Element;
+export interface OptionItem<V extends string> {
+    value: V;
+    label: string;
+    /** 图示（线型 / 箭头端点 / 画框样式…）；不给则显示 label */
+    glyph?: ReactNode;
+    /** 图示 + 文字同时显示 */
+    showLabel?: boolean;
+}
+/** 图示选项块：等宽网格，选中 = accent-soft + accent 描边 */
+export declare function OptionGrid<V extends string>({ options, value, onChange, cols, tall, }: {
+    options: OptionItem<V>[];
+    value: V | null | undefined;
+    onChange: (v: V) => void;
+    cols?: number;
+    /** 图块（上图下字，54px 高） */
+    tall?: boolean;
+}): import("react/jsx-runtime").JSX.Element;
+/** 文字分段（连体描边 Segmented，满宽） */
+export declare function Seg<V extends string>({ label, options, value, onChange, }: {
+    label: string;
+    options: {
+        value: V;
+        label?: string;
+        icon?: import("lucide-react").LucideIcon;
+    }[];
+    value: V;
+    onChange: (v: V) => void;
+}): import("react/jsx-runtime").JSX.Element;
+/** 小图示 svg（28×14 画布，stroke = currentColor） */
+export declare function Glyph({ children }: {
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+/** 线宽档位：横条高度 = 线宽（封顶 8px） */
+export declare function LineWeightGlyph({ width }: {
+    width: number;
+}): import("react/jsx-runtime").JSX.Element;
+/** 圆角档位：左上折角的圆角 = radius / 2（封顶 10px）；0 即直角 */
+export declare function CornerGlyph({ radius }: {
+    radius: number;
+}): import("react/jsx-runtime").JSX.Element;
+/** 不透明度档位：色块浓度 = currentColor 与透明的混合 + 内嵌细描边 */
+export declare function OpacityGlyph({ opacity }: {
+    opacity: number;
+}): import("react/jsx-runtime").JSX.Element;

package/types/packages/whiteboard/src/components/SketchPaths/index.d.ts

@@ -0,0 +1,9 @@
+import type { SketchPath } from "../../utils/sketch/types";
+interface SketchPathsProps {
+    paths: SketchPath[];
+    /** 虚线流动：遮罩 dashoffset 走完一个周期的秒数；不传则静止 */
+    dashFlowDuration?: number;
+}
+/** 渲染 utils/sketch 的输出：墨迹与淡涂是填充多边形，线类填充裁剪在轮廓内，虚线经遮罩切段 */
+declare const SketchPaths: import("react").MemoExoticComponent<({ paths, dashFlowDuration }: SketchPathsProps) => import("react/jsx-runtime").JSX.Element>;
+export default SketchPaths;

package/types/packages/whiteboard/src/components/SketchPopover.d.ts

@@ -0,0 +1,43 @@
+import type { BoardElement } from "../types/element";
+import type { PageSketch, SketchFillStyle, SketchLevel, SketchMode } from "../types/sketch";
+type ModeChoice = SketchMode | "inherit";
+export declare const randomSeed: () => number;
+export declare const isPaintedFill: (color?: string) => boolean;
+interface SketchFieldsProps {
+    page: PageSketch;
+    /** 当前画风选项；多选不一致时为 null（不高亮） */
+    mode: ModeChoice | null;
+    level: SketchLevel | null;
+    levelFollowsPage: boolean;
+    /** 是否有元素生效为手绘：决定是否展示笔触 / 填充 / 换一笔 */
+    enabled: boolean;
+    seed: number;
+    fill?: {
+        color: string;
+        style: SketchFillStyle | null;
+    };
+    onMode: (v: ModeChoice) => void;
+    onLevel: (v: SketchLevel) => void;
+    onFillStyle: (v: SketchFillStyle) => void;
+    onReseed: () => void;
+    hint?: string;
+}
+/** 单选与多选共用的「笔触」弹层内容 */
+export declare function SketchFields(props: SketchFieldsProps): import("react/jsx-runtime").JSX.Element;
+interface SketchPopoverProps<T extends BoardElement> {
+    /** 存覆盖的元素：一般是选中元素本身，思维导图是根节点 */
+    target: T;
+    onChange: (next: T) => void;
+    /** 形状才有：填充样式（有填充色时显示） */
+    fill?: {
+        color?: string;
+        style?: SketchFillStyle;
+        onChange: (style: SketchFillStyle) => void;
+    };
+}
+/**
+ * 元素级「笔触」（D-107）：画风（跟随页面 / 手绘 / 普通）· 笔触档位 · 填充 · 换一笔。
+ * 未单独设置的字段跟随页面，选「跟随页面」即删除覆盖。
+ */
+declare function SketchPopover<T extends BoardElement>({ target, onChange, fill }: SketchPopoverProps<T>): import("react/jsx-runtime").JSX.Element;
+export default SketchPopover;