@fgbg/mdocs 1.3.22 → 1.3.24

package/dist/shared/sheetDocument.js

@@ -0,0 +1,781 @@
+/**
+ * `.sheet` 工作簿：一个文件内多个工作表（tabs）。
+ * 磁盘 JSON；每表行列有稳定 id，供 Agent patch。
+ * 可选 merges + per-cell style（底色/字色/粗斜体/字号）。
+ */
+export const SHEET_FORMAT_VERSION = 2;
+const FONT_SIZE_MIN = 12;
+const FONT_SIZE_MAX = 24;
+const HEX_COLOR_RE = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
+function newId(prefix) {
+    if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+        return `${prefix}_${crypto.randomUUID().slice(0, 8)}`;
+    }
+    return `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+export function emptySheetCell(v = "") {
+    return { v };
+}
+export function getCellValue(cell) {
+    if (cell == null)
+        return "";
+    if (typeof cell === "string")
+        return cell;
+    return cell.v ?? "";
+}
+export function getCellStyle(cell) {
+    if (cell == null || typeof cell === "string")
+        return undefined;
+    return cell.style;
+}
+export function parseCellRaw(raw) {
+    if (typeof raw === "string")
+        return { v: raw };
+    if (raw == null)
+        return { v: "" };
+    if (typeof raw === "object" && !Array.isArray(raw)) {
+        const o = raw;
+        const v = typeof o.v === "string" ? o.v : o.v == null ? "" : String(o.v);
+        const style = normalizeStyle(o.style);
+        return style ? { v, style } : { v };
+    }
+    return { v: String(raw) };
+}
+export function isValidSheetColor(value) {
+    return HEX_COLOR_RE.test(value.trim());
+}
+export function normalizeStyle(raw) {
+    if (raw == null)
+        return undefined;
+    if (typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const o = raw;
+    const style = {};
+    if (typeof o.bg === "string" && o.bg.trim()) {
+        const bg = o.bg.trim();
+        if (isValidSheetColor(bg))
+            style.bg = bg;
+    }
+    if (typeof o.color === "string" && o.color.trim()) {
+        const color = o.color.trim();
+        if (isValidSheetColor(color))
+            style.color = color;
+    }
+    if (o.bold === true)
+        style.bold = true;
+    if (o.italic === true)
+        style.italic = true;
+    if (typeof o.fontSize === "number" && Number.isFinite(o.fontSize)) {
+        const n = Math.round(o.fontSize);
+        if (n >= FONT_SIZE_MIN && n <= FONT_SIZE_MAX)
+            style.fontSize = n;
+    }
+    return Object.keys(style).length > 0 ? style : undefined;
+}
+/** patch 合并进现有 style；传 null 清除 */
+export function mergeCellStyle(current, patch) {
+    if (patch === null)
+        return undefined;
+    if (patch == null)
+        return current;
+    const next = { ...(current ?? {}) };
+    if ("bg" in patch) {
+        if (patch.bg == null || patch.bg === "")
+            delete next.bg;
+        else if (isValidSheetColor(patch.bg))
+            next.bg = patch.bg.trim();
+    }
+    if ("color" in patch) {
+        if (patch.color == null || patch.color === "")
+            delete next.color;
+        else if (isValidSheetColor(patch.color))
+            next.color = patch.color.trim();
+    }
+    if ("bold" in patch) {
+        if (patch.bold)
+            next.bold = true;
+        else
+            delete next.bold;
+    }
+    if ("italic" in patch) {
+        if (patch.italic)
+            next.italic = true;
+        else
+            delete next.italic;
+    }
+    if ("fontSize" in patch) {
+        if (patch.fontSize == null)
+            delete next.fontSize;
+        else {
+            const n = Math.round(Number(patch.fontSize));
+            if (n >= FONT_SIZE_MIN && n <= FONT_SIZE_MAX)
+                next.fontSize = n;
+        }
+    }
+    return Object.keys(next).length > 0 ? next : undefined;
+}
+function compactCellForDisk(cell) {
+    const style = normalizeStyle(cell.style);
+    if (!style)
+        return cell.v;
+    return { v: cell.v, style };
+}
+function compactTabForDisk(tab) {
+    const merges = (tab.merges ?? []).filter(Boolean);
+    return {
+        id: tab.id,
+        name: tab.name,
+        columns: tab.columns,
+        rows: tab.rows.map((r) => ({
+            id: r.id,
+            cells: Object.fromEntries(Object.entries(r.cells).map(([k, cell]) => [k, compactCellForDisk(cell)])),
+        })),
+        ...(merges.length > 0 ? { merges } : {}),
+    };
+}
+function createEmptyTab(opts) {
+    const columnCount = Math.max(1, opts?.columnCount ?? 3);
+    const rowCount = Math.max(0, opts?.rowCount ?? 5);
+    const columns = [];
+    for (let i = 0; i < columnCount; i += 1) {
+        columns.push({ id: newId("c"), name: `列${i + 1}` });
+    }
+    const rows = [];
+    for (let i = 0; i < rowCount; i += 1) {
+        const cells = {};
+        for (const col of columns)
+            cells[col.id] = emptySheetCell();
+        rows.push({ id: newId("r"), cells });
+    }
+    return {
+        id: newId("s"),
+        name: opts?.name?.trim() || "Sheet1",
+        columns,
+        rows,
+        merges: [],
+    };
+}
+export function createEmptySheetDocument(opts) {
+    const tab = createEmptyTab(opts);
+    return {
+        version: SHEET_FORMAT_VERSION,
+        sheets: [tab],
+        activeSheetId: tab.id,
+    };
+}
+export function serializeSheetDocument(doc) {
+    const payload = {
+        version: SHEET_FORMAT_VERSION,
+        activeSheetId: doc.activeSheetId,
+        sheets: doc.sheets.map(compactTabForDisk),
+    };
+    return `${JSON.stringify(payload, null, 2)}\n`;
+}
+function parseMerges(raw, tab) {
+    if (!Array.isArray(raw))
+        return [];
+    const rowIds = new Set(tab.rows.map((r) => r.id));
+    const colIds = new Set(tab.columns.map((c) => c.id));
+    const out = [];
+    for (const m of raw) {
+        if (!m || typeof m !== "object")
+            continue;
+        const o = m;
+        const startRowId = typeof o.startRowId === "string" ? o.startRowId : "";
+        const startColId = typeof o.startColId === "string" ? o.startColId : "";
+        const endRowId = typeof o.endRowId === "string" ? o.endRowId : "";
+        const endColId = typeof o.endColId === "string" ? o.endColId : "";
+        if (!rowIds.has(startRowId) || !rowIds.has(endRowId))
+            continue;
+        if (!colIds.has(startColId) || !colIds.has(endColId))
+            continue;
+        out.push({ startRowId, startColId, endRowId, endColId });
+    }
+    return out;
+}
+function parseTab(raw, fallbackName) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const obj = raw;
+    const columnsIn = Array.isArray(obj.columns) ? obj.columns : [];
+    const rowsIn = Array.isArray(obj.rows) ? obj.rows : [];
+    const columns = [];
+    for (const c of columnsIn) {
+        if (!c || typeof c !== "object")
+            continue;
+        const col = c;
+        const id = typeof col.id === "string" && col.id ? col.id : newId("c");
+        const name = typeof col.name === "string" ? col.name : id;
+        columns.push({ id, name });
+    }
+    if (columns.length === 0)
+        return null;
+    const rows = [];
+    for (const r of rowsIn) {
+        if (!r || typeof r !== "object")
+            continue;
+        const row = r;
+        const id = typeof row.id === "string" && row.id ? row.id : newId("r");
+        const cellsRaw = row.cells && typeof row.cells === "object" && !Array.isArray(row.cells)
+            ? row.cells
+            : {};
+        const cells = {};
+        for (const col of columns) {
+            cells[col.id] = parseCellRaw(cellsRaw[col.id]);
+        }
+        rows.push({ id, cells });
+    }
+    const id = typeof obj.id === "string" && obj.id ? obj.id : newId("s");
+    const name = typeof obj.name === "string" && obj.name.trim()
+        ? obj.name.trim()
+        : fallbackName;
+    const merges = parseMerges(obj.merges, { columns, rows });
+    return { id, name, columns, rows, merges };
+}
+/** 兼容 v1：顶层 columns/rows → 单表工作簿。 */
+export function parseSheetDocument(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return createEmptySheetDocument();
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        return createEmptySheetDocument();
+    }
+    if (!parsed || typeof parsed !== "object")
+        return createEmptySheetDocument();
+    const obj = parsed;
+    if (Array.isArray(obj.sheets) && obj.sheets.length > 0) {
+        const sheets = [];
+        for (let i = 0; i < obj.sheets.length; i += 1) {
+            const tab = parseTab(obj.sheets[i], `Sheet${i + 1}`);
+            if (tab)
+                sheets.push(tab);
+        }
+        if (sheets.length === 0)
+            return createEmptySheetDocument();
+        const activeRaw = typeof obj.activeSheetId === "string" ? obj.activeSheetId : "";
+        const activeSheetId = sheets.some((s) => s.id === activeRaw)
+            ? activeRaw
+            : sheets[0].id;
+        return { version: SHEET_FORMAT_VERSION, sheets, activeSheetId };
+    }
+    const tab = parseTab(obj, "Sheet1");
+    if (!tab)
+        return createEmptySheetDocument();
+    return {
+        version: SHEET_FORMAT_VERSION,
+        sheets: [tab],
+        activeSheetId: tab.id,
+    };
+}
+export function resolveSheetTab(doc, sheet) {
+    const key = sheet?.trim();
+    if (!key) {
+        return doc.sheets.find((s) => s.id === doc.activeSheetId) ?? doc.sheets[0] ?? null;
+    }
+    const byId = doc.sheets.find((s) => s.id === key);
+    if (byId)
+        return byId;
+    const byName = doc.sheets.find((s) => s.name === key);
+    if (byName)
+        return byName;
+    const lower = key.toLowerCase();
+    return doc.sheets.find((s) => s.name.toLowerCase() === lower) ?? null;
+}
+export function replaceSheetTab(doc, tab) {
+    if (!doc.sheets.some((s) => s.id === tab.id)) {
+        throw new Error(`unknown sheet: ${tab.id}`);
+    }
+    return {
+        ...doc,
+        sheets: doc.sheets.map((s) => (s.id === tab.id ? tab : s)),
+    };
+}
+export function setActiveSheet(doc, sheet) {
+    const tab = resolveSheetTab(doc, sheet);
+    if (!tab)
+        throw new Error(`unknown sheet: ${sheet}`);
+    return { ...doc, activeSheetId: tab.id };
+}
+export function addWorkbookSheet(doc, name) {
+    let base = (name?.trim() || `Sheet${doc.sheets.length + 1}`);
+    const existing = new Set(doc.sheets.map((s) => s.name));
+    if (existing.has(base)) {
+        let n = 2;
+        while (existing.has(`${base}${n}`))
+            n += 1;
+        base = `${base}${n}`;
+    }
+    const tab = createEmptyTab({ name: base });
+    return {
+        doc: {
+            ...doc,
+            sheets: [...doc.sheets, tab],
+            activeSheetId: tab.id,
+        },
+        tab,
+    };
+}
+export function renameWorkbookSheet(doc, sheet, name) {
+    const tab = resolveSheetTab(doc, sheet);
+    if (!tab)
+        throw new Error(`unknown sheet: ${sheet}`);
+    const nextName = name.trim();
+    if (!nextName)
+        throw new Error("sheet name is required");
+    const clash = doc.sheets.find((s) => s.id !== tab.id && s.name === nextName);
+    if (clash)
+        throw new Error(`sheet name already exists: ${nextName}`);
+    return replaceSheetTab(doc, { ...tab, name: nextName });
+}
+export function removeWorkbookSheet(doc, sheet) {
+    const tab = resolveSheetTab(doc, sheet);
+    if (!tab)
+        throw new Error(`unknown sheet: ${sheet}`);
+    if (doc.sheets.length <= 1) {
+        throw new Error("cannot delete the last sheet");
+    }
+    const sheets = doc.sheets.filter((s) => s.id !== tab.id);
+    const activeSheetId = doc.activeSheetId === tab.id ? sheets[0].id : doc.activeSheetId;
+    return { ...doc, sheets, activeSheetId };
+}
+/* ── merge helpers ── */
+function rowIndex(tab, rowId) {
+    return tab.rows.findIndex((r) => r.id === rowId);
+}
+function colIndex(tab, colId) {
+    return tab.columns.findIndex((c) => c.id === colId);
+}
+function normalizeMergeRange(tab, range) {
+    const r0 = rowIndex(tab, range.startRowId);
+    const r1 = rowIndex(tab, range.endRowId);
+    const c0 = colIndex(tab, range.startColId);
+    const c1 = colIndex(tab, range.endColId);
+    if (r0 < 0 || r1 < 0 || c0 < 0 || c1 < 0)
+        return null;
+    const rs = Math.min(r0, r1);
+    const re = Math.max(r0, r1);
+    const cs = Math.min(c0, c1);
+    const ce = Math.max(c0, c1);
+    if (rs === re && cs === ce)
+        return null; // 单格不算合并
+    return {
+        startRowId: tab.rows[rs].id,
+        startColId: tab.columns[cs].id,
+        endRowId: tab.rows[re].id,
+        endColId: tab.columns[ce].id,
+    };
+}
+function mergeOverlaps(tab, a, b) {
+    const ar0 = rowIndex(tab, a.startRowId);
+    const ar1 = rowIndex(tab, a.endRowId);
+    const ac0 = colIndex(tab, a.startColId);
+    const ac1 = colIndex(tab, a.endColId);
+    const br0 = rowIndex(tab, b.startRowId);
+    const br1 = rowIndex(tab, b.endRowId);
+    const bc0 = colIndex(tab, b.startColId);
+    const bc1 = colIndex(tab, b.endColId);
+    if (ar0 < 0 || ar1 < 0 || br0 < 0 || br1 < 0)
+        return false;
+    if (ac0 < 0 || ac1 < 0 || bc0 < 0 || bc1 < 0)
+        return false;
+    const aR0 = Math.min(ar0, ar1);
+    const aR1 = Math.max(ar0, ar1);
+    const aC0 = Math.min(ac0, ac1);
+    const aC1 = Math.max(ac0, ac1);
+    const bR0 = Math.min(br0, br1);
+    const bR1 = Math.max(br0, br1);
+    const bC0 = Math.min(bc0, bc1);
+    const bC1 = Math.max(bc0, bc1);
+    return !(aR1 < bR0 || bR1 < aR0 || aC1 < bC0 || bC1 < aC0);
+}
+export function findMergeAt(tab, rowId, columnId) {
+    const ri = rowIndex(tab, rowId);
+    const ci = colIndex(tab, columnId);
+    if (ri < 0 || ci < 0)
+        return null;
+    for (const m of tab.merges ?? []) {
+        const r0 = rowIndex(tab, m.startRowId);
+        const r1 = rowIndex(tab, m.endRowId);
+        const c0 = colIndex(tab, m.startColId);
+        const c1 = colIndex(tab, m.endColId);
+        if (r0 < 0 || r1 < 0 || c0 < 0 || c1 < 0)
+            continue;
+        const rs = Math.min(r0, r1);
+        const re = Math.max(r0, r1);
+        const cs = Math.min(c0, c1);
+        const ce = Math.max(c0, c1);
+        if (ri >= rs && ri <= re && ci >= cs && ci <= ce)
+            return m;
+    }
+    return null;
+}
+export function isMergeMaster(tab, rowId, columnId) {
+    const m = findMergeAt(tab, rowId, columnId);
+    if (!m)
+        return true;
+    return m.startRowId === rowId && m.startColId === columnId;
+}
+export function isCoveredCell(tab, rowId, columnId) {
+    const m = findMergeAt(tab, rowId, columnId);
+    if (!m)
+        return false;
+    return !(m.startRowId === rowId && m.startColId === columnId);
+}
+export function mergeSpan(tab, merge) {
+    const r0 = rowIndex(tab, merge.startRowId);
+    const r1 = rowIndex(tab, merge.endRowId);
+    const c0 = colIndex(tab, merge.startColId);
+    const c1 = colIndex(tab, merge.endColId);
+    return {
+        rowSpan: Math.abs(r1 - r0) + 1,
+        colSpan: Math.abs(c1 - c0) + 1,
+    };
+}
+function scrubMerges(tab) {
+    const rowIds = new Set(tab.rows.map((r) => r.id));
+    const colIds = new Set(tab.columns.map((c) => c.id));
+    const merges = (tab.merges ?? []).filter((m) => rowIds.has(m.startRowId) &&
+        rowIds.has(m.endRowId) &&
+        colIds.has(m.startColId) &&
+        colIds.has(m.endColId) &&
+        normalizeMergeRange(tab, m) != null);
+    return { ...tab, merges };
+}
+export function mergeSheetCells(tab, range) {
+    const normalized = normalizeMergeRange(tab, range);
+    if (!normalized) {
+        throw new Error("invalid merge range (need at least 2 cells)");
+    }
+    for (const existing of tab.merges ?? []) {
+        if (mergeOverlaps(tab, existing, normalized)) {
+            throw new Error("merge overlaps existing merge");
+        }
+    }
+    return {
+        ...tab,
+        merges: [...(tab.merges ?? []), normalized],
+    };
+}
+export function unmergeSheetCells(tab, rowId, columnId) {
+    const hit = findMergeAt(tab, rowId, columnId);
+    if (!hit)
+        return { tab, removed: null };
+    return {
+        tab: {
+            ...tab,
+            merges: (tab.merges ?? []).filter((m) => m !== hit),
+        },
+        removed: hit,
+    };
+}
+/** 写 covered 格时重定向到主格 */
+export function resolveWriteTarget(tab, rowId, columnId) {
+    const m = findMergeAt(tab, rowId, columnId);
+    if (!m || (m.startRowId === rowId && m.startColId === columnId)) {
+        return { rowId, columnId, redirected: false };
+    }
+    return {
+        rowId: m.startRowId,
+        columnId: m.startColId,
+        redirected: true,
+    };
+}
+/* ── 单表（tab）级操作 ── */
+export function addSheetColumn(tab, name) {
+    const col = {
+        id: newId("c"),
+        name: name?.trim() || `列${tab.columns.length + 1}`,
+    };
+    return {
+        ...tab,
+        columns: [...tab.columns, col],
+        rows: tab.rows.map((r) => ({
+            ...r,
+            cells: { ...r.cells, [col.id]: emptySheetCell() },
+        })),
+    };
+}
+export function addSheetRow(tab) {
+    const cells = {};
+    for (const col of tab.columns)
+        cells[col.id] = emptySheetCell();
+    return {
+        ...tab,
+        rows: [...tab.rows, { id: newId("r"), cells }],
+    };
+}
+export function setSheetCell(tab, rowId, columnId, value) {
+    const target = resolveWriteTarget(tab, rowId, columnId);
+    return {
+        ...tab,
+        rows: tab.rows.map((r) => {
+            if (r.id !== target.rowId)
+                return r;
+            const prev = r.cells[target.columnId] ?? emptySheetCell();
+            return {
+                ...r,
+                cells: {
+                    ...r.cells,
+                    [target.columnId]: { v: value, ...(prev.style ? { style: prev.style } : {}) },
+                },
+            };
+        }),
+    };
+}
+export function setSheetCellStyle(tab, rowId, columnId, patch) {
+    const target = resolveWriteTarget(tab, rowId, columnId);
+    return {
+        ...tab,
+        rows: tab.rows.map((r) => {
+            if (r.id !== target.rowId)
+                return r;
+            const prev = r.cells[target.columnId] ?? emptySheetCell();
+            const style = mergeCellStyle(prev.style, patch);
+            const next = style ? { v: prev.v, style } : { v: prev.v };
+            return { ...r, cells: { ...r.cells, [target.columnId]: next } };
+        }),
+    };
+}
+export function setSheetCellStyles(tab, updates) {
+    let next = tab;
+    let applied = 0;
+    const errors = [];
+    const warnings = [];
+    for (const u of updates) {
+        const rowId = u.rowId.trim();
+        const col = resolveSheetColumn(next, u.column);
+        if (!rowId) {
+            errors.push("empty rowId");
+            continue;
+        }
+        if (!col) {
+            errors.push(`unknown column: ${u.column}`);
+            continue;
+        }
+        if (!next.rows.some((r) => r.id === rowId)) {
+            errors.push(`unknown rowId: ${rowId}`);
+            continue;
+        }
+        const target = resolveWriteTarget(next, rowId, col.id);
+        if (target.redirected) {
+            warnings.push(`redirected ${rowId}/${col.id} → merge master`);
+        }
+        next = setSheetCellStyle(next, target.rowId, target.columnId, u.style);
+        applied += 1;
+    }
+    return { tab: next, applied, errors, warnings };
+}
+export function setSheetColumnName(tab, columnId, name) {
+    return {
+        ...tab,
+        columns: tab.columns.map((c) => (c.id === columnId ? { ...c, name } : c)),
+    };
+}
+export function removeSheetRow(tab, rowId) {
+    return scrubMerges({ ...tab, rows: tab.rows.filter((r) => r.id !== rowId) });
+}
+export function removeSheetRows(tab, rowIds) {
+    const want = new Set(rowIds.map((id) => id.trim()).filter(Boolean));
+    const missing = [];
+    for (const id of want) {
+        if (!tab.rows.some((r) => r.id === id))
+            missing.push(id);
+    }
+    const removed = [...want].filter((id) => !missing.includes(id));
+    return {
+        tab: scrubMerges({ ...tab, rows: tab.rows.filter((r) => !want.has(r.id)) }),
+        removed,
+        missing,
+    };
+}
+export function removeSheetColumns(tab, columns) {
+    const errors = [];
+    const toRemove = new Set();
+    const removed = [];
+    for (const raw of columns) {
+        const col = resolveSheetColumn(tab, raw);
+        if (!col) {
+            errors.push(`unknown column: ${raw}`);
+            continue;
+        }
+        if (toRemove.has(col.id))
+            continue;
+        toRemove.add(col.id);
+        removed.push({ id: col.id, name: col.name });
+    }
+    if (toRemove.size === 0) {
+        return { tab, removed: [], errors };
+    }
+    if (tab.columns.length - toRemove.size < 1) {
+        throw new Error("cannot delete all columns; at least one column required");
+    }
+    const nextColumns = tab.columns.filter((c) => !toRemove.has(c.id));
+    const nextRows = tab.rows.map((r) => {
+        const cells = { ...r.cells };
+        for (const id of toRemove)
+            delete cells[id];
+        return { ...r, cells };
+    });
+    return {
+        tab: scrubMerges({ ...tab, columns: nextColumns, rows: nextRows }),
+        removed,
+        errors,
+    };
+}
+export function resolveSheetColumn(tab, column) {
+    const key = column.trim();
+    if (!key)
+        return null;
+    const byId = tab.columns.find((c) => c.id === key);
+    if (byId)
+        return byId;
+    const byName = tab.columns.find((c) => c.name === key);
+    if (byName)
+        return byName;
+    const lower = key.toLowerCase();
+    return tab.columns.find((c) => c.name.toLowerCase() === lower) ?? null;
+}
+export function sheetRowAsNamedCells(tab, row) {
+    const out = {};
+    for (const col of tab.columns) {
+        out[col.name] = getCellValue(row.cells[col.id]);
+    }
+    return out;
+}
+export function setSheetCells(tab, updates) {
+    let next = tab;
+    let applied = 0;
+    const errors = [];
+    const warnings = [];
+    for (const u of updates) {
+        const rowId = u.rowId.trim();
+        const col = resolveSheetColumn(next, u.column);
+        if (!rowId) {
+            errors.push("empty rowId");
+            continue;
+        }
+        if (!col) {
+            errors.push(`unknown column: ${u.column}`);
+            continue;
+        }
+        if (!next.rows.some((r) => r.id === rowId)) {
+            errors.push(`unknown rowId: ${rowId}`);
+            continue;
+        }
+        const target = resolveWriteTarget(next, rowId, col.id);
+        if (target.redirected) {
+            warnings.push(`redirected ${rowId}/${col.id} → merge master`);
+        }
+        next = setSheetCell(next, target.rowId, target.columnId, u.value);
+        applied += 1;
+    }
+    return { tab: next, applied, errors, warnings };
+}
+export function upsertSheetRow(tab, cells, rowId) {
+    const resolved = {};
+    for (const [key, value] of Object.entries(cells)) {
+        const col = resolveSheetColumn(tab, key);
+        if (!col) {
+            throw new Error(`unknown column: ${key}`);
+        }
+        resolved[col.id] = value;
+    }
+    const id = rowId?.trim() || newId("r");
+    const existing = tab.rows.find((r) => r.id === id);
+    if (existing) {
+        const mergedCells = { ...existing.cells };
+        for (const [cid, v] of Object.entries(resolved)) {
+            const prev = mergedCells[cid] ?? emptySheetCell();
+            mergedCells[cid] = {
+                v,
+                ...(prev.style ? { style: prev.style } : {}),
+            };
+        }
+        const row = { id, cells: mergedCells };
+        return {
+            tab: {
+                ...tab,
+                rows: tab.rows.map((r) => (r.id === id ? row : r)),
+            },
+            row,
+            created: false,
+        };
+    }
+    const cellsFull = {};
+    for (const col of tab.columns) {
+        cellsFull[col.id] = emptySheetCell(resolved[col.id] ?? "");
+    }
+    const row = { id, cells: cellsFull };
+    return {
+        tab: { ...tab, rows: [...tab.rows, row] },
+        row,
+        created: true,
+    };
+}
+/** 表末批量追加行；未知列名在写任何行之前失败。 */
+export function insertSheetRows(tab, rows) {
+    for (const cells of rows) {
+        for (const key of Object.keys(cells)) {
+            if (!resolveSheetColumn(tab, key)) {
+                throw new Error(`unknown column: ${key}`);
+            }
+        }
+    }
+    let next = tab;
+    const rowIds = [];
+    for (const cells of rows) {
+        const result = upsertSheetRow(next, cells);
+        next = result.tab;
+        rowIds.push(result.row.id);
+    }
+    return { tab: next, rowIds, inserted: rowIds.length };
+}
+const OVERWRITE_MAX_COLUMNS = 50;
+const OVERWRITE_MAX_ROWS = 500;
+/** 整表替换列与行；保留 tab.id，可选改 name。旧 column/row id 全部重建。 */
+export function overwriteSheetTab(tab, input) {
+    const colNames = input.columns.map((c) => String(c ?? "").trim());
+    if (colNames.length === 0) {
+        throw new Error("columns is required");
+    }
+    if (colNames.length > OVERWRITE_MAX_COLUMNS) {
+        throw new Error(`columns exceeds max ${OVERWRITE_MAX_COLUMNS}`);
+    }
+    if (colNames.some((c) => !c)) {
+        throw new Error("empty column name");
+    }
+    const seen = new Set();
+    for (const name of colNames) {
+        if (seen.has(name)) {
+            throw new Error(`duplicate column: ${name}`);
+        }
+        seen.add(name);
+    }
+    if (input.rows.length > OVERWRITE_MAX_ROWS) {
+        throw new Error(`rows exceeds max ${OVERWRITE_MAX_ROWS}`);
+    }
+    const columns = colNames.map((name) => ({
+        id: newId("c"),
+        name,
+    }));
+    const rows = [];
+    for (let i = 0; i < input.rows.length; i += 1) {
+        const raw = input.rows[i] ?? [];
+        if (raw.length > columns.length) {
+            throw new Error(`row ${i} has too many cells`);
+        }
+        const cells = {};
+        for (let j = 0; j < columns.length; j += 1) {
+            const v = raw[j];
+            cells[columns[j].id] = emptySheetCell(v == null ? "" : String(v));
+        }
+        rows.push({ id: newId("r"), cells });
+    }
+    const name = input.name?.trim() || tab.name;
+    return { id: tab.id, name, columns, rows, merges: [] };
+}
+//# sourceMappingURL=sheetDocument.js.map