@kuzuma/colwork 0.0.0-stage → 0.2.0

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;

package/dist/model.js

@@ -0,0 +1,259 @@
+import * as p from "yjs";
+const M = 1, g = Object.freeze({
+  cells: "cells",
+  styles: "styles",
+  rowHeights: "rowHeights",
+  columnWidths: "columnWidths",
+  merges: "merges",
+  locks: "locks",
+  metadata: "colwork-metadata"
+});
+function w(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 _(e) {
+  return `${e.start.row}:${e.start.column}-${e.end.row}:${e.end.column}`;
+}
+function A(e) {
+  const t = e.split("-");
+  if (t.length !== 2) return;
+  const r = w(t[0]), n = w(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 I(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), l = (i, m, c, u, o, s) => {
+    if (u <= m && c <= o) {
+      f[i] += s, d[i] += s;
+      return;
+    }
+    const a = Math.floor((m + c) / 2);
+    u <= a && l(i * 2, m, a, u, o, s), o > a && l(i * 2 + 1, a + 1, c, u, o, s), f[i] = d[i] + Math.max(f[i * 2], f[i * 2 + 1]);
+  };
+  for (const i of n)
+    if (l(1, 0, t.length - 2, i.left, i.right, i.delta), f[1] > 1) return !0;
+  return !1;
+}
+const S = (e) => !!e && typeof e == "object" && !Array.isArray(e) && Object.getPrototypeOf(e) === Object.prototype, x = (e, t) => Object.keys(e).every((r) => t.includes(r));
+function C(e) {
+  return S(e) && x(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 R(e) {
+  if (!S(e) || !x(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 (!S(e.border) || !x(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 k(e) {
+  return {
+    cells: e.getMap(g.cells),
+    styles: e.getMap(g.styles),
+    rowHeights: e.getMap(g.rowHeights),
+    columnWidths: e.getMap(g.columnWidths),
+    merges: e.getMap(g.merges),
+    locks: e.getMap(g.locks)
+  };
+}
+function j(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(g).includes(o) || n(o, "Unknown document root");
+  let f, d;
+  try {
+    f = k(e), d = e.getMap(g.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 p.Map) || s._start !== null) && n(o, "Expected map entries without sequence content");
+  const l = Object.values(f).reduce((o, s) => o + s.size, d.size);
+  t.maxEntries !== void 0 && l > 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 = w(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, R) && n(`${o}.${a}`, "Expected a JSON CellStyle object"), o === "locks" && s !== "1" && !m(s, C) && 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), E = o === "rowHeights" ? t.maxRows : t.maxColumns;
+      (!/^(0|[1-9]\d*)$/.test(a) || !Number.isSafeInteger(h) || h >= Number.MAX_SAFE_INTEGER || E !== void 0 && h >= E) && 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 u = [];
+  return f.merges.forEach((o, s) => {
+    const a = A(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"), u.push(a));
+  }), I(u) && n("merges", "Merge ranges must not overlap"), d.forEach((o, s) => {
+    s === "schemaVersion" ? o !== M && 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 y(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 N(e) {
+  if (e != null && e.trim())
+    return JSON.parse(e);
+}
+function U(e) {
+  if (!(!e || e.format === "colwork.update-log"))
+    return e.format === "colwork.archive" ? e.snapshot : e;
+}
+function O(e) {
+  return !e || e.format === "colwork.snapshot" ? [] : e.updates ?? [];
+}
+function W(e, t) {
+  const r = N(e), n = N(t), f = U(r), d = [...O(r), ...O(n)], l = new p.Doc();
+  try {
+    f != null && f.snapshot && p.applyUpdate(l, $(f.snapshot));
+    const i = Number((f == null ? void 0 : f.sequence) ?? 0), m = /* @__PURE__ */ new Set(), c = /* @__PURE__ */ new Set();
+    let u = 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) || (p.applyUpdate(l, $(o.update)), m.add(s), c.add(o.update), u = Math.max(u, s));
+    }
+    return {
+      format: "colwork.snapshot",
+      version: 1,
+      room: f == null ? void 0 : f.room,
+      sequence: u,
+      snapshot: y(p.encodeStateAsUpdate(l)),
+      stateVector: y(p.encodeStateVector(l))
+    };
+  } finally {
+    l.destroy();
+  }
+}
+function q(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]) => q(t, r));
+}
+function V(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 H(e, t) {
+  const r = j(e, t);
+  if (r.length) throw new TypeError(`Invalid Colwork document at ${r[0].path}: ${r[0].message}`);
+  const n = k(e), f = Object.fromEntries(b(n.styles).map(([c, u]) => [c, V(JSON.parse(u))])), d = Object.fromEntries(b(n.locks).map(([c, u]) => {
+    if (u === "1") return [c, "1"];
+    const o = JSON.parse(u);
+    return [c, { version: o.version, algorithm: o.algorithm, iterations: o.iterations, salt: o.salt, verifier: o.verifier }];
+  })), l = [...n.merges.keys()].map((c) => A(c)).sort((c, u) => c.start.row - u.start.row || c.start.column - u.start.column || c.end.row - u.end.row || c.end.column - u.end.column);
+  let i = 1, m = 1;
+  for (const c of [...n.cells.keys(), ...n.styles.keys(), ...n.locks.keys()]) {
+    const u = w(c);
+    i = Math.max(i, u.row + 1), m = Math.max(m, u.column + 1);
+  }
+  for (const c of l)
+    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: M,
+    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: l,
+    locks: d
+  };
+}
+function D(e) {
+  const t = j(e);
+  if (t.length) throw new TypeError(`Invalid Colwork document at ${t[0].path}: ${t[0].message}`);
+  if (Object.values(k(e)).some((n) => n.size > 0)) throw new Error("Blank initialization requires an empty sheet");
+  const r = e.getMap(g.metadata);
+  e.transact(() => {
+    r.set("schemaVersion", M), r.set("initialized", !0);
+  });
+}
+function K(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: y(p.encodeStateAsUpdate(e)),
+    stateVector: y(p.encodeStateVector(e))
+  };
+}
+function L(e, t) {
+  const r = new p.Doc();
+  try {
+    return p.applyUpdate(r, e), H(r, t);
+  } finally {
+    r.destroy();
+  }
+}
+export {
+  g as COLWORK_MAP_NAMES,
+  M as COLWORK_SCHEMA_VERSION,
+  K as exportYjsSnapshot,
+  k as getSheetMaps,
+  D as initializeBlankSheet,
+  _ as mergeKey,
+  w as parseCellKey,
+  A as parseMergeKey,
+  H as readSheetSnapshot,
+  L as readSheetSnapshotUpdate,
+  W as rebuildYjsSnapshot,
+  j as validateSheetDocument
+};

package/dist/range.d.cts

@@ -0,0 +1,15 @@
+export type CellPosition = {
+    row: number;
+    column: number;
+};
+export type CellRange = {
+    start: CellPosition;
+    end: CellPosition;
+};
+export declare function normalizeRange(start: CellPosition, end: CellPosition): CellRange;
+export declare function containsPosition(range: CellRange, position: CellPosition): boolean;
+export declare function rangeSize(range: CellRange): {
+    rows: number;
+    columns: number;
+};
+export declare function cellKey(position: CellPosition): string;

package/dist/range.d.ts

@@ -0,0 +1,15 @@
+export type CellPosition = {
+    row: number;
+    column: number;
+};
+export type CellRange = {
+    start: CellPosition;
+    end: CellPosition;
+};
+export declare function normalizeRange(start: CellPosition, end: CellPosition): CellRange;
+export declare function containsPosition(range: CellRange, position: CellPosition): boolean;
+export declare function rangeSize(range: CellRange): {
+    rows: number;
+    columns: number;
+};
+export declare function cellKey(position: CellPosition): string;

package/dist/yjsArchive.d.cts

@@ -0,0 +1,28 @@
+export type YjsUpdateRecord = {
+    seq: number;
+    update: string;
+    timestamp: number;
+};
+export type YjsSnapshotFile = {
+    format: 'colwork.snapshot';
+    version: 1;
+    room?: string;
+    sequence: number;
+    snapshot: string;
+    stateVector: string;
+};
+export type YjsUpdateLogFile = {
+    format: 'colwork.update-log';
+    version: 1;
+    room?: string;
+    updates: YjsUpdateRecord[];
+};
+export type YjsArchiveFile = {
+    format: 'colwork.archive';
+    version: 1;
+    room?: string;
+    snapshot?: YjsSnapshotFile;
+    updates: YjsUpdateRecord[];
+};
+export declare function bytesToBase64(bytes: Uint8Array): string;
+export declare function base64ToBytes(value: string): Uint8Array<ArrayBuffer>;

package/dist/yjsArchive.d.ts

@@ -0,0 +1,28 @@
+export type YjsUpdateRecord = {
+    seq: number;
+    update: string;
+    timestamp: number;
+};
+export type YjsSnapshotFile = {
+    format: 'colwork.snapshot';
+    version: 1;
+    room?: string;
+    sequence: number;
+    snapshot: string;
+    stateVector: string;
+};
+export type YjsUpdateLogFile = {
+    format: 'colwork.update-log';
+    version: 1;
+    room?: string;
+    updates: YjsUpdateRecord[];
+};
+export type YjsArchiveFile = {
+    format: 'colwork.archive';
+    version: 1;
+    room?: string;
+    snapshot?: YjsSnapshotFile;
+    updates: YjsUpdateRecord[];
+};
+export declare function bytesToBase64(bytes: Uint8Array): string;
+export declare function base64ToBytes(value: string): Uint8Array<ArrayBuffer>;

package/dist/yjsRebuild.d.cts

@@ -0,0 +1,2 @@
+import { YjsSnapshotFile } from './yjsArchive.cjs';
+export declare function rebuildYjsSnapshot(snapshotText?: string, updateLogText?: string): YjsSnapshotFile;

package/dist/yjsRebuild.d.ts

@@ -0,0 +1,2 @@
+import { YjsSnapshotFile } from './yjsArchive.js';
+export declare function rebuildYjsSnapshot(snapshotText?: string, updateLogText?: string): YjsSnapshotFile;

package/package.json

@@ -1,6 +1,92 @@
 {
   "name": "@kuzuma/colwork",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "dev": "node script/demo.mjs dev",
+    "dev:test": "node script/demo.mjs dev",
+    "server": "node server/index.mjs",
+    "server:test": "node server/index.mjs --mode test",
+    "rebuild:yjs": "node script/rebuild-yjs.mjs",
+    "build": "npm run build:lib",
+    "build:lib": "tsc --noEmit && vite build --config vite.lib.config.ts && vite build --config vite.model.config.ts",
+    "test:e2e": "playwright test",
+    "build:site": "node script/demo.mjs build",
+    "dev:cloudflare": "npm run build:site && wrangler dev --config config/cloudflare/wrangler.dev.json --persist-to .wrangler/state",
+    "deploy:check": "node script/deploy-cloudflare.mjs --dry-run",
+    "deploy": "node script/deploy-cloudflare.mjs",
+    "test:cloudflare": "node --test test/cloudflare/*.test.mjs",
+    "prepublishOnly": "npm run build:lib",
+    "test:model": "node --test test/model/*.test.mjs"
+  },
+  "dependencies": {
+    "y-protocols": "^1.0.7",
+    "y-webrtc": "^10.3.0",
+    "y-websocket": "^2.1.0",
+    "yjs": "^13.6.27"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.63.0",
+    "@types/react": "^19.1.2",
+    "@types/react-dom": "^19.1.2",
+    "@vitejs/plugin-react": "^4.4.1",
+    "@vitejs/plugin-vue": "^5.2.3",
+    "lib0": "^0.2.119",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "typescript": "^5.8.3",
+    "vite": "^6.3.5",
+    "vite-plugin-dts": "^4.5.4",
+    "vue": "^3.5.13",
+    "wrangler": "^4.145.0",
+    "ws": "^8.21.3"
+  },
+  "description": "A collaborative spreadsheet library powered by Yjs, with native DOM rendering, frozen panes, and password-protected ranges.",
+  "main": "./dist/colwork.umd.cjs",
+  "module": "./dist/colwork.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/colwork.js",
+      "require": "./dist/colwork.umd.cjs"
+    },
+    "./colwork.css": "./dist/colwork.css",
+    "./model": {
+      "import": {
+        "types": "./dist/model.d.ts",
+        "default": "./dist/model.js"
+      },
+      "require": {
+        "types": "./dist/model.d.cts",
+        "default": "./dist/model.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dlwm/colwork.git"
+  },
+  "homepage": "https://github.com/dlwm/colwork#readme",
+  "bugs": {
+    "url": "https://github.com/dlwm/colwork/issues"
+  },
+  "keywords": [
+    "spreadsheet",
+    "collaboration",
+    "yjs",
+    "vue",
+    "react"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}