@kuzuma/colwork 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,11 +1,36 @@
+import { Awareness } from 'y-protocols/awareness';
+import * as Y from 'yjs';
+
 export declare type AwarenessSelection = {
     anchor?: CellPosition;
     focus?: CellPosition;
     mode?: SelectionMode_2;
 };
 
+export declare type BuiltInCollaborationOptions = CommonOptions & {
+    room: string;
+    transport?: 'webrtc' | 'websocket';
+    collaboration?: never;
+    signalingUrl?: string;
+    websocketUrl?: string;
+    peerOpts?: Record<string, unknown>;
+    initializeAfterSync?: boolean;
+    rows?: string[][];
+    snapshot?: Uint8Array;
+    updates?: Uint8Array[];
+};
+
+export declare type CellBorder = {
+    top?: boolean;
+    right?: boolean;
+    bottom?: boolean;
+    left?: boolean;
+};
+
 export declare function cellKey(position: CellPosition): string;
 
+export declare type CellLock = '1' | PasswordLock;
+
 export declare type CellPosition = {
     row: number;
     column: number;
@@ -16,16 +41,49 @@ export declare type CellRange = {
     end: CellPosition;
 };
 
+export declare type CellStyle = {
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strike?: boolean;
+    wrap?: boolean;
+    border?: CellBorder;
+    fontSize?: number;
+    color?: string;
+    background?: string;
+    align?: 'left' | 'center' | 'right';
+    format?: 'general' | 'number' | 'date' | 'percent';
+};
+
+export declare const COLWORK_MAP_NAMES: Readonly<{
+    readonly cells: "cells";
+    readonly styles: "styles";
+    readonly rowHeights: "rowHeights";
+    readonly columnWidths: "columnWidths";
+    readonly merges: "merges";
+    readonly locks: "locks";
+    readonly metadata: "colwork-metadata";
+}>;
+
+/** The existing version-one wire format. Missing metadata is valid legacy data. */
+export declare const COLWORK_SCHEMA_VERSION: 1;
+
 export declare class ColworkTable {
+    private readonly session;
     private readonly doc;
+    private readonly sheet;
     private readonly cells;
     private readonly styles;
     private readonly rowHeights;
     private readonly columnWidths;
     private readonly locks;
-    private messageDialog?;
-    private passwordDialog?;
+    private readonly pointer;
+    private readonly clipboard;
+    private readonly selection;
+    private readonly formatting;
+    private readonly dialogs;
     private destroyed;
+    private editEpoch;
     private frozenRows;
     private frozenColumns;
     private readonly merges;
@@ -34,27 +92,21 @@ export declare class ColworkTable {
     private readonly awareness;
     private readonly root;
     private readonly options;
+    private readonly toolbar;
     private readonly table;
     private readonly viewportResizeObserver;
     private readonly viewport;
     private readonly frozenBoundaryLayer;
     private protectionMenuButton?;
-    private contextMenu?;
-    private pendingCellContext?;
-    private rightButtonReleased;
-    private rightMouseUpPoint?;
-    private rightDrag?;
+    private readonly menu;
     private undoButton?;
     private redoButton?;
-    private rowCountValue;
-    private columnCountValue;
+    private readonly dimensions;
     private zoomRatio;
     private showGridLines;
     private bandedRows;
-    private readonly readOnly;
-    private documentRevision;
-    private updateSequence;
-    private readonly updateLog;
+    private readOnly;
+    private readonly archive;
     private resizing?;
     private readonly onCellsChange;
     private readonly onStylesChange;
@@ -72,42 +124,26 @@ export declare class ColworkTable {
     private readonly onWindowBlur;
     private readonly onWindowMouseMove;
     private readonly onHistoryChange;
-    private editor?;
-    private editingKey?;
-    private editingOriginal;
-    private selectedKey?;
-    private selectionAnchor?;
-    private selectionFocus?;
-    private selectionMode?;
-    private selecting;
-    private headerSelecting?;
-    private pendingAwarenessCursor?;
-    private readonly loggedPeers;
-    private readonly loggedSignals;
-    private readonly onDocUpdate;
-    private readonly onAwarenessUpdate;
+    private readonly editing;
     constructor(root: HTMLElement, options: ColworkTableOptions);
     private log;
     private undo;
     private redo;
     private refreshHistoryButtons;
+    /** Changes local editing affordances. Hosts enforce actual document permissions. */
+    setReadOnly(readOnly: boolean): void;
+    /** Explicitly commits the active cell draft before a host publishes or exports. */
+    commitEditing(): void;
+    /** Discards an active draft while preserving the current shared document value. */
+    cancelEditing(): void;
     getYjsSnapshot(): YjsSnapshotFile;
     getYjsUpdateLog(): YjsUpdateLogFile;
-    /** Freeze a leading prefix of rows/columns in this client only. */
+    /** Freeze a leading prefix in this local view. */
     setFrozenPanes(rows: number, columns: number): boolean;
-    private hasPartialMerge;
     private crossesFrozenBoundary;
     private freezeSelection;
-    private rangeHasLocks;
-    private isCellLocked;
-    private isCellPasswordLocked;
     private selectionHasLocks;
-    private isAxisLocked;
-    /** Passwords are optional for legacy/plain locks; protected locks require verification. */
     setSelectionLocked(locked: boolean, password?: string): Promise<void>;
-    private requestSelectionLock;
-    private closeLockMessage;
-    private showLockMessage;
     private get rowCount();
     private get columnCount();
     private get rowHeaderWidth();
@@ -116,100 +152,145 @@ export declare class ColworkTable {
     private getColumnWidth;
     private beginResize;
     private addResizeHandle;
-    private selectRange;
-    private hideContextMenu;
-    private showContextMenu;
-    private protectionActions;
-    private hasHeaderSelection;
-    private openRowContextMenu;
-    private openColumnContextMenu;
-    private mergeKey;
-    private parseMergeKey;
-    private getMergeRanges;
-    private expandSelectionToMerges;
-    private getMergeStartingAt;
-    private isMergeCovered;
     private mergeSelection;
     private unmergeSelection;
     private modifyAxis;
     private deleteRows;
     private deleteColumns;
-    private selectHeaderRange;
-    private selectHeaderSpan;
-    private addHeaderSelection;
     private expandLogicalSpace;
-    private publishSelection;
-    private updateAwareness;
     private expandForRemoteSelections;
-    private getSelectionBounds;
-    private selectCell;
-    private isPositionSelected;
-    private selectionToClipboard;
-    private selectionToText;
-    private copySelection;
     private clearSelectionContents;
-    private showCellContextMenu;
-    private openCellContextMenu;
-    private sendAwareness;
-    private onCopy;
-    private onPaste;
-    private logChunk;
-    private inspectConnections;
-    private seed;
-    private seedDemoFormatting;
     private expandLogicalSizeFromDocument;
     private render;
-    private refreshFrozenBoundaries;
     private refreshValues;
     private refreshSelection;
     private refreshCursors;
-    private addSelectionOverlay;
-    private addCursorLabel;
-    private startEdit;
-    private readStyle;
-    private applyStyle;
-    private displayValue;
-    private toggleFormat;
-    private clearFormatting;
-    private toggleBorder;
-    private setStyle;
     private refreshStyles;
-    private finishEdit;
+    private refreshView;
     destroy(): void;
 }
 
-export declare type ColworkTableOptions = {
-    room: string;
-    signalingUrl?: string;
+export declare type ColworkTableOptions = ExternalCollaborationOptions | BuiltInCollaborationOptions;
+
+declare type CommonOptions = {
     user: string;
-    rows?: string[][];
+    userColor?: string;
     rowCount?: number;
     columnCount?: number;
     onLog?: (message: string) => void;
-    userColor?: string;
-    peerOpts?: Record<string, unknown>;
-    transport?: 'webrtc' | 'websocket';
-    websocketUrl?: string;
-    initializeAfterSync?: boolean;
     readOnly?: boolean;
-    snapshot?: Uint8Array;
-    updates?: Uint8Array[];
+    onEditingChange?: (state: EditingState) => void;
 };
 
 export declare function containsPosition(range: CellRange, position: CellPosition): boolean;
 
+export declare type EditingState = {
+    editing: boolean;
+    dirty: boolean;
+};
+
+export declare function exportYjsSnapshot(document: Y.Doc, options?: {
+    room?: string;
+    sequence?: number;
+}): YjsSnapshotFile;
+
+export declare type ExternalCollaborationOptions = CommonOptions & {
+    transport: 'external';
+    collaboration: {
+        document: Y.Doc;
+        awareness: Awareness;
+    };
+    room?: string;
+    rows?: never;
+    snapshot?: never;
+    updates?: never;
+    initializeAfterSync?: false;
+    signalingUrl?: never;
+    websocketUrl?: never;
+    peerOpts?: never;
+};
+
+/** Materializes named Y.Map roots, preserving the version-one encoding. */
+export declare function getSheetMaps(document: Y.Doc): SheetMaps;
+
+/** Initializes an empty document without demo cells, headers, styles, or network access. */
+export declare function initializeBlankSheet(document: Y.Doc): void;
+
+export declare function mergeKey(range: CellRange): string;
+
 export declare function normalizeRange(start: CellPosition, end: CellPosition): CellRange;
 
+export declare function parseCellKey(key: string): {
+    row: number;
+    column: number;
+} | undefined;
+
+export declare function parseMergeKey(key: string): CellRange | undefined;
+
+export declare type PasswordLock = {
+    version: 1;
+    algorithm: 'PBKDF2-SHA-256';
+    iterations: 600000;
+    salt: string;
+    verifier: string;
+};
+
 export declare function rangeSize(range: CellRange): {
     rows: number;
     columns: number;
 };
 
+/** Reads a deterministic sparse sheet without loading a renderer, browser globals, or CSS. */
+export declare function readSheetSnapshot(document: Y.Doc, limits?: SheetValidationLimits): SheetSnapshot;
+
+/** Decodes a Yjs state update and releases its temporary document after export. */
+export declare function readSheetSnapshotUpdate(update: Uint8Array, limits?: SheetValidationLimits): SheetSnapshot;
+
 export declare function rebuildYjsSnapshot(snapshotText?: string, updateLogText?: string): YjsSnapshotFile;
 
 declare type SelectionMode_2 = 'row' | 'column' | 'all';
 export { SelectionMode_2 as SelectionMode }
 
+export declare type SheetMaps = {
+    cells: Y.Map<string>;
+    styles: Y.Map<string>;
+    rowHeights: Y.Map<number>;
+    columnWidths: Y.Map<number>;
+    merges: Y.Map<string>;
+    locks: Y.Map<string>;
+};
+
+/** Sparse, JSON-serializable logical sheet. Dimensions are derived from stored data. */
+export declare type SheetSnapshot = {
+    schemaVersion: typeof COLWORK_SCHEMA_VERSION;
+    rowCount: number;
+    columnCount: number;
+    cells: Record<string, string>;
+    styles: Record<string, CellStyle>;
+    rowHeights: Record<string, number>;
+    columnWidths: Record<string, number>;
+    merges: CellRange[];
+    locks: Record<string, CellLock>;
+};
+
+export declare type SheetValidationIssue = {
+    path: string;
+    message: string;
+};
+
+/** Optional host policy. Omitted numeric limits impose no application-specific cap. */
+export declare type SheetValidationLimits = {
+    maxRows?: number;
+    maxColumns?: number;
+    maxEntries?: number;
+    maxStringLength?: number;
+    maxMergeArea?: number;
+    maxMerges?: number;
+    allowUnknownRoots?: boolean;
+};
+
+export declare function validateSheetDocument(document: Y.Doc, limits?: SheetValidationLimits): SheetValidationIssue[];
+
 export declare type YjsArchiveFile = {
     format: 'colwork.archive';
     version: 1;

package/dist/model-merges.d.cts

@@ -0,0 +1,3 @@
+import { CellRange } from './range.cjs';
+/** Sweep rectangles across rows with a range-add tree over compressed columns. */
+export declare function hasOverlappingMerges(merges: CellRange[]): boolean;

package/dist/model-merges.d.ts

@@ -0,0 +1,3 @@
+import { CellRange } from './range.js';
+/** Sweep rectangles across rows with a range-add tree over compressed columns. */
+export declare function hasOverlappingMerges(merges: CellRange[]): boolean;

package/dist/model-schema.d.cts

@@ -0,0 +1,80 @@
+import { CellRange } from './range.cjs';
+import type * as Y from 'yjs';
+/** The existing version-one wire format. Missing metadata is valid legacy data. */
+export declare const COLWORK_SCHEMA_VERSION: 1;
+export declare const COLWORK_MAP_NAMES: Readonly<{
+    readonly cells: "cells";
+    readonly styles: "styles";
+    readonly rowHeights: "rowHeights";
+    readonly columnWidths: "columnWidths";
+    readonly merges: "merges";
+    readonly locks: "locks";
+    readonly metadata: "colwork-metadata";
+}>;
+export type CellBorder = {
+    top?: boolean;
+    right?: boolean;
+    bottom?: boolean;
+    left?: boolean;
+};
+export type CellStyle = {
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strike?: boolean;
+    wrap?: boolean;
+    border?: CellBorder;
+    fontSize?: number;
+    color?: string;
+    background?: string;
+    align?: 'left' | 'center' | 'right';
+    format?: 'general' | 'number' | 'date' | 'percent';
+};
+export type PasswordLock = {
+    version: 1;
+    algorithm: 'PBKDF2-SHA-256';
+    iterations: 600000;
+    salt: string;
+    verifier: string;
+};
+export type CellLock = '1' | PasswordLock;
+export type SheetMaps = {
+    cells: Y.Map<string>;
+    styles: Y.Map<string>;
+    rowHeights: Y.Map<number>;
+    columnWidths: Y.Map<number>;
+    merges: Y.Map<string>;
+    locks: Y.Map<string>;
+};
+/** Sparse, JSON-serializable logical sheet. Dimensions are derived from stored data. */
+export type SheetSnapshot = {
+    schemaVersion: typeof COLWORK_SCHEMA_VERSION;
+    rowCount: number;
+    columnCount: number;
+    cells: Record<string, string>;
+    styles: Record<string, CellStyle>;
+    rowHeights: Record<string, number>;
+    columnWidths: Record<string, number>;
+    merges: CellRange[];
+    locks: Record<string, CellLock>;
+};
+export type SheetValidationIssue = {
+    path: string;
+    message: string;
+};
+export declare function parseCellKey(key: string): {
+    row: number;
+    column: number;
+} | undefined;
+export declare function mergeKey(range: CellRange): string;
+export declare function parseMergeKey(key: string): CellRange | undefined;
+/** Optional host policy. Omitted numeric limits impose no application-specific cap. */
+export type SheetValidationLimits = {
+    maxRows?: number;
+    maxColumns?: number;
+    maxEntries?: number;
+    maxStringLength?: number;
+    maxMergeArea?: number;
+    maxMerges?: number;
+    allowUnknownRoots?: boolean;
+};

package/dist/model-schema.d.ts

@@ -0,0 +1,80 @@
+import { CellRange } from './range.js';
+import type * as Y from 'yjs';
+/** The existing version-one wire format. Missing metadata is valid legacy data. */
+export declare const COLWORK_SCHEMA_VERSION: 1;
+export declare const COLWORK_MAP_NAMES: Readonly<{
+    readonly cells: "cells";
+    readonly styles: "styles";
+    readonly rowHeights: "rowHeights";
+    readonly columnWidths: "columnWidths";
+    readonly merges: "merges";
+    readonly locks: "locks";
+    readonly metadata: "colwork-metadata";
+}>;
+export type CellBorder = {
+    top?: boolean;
+    right?: boolean;
+    bottom?: boolean;
+    left?: boolean;
+};
+export type CellStyle = {
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strike?: boolean;
+    wrap?: boolean;
+    border?: CellBorder;
+    fontSize?: number;
+    color?: string;
+    background?: string;
+    align?: 'left' | 'center' | 'right';
+    format?: 'general' | 'number' | 'date' | 'percent';
+};
+export type PasswordLock = {
+    version: 1;
+    algorithm: 'PBKDF2-SHA-256';
+    iterations: 600000;
+    salt: string;
+    verifier: string;
+};
+export type CellLock = '1' | PasswordLock;
+export type SheetMaps = {
+    cells: Y.Map<string>;
+    styles: Y.Map<string>;
+    rowHeights: Y.Map<number>;
+    columnWidths: Y.Map<number>;
+    merges: Y.Map<string>;
+    locks: Y.Map<string>;
+};
+/** Sparse, JSON-serializable logical sheet. Dimensions are derived from stored data. */
+export type SheetSnapshot = {
+    schemaVersion: typeof COLWORK_SCHEMA_VERSION;
+    rowCount: number;
+    columnCount: number;
+    cells: Record<string, string>;
+    styles: Record<string, CellStyle>;
+    rowHeights: Record<string, number>;
+    columnWidths: Record<string, number>;
+    merges: CellRange[];
+    locks: Record<string, CellLock>;
+};
+export type SheetValidationIssue = {
+    path: string;
+    message: string;
+};
+export declare function parseCellKey(key: string): {
+    row: number;
+    column: number;
+} | undefined;
+export declare function mergeKey(range: CellRange): string;
+export declare function parseMergeKey(key: string): CellRange | undefined;
+/** Optional host policy. Omitted numeric limits impose no application-specific cap. */
+export type SheetValidationLimits = {
+    maxRows?: number;
+    maxColumns?: number;
+    maxEntries?: number;
+    maxStringLength?: number;
+    maxMergeArea?: number;
+    maxMerges?: number;
+    allowUnknownRoots?: boolean;
+};

package/dist/model-validation.d.cts

@@ -0,0 +1,7 @@
+import { CellStyle, PasswordLock, SheetMaps, SheetValidationIssue, SheetValidationLimits } from './model-schema.cjs';
+import * as Y from 'yjs';
+export declare function isPasswordLock(value: unknown): value is PasswordLock;
+export declare function isCellStyle(value: unknown): value is CellStyle;
+/** Materializes named Y.Map roots, preserving the version-one encoding. */
+export declare function getSheetMaps(document: Y.Doc): SheetMaps;
+export declare function validateSheetDocument(document: Y.Doc, limits?: SheetValidationLimits): SheetValidationIssue[];

package/dist/model-validation.d.ts

@@ -0,0 +1,7 @@
+import { CellStyle, PasswordLock, SheetMaps, SheetValidationIssue, SheetValidationLimits } from './model-schema.js';
+import * as Y from 'yjs';
+export declare function isPasswordLock(value: unknown): value is PasswordLock;
+export declare function isCellStyle(value: unknown): value is CellStyle;
+/** Materializes named Y.Map roots, preserving the version-one encoding. */
+export declare function getSheetMaps(document: Y.Doc): SheetMaps;
+export declare function validateSheetDocument(document: Y.Doc, limits?: SheetValidationLimits): SheetValidationIssue[];

package/dist/model.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const I=require("yjs");function _(e){const t=Object.create(null,{[Symbol.toStringTag]:{value:"Module"}});if(e){for(const r in e)if(r!=="default"){const n=Object.getOwnPropertyDescriptor(e,r);Object.defineProperty(t,r,n.get?n:{enumerable:!0,get:()=>e[r]})}}return t.default=e,Object.freeze(t)}const g=_(I),y=1,p=Object.freeze({cells:"cells",styles:"styles",rowHeights:"rowHeights",columnWidths:"columnWidths",merges:"merges",locks:"locks",metadata:"colwork-metadata"});function S(e){if(!/^(0|[1-9]\d*):(0|[1-9]\d*)$/.test(e))return;const[t,r]=e.split(":").map(Number);return Number.isSafeInteger(t)&&Number.isSafeInteger(r)?{row:t,column:r}:void 0}function R(e){return`${e.start.row}:${e.start.column}-${e.end.row}:${e.end.column}`}function E(e){const t=e.split("-");if(t.length!==2)return;const r=S(t[0]),n=S(t[1]);if(!(!r||!n||r.row>n.row||r.column>n.column))return{start:r,end:n}}function z(e){for(const t of e){const r=t.codePointAt(0);if(r>=55296&&r<=57343)return!1}return!0}function U(e){if(e.length<2)return!1;const t=[...new Set(e.flatMap(i=>[i.start.column,i.end.column+1]))].sort((i,m)=>i-m),r=new Map(t.map((i,m)=>[i,m])),n=e.flatMap(i=>[{row:i.start.row,left:r.get(i.start.column),right:r.get(i.end.column+1)-1,delta:1},{row:i.end.row+1,left:r.get(i.start.column),right:r.get(i.end.column+1)-1,delta:-1}]).sort((i,m)=>i.row-m.row||i.delta-m.delta),f=new Int32Array(t.length*4),d=new Int32Array(t.length*4),u=(i,m,c,l,o,s)=>{if(l<=m&&c<=o){f[i]+=s,d[i]+=s;return}const a=Math.floor((m+c)/2);l<=a&&u(i*2,m,a,l,o,s),o>a&&u(i*2+1,a+1,c,l,o,s),f[i]=d[i]+Math.max(f[i*2],f[i*2+1])};for(const i of n)if(u(1,0,t.length-2,i.left,i.right,i.delta),f[1]>1)return!0;return!1}const x=e=>!!e&&typeof e=="object"&&!Array.isArray(e)&&Object.getPrototypeOf(e)===Object.prototype,k=(e,t)=>Object.keys(e).every(r=>t.includes(r));function q(e){return x(e)&&k(e,["version","algorithm","iterations","salt","verifier"])&&e.version===1&&e.algorithm==="PBKDF2-SHA-256"&&e.iterations===6e5&&typeof e.salt=="string"&&/^[0-9a-f]{32}$/.test(e.salt)&&typeof e.verifier=="string"&&/^[0-9a-f]{64}$/.test(e.verifier)}function K(e){if(!x(e)||!k(e,["bold","italic","underline","strike","wrap","border","fontSize","color","background","align","format"]))return!1;for(const t of["bold","italic","underline","strike","wrap"])if(t in e&&typeof e[t]!="boolean")return!1;for(const t of["color","background"])if(t in e&&(typeof e[t]!="string"||!z(e[t])))return!1;if("fontSize"in e&&(typeof e.fontSize!="number"||!Number.isFinite(e.fontSize)||e.fontSize<=0)||"align"in e&&(typeof e.align!="string"||!["left","center","right"].includes(e.align))||"format"in e&&(typeof e.format!="string"||!["general","number","date","percent"].includes(e.format)))return!1;if("border"in e){if(!x(e.border)||!k(e.border,["top","right","bottom","left"]))return!1;for(const t of Object.keys(e.border))if(typeof e.border[t]!="boolean")return!1}return!0}function M(e){return{cells:e.getMap(p.cells),styles:e.getMap(p.styles),rowHeights:e.getMap(p.rowHeights),columnWidths:e.getMap(p.columnWidths),merges:e.getMap(p.merges),locks:e.getMap(p.locks)}}function O(e,t={}){for(const o of["maxRows","maxColumns","maxEntries","maxStringLength","maxMergeArea","maxMerges"]){const s=t[o];if(s!==void 0&&(!Number.isSafeInteger(s)||s<0))throw new RangeError(`${o} must be a non-negative safe integer`)}const r=[];(e.store.pendingStructs!==null||e.store.pendingDs!==null)&&r.push({path:"$",message:"Document contains unresolved Yjs update dependencies"});const n=(o,s)=>{r.push({path:o,message:s})};if(!t.allowUnknownRoots)for(const o of e.share.keys())Object.values(p).includes(o)||n(o,"Unknown document root");let f,d;try{f=M(e),d=e.getMap(p.metadata)}catch{return[...r,{path:"$",message:"Sheet roots must be Y.Map values"}]}for(const[o,s]of[...Object.entries(f),["metadata",d]])(!(s instanceof g.Map)||s._start!==null)&&n(o,"Expected map entries without sequence content");const u=Object.values(f).reduce((o,s)=>o+s.size,d.size);t.maxEntries!==void 0&&u>t.maxEntries&&n("$","Document exceeds maxEntries");const i=(o,s)=>o<Number.MAX_SAFE_INTEGER&&s<Number.MAX_SAFE_INTEGER&&(t.maxRows===void 0||o<t.maxRows)&&(t.maxColumns===void 0||s<t.maxColumns),m=(o,s)=>{if(typeof o!="string")return!1;try{return s(JSON.parse(o))}catch{return!1}},c=(o,s,a)=>{typeof a=="string"&&t.maxStringLength!==void 0&&a.length>t.maxStringLength&&n(`${o}.${s}`,"String exceeds maxStringLength")};for(const o of["cells","styles","locks"])f[o].forEach((s,a)=>{const h=S(a);(!h||!i(h.row,h.column))&&n(`${o}.${a}`,"Invalid or out-of-bounds row:column key"),c(o,a,s),o==="cells"&&(typeof s!="string"||!z(s))&&n(`${o}.${a}`,"Cell values must be strings"),o==="styles"&&!m(s,K)&&n(`${o}.${a}`,"Expected a JSON CellStyle object"),o==="locks"&&s!=="1"&&!m(s,q)&&n(`${o}.${a}`,"Expected a plain lock or version-one password verifier")});for(const o of["rowHeights","columnWidths"])f[o].forEach((s,a)=>{const h=Number(a),N=o==="rowHeights"?t.maxRows:t.maxColumns;(!/^(0|[1-9]\d*)$/.test(a)||!Number.isSafeInteger(h)||h>=Number.MAX_SAFE_INTEGER||N!==void 0&&h>=N)&&n(`${o}.${a}`,"Invalid or out-of-bounds index"),(typeof s!="number"||!Number.isFinite(s)||s<=0)&&n(`${o}.${a}`,"Sizes must be finite positive numbers")});t.maxMerges!==void 0&&f.merges.size>t.maxMerges&&n("merges","Document exceeds maxMerges");const l=[];return f.merges.forEach((o,s)=>{const a=E(s);!a||o!=="1"||!i(a.end.row,a.end.column)?n(`merges.${s}`,"Invalid or out-of-bounds merge range"):(t.maxMergeArea!==void 0&&a.end.row-a.start.row+1>t.maxMergeArea/(a.end.column-a.start.column+1)&&n(`merges.${s}`,"Merge exceeds maxMergeArea"),l.push(a))}),U(l)&&n("merges","Merge ranges must not overlap"),d.forEach((o,s)=>{s==="schemaVersion"?o!==y&&n("metadata.schemaVersion","Unsupported schema version"):s==="initialized"?typeof o!="boolean"&&n("metadata.initialized","Expected a boolean"):n(`metadata.${s}`,"Unknown metadata field")}),r}function w(e){let t="";for(let n=0;n<e.length;n+=32768)t+=String.fromCharCode(...e.subarray(n,n+32768));return btoa(t)}function $(e){const t=atob(e);return Uint8Array.from(t,r=>r.charCodeAt(0))}function j(e){if(e!=null&&e.trim())return JSON.parse(e)}function V(e){if(!(!e||e.format==="colwork.update-log"))return e.format==="colwork.archive"?e.snapshot:e}function A(e){return!e||e.format==="colwork.snapshot"?[]:e.updates??[]}function H(e,t){const r=j(e),n=j(t),f=V(r),d=[...A(r),...A(n)],u=new g.Doc;try{f!=null&&f.snapshot&&g.applyUpdate(u,$(f.snapshot));const i=Number((f==null?void 0:f.sequence)??0),m=new Set,c=new Set;let l=i;for(const o of d.sort((s,a)=>Number(s.seq)-Number(a.seq))){const s=Number(o.seq);!Number.isInteger(s)||typeof o.update!="string"||s<=i||m.has(s)||c.has(o.update)||(g.applyUpdate(u,$(o.update)),m.add(s),c.add(o.update),l=Math.max(l,s))}return{format:"colwork.snapshot",version:1,room:f==null?void 0:f.room,sequence:l,snapshot:w(g.encodeStateAsUpdate(u)),stateVector:w(g.encodeStateVector(u))}}finally{u.destroy()}}function W(e,t){const r=e.split(":").map(Number),n=t.split(":").map(Number);return r[0]-n[0]||(r[1]??0)-(n[1]??0)}function b(e){return[...e].sort(([t],[r])=>W(t,r))}function D(e){const t={};for(const r of["bold","italic","underline","strike","wrap","fontSize","color","background","align","format"])e[r]!==void 0&&(t[r]=e[r]);if(e.border!==void 0){const r={};for(const n of["top","right","bottom","left"])e.border[n]!==void 0&&(r[n]=e.border[n]);t.border=r}return t}function C(e,t){const r=O(e,t);if(r.length)throw new TypeError(`Invalid Colwork document at ${r[0].path}: ${r[0].message}`);const n=M(e),f=Object.fromEntries(b(n.styles).map(([c,l])=>[c,D(JSON.parse(l))])),d=Object.fromEntries(b(n.locks).map(([c,l])=>{if(l==="1")return[c,"1"];const o=JSON.parse(l);return[c,{version:o.version,algorithm:o.algorithm,iterations:o.iterations,salt:o.salt,verifier:o.verifier}]})),u=[...n.merges.keys()].map(c=>E(c)).sort((c,l)=>c.start.row-l.start.row||c.start.column-l.start.column||c.end.row-l.end.row||c.end.column-l.end.column);let i=1,m=1;for(const c of[...n.cells.keys(),...n.styles.keys(),...n.locks.keys()]){const l=S(c);i=Math.max(i,l.row+1),m=Math.max(m,l.column+1)}for(const c of u)i=Math.max(i,c.end.row+1),m=Math.max(m,c.end.column+1);for(const c of n.rowHeights.keys())i=Math.max(i,Number(c)+1);for(const c of n.columnWidths.keys())m=Math.max(m,Number(c)+1);return{schemaVersion:y,rowCount:i,columnCount:m,cells:Object.fromEntries(b(n.cells)),styles:f,rowHeights:Object.fromEntries(b(n.rowHeights)),columnWidths:Object.fromEntries(b(n.columnWidths)),merges:u,locks:d}}function L(e){const t=O(e);if(t.length)throw new TypeError(`Invalid Colwork document at ${t[0].path}: ${t[0].message}`);if(Object.values(M(e)).some(n=>n.size>0))throw new Error("Blank initialization requires an empty sheet");const r=e.getMap(p.metadata);e.transact(()=>{r.set("schemaVersion",y),r.set("initialized",!0)})}function P(e,t={}){const r=t.sequence??0;if(!Number.isSafeInteger(r)||r<0)throw new RangeError("sequence must be a non-negative safe integer");return{format:"colwork.snapshot",version:1,room:t.room,sequence:r,snapshot:w(g.encodeStateAsUpdate(e)),stateVector:w(g.encodeStateVector(e))}}function T(e,t){const r=new g.Doc;try{return g.applyUpdate(r,e),C(r,t)}finally{r.destroy()}}exports.COLWORK_MAP_NAMES=p;exports.COLWORK_SCHEMA_VERSION=y;exports.exportYjsSnapshot=P;exports.getSheetMaps=M;exports.initializeBlankSheet=L;exports.mergeKey=R;exports.parseCellKey=S;exports.parseMergeKey=E;exports.readSheetSnapshot=C;exports.readSheetSnapshotUpdate=T;exports.rebuildYjsSnapshot=H;exports.validateSheetDocument=O;

package/dist/model.d.cts

@@ -0,0 +1,18 @@
+import { SheetSnapshot, SheetValidationLimits } from './model-schema.cjs';
+import { YjsSnapshotFile } from './yjsArchive.cjs';
+import * as Y from 'yjs';
+export * from './model-schema.cjs';
+export type { CellPosition, CellRange } from './range.cjs';
+export { getSheetMaps, validateSheetDocument } from './model-validation.cjs';
+export { rebuildYjsSnapshot } from './yjsRebuild.cjs';
+export type { YjsArchiveFile, YjsSnapshotFile, YjsUpdateLogFile, YjsUpdateRecord } from './yjsArchive.cjs';
+/** Reads a deterministic sparse sheet without loading a renderer, browser globals, or CSS. */
+export declare function readSheetSnapshot(document: Y.Doc, limits?: SheetValidationLimits): SheetSnapshot;
+/** Initializes an empty document without demo cells, headers, styles, or network access. */
+export declare function initializeBlankSheet(document: Y.Doc): void;
+export declare function exportYjsSnapshot(document: Y.Doc, options?: {
+    room?: string;
+    sequence?: number;
+}): YjsSnapshotFile;
+/** Decodes a Yjs state update and releases its temporary document after export. */
+export declare function readSheetSnapshotUpdate(update: Uint8Array, limits?: SheetValidationLimits): SheetSnapshot;

package/dist/model.d.ts

@@ -0,0 +1,18 @@
+import { SheetSnapshot, SheetValidationLimits } from './model-schema.js';
+import { YjsSnapshotFile } from './yjsArchive.js';
+import * as Y from 'yjs';
+export * from './model-schema.js';
+export type { CellPosition, CellRange } from './range.js';
+export { getSheetMaps, validateSheetDocument } from './model-validation.js';
+export { rebuildYjsSnapshot } from './yjsRebuild.js';
+export type { YjsArchiveFile, YjsSnapshotFile, YjsUpdateLogFile, YjsUpdateRecord } from './yjsArchive.js';
+/** Reads a deterministic sparse sheet without loading a renderer, browser globals, or CSS. */
+export declare function readSheetSnapshot(document: Y.Doc, limits?: SheetValidationLimits): SheetSnapshot;
+/** Initializes an empty document without demo cells, headers, styles, or network access. */
+export declare function initializeBlankSheet(document: Y.Doc): void;
+export declare function exportYjsSnapshot(document: Y.Doc, options?: {
+    room?: string;
+    sequence?: number;
+}): YjsSnapshotFile;
+/** Decodes a Yjs state update and releases its temporary document after export. */
+export declare function readSheetSnapshotUpdate(update: Uint8Array, limits?: SheetValidationLimits): SheetSnapshot;