wendang 0.0.1 → 0.1.0

package/dist/esm/shared/node-catalog.js

@@ -0,0 +1,57 @@
+/**
+ * 节点目录：编辑器的 nodeView 与只读渲染规则**共用的单一真源**
+ * （对齐《Wiki好用技术方案》1.1）。
+ *
+ * 这里只放纯数据（无 Vue、无 Tiptap 依赖），因此阅读端可以只引它 + Renderer，
+ * 而完全不加载编辑器代码；编辑器端再基于同一份目录生成扩展。
+ *
+ * 新增节点时必须同时更新：
+ *  1) 本目录  2) 服务端 doc-schema.service.ts 白名单  3) 提升 schema 版本
+ * 否则旧客户端会因「遇到不支持节点」而被服务端拒写（这是预期行为，避免静默丢内容）。
+ */
+export const NODE_CATALOG = [
+    { type: 'doc', kind: 'block', label: '文档', topLevel: true },
+    { type: 'paragraph', kind: 'block', label: '段落', topLevel: true },
+    { type: 'heading', kind: 'block', label: '标题', topLevel: true },
+    { type: 'bulletList', kind: 'block', label: '无序列表', topLevel: true },
+    { type: 'orderedList', kind: 'block', label: '有序列表', topLevel: true },
+    { type: 'taskList', kind: 'block', label: '待办列表', topLevel: true },
+    { type: 'listItem', kind: 'block', label: '列表项' },
+    { type: 'taskItem', kind: 'block', label: '待办项' },
+    { type: 'blockquote', kind: 'block', label: '引用块', topLevel: true },
+    { type: 'codeBlock', kind: 'block', label: '代码块', topLevel: true },
+    { type: 'horizontalRule', kind: 'atom', atom: true, label: '分割线', topLevel: true },
+    { type: 'table', kind: 'block', label: '表格', topLevel: true },
+    { type: 'tableRow', kind: 'block', label: '表格行' },
+    { type: 'tableHeader', kind: 'block', label: '表头单元格' },
+    { type: 'tableCell', kind: 'block', label: '单元格' },
+    { type: 'image', kind: 'atom', atom: true, label: '图片', topLevel: true },
+    { type: 'fileAttachment', kind: 'atom', atom: true, label: '视频或文件', topLevel: true },
+    { type: 'videoEmbed', kind: 'atom', atom: true, label: '嵌入视频', topLevel: true },
+    { type: 'mindMap', kind: 'block', label: '思维导图', topLevel: true },
+    { type: 'mindMapDescription', kind: 'inline', label: '主题描述' },
+    { type: 'mindMapNote', kind: 'inline', label: '主题备注' },
+    { type: 'mindMapRelation', kind: 'block', label: '主题关系' },
+    { type: 'mindMapTopic', kind: 'block', label: '导图主题' },
+    { type: 'callout', kind: 'block', label: '高亮块', topLevel: true },
+    // 分栏：columns 是顶层行，column 只在其内部（故 column 无 topLevel）
+    { type: 'columns', kind: 'block', label: '分栏', topLevel: true },
+    { type: 'column', kind: 'block', label: '栏' },
+    { type: 'pageLink', kind: 'atom', atom: true, label: '页面引用' },
+    { type: 'mention', kind: 'atom', atom: true, label: '提及用户' },
+    { type: 'mathInline', kind: 'atom', atom: true, label: '行内公式' },
+    { type: 'mathBlock', kind: 'atom', atom: true, label: '公式块', topLevel: true },
+    { type: 'text', kind: 'text', label: '文本' },
+    { type: 'hardBreak', kind: 'inline', atom: true, label: '换行' },
+];
+const META_BY_TYPE = new Map(NODE_CATALOG.map((n) => [n.type, n]));
+export function nodeMeta(type) {
+    return type ? META_BY_TYPE.get(type) : undefined;
+}
+/** 只读渲染遇到未知节点时使用的降级提示（不静默丢弃，向用户明示）。 */
+export const UNKNOWN_NODE_LABEL = '此内容由更高版本的编辑器创建，当前版本无法显示';
+/** 标题级别 → HTML 标签 */
+export function headingTag(level) {
+    const n = typeof level === 'number' ? level : 1;
+    return `h${Math.min(Math.max(n, 1), 6)}`;
+}

package/dist/esm/shared/presence.js

@@ -0,0 +1,130 @@
+/**
+ * 协同在线状态（presence）的纯逻辑（可单测，不依赖 DOM / Yjs / 网络）。
+ *
+ * ## 为什么单独抽出来
+ *
+ * 在线状态有两个容易做错、且出错后**不报错、只是显示不对**的地方：
+ *  1) 颜色分配：同一用户在不同客户端必须得到**相同颜色**（否则"那个蓝色光标是谁"
+ *     无法对应），而颜色若只按"连接顺序"分，B 客户端上同一个人的颜色就会变。
+ *     因此颜色必须由**用户身份**稳定推导，不能依赖顺序或随机。
+ *  2) 对比度：名字气泡上的文字要与背景色对比可读；简单地对 6 个色相取固定亮度，
+ *     在浅色模式下会有几个色相偏亮、白字看不清。
+ * 这些都能用纯函数锁定，因此放在这里。
+ */
+/**
+ * 稳定的用户色板。
+ *
+ * 选取标准不是"好看"，而是**所有颜色配白字都达到 WCAG AA（≥4.5:1）**——
+ * 这样光标/名字气泡永远是"彩色底 + 白字"，视觉一致，也不会出现浅底白字看不清。
+ * （初版用了偏亮的绿 `#1a9d5a`（3.49:1）与橙 `#d97706`（3.19:1），配白字或深字
+ * 都不到 AA；这里换成更深的一档，由单测锁定对比度。）
+ */
+export const PRESENCE_PALETTE = [
+    '#2f6feb', // 蓝 4.57:1
+    '#127a45', // 绿 5.39:1
+    '#b45309', // 棕橙 5.02:1
+    '#c026d3', // 紫 4.71:1
+    '#dc2626', // 红 4.83:1
+    '#0e7490', // 青 5.36:1
+    '#7c3aed', // 靛 5.70:1
+    '#9a4a08', // 深橙 6.26:1
+];
+/**
+ * 由用户 id 稳定映射到调色板颜色。
+ *
+ * 用 FNV-1a 哈希而非 simple sum：简单的字符求和会让 `user1`/`user2`
+ * 这类相邻 id 落到同一颜色，而实际用户 id 常是顺序生成的。
+ */
+export function colorForUser(userId) {
+    return PRESENCE_PALETTE[hashIndex(userId, PRESENCE_PALETTE.length)];
+}
+/** FNV-1a 32 位哈希 → 取模。 */
+export function hashIndex(input, buckets) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < input.length; i++) {
+        h ^= input.charCodeAt(i);
+        // h *= 16777619（用移位避免大整数精度问题）
+        h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;
+    }
+    return buckets > 0 ? h % buckets : 0;
+}
+/** 名字首字（用于头像占位）。中文取首字，英文取首字母大写。 */
+export function initialOf(displayName) {
+    const t = displayName.trim();
+    if (t === '')
+        return '?';
+    return t.slice(0, 1).toUpperCase();
+}
+/**
+ * 汇总在线用户：去重（同一用户多标签页只显示一次）、排除自己、稳定排序。
+ *
+ * 稳定性很重要：若按 Map 遍历顺序输出，光标/头像列表会随消息到达顺序抖动。
+ * 这里按 displayName 排序，保证界面上顺序稳定。
+ */
+export function collectPresence(states, selfUserId) {
+    const byUser = new Map();
+    for (const s of states) {
+        if (!s.userId)
+            continue;
+        if (selfUserId && s.userId === selfUserId)
+            continue;
+        if (!byUser.has(s.userId)) {
+            byUser.set(s.userId, {
+                userId: s.userId,
+                displayName: s.displayName || '匿名',
+                color: colorForUser(s.userId),
+            });
+        }
+    }
+    return [...byUser.values()].sort((a, b) => a.displayName.localeCompare(b.displayName, 'zh-Hans-CN'));
+}
+/**
+ * 相对亮度（WCAG），用于决定光标/气泡上该用白字还是深字。
+ * 返回 0（黑）~1（白）。
+ */
+export function relativeLuminance(hex) {
+    const rgb = parseHex(hex);
+    if (!rgb)
+        return 0;
+    const [r, g, b] = rgb.map((v) => {
+        const c = v / 255;
+        return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+    });
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+/** 前景深色的基准（与 :root 的 --color-text 接近）。 */
+export const DARK_TEXT = '#1f2937';
+/** WCAG 对比度。 */
+export function contrastRatio(a, b) {
+    const la = relativeLuminance(a);
+    const lb = relativeLuminance(b);
+    const hi = Math.max(la, lb);
+    const lo = Math.min(la, lb);
+    return (hi + 0.05) / (lo + 0.05);
+}
+/**
+ * 该背景色上应使用的前景色。
+ *
+ * 实现为「比较白字与深字各自的对比度，取更高的那个」，而不是用一个亮度阈值判断——
+ * 阈值是脆弱的：初版用 0.179 作分界，`#2f6feb`（亮度 0.180）被判为用深字，
+ * 但实际白字对比度 4.57 优于深字 3.21，选错了。（由单测发现。）
+ */
+export function readableTextColor(hex) {
+    const withWhite = contrastRatio(hex, '#ffffff');
+    const withDark = contrastRatio(hex, DARK_TEXT);
+    return withWhite >= withDark ? '#ffffff' : DARK_TEXT;
+}
+/** 解析 #rgb / #rrggbb；非法返回 null。 */
+export function parseHex(hex) {
+    const m = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(hex.trim());
+    if (!m)
+        return null;
+    let s = m[1];
+    if (s.length === 3)
+        s = s.split('').map((c) => c + c).join('');
+    return [
+        parseInt(s.slice(0, 2), 16),
+        parseInt(s.slice(2, 4), 16),
+        parseInt(s.slice(4, 6), 16),
+    ];
+}

package/dist/esm/shared/safe-href.js

@@ -0,0 +1,32 @@
+/**
+ * href 协议白名单（客户端纵深防御，L4）。
+ *
+ * 服务端在写入与读取投影时都做了协议白名单（挡 `javascript:`），但历史数据、
+ * 导入内容或服务端回归仍可能让危险 href 出现在正文 JSON 里。渲染器直接把它
+ * 写进 `<a href>`，等于给浏览器一个可执行入口——因此在**渲染侧**再兜一层：
+ * 只放行确定安全的协议；其余（含 `javascript:` / `data:` / `vbscript:` 等）
+ * 一律降级为不可点击的锚点（href 置为 `#`）。
+ *
+ * 允许：http(s)、mailto、以 `/` 或 `#` 开头的站内相对链接，以及相对路径。
+ */
+const SAFE_ABSOLUTE = /^(https?:|mailto:)/i;
+export function isSafeHref(raw) {
+    if (typeof raw !== 'string')
+        return false;
+    // 去掉控制字符与空白后再判断，避免 `java\nscript:` 之类绕过
+    const href = raw.replace(/[\u0000-\u001f\u007f\s]/g, '').toLowerCase();
+    if (href === '')
+        return false;
+    if (href.startsWith('/') || href.startsWith('#'))
+        return true;
+    if (SAFE_ABSOLUTE.test(href))
+        return true;
+    // 相对路径（无协议、无 `:` 前缀）：允许。含 `:` 的一律按协议处理并要求在白名单内。
+    if (!href.includes(':'))
+        return true;
+    return false;
+}
+/** 渲染用：安全则原样返回，否则返回 '#'。 */
+export function safeHref(raw) {
+    return isSafeHref(raw) ? String(raw) : '#';
+}

package/dist/esm/shared/table-cell-format.js

@@ -0,0 +1,14 @@
+/** 固定单元格底色，不接受任意 CSS；读写端共用，服务端同步白名单。 */
+export const CELL_BACKGROUNDS = [
+    { name: '默认', value: null },
+    { name: '灰', value: '#f1f3f5' },
+    { name: '黄', value: '#fff3bf' },
+    { name: '绿', value: '#d3f9d8' },
+    { name: '蓝', value: '#d0ebff' },
+    { name: '紫', value: '#e5dbff' },
+    { name: '红', value: '#ffe3e3' },
+];
+export function cellBackground(value) {
+    return typeof value === 'string' && CELL_BACKGROUNDS.some((c) => c.value === value)
+        ? value : null;
+}

package/dist/esm/shared/table-layout.js

@@ -0,0 +1,23 @@
+/** 自动列宽保留可读空间；窄屏在表格内部滚动，不把长文本压成单字列。 */
+export const TABLE_CELL_MIN_WIDTH = 120;
+/** 首行合并单元格的 colwidth 数组包含多个视觉列，必须逐列展开。 */
+export function tableColumnWidths(table) {
+    const row = table.content?.find((node) => node.type === 'tableRow');
+    const widths = [];
+    for (const cell of row?.content ?? []) {
+        const span = Number(cell.attrs?.colspan ?? 1);
+        const count = Number.isSafeInteger(span) && span > 0 ? Math.min(span, 1000) : 1;
+        const colwidth = cell.attrs?.colwidth;
+        for (let index = 0; index < count; index += 1) {
+            const value = Array.isArray(colwidth) ? colwidth[index] : undefined;
+            widths.push(typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : 0);
+        }
+    }
+    return widths;
+}
+/** 未设置宽度的列与编辑器 cellMinWidth 共用同一默认值；保留历史显式列宽。 */
+export function tableMinWidth(widths) {
+    return widths.length > 0
+        ? widths.reduce((sum, width) => sum + (width > 0 ? width : TABLE_CELL_MIN_WIDTH), 0)
+        : undefined;
+}

package/dist/esm/shared/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/shared/video-embed.js

@@ -0,0 +1,96 @@
+export function normalizeVideoEmbed(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const data = raw;
+    const validId = data.provider === 'youtube'
+        ? typeof data.videoId === 'string' && /^[\w-]{11}$/.test(data.videoId)
+        : data.provider === 'bilibili' && typeof data.videoId === 'string' &&
+            /^(BV[A-Za-z0-9]{10}|av[1-9]\d{0,15})$/.test(data.videoId);
+    const page = data.page ?? 1;
+    const startSeconds = data.startSeconds ?? 0;
+    if (!validId || !Number.isInteger(page) || Number(page) < 1 || Number(page) > 1000 ||
+        !Number.isInteger(startSeconds) || Number(startSeconds) < 0 || Number(startSeconds) > 604800)
+        return null;
+    return { provider: data.provider, videoId: data.videoId,
+        page: data.provider === 'youtube' ? 1 : Number(page), startSeconds: Number(startSeconds) };
+}
+function seconds(value) {
+    if (!value)
+        return 0;
+    if (/^\d+$/.test(value))
+        return Number(value);
+    const match = /^(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s)?$/.exec(value);
+    if (!match || !match[0])
+        return NaN;
+    return Number(match[1] ?? 0) * 3600 + Number(match[2] ?? 0) * 60 + Number(match[3] ?? 0);
+}
+export function parseVideoUrl(value) {
+    let url;
+    try {
+        url = new URL(value.trim());
+    }
+    catch {
+        return null;
+    }
+    if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password || url.port)
+        return null;
+    const host = url.hostname.toLowerCase();
+    const path = url.pathname.split('/').filter(Boolean);
+    let provider;
+    let videoId;
+    if (host === 'youtu.be') {
+        provider = 'youtube';
+        videoId = path.length === 1 ? path[0] : null;
+    }
+    else if (['youtube.com', 'www.youtube.com', 'm.youtube.com', 'www.youtube-nocookie.com'].includes(host)) {
+        provider = 'youtube';
+        videoId = url.pathname === '/watch' ? url.searchParams.get('v')
+            : ['embed', 'shorts', 'live'].includes(path[0]) && path.length === 2 ? path[1] : null;
+    }
+    else if (['bilibili.com', 'www.bilibili.com', 'm.bilibili.com'].includes(host)) {
+        provider = 'bilibili';
+        videoId = path[0] === 'video' && path.length === 2 ? path[1] : null;
+    }
+    else if (host === 'player.bilibili.com' && url.pathname === '/player.html') {
+        provider = 'bilibili';
+        videoId = url.searchParams.get('bvid') ?? (url.searchParams.get('aid') ? `av${url.searchParams.get('aid')}` : null);
+    }
+    else
+        return null;
+    const hashTime = /^#t=(.*)$/.exec(url.hash)?.[1] ?? null;
+    return normalizeVideoEmbed({ provider, videoId, page: Number(url.searchParams.get('p') ?? 1),
+        startSeconds: seconds(url.searchParams.get('start') ?? url.searchParams.get('t') ?? hashTime) });
+}
+export function videoSourceUrl(data) {
+    const safe = normalizeVideoEmbed(data);
+    if (!safe)
+        return '';
+    const url = new URL(safe.provider === 'youtube'
+        ? `https://www.youtube.com/watch?v=${safe.videoId}`
+        : `https://www.bilibili.com/video/${safe.videoId}`);
+    if (safe.provider === 'bilibili' && safe.page > 1)
+        url.searchParams.set('p', String(safe.page));
+    if (safe.startSeconds)
+        url.searchParams.set('t', String(safe.startSeconds));
+    return url.href;
+}
+export function videoPlayerUrl(data) {
+    const safe = normalizeVideoEmbed(data);
+    if (!safe)
+        return '';
+    const url = new URL(safe.provider === 'youtube'
+        ? `https://www.youtube.com/embed/${safe.videoId}` : 'https://player.bilibili.com/player.html');
+    url.searchParams.set('autoplay', '0');
+    if (safe.provider === 'youtube') {
+        url.searchParams.set('playsinline', '1');
+        if (safe.startSeconds)
+            url.searchParams.set('start', String(safe.startSeconds));
+    }
+    else {
+        url.searchParams.set(safe.videoId.startsWith('BV') ? 'bvid' : 'aid', safe.videoId.startsWith('BV') ? safe.videoId : safe.videoId.slice(2));
+        url.searchParams.set('p', String(safe.page));
+        url.searchParams.set('t', String(safe.startSeconds));
+        url.searchParams.set('danmaku', '0');
+    }
+    return url.href;
+}

package/dist/esm/shared/workbook.js

@@ -0,0 +1,144 @@
+export const WORKBOOK_LIMITS = { sheets: 20, rows: 10000, columns: 200, cells: 50000, bytes: 4 * 1024 * 1024 };
+export function isWorkbookDocument(value) {
+    return !!value && typeof value === 'object' && value.type === 'workbook';
+}
+export function emptyWorkbook(id) {
+    return {
+        type: 'workbook', formatVersion: 1,
+        workbook: {
+            id, name: '工作簿', appVersion: '1.1.0', locale: 'zhCN',
+            sheetOrder: ['sheet1'],
+            sheets: { sheet1: { id: 'sheet1', name: 'Sheet1', rowCount: 1000, columnCount: 26, cellData: {} } },
+        },
+    };
+}
+function record(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function index(key, upper) {
+    return /^(0|[1-9]\d*)$/.test(key) && Number(key) < upper;
+}
+/** Validate the complete snapshot without silently dropping supported engine attributes. */
+export function validateWorkbook(raw) {
+    const fail = (message) => { throw new Error(`工作表格式无效：${message}`); };
+    if (!isWorkbookDocument(raw) || raw.formatVersion !== 1 || !record(raw.workbook))
+        fail('不支持的版本');
+    const doc = raw;
+    const json = JSON.stringify(doc);
+    if (new TextEncoder().encode(json).byteLength > WORKBOOK_LIMITS.bytes)
+        fail('超过 4MB');
+    let nodes = 0;
+    const walk = (value, depth) => {
+        if (++nodes > 500000 || depth > 40)
+            fail('结构过大或嵌套过深');
+        if (typeof value === 'number' && !Number.isFinite(value))
+            fail('包含非法数值');
+        if (Array.isArray(value))
+            value.forEach(item => walk(item, depth + 1));
+        else if (record(value)) {
+            if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)
+                fail('包含非法对象');
+            for (const [key, item] of Object.entries(value)) {
+                if (['__proto__', 'constructor', 'prototype'].includes(key))
+                    fail('包含非法属性');
+                walk(item, depth + 1);
+            }
+        }
+    };
+    walk(doc, 0);
+    const book = doc.workbook;
+    if (typeof book.id !== 'string' || !book.id || book.id.length > 128 ||
+        typeof book.name !== 'string' || book.name.length > 256)
+        fail('工作簿名称或标识无效');
+    if (!Array.isArray(book.sheetOrder) || !book.sheetOrder.length || book.sheetOrder.length > WORKBOOK_LIMITS.sheets ||
+        new Set(book.sheetOrder).size !== book.sheetOrder.length || !record(book.sheets) ||
+        Object.keys(book.sheets).length !== book.sheetOrder.length)
+        fail('表页数量或顺序无效');
+    let cells = 0;
+    const names = new Set();
+    for (const id of book.sheetOrder) {
+        if (typeof id !== 'string' || !id || id.length > 128)
+            fail('表页标识无效');
+        const sheet = book.sheets[id];
+        if (!record(sheet) || sheet.id !== id || typeof sheet.name !== 'string' || !sheet.name.trim() ||
+            sheet.name.length > 31 || /[\\/*?:[\]]/.test(sheet.name) || names.has(sheet.name.toLowerCase()))
+            fail('表页名称无效或重复（最多 31 字符）');
+        names.add(sheet.name.toLowerCase());
+        if (!Number.isInteger(sheet.rowCount) || sheet.rowCount < 1 || sheet.rowCount > WORKBOOK_LIMITS.rows ||
+            !Number.isInteger(sheet.columnCount) || sheet.columnCount < 1 || sheet.columnCount > WORKBOOK_LIMITS.columns)
+            fail('行列超出上限');
+        if (sheet.cellData !== undefined) {
+            if (!record(sheet.cellData))
+                fail('单元格结构无效');
+            for (const [r, row] of Object.entries(sheet.cellData)) {
+                if (!index(r, sheet.rowCount) || !record(row))
+                    fail('单元格行号无效');
+                for (const [c, cell] of Object.entries(row)) {
+                    if (++cells > WORKBOOK_LIMITS.cells)
+                        fail('单元格超过 50000 个');
+                    if (!index(c, sheet.columnCount))
+                        fail('单元格列号无效');
+                    if (cell === null)
+                        continue;
+                    if (!record(cell))
+                        fail('单元格结构无效');
+                    if (cell.v !== undefined && cell.v !== null && !['string', 'number', 'boolean'].includes(typeof cell.v))
+                        fail('单元格值无效');
+                    if (typeof cell.v === 'string' && cell.v.length > 16000)
+                        fail('单元格文字过长');
+                    if (cell.f !== undefined && (typeof cell.f !== 'string' || cell.f.length > 4000))
+                        fail('公式无效');
+                    if (cell.t !== undefined && (!Number.isInteger(cell.t) || Number(cell.t) < 0 || Number(cell.t) > 4))
+                        fail('单元格类型无效');
+                    if (cell.s !== undefined && cell.s !== null && typeof cell.s !== 'string' && !record(cell.s))
+                        fail('单元格样式无效');
+                    if (cell.p !== undefined && (!record(cell.p) || (cell.p.body !== undefined &&
+                        (!record(cell.p.body) || typeof cell.p.body.dataStream !== 'string' || cell.p.body.dataStream.length > 16000))))
+                        fail('单元格富文本无效');
+                }
+            }
+        }
+        for (const [data, upper] of [[sheet.rowData, sheet.rowCount], [sheet.columnData, sheet.columnCount]]) {
+            if (data !== undefined && (!record(data) || Object.keys(data).some(key => !index(key, upper))))
+                fail('行列属性越界');
+        }
+        if (sheet.mergeData !== undefined) {
+            if (!Array.isArray(sheet.mergeData) || sheet.mergeData.length > WORKBOOK_LIMITS.cells)
+                fail('合并区域无效');
+            const occupied = new Set();
+            for (const range of sheet.mergeData) {
+                if (!record(range) || ![range.startRow, range.endRow, range.startColumn, range.endColumn].every(Number.isInteger) ||
+                    range.startRow < 0 || range.endRow < range.startRow || range.endRow >= sheet.rowCount ||
+                    range.startColumn < 0 || range.endColumn < range.startColumn || range.endColumn >= sheet.columnCount)
+                    fail('合并区域越界');
+                const area = (range.endRow - range.startRow + 1) * (range.endColumn - range.startColumn + 1);
+                if (occupied.size + area > 200000)
+                    fail('合并区域总范围过大');
+                for (let r = range.startRow; r <= range.endRow; r++) {
+                    for (let c = range.startColumn; c <= range.endColumn; c++) {
+                        const position = r * WORKBOOK_LIMITS.columns + c;
+                        if (occupied.has(position))
+                            fail('合并区域重叠');
+                        occupied.add(position);
+                    }
+                }
+            }
+        }
+    }
+    return JSON.parse(json);
+}
+export function workbookCellText(cell) {
+    if (!cell)
+        return '';
+    if (cell.p?.body?.dataStream)
+        return cell.p.body.dataStream.replace(/[\r\n]+$/, '');
+    if (cell.v !== undefined && cell.v !== null)
+        return String(cell.v);
+    return cell.f ?? '';
+}
+export function workbookText(doc) {
+    return doc.workbook.sheetOrder.map(id => {
+        const sheet = doc.workbook.sheets[id];
+        return `${sheet.name} ${Object.values(sheet.cellData ?? {}).flatMap(row => Object.values(row).map(workbookCellText)).join(' ')}`;
+    }).join(' ').slice(0, 200000);
+}

package/dist/esm/spreadsheet.js

@@ -0,0 +1 @@
+export * from './shared/workbook.js';

package/dist/esm/types.js

@@ -0,0 +1 @@
+export * from './shared/types.js';

package/dist/esm/validation/callout.js

@@ -0,0 +1 @@
+export * from '../shared/callout.js';

package/dist/esm/validation/doc-node-whitelist.js

@@ -0,0 +1,68 @@
+/**
+ * 文档节点白名单（**纯数据，无依赖**）。
+ *
+ * 为什么单独成文件：白名单需要被三处引用——
+ *  1) 服务端校验（doc-schema.service.ts）
+ *  2) 一致性测试（与前端 node-catalog 交叉核对）
+ *  3) 导出序列化器的防漂移测试
+ * 若把它放在 doc-schema.service.ts 里，测试导入会连带加载 Nest 依赖，
+ * 导致 spec 在测试环境下加载失败（实测：整个测试文件被静默跳过）。
+ *
+ * 因此这里只放数据，不放逻辑，任何一方都能安全引用。
+ *
+ * 新增节点时必须同时更新：
+ *  1) 本文件
+ *  2) 前端 web/src/shared/node-catalog.ts
+ *  3) 导出序列化器 markdown-serializer.ts 的处理分支
+ * 三处一致性由测试自动核对（读取真实文件，而非维护测试内副本）。
+ */
+export const ALLOWED_NODES = new Set([
+    'mindMapDescription', 'mindMapNote', 'mindMapRelation',
+    'mindMap',
+    'mindMapTopic',
+    'doc',
+    'paragraph',
+    'text',
+    'heading',
+    'bulletList',
+    'orderedList',
+    'listItem',
+    // 待办列表：前端编辑器（TaskList/TaskItem）支持，导出序列化器也支持，
+    // 但白名单此前漏了这两个节点 —— 导致「用户插入待办列表后保存必被拒」。
+    // 由导入测试暴露（详见 doc-schema.service.spec.ts 的三方一致性断言）。
+    'taskList',
+    'taskItem',
+    'blockquote',
+    'codeBlock',
+    'horizontalRule',
+    'hardBreak',
+    'image',
+    'fileAttachment', // 视频或文件卡片（只存 attachmentId，不存存储地址）
+    'videoEmbed',
+    'callout', // 高亮块（容器，content: block+）
+    // 分栏：columns（行，content: column+）包 column（栏，content: block+）。
+    // 两个都要登记——只登记外层时，栏节点会在保存校验处被判为「不支持」而拒绝写入。
+    'columns',
+    'column',
+    'table',
+    'tableRow',
+    'tableHeader',
+    'tableCell',
+    'pageLink', // 内部页面引用 [[page]]
+    'mention', // @提及用户
+    'mathInline', // 行内公式（KaTeX）
+    'mathBlock', // 块级公式（KaTeX）
+]);
+/** 允许的标记类型。 */
+export const ALLOWED_MARKS = new Set([
+    'bold',
+    'italic',
+    'strike',
+    'code',
+    'link',
+    // 行内样式：文字颜色与背景高亮。两者的颜色属性必须在
+    // doc-schema.service.ts 的 ALLOWED_ATTRS 里同时登记，否则颜色值会被剥离、
+    // 只剩一个空标记（实测的"颜色丢失但标记还在"就是这么来的）。
+    'textStyle',
+    'highlight',
+]);

package/dist/esm/validation/error.js

@@ -0,0 +1,13 @@
+export class ContentValidationError extends Error {
+    code;
+    status;
+    details;
+    constructor(code, message, status = 422, details) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.details = details;
+        this.name = 'ContentValidationError';
+    }
+    static validation(message) { return new ContentValidationError('validation.failed', message); }
+}