wendang 0.0.1 → 0.1.0

package/LICENSE

@@ -0,0 +1,3 @@
+UNLICENSED
+
+No license to use, copy, modify or distribute the Wendang source is granted by this file. Contact the maintainer for terms. Third-party components retain their own licenses; see NOTICE.md.

package/NOTICE.md

@@ -0,0 +1,7 @@
+# Third-party notices
+
+Generated from the installed runtime dependency graph; package licenses remain unchanged.
+Wendang itself remains UNLICENSED. This inventory is not a grant of rights or a statement that optional Pro services are included.
+
+| Package | Version | Declared license | Included upstream notice |
+| --- | --- | --- | --- |

package/README.md

@@ -1,5 +1,104 @@
 # wendang
 
-项目筹备中，当前版本暂不提供可用功能。
+文档、电子表格、思维导图的内容协议与校验核心。适用于前端数据层和 Node 服务端，不包含可视编辑器。当前源码 0.1.0 为开发版，npm 0.0.1 仅为占位。
 
-This package is under development. No public API is available yet.
+源码位于 [ztes/wendang 的 packages/core](https://gitee.com/ztes/wendang/tree/main/packages/core)。本项目单仓双包维护，开发、问题和版本规范见 [仓库 README](https://gitee.com/ztes/wendang/blob/main/README.md)。
+
+## 安装与使用
+
+对应版本正式发布后：
+
+```sh
+npm install wendang
+```
+
+```ts
+import { ContentSchemaService, SCHEMA_VERSION } from 'wendang/schema'
+import { emptyWorkbook, validateWorkbook } from 'wendang/spreadsheet'
+import { createMindMap, readMindMap, mindMapToJson } from 'wendang/mindmap'
+import type { ProseMirrorDoc, WorkbookDocument } from 'wendang/types'
+
+const result = new ContentSchemaService().validate({
+  type: 'doc',
+  content: [{ type: 'paragraph', content: [{ type: 'text', text: '你好' }] }],
+}, SCHEMA_VERSION)
+
+const book = validateWorkbook(emptyWorkbook(crypto.randomUUID()))
+const map = readMindMap(createMindMap('both'))
+```
+
+支持 Node >=20.19、ESM 和 CommonJS：
+
+```js
+const { ContentSchemaService, SCHEMA_VERSION } = require('wendang/schema')
+const result = new ContentSchemaService().validate(
+  { type: 'doc', content: [{ type: 'paragraph' }] },
+  SCHEMA_VERSION,
+)
+```
+
+同步校验不发网络请求，不初始化框架、登录、数据库或 DOM。布局默认使用确定的保守度量，Vue 层按需注入浏览器字体度量；核心不执行 Excel 公式。
+
+## API 入口
+
+| 入口 | 内容 |
+| --- | --- |
+| `wendang` | schema、版本、主要类型、创建工作簿 / 导图 |
+| `wendang/schema` | `ContentSchemaService`、`ContentValidationError`、`SCHEMA_VERSION`、节点 / mark 白名单 |
+| `wendang/document` | 文档类型、节点目录、文本工具和 schema |
+| `wendang/spreadsheet` | 工作簿类型、`emptyWorkbook`、`validateWorkbook`、`workbookText` |
+| `wendang/mindmap` | 创建 / 解析 / 序列化、布局、分支、搜索及校验 |
+| `wendang/types` | 内容、工作簿、导图和讨论类型 |
+
+`internal/*` / `validation/*` 仅为现有应用迁移兼容入口，三方新增代码优先使用上表入口，不依赖 dist 深层文件。
+
+## 文档校验与服务端规范
+
+`new ContentSchemaService().validate(raw, schemaVersion)` 返回：
+
+- `doc`、`schemaVersion`：按支持规则校验 / 处理后的内容；
+- `attachmentIds`、`linkTargetIds`、`mentionUserIds`：供业务授权、引用、通知使用。
+
+失败抛 `ContentValidationError`，包含 `message`、`code`（`validation.failed`）、`status`（422）、可选 `details`；宿主自行转为框架异常。schemaVersion 必须为正整数。未知节点拒绝，普通脏属性按白名单处理，未知更高版本拒绝写入。
+
+**校验不等于授权。** 后端仍需检查写入权限、附件归属、引用可见性和审批发布；前端检查不替代后端。当前普通文档 schemaVersion 为 **10**，不是 npm 包版本。
+
+当前协议的页面、用户、附件引用使用 UUID。宿主若使用数字或其他业务主键，应建立稳定映射；不要把存储 URL 或临时 token 当作 ID。
+
+## 工作簿规范
+
+```ts
+const doc = emptyWorkbook(crypto.randomUUID())
+doc.workbook.sheets.sheet1.cellData = {
+  0: {
+    0: { v: 12, t: 2 },
+    1: { f: '=A1*2', v: 24, t: 2 },
+  },
+}
+const snapshot = validateWorkbook(doc)
+```
+
+根为 `{ type: 'workbook', formatVersion: 1, workbook: ... }`。`f` 为表达式，`v` 为数值或保存的公式缓存。最多 20 Sheet、每表 10000 行 / 200 列、实际单元格总数 50000、JSON 4MiB。验证拒绝危险属性、非法值、越界、重叠合并，并返回独立快照。
+
+workbook 含 Univer 1.1.0 兼容数据与资源，是已版本化的引擎适配格式；不承诺任意引擎大版本无损兼容。XLSX 转换在 `wendang-vue/spreadsheet/xlsx`，本包不引入 ExcelJS。
+
+## 思维导图规范
+
+`createMindMap(layout)` 创建持久化 `MindMapJson`，`readMindMap(json)` 返回 `MindMapModel | null`，`mindMapToJson(model)` 序列化。当前 formatVersion 为 **3**，支持读取已有受支持旧版。
+
+主题和关系线使用稳定 ID；主题包含 parentId、order、文字及可选富文本、描述、备注、附件与样式。单图最多 500 主题，标题 2000 字符。视口、选区、折叠属于视图状态。复制分支重建身份，不能直接沿用旧讨论锚点。
+
+## 升级与扩展
+
+1. SDK semver、文档 schemaVersion、工作簿 / 导图 formatVersion 分开管理。
+2. 关闭新增按钮不能剥离已有内容；不支持的更高版本提示升级或只读保留。
+3. 不把 HTML、截图或绘图坐标当作唯一源数据。
+4. 核心不自动迁移宿主数据库；迁移必须有明确操作、样本和回退，失败保留原文。
+5. 自定义节点必须同步编辑、阅读、校验和导出，不仅放宽前端 JSON。
+6. ESM / CommonJS 通过实际 tarball 消费验证，禁止靠源码路径掩盖缺失导出。
+
+## 开发与发布
+
+在仓库根运行 `pnpm build`、`pnpm test`、`pnpm typecheck`、`pnpm pack:all`、`pnpm check:package`。只发布 dist、文档及许可文件。完整本地 link 和发布流程见仓库 README。
+
+当前许可 `UNLICENSED`；维护者另行决定自身授权，不改变第三方依赖授权边界。

package/dist/cjs/document.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./schema.js"), exports);
+__exportStar(require("./shared/node-catalog.js"), exports);
+__exportStar(require("./shared/doc-text.js"), exports);

package/dist/cjs/index.js

@@ -0,0 +1,25 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mindMapToJson = exports.readMindMap = exports.createMindMap = exports.validateWorkbook = exports.emptyWorkbook = void 0;
+__exportStar(require("./schema.js"), exports);
+var spreadsheet_js_1 = require("./spreadsheet.js");
+Object.defineProperty(exports, "emptyWorkbook", { enumerable: true, get: function () { return spreadsheet_js_1.emptyWorkbook; } });
+Object.defineProperty(exports, "validateWorkbook", { enumerable: true, get: function () { return spreadsheet_js_1.validateWorkbook; } });
+var mindmap_js_1 = require("./mindmap.js");
+Object.defineProperty(exports, "createMindMap", { enumerable: true, get: function () { return mindmap_js_1.createMindMap; } });
+Object.defineProperty(exports, "readMindMap", { enumerable: true, get: function () { return mindmap_js_1.readMindMap; } });
+Object.defineProperty(exports, "mindMapToJson", { enumerable: true, get: function () { return mindmap_js_1.mindMapToJson; } });

package/dist/cjs/mindmap.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateMindMap = void 0;
+__exportStar(require("./shared/mind-map.js"), exports);
+__exportStar(require("./shared/mind-map-phase2.js"), exports);
+__exportStar(require("./shared/mind-map-folding.js"), exports);
+var mind_map_js_1 = require("./validation/mind-map.js");
+Object.defineProperty(exports, "validateMindMap", { enumerable: true, get: function () { return mind_map_js_1.validateMindMap; } });

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/schema.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALLOWED_MARKS = exports.ALLOWED_NODES = exports.ContentValidationError = exports.SCHEMA_VERSION = exports.ContentSchemaService = void 0;
+var schema_js_1 = require("./validation/schema.js");
+Object.defineProperty(exports, "ContentSchemaService", { enumerable: true, get: function () { return schema_js_1.ContentSchemaService; } });
+Object.defineProperty(exports, "SCHEMA_VERSION", { enumerable: true, get: function () { return schema_js_1.SCHEMA_VERSION; } });
+var error_js_1 = require("./validation/error.js");
+Object.defineProperty(exports, "ContentValidationError", { enumerable: true, get: function () { return error_js_1.ContentValidationError; } });
+var doc_node_whitelist_js_1 = require("./validation/doc-node-whitelist.js");
+Object.defineProperty(exports, "ALLOWED_NODES", { enumerable: true, get: function () { return doc_node_whitelist_js_1.ALLOWED_NODES; } });
+Object.defineProperty(exports, "ALLOWED_MARKS", { enumerable: true, get: function () { return doc_node_whitelist_js_1.ALLOWED_MARKS; } });

package/dist/cjs/shared/anchor.js

@@ -0,0 +1,201 @@
+"use strict";
+/**
+ * 行内评论的锚点定位（纯函数，可单测）。
+ *
+ * ## 为什么不能存位置
+ *
+ * 直觉做法是「记录选中文字的 start/end 偏移」。但文档会被编辑：
+ * 在选区前面插入一个字，所有后续位置全部偏移——锚点立刻指向错误文字，
+ * 而且**错得很安静**（评论跑到别的地方，没人会立刻发现）。
+ *
+ * ## 采用方案：文本引用（TextQuoteSelector 思路，W3C Web Annotation）
+ *
+ * 存三样东西：
+ *  - `quote`：选中的原文
+ *  - `prefix` / `suffix`：前后各一小段上下文（用于区分重复文本）
+ *
+ * 定位时在文档纯文本里搜索 quote；有多处命中时，用 prefix/suffix 的匹配长度打分，
+ * 取最匹配的一处。这样：
+ *  - 在文档**别处**编辑（不碰该段文字）→ 锚点依然准确定位；
+ *  - 该段文字本身被改动 → 匹配不到，此时用 prefix+suffix 的接缝尽力定位，
+ *    返回一个「降级」结果（exact=false），前端据此提示「原文已改动」；
+ *  - 完全找不到（整段被删）→ 返回 null，前端把评论归入「已失联」，
+ *    **而不是指向一处无关文字**。
+ *
+ * 宁可显示「已失联」，也不要指向错误位置——后者会让用户读到与上下文无关的评论，
+ * 比看得见的缺失更有害。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ANCHOR_QUOTE_MAX = exports.ANCHOR_CONTEXT_LENGTH = void 0;
+exports.flattenDocText = flattenDocText;
+exports.locateBlock = locateBlock;
+exports.resolveAnchor = resolveAnchor;
+exports.commonSuffixLength = commonSuffixLength;
+exports.commonPrefixLength = commonPrefixLength;
+exports.clipContext = clipContext;
+/** 上下文最大长度（与提交时截断长度一致）。 */
+exports.ANCHOR_CONTEXT_LENGTH = 64;
+exports.ANCHOR_QUOTE_MAX = 500;
+/**
+ * 把若干块文本拼成扁平文本，记录片段边界。
+ * 块之间插入换行（可用块间匹配不应跨越块边界，换行同时避免把块首块尾误连成词）。
+ */
+function flattenDocText(blocks) {
+    const segments = [];
+    let text = '';
+    blocks.forEach((blockText, blockIndex) => {
+        if (blockIndex > 0)
+            text += '\n';
+        segments.push({ start: text.length, blockIndex, length: blockText.length });
+        text += blockText;
+    });
+    return { text, segments };
+}
+/** 由扁平字符偏移定位到 (块索引, 块内偏移)。 */
+function locateBlock(flat, charOffset) {
+    for (const seg of flat.segments) {
+        if (charOffset >= seg.start && charOffset <= seg.start + seg.length) {
+            return { blockIndex: seg.blockIndex, offsetInBlock: charOffset - seg.start };
+        }
+    }
+    // 落在块间换行或末尾时，归到最后一个片段
+    const last = flat.segments[flat.segments.length - 1];
+    if (!last)
+        return null;
+    if (charOffset > last.start + last.length) {
+        return { blockIndex: last.blockIndex, offsetInBlock: last.length };
+    }
+    return null;
+}
+/**
+ * 定位锚点。返回 null 表示无法可信定位（整段被删），调用方应标记为「已失联」。
+ */
+function resolveAnchor(text, anchor) {
+    const quote = (anchor.quote ?? '').trim();
+    if (quote.length === 0)
+        return null;
+    const prefix = anchor.prefix ?? '';
+    const suffix = anchor.suffix ?? '';
+    const expectedStart = anchor.start ?? -1;
+    // 1) 收集 quote 的全部出现位置
+    const candidates = [];
+    let idx = text.indexOf(quote);
+    while (idx !== -1) {
+        candidates.push(idx);
+        // 从下一个字符继续，避免重叠匹配导致死循环
+        idx = text.indexOf(quote, idx + 1);
+    }
+    if (candidates.length > 0) {
+        let best = null;
+        for (const start of candidates) {
+            const score = scoreCandidate(text, start, quote.length, prefix, suffix, expectedStart);
+            if (!best || score > best.score)
+                best = { start, score };
+        }
+        if (best) {
+            return {
+                from: best.start,
+                to: best.start + quote.length,
+                score: best.score,
+                exact: true,
+            };
+        }
+    }
+    // 2) quote 已不在文档中：用上下文降级定位，返回零长度锚点。
+    //    两种情况：
+    //    a) quote 整段被删除 → prefix 与 suffix 在文档中相邻，用接缝精确落点；
+    //    b) quote 被改写但上下文还在 → 用较长的一侧贴住，落在其边缘。
+    //    两者都标记 exact=false，前端据此提示「原文已改动」。
+    // 2a) prefix 与 suffix 相邻（说明中间的原引用被删掉了）
+    if (prefix.length > 0 && suffix.length > 0) {
+        const needle = prefix + suffix;
+        const at = text.indexOf(needle);
+        if (at !== -1) {
+            const pos = at + prefix.length;
+            return { from: pos, to: pos, score: 50, exact: false };
+        }
+    }
+    // 2b) 用较长的一侧贴住边缘。
+    //     注意两点（都是实测教训）：
+    //     - 阈值取 4 而非 8：中文一个词常只有 2–4 字，阈值过高会让中文文档
+    //       几乎无法降级定位；
+    //     - 必须遍历**全部**出现位置并取最接近原偏移的那个：
+    //       短上下文在文档中可能重复，取首个出现会落到错误位置。
+    const side = prefix.length >= suffix.length ? prefix : suffix;
+    if (side.length >= 4) {
+        const at = nearestOccurrence(text, side, expectedStart);
+        if (at !== -1) {
+            const pos = prefix.length >= suffix.length ? at + side.length : at;
+            return { from: pos, to: pos, score: 10, exact: false };
+        }
+    }
+    return null;
+}
+/**
+ * 在文本中找出 needle 的全部出现位置，返回最接近 expected 的那个。
+ * expected < 0（无提示）时退化为返回第一个出现位置。
+ * 这样短上下文重复时不会盲目落到首次出现处。
+ */
+function nearestOccurrence(text, needle, expected) {
+    if (needle.length === 0)
+        return -1;
+    const positions = [];
+    let idx = text.indexOf(needle);
+    while (idx !== -1) {
+        positions.push(idx);
+        if (positions.length > 500)
+            break; // 防御：极端重复文本
+        idx = text.indexOf(needle, idx + 1);
+    }
+    if (positions.length === 0)
+        return -1;
+    if (expected < 0)
+        return positions[0];
+    let best = positions[0];
+    for (const p of positions) {
+        if (Math.abs(p - expected) < Math.abs(best - expected))
+            best = p;
+    }
+    return best;
+}
+/**
+ * 给候选位置打分：
+ *  - 引用本身匹配是基础分；
+ *  - 前后文匹配越长越可信（能区分「同一句话在文档里出现多次」）；
+ *  - 与提交时偏移越近，略微加分（仅在文本重复且上下文缺失时起作用）。
+ */
+function scoreCandidate(text, start, quoteLength, prefix, suffix, expectedStart) {
+    let score = 1000;
+    if (prefix.length > 0) {
+        const actualPrefix = text.slice(Math.max(0, start - prefix.length), start);
+        score += commonSuffixLength(actualPrefix, prefix) * 4;
+    }
+    if (suffix.length > 0) {
+        const actualSuffix = text.slice(start + quoteLength, start + quoteLength + suffix.length);
+        score += commonPrefixLength(actualSuffix, suffix) * 4;
+    }
+    if (expectedStart >= 0) {
+        score -= Math.min(Math.abs(start - expectedStart), 200);
+    }
+    return score;
+}
+/** 两个字符串从末尾开始相同的字符数。 */
+function commonSuffixLength(a, b) {
+    let n = 0;
+    while (n < a.length && n < b.length && a[a.length - 1 - n] === b[b.length - 1 - n]) {
+        n += 1;
+    }
+    return n;
+}
+/** 两个字符串从头开始相同的字符数。 */
+function commonPrefixLength(a, b) {
+    let n = 0;
+    while (n < a.length && n < b.length && a[n] === b[n]) {
+        n += 1;
+    }
+    return n;
+}
+/** 截断上下文到限定长度（提交时使用）。 */
+function clipContext(text) {
+    return text.slice(0, exports.ANCHOR_CONTEXT_LENGTH);
+}

package/dist/cjs/shared/callout.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CALLOUT_FILLS = exports.CALLOUT_COLORS = exports.CALLOUT_ICONS = exports.CALLOUT_TONES = void 0;
+exports.validCalloutAttrs = validCalloutAttrs;
+exports.effectiveCallout = effectiveCallout;
+exports.calloutDOMAttributes = calloutDOMAttributes;
+exports.calloutMetadata = calloutMetadata;
+exports.readCalloutMetadata = readCalloutMetadata;
+/** Document attributes only; shared with server validation by a source parity test. */
+exports.CALLOUT_TONES = ['info', 'success', 'warning', 'danger'];
+exports.CALLOUT_ICONS = ['💡', 'ℹ️', '✅', '⚠️', '❗', '📌', '🎯', '💬', '📖', '📝', '🚀', '🔔', '🔎', '⭐', '🌅', '🛠️', '📅', '🔒', '❤️', '🎉', '❓', '📎', '🏁', '🔥'];
+exports.CALLOUT_COLORS = ['gray', 'red', 'orange', 'yellow', 'green', 'blue', 'purple'];
+exports.CALLOUT_FILLS = [...exports.CALLOUT_COLORS, ...exports.CALLOUT_COLORS.map(c => `${c}-strong`)];
+function validCalloutAttrs(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return false;
+    const attrs = raw;
+    const valid = (key, values) => attrs[key] === undefined || attrs[key] === null ||
+        (typeof attrs[key] === 'string' && values.includes(attrs[key]));
+    return valid('tone', exports.CALLOUT_TONES) && valid('icon', ['', ...exports.CALLOUT_ICONS]) && valid('textColor', exports.CALLOUT_COLORS) &&
+        valid('borderColor', ['none', ...exports.CALLOUT_COLORS]) && valid('backgroundColor', ['none', ...exports.CALLOUT_FILLS]);
+}
+function effectiveCallout(attrs = {}) {
+    const tone = exports.CALLOUT_TONES.includes(attrs.tone) ? attrs.tone : 'info';
+    const hue = { info: 'blue', success: 'green', warning: 'orange', danger: 'red' }[tone];
+    return { tone, icon: attrs.icon === null || attrs.icon === undefined ? { info: '💡', success: '✅', warning: '⚠️', danger: '❗' }[tone] :
+            ['', ...exports.CALLOUT_ICONS].includes(attrs.icon) ? attrs.icon : '💡',
+        textColor: exports.CALLOUT_COLORS.includes(attrs.textColor) ? attrs.textColor : null,
+        borderColor: ['none', ...exports.CALLOUT_COLORS].includes(attrs.borderColor) ? attrs.borderColor : hue,
+        backgroundColor: ['none', ...exports.CALLOUT_FILLS].includes(attrs.backgroundColor) ? attrs.backgroundColor : hue };
+}
+function calloutDOMAttributes(attrs = {}) {
+    const value = effectiveCallout(attrs);
+    return { 'data-callout': 'true', 'data-tone': value.tone, 'data-callout-icon': attrs.icon ?? 'default',
+        ...Object.fromEntries(['textColor', 'borderColor', 'backgroundColor'].filter(key => attrs[key] != null)
+            .map(key => [`data-callout-${key.toLowerCase()}`, String(attrs[key])])),
+        ...(value.icon === '' ? { 'data-icon-hidden': 'true' } : {}),
+        style: [`--callout-border:${value.borderColor === 'none' ? 'transparent' : `var(--callout-border-${value.borderColor})`}`,
+            `--callout-fill:${value.backgroundColor === 'none' ? 'transparent' : `var(--doc-highlight-${value.backgroundColor === 'gray' ? 'gray-soft' : value.backgroundColor})`}`,
+            `--callout-text:${value.textColor ? `var(--doc-text-${value.textColor})` : 'var(--content-text-color, var(--color-text))'}`].join(';') };
+}
+/** Optional Markdown metadata never contains free CSS or HTML. */
+function calloutMetadata(attrs) {
+    if (!validCalloutAttrs(attrs))
+        return '';
+    const extra = Object.fromEntries(['icon', 'textColor', 'borderColor', 'backgroundColor']
+        .filter(key => attrs[key] !== undefined && attrs[key] !== null)
+        .map(key => [key, attrs[key]]));
+    return Object.keys(extra).length ? ` <!--ywiki-callout:${encodeURIComponent(JSON.stringify(extra))}-->` : '';
+}
+function readCalloutMetadata(text) {
+    const match = /^\s*<!--ywiki-callout:([^\s<>]{1,4096})-->\s*/.exec(text);
+    if (!match)
+        return null;
+    try {
+        const attrs = JSON.parse(decodeURIComponent(match[1]));
+        if (!validCalloutAttrs(attrs) || Object.keys(attrs).some(k => !['icon', 'textColor', 'borderColor', 'backgroundColor'].includes(k)))
+            return null;
+        return { attrs, length: match[0].length };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/cjs/shared/code-block.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CODE_THEMES = void 0;
+exports.codeBlockDisplay = codeBlockDisplay;
+exports.rememberCodeTheme = rememberCodeTheme;
+exports.codeLineCount = codeLineCount;
+exports.codeLineNumbers = codeLineNumbers;
+exports.codeBlockClass = codeBlockClass;
+/** Presentation metadata only; code, whitespace and the document schema remain unchanged. */
+exports.CODE_THEMES = [
+    { value: 'auto', label: '跟随页面' },
+    { value: 'paper', label: '纸白' },
+    { value: 'soft', label: '柔和' },
+    { value: 'night', label: '深色' },
+];
+function codeBlockDisplay() {
+    return { collapsed: false, lineNumbers: true, limited: true, theme: 'auto' };
+}
+function rememberCodeTheme(_theme) { }
+function codeLineCount(text) {
+    let count = 1;
+    for (let i = 0; i < text.length; i++)
+        if (text[i] === '\n')
+            count++;
+    return count;
+}
+function codeLineNumbers(text) {
+    return Array.from({ length: codeLineCount(text) }, (_, i) => String(i + 1)).join('\n');
+}
+function codeBlockClass(display) {
+    return ['ywiki-code-panel', `code-theme-${display.theme}`, ...(display.collapsed ? ['is-collapsed'] : []),
+        ...(display.lineNumbers ? [] : ['without-line-numbers']), ...(display.limited ? [] : ['is-unlimited'])];
+}

package/dist/cjs/shared/code-languages.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CODE_LANGUAGES = void 0;
+exports.codeLanguageLabel = codeLanguageLabel;
+exports.isKnownCodeLanguage = isKnownCodeLanguage;
+/** 空字符串表示「纯文本 / 不指定」。 */
+exports.CODE_LANGUAGES = [
+    { value: '', label: '纯文本' },
+    { value: 'bash', label: 'Bash / Shell' },
+    { value: 'json', label: 'JSON' },
+    { value: 'yaml', label: 'YAML' },
+    { value: 'sql', label: 'SQL' },
+    { value: 'markdown', label: 'Markdown' },
+    { value: 'diff', label: 'Diff' },
+    { value: 'javascript', label: 'JavaScript' },
+    { value: 'typescript', label: 'TypeScript' },
+    { value: 'jsx', label: 'JSX' },
+    { value: 'tsx', label: 'TSX' },
+    { value: 'python', label: 'Python' },
+    { value: 'java', label: 'Java' },
+    { value: 'go', label: 'Go' },
+    { value: 'rust', label: 'Rust' },
+    { value: 'c', label: 'C' },
+    { value: 'cpp', label: 'C++' },
+    { value: 'csharp', label: 'C#' },
+    { value: 'php', label: 'PHP' },
+    { value: 'ruby', label: 'Ruby' },
+    { value: 'kotlin', label: 'Kotlin' },
+    { value: 'swift', label: 'Swift' },
+    { value: 'html', label: 'HTML' },
+    { value: 'css', label: 'CSS' },
+    { value: 'xml', label: 'XML' },
+    { value: 'dockerfile', label: 'Dockerfile' },
+    { value: 'ini', label: 'INI / TOML' },
+];
+const LABEL_BY_VALUE = new Map(exports.CODE_LANGUAGES.map((l) => [l.value, l.label]));
+/**
+ * 取语言的展示标签。
+ *
+ * 未知语言（如用户从 Markdown 导入的少见围栏标记）直接显示原值——
+ * 不隐藏、不改写，避免"我明明标了语言却看不到"。
+ */
+function codeLanguageLabel(value) {
+    if (!value)
+        return '';
+    return LABEL_BY_VALUE.get(value) ?? value;
+}
+/** 是否为目录内已知语言（用于选择器回显：未知值时追加一个临时选项）。 */
+function isKnownCodeLanguage(value) {
+    return LABEL_BY_VALUE.has(value);
+}

package/dist/cjs/shared/doc-compatibility.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.supportsDocument = supportsDocument;
+const node_catalog_js_1 = require("./node-catalog.js");
+const schema_js_1 = require("../schema.js");
+const mind_map_js_1 = require("./mind-map.js");
+const callout_js_1 = require("./callout.js");
+function supportsDocument(raw, version = 1) {
+    if (version > schema_js_1.SCHEMA_VERSION)
+        return false;
+    if (!raw)
+        return true;
+    if (typeof raw !== 'object')
+        return false;
+    const doc = raw;
+    if (!doc.type || !(0, node_catalog_js_1.nodeMeta)(doc.type))
+        return false;
+    if (doc.type === 'mindMap' && !(0, mind_map_js_1.readMindMap)(doc))
+        return false;
+    if (doc.type === 'callout' && !(0, callout_js_1.validCalloutAttrs)(doc.attrs ?? {}))
+        return false;
+    return !doc.content || Array.isArray(doc.content) && doc.content.every(node => supportsDocument(node));
+}

package/dist/cjs/shared/doc-text.js

@@ -0,0 +1,52 @@
+"use strict";
+/**
+ * 从 ProseMirror 文档提取用于锚点定位的块级纯文本。
+ *
+ * 与 anchor.ts 配合：锚点用「在扁平文本中的字符偏移」表达，
+ * 这里负责把文档结构摊平，并保留「块 → 字符区间」的映射，
+ * 以便把定位结果映射回具体的块（前端据此在对应块上加高亮）。
+ *
+ * 与后端 DocSchemaService.extractPlainText 保持一致的遍历顺序（先文本、后子节点），
+ * 否则同一段内容在提交锚点与解析锚点时会得到不同的字符偏移。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractBlockTexts = extractBlockTexts;
+exports.plainTextOf = plainTextOf;
+/** 提取顶层块（含嵌套块）的纯文本。列表会递归取出每一项。 */
+function extractBlockTexts(doc) {
+    const blocks = [];
+    const walk = (node, topIndex) => {
+        // 块级容器（段落/标题/列表项/引用/代码块等）各自作为一个「块」
+        const isBlockContainer = [
+            'paragraph',
+            'heading',
+            'codeBlock',
+            'blockquote',
+            'listItem',
+            'taskItem',
+            'tableCell',
+            'tableHeader',
+            'mindMapTopic',
+        ].includes(node.type ?? '');
+        if (isBlockContainer) {
+            blocks.push({ index: topIndex, text: plainTextOf(node) });
+            return;
+        }
+        for (const child of node.content ?? [])
+            walk(child, topIndex);
+    };
+    (doc?.content ?? []).forEach((node, i) => walk(node, i));
+    return blocks.filter((b) => b.text.length > 0);
+}
+/** 取节点的全部文本（含后代）。 */
+function plainTextOf(node) {
+    const buf = [];
+    const walk = (n) => {
+        if (typeof n.text === 'string')
+            buf.push(n.text);
+        for (const c of n.content ?? [])
+            walk(c);
+    };
+    walk(node);
+    return buf.join('');
+}