ducjs 3.0.4 → 3.1.0

package/dist/ducjs_wasm.d.ts

@@ -1,28 +1,30 @@
 /* tslint:disable */
 /* eslint-disable */
 /**
- * Parse a `.duc` file (Uint8Array) into a JS object (ExportedDataState).
+ * Fetch a single external file from a `.duc` buffer by file ID.
+ *
+ * Returns the file entry as a JS object, or `undefined` if not found.
  */
-export function parseDuc(buf: Uint8Array): any;
+export function getExternalFile(buf: Uint8Array, file_id: string): any;
 /**
- * Read the full VersionGraph from a `.duc` file buffer.
+ * Restore a specific checkpoint by its ID from a `.duc` file buffer.
  *
- * Returns a JS object matching the `VersionGraph` TypeScript interface,
- * or `undefined` if no version graph exists.
+ * Returns a JS object `{ versionNumber, schemaVersion, data, fromCheckpoint }`.
  */
-export function readVersionGraph(duc_buf: Uint8Array): any;
+export function restoreCheckpoint(duc_buf: Uint8Array, checkpoint_id: string): any;
 /**
- * Fetch a single external file from a `.duc` buffer by file ID.
+ * List all versions (checkpoints + deltas) from a `.duc` file buffer.
  *
- * Returns the file entry as a JS object, or `undefined` if not found.
+ * Returns a JS array of `VersionEntry` objects (no heavy data blobs).
  */
-export function getExternalFile(buf: Uint8Array, file_id: string): any;
+export function listVersions(duc_buf: Uint8Array): any;
 /**
- * Revert the document to a specific version, removing all newer versions.
+ * Read the full VersionGraph from a `.duc` file buffer.
  *
- * Returns a JS object `{ versionNumber, schemaVersion, data, fromCheckpoint }`.
+ * Returns a JS object matching the `VersionGraph` TypeScript interface,
+ * or `undefined` if no version graph exists.
  */
-export function revertToVersion(duc_buf: Uint8Array, target_version: number): any;
+export function readVersionGraph(duc_buf: Uint8Array): any;
 /**
  * Returns the current version-control schema version defined in Rust.
  *
@@ -32,12 +34,6 @@ export function revertToVersion(duc_buf: Uint8Array, target_version: number): an
  * recording migrations) the next time a checkpoint or delta is created.
  */
 export function getCurrentSchemaVersion(): number;
-/**
- * List all versions (checkpoints + deltas) from a `.duc` file buffer.
- *
- * Returns a JS array of `VersionEntry` objects (no heavy data blobs).
- */
-export function listVersions(duc_buf: Uint8Array): any;
 /**
  * Restore the document state at `version_number` from a `.duc` file buffer.
  *
@@ -47,31 +43,58 @@ export function listVersions(duc_buf: Uint8Array): any;
  * Returns a JS object `{ versionNumber, schemaVersion, data, fromCheckpoint }`.
  */
 export function restoreVersion(duc_buf: Uint8Array, version_number: number): any;
+/**
+ * Revert the document to a specific version, removing all newer versions.
+ *
+ * Returns a JS object `{ versionNumber, schemaVersion, data, fromCheckpoint }`.
+ */
+export function revertToVersion(duc_buf: Uint8Array, target_version: number): any;
+/**
+ * Apply a changeset to reconstruct document state.
+ *
+ * `base_state` must be the exact checkpoint data used when the changeset
+ * was created. Returns the full document state as `Uint8Array`.
+ *
+ * Handles all changeset formats transparently:
+ *   - v3 (bsdiff), v2 (XOR diff), v1 (zlib full snapshot)
+ */
+export function applyDeltaChangeset(base_state: Uint8Array, changeset: Uint8Array): Uint8Array;
+/**
+ * List metadata for all external files (without loading the heavy data blobs).
+ */
+export function listExternalFiles(buf: Uint8Array): any;
 /**
  * Serialize a JS object (ExportedDataState) into `.duc` bytes (Uint8Array).
  */
 export function serializeDuc(data: any): Uint8Array;
 /**
- * Restore a specific checkpoint by its ID from a `.duc` file buffer.
+ * Compute a checkpoint-relative binary diff changeset using bsdiff.
  *
- * Returns a JS object `{ versionNumber, schemaVersion, data, fromCheckpoint }`.
+ * `base_state` is the checkpoint's full data blob.
+ * `current_state` is the full document state at the new version.
+ *
+ * Returns an encoded changeset (`Uint8Array`) ready for storage in a
+ * `Delta.payload`. bsdiff finds matching blocks even when they shift
+ * offsets, which is critical for SQLite databases.
  */
-export function restoreCheckpoint(duc_buf: Uint8Array, checkpoint_id: string): any;
+export function createDeltaChangeset(base_state: Uint8Array, current_state: Uint8Array): Uint8Array;
+/**
+ * Parse a `.duc` file (Uint8Array) into a JS object (ExportedDataState).
+ */
+export function parseDuc(buf: Uint8Array): any;
 /**
  * Parse a `.duc` file lazily — returns everything EXCEPT external file data blobs.
  *
  * Use `getExternalFile()` or `listExternalFiles()` for on-demand access.
  */
 export function parseDucLazy(buf: Uint8Array): any;
-/**
- * List metadata for all external files (without loading the heavy data blobs).
- */
-export function listExternalFiles(buf: Uint8Array): any;
 
 export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
 
 export interface InitOutput {
   readonly memory: WebAssembly.Memory;
+  readonly applyDeltaChangeset: (a: number, b: number, c: number, d: number) => [number, number, number, number];
+  readonly createDeltaChangeset: (a: number, b: number, c: number, d: number) => [number, number, number, number];
   readonly getCurrentSchemaVersion: () => number;
   readonly getExternalFile: (a: number, b: number, c: number, d: number) => [number, number, number];
   readonly listExternalFiles: (a: number, b: number) => [number, number, number];

package/dist/ducjs_wasm.js

@@ -195,14 +195,19 @@ function takeFromExternrefTable0(idx) {
     return value;
 }
 /**
- * Parse a `.duc` file (Uint8Array) into a JS object (ExportedDataState).
+ * Fetch a single external file from a `.duc` buffer by file ID.
+ *
+ * Returns the file entry as a JS object, or `undefined` if not found.
  * @param {Uint8Array} buf
+ * @param {string} file_id
  * @returns {any}
  */
-export function parseDuc(buf) {
+export function getExternalFile(buf, file_id) {
     const ptr0 = passArray8ToWasm0(buf, wasm.__wbindgen_malloc);
     const len0 = WASM_VECTOR_LEN;
-    const ret = wasm.parseDuc(ptr0, len0);
+    const ptr1 = passStringToWasm0(file_id, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len1 = WASM_VECTOR_LEN;
+    const ret = wasm.getExternalFile(ptr0, len0, ptr1, len1);
     if (ret[2]) {
         throw takeFromExternrefTable0(ret[1]);
     }
@@ -210,17 +215,19 @@ export function parseDuc(buf) {
 }
 
 /**
- * Read the full VersionGraph from a `.duc` file buffer.
+ * Restore a specific checkpoint by its ID from a `.duc` file buffer.
  *
- * Returns a JS object matching the `VersionGraph` TypeScript interface,
- * or `undefined` if no version graph exists.
+ * Returns a JS object `{ versionNumber, schemaVersion, data, fromCheckpoint }`.
  * @param {Uint8Array} duc_buf
+ * @param {string} checkpoint_id
  * @returns {any}
  */
-export function readVersionGraph(duc_buf) {
+export function restoreCheckpoint(duc_buf, checkpoint_id) {
     const ptr0 = passArray8ToWasm0(duc_buf, wasm.__wbindgen_malloc);
     const len0 = WASM_VECTOR_LEN;
-    const ret = wasm.readVersionGraph(ptr0, len0);
+    const ptr1 = passStringToWasm0(checkpoint_id, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len1 = WASM_VECTOR_LEN;
+    const ret = wasm.restoreCheckpoint(ptr0, len0, ptr1, len1);
     if (ret[2]) {
         throw takeFromExternrefTable0(ret[1]);
     }
@@ -228,19 +235,16 @@ export function readVersionGraph(duc_buf) {
 }
 
 /**
- * Fetch a single external file from a `.duc` buffer by file ID.
+ * List all versions (checkpoints + deltas) from a `.duc` file buffer.
  *
- * Returns the file entry as a JS object, or `undefined` if not found.
- * @param {Uint8Array} buf
- * @param {string} file_id
+ * Returns a JS array of `VersionEntry` objects (no heavy data blobs).
+ * @param {Uint8Array} duc_buf
  * @returns {any}
  */
-export function getExternalFile(buf, file_id) {
-    const ptr0 = passArray8ToWasm0(buf, wasm.__wbindgen_malloc);
+export function listVersions(duc_buf) {
+    const ptr0 = passArray8ToWasm0(duc_buf, wasm.__wbindgen_malloc);
     const len0 = WASM_VECTOR_LEN;
-    const ptr1 = passStringToWasm0(file_id, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
-    const len1 = WASM_VECTOR_LEN;
-    const ret = wasm.getExternalFile(ptr0, len0, ptr1, len1);
+    const ret = wasm.listVersions(ptr0, len0);
     if (ret[2]) {
         throw takeFromExternrefTable0(ret[1]);
     }
@@ -248,17 +252,17 @@ export function getExternalFile(buf, file_id) {
 }
 
 /**
- * Revert the document to a specific version, removing all newer versions.
+ * Read the full VersionGraph from a `.duc` file buffer.
  *
- * Returns a JS object `{ versionNumber, schemaVersion, data, fromCheckpoint }`.
+ * Returns a JS object matching the `VersionGraph` TypeScript interface,
+ * or `undefined` if no version graph exists.
  * @param {Uint8Array} duc_buf
- * @param {number} target_version
  * @returns {any}
  */
-export function revertToVersion(duc_buf, target_version) {
+export function readVersionGraph(duc_buf) {
     const ptr0 = passArray8ToWasm0(duc_buf, wasm.__wbindgen_malloc);
     const len0 = WASM_VECTOR_LEN;
-    const ret = wasm.revertToVersion(ptr0, len0, target_version);
+    const ret = wasm.readVersionGraph(ptr0, len0);
     if (ret[2]) {
         throw takeFromExternrefTable0(ret[1]);
     }
@@ -275,20 +279,24 @@ export function revertToVersion(duc_buf, target_version) {
  * @returns {number}
  */
 export function getCurrentSchemaVersion() {
-    return 3000000;
+    return 3000001;
 }
 
 /**
- * List all versions (checkpoints + deltas) from a `.duc` file buffer.
+ * Restore the document state at `version_number` from a `.duc` file buffer.
  *
- * Returns a JS array of `VersionEntry` objects (no heavy data blobs).
+ * The `.duc` file is a SQLite database — this function opens it and queries
+ * the `checkpoints` / `deltas` tables directly for version restoration.
+ *
+ * Returns a JS object `{ versionNumber, schemaVersion, data, fromCheckpoint }`.
  * @param {Uint8Array} duc_buf
+ * @param {number} version_number
  * @returns {any}
  */
-export function listVersions(duc_buf) {
+export function restoreVersion(duc_buf, version_number) {
     const ptr0 = passArray8ToWasm0(duc_buf, wasm.__wbindgen_malloc);
     const len0 = WASM_VECTOR_LEN;
-    const ret = wasm.listVersions(ptr0, len0);
+    const ret = wasm.restoreVersion(ptr0, len0, version_number);
     if (ret[2]) {
         throw takeFromExternrefTable0(ret[1]);
     }
@@ -296,20 +304,58 @@ export function listVersions(duc_buf) {
 }
 
 /**
- * Restore the document state at `version_number` from a `.duc` file buffer.
- *
- * The `.duc` file is a SQLite database — this function opens it and queries
- * the `checkpoints` / `deltas` tables directly for version restoration.
+ * Revert the document to a specific version, removing all newer versions.
  *
  * Returns a JS object `{ versionNumber, schemaVersion, data, fromCheckpoint }`.
  * @param {Uint8Array} duc_buf
- * @param {number} version_number
+ * @param {number} target_version
  * @returns {any}
  */
-export function restoreVersion(duc_buf, version_number) {
+export function revertToVersion(duc_buf, target_version) {
     const ptr0 = passArray8ToWasm0(duc_buf, wasm.__wbindgen_malloc);
     const len0 = WASM_VECTOR_LEN;
-    const ret = wasm.restoreVersion(ptr0, len0, version_number);
+    const ret = wasm.revertToVersion(ptr0, len0, target_version);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
+/**
+ * Apply a changeset to reconstruct document state.
+ *
+ * `base_state` must be the exact checkpoint data used when the changeset
+ * was created. Returns the full document state as `Uint8Array`.
+ *
+ * Handles all changeset formats transparently:
+ *   - v3 (bsdiff), v2 (XOR diff), v1 (zlib full snapshot)
+ * @param {Uint8Array} base_state
+ * @param {Uint8Array} changeset
+ * @returns {Uint8Array}
+ */
+export function applyDeltaChangeset(base_state, changeset) {
+    const ptr0 = passArray8ToWasm0(base_state, wasm.__wbindgen_malloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ptr1 = passArray8ToWasm0(changeset, wasm.__wbindgen_malloc);
+    const len1 = WASM_VECTOR_LEN;
+    const ret = wasm.applyDeltaChangeset(ptr0, len0, ptr1, len1);
+    if (ret[3]) {
+        throw takeFromExternrefTable0(ret[2]);
+    }
+    var v3 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
+    wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
+    return v3;
+}
+
+/**
+ * List metadata for all external files (without loading the heavy data blobs).
+ * @param {Uint8Array} buf
+ * @returns {any}
+ */
+export function listExternalFiles(buf) {
+    const ptr0 = passArray8ToWasm0(buf, wasm.__wbindgen_malloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.listExternalFiles(ptr0, len0);
     if (ret[2]) {
         throw takeFromExternrefTable0(ret[1]);
     }
@@ -332,36 +378,41 @@ export function serializeDuc(data) {
 }
 
 /**
- * Restore a specific checkpoint by its ID from a `.duc` file buffer.
+ * Compute a checkpoint-relative binary diff changeset using bsdiff.
  *
- * Returns a JS object `{ versionNumber, schemaVersion, data, fromCheckpoint }`.
- * @param {Uint8Array} duc_buf
- * @param {string} checkpoint_id
- * @returns {any}
+ * `base_state` is the checkpoint's full data blob.
+ * `current_state` is the full document state at the new version.
+ *
+ * Returns an encoded changeset (`Uint8Array`) ready for storage in a
+ * `Delta.payload`. bsdiff finds matching blocks even when they shift
+ * offsets, which is critical for SQLite databases.
+ * @param {Uint8Array} base_state
+ * @param {Uint8Array} current_state
+ * @returns {Uint8Array}
  */
-export function restoreCheckpoint(duc_buf, checkpoint_id) {
-    const ptr0 = passArray8ToWasm0(duc_buf, wasm.__wbindgen_malloc);
+export function createDeltaChangeset(base_state, current_state) {
+    const ptr0 = passArray8ToWasm0(base_state, wasm.__wbindgen_malloc);
     const len0 = WASM_VECTOR_LEN;
-    const ptr1 = passStringToWasm0(checkpoint_id, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const ptr1 = passArray8ToWasm0(current_state, wasm.__wbindgen_malloc);
     const len1 = WASM_VECTOR_LEN;
-    const ret = wasm.restoreCheckpoint(ptr0, len0, ptr1, len1);
-    if (ret[2]) {
-        throw takeFromExternrefTable0(ret[1]);
+    const ret = wasm.createDeltaChangeset(ptr0, len0, ptr1, len1);
+    if (ret[3]) {
+        throw takeFromExternrefTable0(ret[2]);
     }
-    return takeFromExternrefTable0(ret[0]);
+    var v3 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
+    wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
+    return v3;
 }
 
 /**
- * Parse a `.duc` file lazily — returns everything EXCEPT external file data blobs.
- *
- * Use `getExternalFile()` or `listExternalFiles()` for on-demand access.
+ * Parse a `.duc` file (Uint8Array) into a JS object (ExportedDataState).
  * @param {Uint8Array} buf
  * @returns {any}
  */
-export function parseDucLazy(buf) {
+export function parseDuc(buf) {
     const ptr0 = passArray8ToWasm0(buf, wasm.__wbindgen_malloc);
     const len0 = WASM_VECTOR_LEN;
-    const ret = wasm.parseDucLazy(ptr0, len0);
+    const ret = wasm.parseDuc(ptr0, len0);
     if (ret[2]) {
         throw takeFromExternrefTable0(ret[1]);
     }
@@ -369,14 +420,16 @@ export function parseDucLazy(buf) {
 }
 
 /**
- * List metadata for all external files (without loading the heavy data blobs).
+ * Parse a `.duc` file lazily — returns everything EXCEPT external file data blobs.
+ *
+ * Use `getExternalFile()` or `listExternalFiles()` for on-demand access.
  * @param {Uint8Array} buf
  * @returns {any}
  */
-export function listExternalFiles(buf) {
+export function parseDucLazy(buf) {
     const ptr0 = passArray8ToWasm0(buf, wasm.__wbindgen_malloc);
     const len0 = WASM_VECTOR_LEN;
-    const ret = wasm.listExternalFiles(ptr0, len0);
+    const ret = wasm.parseDucLazy(ptr0, len0);
     if (ret[2]) {
         throw takeFromExternrefTable0(ret[1]);
     }

package/dist/ducjs_wasm_bg.wasm.d.ts

@@ -1,6 +1,8 @@
 /* tslint:disable */
 /* eslint-disable */
 export const memory: WebAssembly.Memory;
+export const applyDeltaChangeset: (a: number, b: number, c: number, d: number) => [number, number, number, number];
+export const createDeltaChangeset: (a: number, b: number, c: number, d: number) => [number, number, number, number];
 export const getCurrentSchemaVersion: () => number;
 export const getExternalFile: (a: number, b: number, c: number, d: number) => [number, number, number];
 export const listExternalFiles: (a: number, b: number) => [number, number, number];

package/dist/lazy-files.d.ts

@@ -1,4 +1,4 @@
-import type { DucExternalFileData, DucExternalFiles } from "./types";
+import type { DucExternalFile, DucExternalFiles, ExternalFileRevision } from "./types";
 export type LazyFileMetadata = {
     id: string;
     mimeType: string;
@@ -26,17 +26,19 @@ export declare class LazyExternalFileStore {
     getMetadata(fileId: string): LazyFileMetadata | undefined;
     /** Get metadata for all files. */
     getAllMetadata(): LazyFileMetadata[];
-    /** Fetch the full file data (including blob) for a specific file. */
-    getFileData(fileId: string): DucExternalFileData | null;
-    /** Fetch file data and return a copy of the data buffer (safe for transfer). */
-    getFileDataCopy(fileId: string): DucExternalFileData | null;
+    /** Fetch the full file (including data blobs for all revisions) for a specific file. */
+    getFile(fileId: string): DucExternalFile | null;
+    /** Get the active revision data for a specific file. */
+    getFileData(fileId: string): ExternalFileRevision | null;
+    /** Fetch active revision data and return a copy of the data buffer (safe for transfer). */
+    getFileDataCopy(fileId: string): ExternalFileRevision | null;
     /** Add a file at runtime (not persisted in .duc until next serialize). */
-    addRuntimeFile(fileId: string, data: DucExternalFileData): void;
+    addRuntimeFile(fileId: string, file: DucExternalFile): void;
     /** Remove a runtime file. */
     removeRuntimeFile(fileId: string): boolean;
     /** Export all files eagerly as a DucExternalFiles record. */
     toExternalFiles(): DucExternalFiles;
-    /** Merge files from another source (only adds missing). */
+    /** Merge files from another source. Adds missing files and merges new revisions into existing ones. */
     mergeFiles(files: DucExternalFiles): void;
     /** Release the underlying buffer to free memory. */
     release(): void;

package/dist/lazy-files.js

@@ -26,11 +26,14 @@ export class LazyExternalFileStore {
     getMetadata(fileId) {
         const rt = this.runtimeFiles.get(fileId);
         if (rt) {
+            const active = rt.revisions[rt.activeRevisionId];
+            if (!active)
+                return undefined;
             return {
                 id: rt.id,
-                mimeType: rt.mimeType,
-                created: rt.created,
-                lastRetrieved: rt.lastRetrieved,
+                mimeType: active.mimeType,
+                created: active.created,
+                lastRetrieved: active.lastRetrieved,
                 version: rt.version,
             };
         }
@@ -39,24 +42,28 @@ export class LazyExternalFileStore {
     /** Get metadata for all files. */
     getAllMetadata() {
         const result = [];
-        for (const meta of this.getMetadataMap().values()) {
+        const persisted = this.getMetadataMap();
+        for (const meta of persisted.values()) {
             result.push(meta);
         }
-        for (const [id, data] of this.runtimeFiles) {
-            if (!this.getMetadataMap().has(id)) {
-                result.push({
-                    id: data.id,
-                    mimeType: data.mimeType,
-                    created: data.created,
-                    lastRetrieved: data.lastRetrieved,
-                    version: data.version,
-                });
+        for (const [id, file] of this.runtimeFiles) {
+            if (!persisted.has(id)) {
+                const active = file.revisions[file.activeRevisionId];
+                if (active) {
+                    result.push({
+                        id: file.id,
+                        mimeType: active.mimeType,
+                        created: active.created,
+                        lastRetrieved: active.lastRetrieved,
+                        version: file.version,
+                    });
+                }
             }
         }
         return result;
     }
-    /** Fetch the full file data (including blob) for a specific file. */
-    getFileData(fileId) {
+    /** Fetch the full file (including data blobs for all revisions) for a specific file. */
+    getFile(fileId) {
         const rt = this.runtimeFiles.get(fileId);
         if (rt)
             return rt;
@@ -65,15 +72,17 @@ export class LazyExternalFileStore {
         const result = wasmGetExternalFile(this.buffer, fileId);
         if (!result)
             return null;
-        // WASM returns DucExternalFileEntry { key, value: DucExternalFileData }.
-        // Unwrap to get the actual file data.
-        const entry = result;
-        if (entry.value && typeof entry.value === "object") {
-            return entry.value;
-        }
-        return entry;
+        return result;
     }
-    /** Fetch file data and return a copy of the data buffer (safe for transfer). */
+    /** Get the active revision data for a specific file. */
+    getFileData(fileId) {
+        var _a;
+        const file = this.getFile(fileId);
+        if (!file)
+            return null;
+        return (_a = file.revisions[file.activeRevisionId]) !== null && _a !== void 0 ? _a : null;
+    }
+    /** Fetch active revision data and return a copy of the data buffer (safe for transfer). */
     getFileDataCopy(fileId) {
         const data = this.getFileData(fileId);
         if (!data)
@@ -81,8 +90,8 @@ export class LazyExternalFileStore {
         return Object.assign(Object.assign({}, data), { data: new Uint8Array(data.data) });
     }
     /** Add a file at runtime (not persisted in .duc until next serialize). */
-    addRuntimeFile(fileId, data) {
-        this.runtimeFiles.set(fileId, data);
+    addRuntimeFile(fileId, file) {
+        this.runtimeFiles.set(fileId, file);
     }
     /** Remove a runtime file. */
     removeRuntimeFile(fileId) {
@@ -92,24 +101,42 @@ export class LazyExternalFileStore {
     toExternalFiles() {
         const result = {};
         if (this.buffer) {
-            const metas = this.getMetadataMap();
-            for (const [id] of metas) {
-                const data = this.getFileData(id);
-                if (data) {
-                    result[id] = data;
+            for (const [id] of this.getMetadataMap()) {
+                const file = this.getFile(id);
+                if (file) {
+                    result[id] = file;
                 }
             }
         }
-        for (const [id, data] of this.runtimeFiles) {
-            result[id] = data;
+        for (const [id, file] of this.runtimeFiles) {
+            result[id] = file;
         }
         return result;
     }
-    /** Merge files from another source (only adds missing). */
+    /** Merge files from another source. Adds missing files and merges new revisions into existing ones. */
     mergeFiles(files) {
-        for (const [id, data] of Object.entries(files)) {
+        var _a, _b, _c;
+        for (const [id, file] of Object.entries(files)) {
             if (!this.has(id)) {
-                this.runtimeFiles.set(id, data);
+                this.runtimeFiles.set(id, file);
+                continue;
+            }
+            const existing = (_a = this.runtimeFiles.get(id)) !== null && _a !== void 0 ? _a : this.getFile(id);
+            if (!existing) {
+                this.runtimeFiles.set(id, file);
+                continue;
+            }
+            // Merge: add any new revisions that don't exist yet, and update metadata
+            let merged = false;
+            const mergedRevisions = Object.assign({}, existing.revisions);
+            for (const [revId, rev] of Object.entries(file.revisions)) {
+                if (!mergedRevisions[revId]) {
+                    mergedRevisions[revId] = rev;
+                    merged = true;
+                }
+            }
+            if (merged || file.updated > existing.updated) {
+                this.runtimeFiles.set(id, Object.assign(Object.assign({}, existing), { activeRevisionId: file.activeRevisionId, updated: Math.max(file.updated, existing.updated), version: Math.max((_b = file.version) !== null && _b !== void 0 ? _b : 0, (_c = existing.version) !== null && _c !== void 0 ? _c : 0), revisions: mergedRevisions }));
             }
         }
     }

package/dist/parse.js

@@ -40,7 +40,18 @@ export function parseDuc(blob, _fileHandle, elementsConfig, restoreConfig) {
             throw new Error(`[parseDuc] wasm parse failed (size=${buffer.byteLength}, header="${header}", prefix=${prefixHex}): ${error instanceof Error ? error.message : String(error)}`);
         }
         const data = transformFromRust(raw);
-        return restore(data, elementsConfig !== null && elementsConfig !== void 0 ? elementsConfig : { syncInvalidIndices: (els) => els }, restoreConfig);
+        // Preserve the original version graph from Rust before restore() can
+        // filter out entries through restoreCheckpoint/restoreDelta validation.
+        // The VG data is already validated by the Rust parser.
+        const originalVG = data.versionGraph;
+        const restored = restore(Object.assign(Object.assign({}, data), { 
+            // Preserve versionGraph from Rust separately; do not run it through restore()
+            versionGraph: undefined }), elementsConfig !== null && elementsConfig !== void 0 ? elementsConfig : { syncInvalidIndices: (els) => els }, restoreConfig);
+        // Use the original version graph from Rust, bypassing restore's lossy filtering
+        if (originalVG) {
+            restored.versionGraph = originalVG;
+        }
+        return restored;
     });
 }
 /**
@@ -65,10 +76,18 @@ export function parseDucLazy(buffer, elementsConfig, restoreConfig) {
             throw new Error(`[parseDucLazy] wasm parse failed (size=${buffer.byteLength}, header="${header}", prefix=${prefixHex}): ${error instanceof Error ? error.message : String(error)}`);
         }
         const data = transformFromRust(raw);
+        // Preserve the original version graph from Rust before restore() filters
+        const originalVG = data.versionGraph;
         const lazyFileStore = new LazyExternalFileStore(buffer);
         const files = {};
-        const restored = restore(Object.assign(Object.assign({}, data), { files }), elementsConfig !== null && elementsConfig !== void 0 ? elementsConfig : { syncInvalidIndices: (els) => els }, restoreConfig);
+        const restored = restore(Object.assign(Object.assign({}, data), { files, 
+            // Preserve versionGraph from Rust separately; do not run it through restore()
+            versionGraph: undefined }), elementsConfig !== null && elementsConfig !== void 0 ? elementsConfig : { syncInvalidIndices: (els) => els }, restoreConfig);
         restored.lazyFileStore = lazyFileStore;
+        // Use the original version graph from Rust, bypassing restore's lossy filtering
+        if (originalVG) {
+            restored.versionGraph = originalVG;
+        }
         return restored;
     });
 }

package/dist/restore/restoreDataState.js

@@ -41,46 +41,94 @@ export const restore = (data, elementsConfig, restoreConfig = {}) => {
     };
 };
 export const restoreFiles = (importedFiles) => {
-    var _a;
+    var _a, _b;
     if (!importedFiles || typeof importedFiles !== "object") {
         return {};
     }
     const restoredFiles = {};
     const files = importedFiles;
     for (const key in files) {
-        if (Object.prototype.hasOwnProperty.call(files, key)) {
-            let fileData = files[key];
-            if (!fileData || typeof fileData !== "object") {
+        if (!Object.prototype.hasOwnProperty.call(files, key))
+            continue;
+        const fileData = files[key];
+        if (!fileData || typeof fileData !== "object")
+            continue;
+        const fd = fileData;
+        // New format: DucExternalFile with revisions map
+        if (fd.revisions && typeof fd.revisions === "object" && fd.activeRevisionId) {
+            const id = isValidExternalFileId(fd.id);
+            if (!id)
                 continue;
-            }
-            // Handle the nested DucExternalFileEntry structure { key, value: { ... } }
-            // produced by Rust serde or legacy exports.
-            if (fileData.value && typeof fileData.value === "object") {
-                fileData = fileData.value;
-            }
-            const id = isValidExternalFileId(fileData.id);
-            const mimeType = isValidString(fileData.mimeType);
-            const created = isFiniteNumber(fileData.created)
-                ? fileData.created
-                : Date.now();
-            // Check for data under 'data' or 'dataURL' to be more flexible.
-            const dataSource = (_a = fileData.data) !== null && _a !== void 0 ? _a : fileData.dataURL;
-            const data = isValidUint8Array(dataSource);
-            if (id && mimeType && data) {
-                restoredFiles[id] = {
-                    id,
+            const restoredRevisions = {};
+            const rawRevisions = fd.revisions;
+            for (const revKey in rawRevisions) {
+                if (!Object.prototype.hasOwnProperty.call(rawRevisions, revKey))
+                    continue;
+                const rev = rawRevisions[revKey];
+                if (!rev || typeof rev !== "object")
+                    continue;
+                const r = rev;
+                const revId = isValidString(r.id);
+                const mimeType = isValidString(r.mimeType);
+                const dataSource = (_a = r.data) !== null && _a !== void 0 ? _a : r.dataURL;
+                const data = isValidUint8Array(dataSource);
+                if (!revId || !mimeType || !data)
+                    continue;
+                restoredRevisions[revKey] = {
+                    id: revId,
+                    sizeBytes: isFiniteNumber(r.sizeBytes) ? r.sizeBytes : data.byteLength,
+                    checksum: isValidString(r.checksum) || undefined,
+                    sourceName: isValidString(r.sourceName) || undefined,
                     mimeType,
+                    message: isValidString(r.message) || undefined,
+                    created: isFiniteNumber(r.created) ? r.created : Date.now(),
+                    lastRetrieved: isFiniteNumber(r.lastRetrieved) ? r.lastRetrieved : undefined,
                     data,
-                    created,
-                    lastRetrieved: isFiniteNumber(fileData.lastRetrieved)
-                        ? fileData.lastRetrieved
-                        : undefined,
-                    version: isFiniteNumber(fileData.version)
-                        ? fileData.version
-                        : undefined,
                 };
             }
+            if (Object.keys(restoredRevisions).length === 0)
+                continue;
+            restoredFiles[id] = {
+                id,
+                activeRevisionId: isValidString(fd.activeRevisionId) || Object.keys(restoredRevisions)[0],
+                updated: isFiniteNumber(fd.updated) ? fd.updated : Date.now(),
+                revisions: restoredRevisions,
+                version: isFiniteNumber(fd.version) ? fd.version : undefined,
+            };
+            continue;
+        }
+        // Legacy flat format: DucExternalFileData — wrap in a single-revision DucExternalFile.
+        let legacyData = fd;
+        // Handle the nested { key, value: { ... } } structure from old Rust serde output.
+        if (fd.value && typeof fd.value === "object") {
+            legacyData = fd.value;
         }
+        const id = isValidExternalFileId(legacyData.id);
+        const mimeType = isValidString(legacyData.mimeType);
+        const dataSource = (_b = legacyData.data) !== null && _b !== void 0 ? _b : legacyData.dataURL;
+        const data = isValidUint8Array(dataSource);
+        if (!id || !mimeType || !data)
+            continue;
+        const revId = `${id}_rev1`;
+        const created = isFiniteNumber(legacyData.created) ? legacyData.created : Date.now();
+        restoredFiles[id] = {
+            id,
+            activeRevisionId: revId,
+            updated: created,
+            version: isFiniteNumber(legacyData.version) ? legacyData.version : undefined,
+            revisions: {
+                [revId]: {
+                    id: revId,
+                    sizeBytes: data.byteLength,
+                    mimeType,
+                    created,
+                    lastRetrieved: isFiniteNumber(legacyData.lastRetrieved)
+                        ? legacyData.lastRetrieved
+                        : undefined,
+                    data,
+                },
+            },
+        };
     }
     return restoredFiles;
 };
@@ -367,11 +415,6 @@ export const restoreVersionGraph = (importedGraph) => {
     if (!importedGraph || typeof importedGraph !== "object") {
         return undefined;
     }
-    const userCheckpointVersionId = isValidString(importedGraph.userCheckpointVersionId);
-    const latestVersionId = isValidString(importedGraph.latestVersionId);
-    if (!userCheckpointVersionId || !latestVersionId) {
-        return undefined;
-    }
     const checkpoints = Array.isArray(importedGraph.checkpoints)
         ? importedGraph.checkpoints
             .map((checkpoint) => restoreCheckpoint(checkpoint))
@@ -382,6 +425,17 @@ export const restoreVersionGraph = (importedGraph) => {
             .map((delta) => restoreDelta(delta))
             .filter((delta) => Boolean(delta))
         : [];
+    if (checkpoints.length === 0 && deltas.length === 0) {
+        return undefined;
+    }
+    // Head IDs can legitimately be empty strings (e.g. after Rust roundtrip
+    // where the DB stores NULL → unwrap_or_default → ""). Accept any string.
+    const userCheckpointVersionId = typeof importedGraph.userCheckpointVersionId === "string"
+        ? importedGraph.userCheckpointVersionId
+        : "";
+    const latestVersionId = typeof importedGraph.latestVersionId === "string"
+        ? importedGraph.latestVersionId
+        : "";
     const importedMetadata = importedGraph.metadata;
     const metadata = {
         currentVersion: isFiniteNumber(importedMetadata === null || importedMetadata === void 0 ? void 0 : importedMetadata.currentVersion) && importedMetadata.currentVersion >= 0
@@ -411,6 +465,7 @@ export const restoreVersionGraph = (importedGraph) => {
     };
 };
 export const restoreCheckpoint = (importedCheckpoint) => {
+    var _a, _b, _c;
     if (!importedCheckpoint || typeof importedCheckpoint !== "object") {
         return undefined;
     }
@@ -419,10 +474,11 @@ export const restoreCheckpoint = (importedCheckpoint) => {
         return undefined;
     }
     const id = isValidString(checkpoint.id);
-    const data = isValidUint8Array(checkpoint.data);
-    if (!id || !data) {
+    if (!id) {
         return undefined;
     }
+    // Accept empty Uint8Array — shell/remote entries have byteLength === 0
+    const data = (_c = (_b = (_a = isValidUint8Array(checkpoint.data)) !== null && _a !== void 0 ? _a : (checkpoint.data instanceof Uint8Array ? checkpoint.data : undefined)) !== null && _b !== void 0 ? _b : (checkpoint.data instanceof ArrayBuffer ? new Uint8Array(checkpoint.data) : undefined)) !== null && _c !== void 0 ? _c : new Uint8Array(0);
     return {
         type: "checkpoint",
         id,
@@ -443,6 +499,7 @@ export const restoreCheckpoint = (importedCheckpoint) => {
     };
 };
 export const restoreDelta = (importedDelta) => {
+    var _a, _b, _c;
     if (!importedDelta || typeof importedDelta !== "object") {
         return undefined;
     }
@@ -451,11 +508,13 @@ export const restoreDelta = (importedDelta) => {
         return undefined;
     }
     const id = isValidString(delta.id);
-    const payload = isValidUint8Array(delta.payload);
-    const baseCheckpointId = isValidString(delta.baseCheckpointId);
-    if (!id || !payload || !baseCheckpointId) {
+    if (!id) {
         return undefined;
     }
+    // Accept empty Uint8Array — shell/remote entries have byteLength === 0
+    const payload = (_c = (_b = (_a = isValidUint8Array(delta.payload)) !== null && _a !== void 0 ? _a : (delta.payload instanceof Uint8Array ? delta.payload : undefined)) !== null && _b !== void 0 ? _b : (delta.payload instanceof ArrayBuffer ? new Uint8Array(delta.payload) : undefined)) !== null && _c !== void 0 ? _c : new Uint8Array(0);
+    // baseCheckpointId can be empty for shell entries or first-in-chain deltas
+    const baseCheckpointId = typeof delta.baseCheckpointId === "string" ? delta.baseCheckpointId : "";
     return {
         type: "delta",
         id,

package/dist/serialize.js

@@ -33,15 +33,111 @@ export function serializeDuc(data, elementsConfig, restoreConfig) {
     return __awaiter(this, void 0, void 0, function* () {
         var _a, _b, _c, _d;
         yield ensureWasm();
-        const restored = restore(data, elementsConfig !== null && elementsConfig !== void 0 ? elementsConfig : { syncInvalidIndices: (els) => els }, restoreConfig);
-        const shouldDropLegacyVersionGraph = hasLegacyVersionGraphShape(data === null || data === void 0 ? void 0 : data.versionGraph);
-        const payloadForRust = Object.assign(Object.assign({ type: (_a = data.type) !== null && _a !== void 0 ? _a : "duc", version: (_c = (_b = data.version) !== null && _b !== void 0 ? _b : DUC_SCHEMA_VERSION) !== null && _c !== void 0 ? _c : decodeUserVersionToSemver(wasmGetCurrentSchemaVersion()), source: (_d = data.source) !== null && _d !== void 0 ? _d : "ducjs" }, restored), { versionGraph: shouldDropLegacyVersionGraph
-                ? undefined
-                : restored.versionGraph });
+        const inputVG = data === null || data === void 0 ? void 0 : data.versionGraph;
+        const restored = restore(Object.assign(Object.assign({}, data), { 
+            // Version graph is preserved separately — bypass restore()'s VG processing.
+            versionGraph: undefined }), elementsConfig !== null && elementsConfig !== void 0 ? elementsConfig : { syncInvalidIndices: (els) => els }, restoreConfig);
+        const shouldDropLegacyVersionGraph = hasLegacyVersionGraphShape(inputVG);
+        // Use the ORIGINAL version graph data instead of the restored one.
+        // The restore pipeline (restoreCheckpoint/restoreDelta) filters checkpoints
+        // and deltas through isValidUint8Array which can reject valid in-memory 
+        // Uint8Array data (e.g. empty remote placeholders or detached buffers),
+        // silently dropping version history.
+        // hasLegacyVersionGraphShape already validates structural integrity.
+        const versionGraphForPayload = shouldDropLegacyVersionGraph
+            ? undefined
+            : prepareVersionGraphForSerialization(inputVG);
+        const normalizedVersionGraphForPayload = versionGraphForPayload
+            ? normalizeVersionGraphVersionNumbers(versionGraphForPayload)
+            : undefined;
+        const payloadForRust = Object.assign(Object.assign({ type: (_a = data.type) !== null && _a !== void 0 ? _a : "duc", version: (_c = (_b = data.version) !== null && _b !== void 0 ? _b : DUC_SCHEMA_VERSION) !== null && _c !== void 0 ? _c : decodeUserVersionToSemver(wasmGetCurrentSchemaVersion()), source: (_d = data.source) !== null && _d !== void 0 ? _d : "ducjs" }, restored), { versionGraph: normalizedVersionGraphForPayload });
         const prepared = transformToRust(payloadForRust);
-        return wasmSerializeDuc(prepared);
+        const serialized = wasmSerializeDuc(prepared);
+        return serialized;
     });
 }
+/**
+ * Ensure version numbers are unique before persistence.
+ * SQLite schema enforces UNIQUE(version_number) on both checkpoints and deltas.
+ * Collisions would otherwise cause INSERT OR REPLACE to drop historical entries.
+ */
+function normalizeVersionGraphVersionNumbers(vg) {
+    var _a;
+    const normalizeList = (items) => {
+        if (!Array.isArray(items) || items.length === 0) {
+            return [];
+        }
+        const sorted = [...items].sort((a, b) => {
+            const aNum = Number.isFinite(a === null || a === void 0 ? void 0 : a.versionNumber) ? Number(a.versionNumber) : Number.MAX_SAFE_INTEGER;
+            const bNum = Number.isFinite(b === null || b === void 0 ? void 0 : b.versionNumber) ? Number(b.versionNumber) : Number.MAX_SAFE_INTEGER;
+            if (aNum !== bNum)
+                return aNum - bNum;
+            const aTs = Number.isFinite(a === null || a === void 0 ? void 0 : a.timestamp) ? Number(a.timestamp) : 0;
+            const bTs = Number.isFinite(b === null || b === void 0 ? void 0 : b.timestamp) ? Number(b.timestamp) : 0;
+            if (aTs !== bTs)
+                return aTs - bTs;
+            const aId = typeof (a === null || a === void 0 ? void 0 : a.id) === "string" ? a.id : "";
+            const bId = typeof (b === null || b === void 0 ? void 0 : b.id) === "string" ? b.id : "";
+            return aId.localeCompare(bId);
+        });
+        let nextVersion = 0;
+        return sorted.map((item) => {
+            const candidate = Number.isFinite(item === null || item === void 0 ? void 0 : item.versionNumber) ? Number(item.versionNumber) : nextVersion;
+            const assigned = Math.max(candidate, nextVersion);
+            nextVersion = assigned + 1;
+            return Object.assign(Object.assign({}, item), { versionNumber: assigned });
+        });
+    };
+    const checkpoints = normalizeList(Array.isArray(vg === null || vg === void 0 ? void 0 : vg.checkpoints) ? vg.checkpoints : []);
+    const deltas = normalizeList(Array.isArray(vg === null || vg === void 0 ? void 0 : vg.deltas) ? vg.deltas : []);
+    const maxCheckpointVersion = checkpoints.length
+        ? Math.max(...checkpoints.map((cp) => Number(cp.versionNumber) || 0))
+        : 0;
+    const maxDeltaVersion = deltas.length
+        ? Math.max(...deltas.map((d) => Number(d.versionNumber) || 0))
+        : 0;
+    const maxVersion = Math.max(maxCheckpointVersion, maxDeltaVersion, 0);
+    return Object.assign(Object.assign({}, vg), { checkpoints,
+        deltas, metadata: Object.assign(Object.assign({}, vg.metadata), { currentVersion: Number.isFinite((_a = vg === null || vg === void 0 ? void 0 : vg.metadata) === null || _a === void 0 ? void 0 : _a.currentVersion)
+                ? Math.max(Number(vg.metadata.currentVersion), maxVersion)
+                : maxVersion }) });
+}
+/**
+ * Prepares version graph for serialization by filtering out shell entries
+ * (remote placeholders with empty data/payload) while preserving all entries
+ * with actual binary data intact.
+ */
+function prepareVersionGraphForSerialization(vg) {
+    if (!vg || typeof vg !== "object")
+        return undefined;
+    const checkpoints = Array.isArray(vg.checkpoints)
+        ? vg.checkpoints.filter((cp) => {
+            const data = cp === null || cp === void 0 ? void 0 : cp.data;
+            if (data instanceof Uint8Array)
+                return data.byteLength > 0;
+            if (data instanceof ArrayBuffer)
+                return data.byteLength > 0;
+            // Accept base64 strings (from JSON imports)
+            if (typeof data === "string" && data.length > 0)
+                return true;
+            return false;
+        })
+        : [];
+    const deltas = Array.isArray(vg.deltas)
+        ? vg.deltas.filter((d) => {
+            const payload = d === null || d === void 0 ? void 0 : d.payload;
+            if (payload instanceof Uint8Array)
+                return payload.byteLength > 0;
+            if (payload instanceof ArrayBuffer)
+                return payload.byteLength > 0;
+            if (typeof payload === "string" && payload.length > 0)
+                return true;
+            return false;
+        })
+        : [];
+    return Object.assign(Object.assign({}, vg), { checkpoints,
+        deltas });
+}
 function hasLegacyVersionGraphShape(versionGraph) {
     if (!versionGraph || typeof versionGraph !== "object") {
         return false;

package/dist/types/index.d.ts

@@ -79,30 +79,36 @@ export type DucUcs = {
     angle: Radian;
 };
 export type Scope = SupportedMeasures;
-export type DucExternalFileData = {
+export type ExternalFileRevision = {
+    id: string;
+    sizeBytes: number;
+    /** Content hash for integrity checks and optional deduplication. */
+    checksum?: string;
+    /** Original upload filename shown to the user. */
+    sourceName?: string;
     mimeType: string;
-    id: ExternalFileId;
-    data: Uint8Array;
-    /**
-     * Epoch timestamp in milliseconds
-     */
+    /** Optional note describing what changed in this revision. */
+    message?: string;
+    /** Epoch timestamp in milliseconds when this revision was created. */
     created: number;
     /**
-     * Indicates when the file was last retrieved from storage to be loaded
-     * onto the scene. We use this flag to determine whether to delete unused
-     * files from storage.
-     *
-     * Epoch timestamp in milliseconds.
+     * Epoch timestamp in milliseconds when this revision was last loaded onto
+     * the scene. Used to determine whether to delete unused files from storage.
      */
     lastRetrieved?: number;
-    /**
-     * indicates the version of the file. This can be used to determine whether
-     * the file data has changed e.g. as part of restore due to schema update.
-     */
+    /** The actual file content bytes. */
+    data: Uint8Array;
+};
+export type DucExternalFile = {
+    id: ExternalFileId;
+    activeRevisionId: string;
+    /** Epoch ms when the logical file was last mutated (revision added or active changed). */
+    updated: number;
+    /** All revisions of this file, keyed by their id. */
+    revisions: Record<string, ExternalFileRevision>;
     version?: number;
 };
-export type DucExternalFileMetadata = Omit<DucExternalFileData, "data">;
-export type DucExternalFiles = Record<DucElement["id"], DucExternalFileData>;
+export type DucExternalFiles = Record<ExternalFileId, DucExternalFile>;
 export type SuggestedBinding = NonDeleted<DucBindableElement> | SuggestedPointBinding;
 export type SuggestedPointBinding = [
     NonDeleted<DucLinearElement>,

package/dist/version-control.d.ts

@@ -59,3 +59,29 @@ export declare const revertToVersion: (ducBuffer: Uint8Array, targetVersion: num
  * on the next checkpoint or delta creation.
  */
 export declare const getCurrentSchemaVersion: () => Promise<number>;
+/**
+ * Compute a checkpoint-relative binary diff changeset using bsdiff.
+ *
+ * `baseState` is the checkpoint's full data blob (the snapshot at the
+ * base checkpoint version). `currentState` is the full document state
+ * at the new version being saved as a delta.
+ *
+ * Returns an encoded changeset (`Uint8Array`) suitable for use as
+ * `Delta.payload`. bsdiff finds matching blocks even when they shift
+ * offsets, which is critical for SQLite databases where internal page
+ * reordering makes simple byte-level diffs ineffective.
+ *
+ * Use this when constructing `Delta` objects for the `VersionGraph`
+ * before calling `serializeDuc()`.
+ */
+export declare const createDeltaChangeset: (baseState: Uint8Array, currentState: Uint8Array) => Promise<Uint8Array>;
+/**
+ * Apply a changeset to reconstruct document state.
+ *
+ * `baseState` must be the exact checkpoint data used when the changeset
+ * was created. Returns the full document state as `Uint8Array`.
+ *
+ * Handles all changeset formats transparently:
+ *   - v3 (bsdiff), v2 (XOR diff), v1 (zlib full snapshot)
+ */
+export declare const applyDeltaChangeset: (baseState: Uint8Array, changeset: Uint8Array) => Promise<Uint8Array>;

package/dist/version-control.js

@@ -7,7 +7,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import { ensureWasm, wasmGetCurrentSchemaVersion, wasmListVersions, wasmReadVersionGraph, wasmRestoreCheckpoint, wasmRestoreVersion, wasmRevertToVersion, } from "./wasm";
+import { ensureWasm, wasmApplyDeltaChangeset, wasmCreateDeltaChangeset, wasmGetCurrentSchemaVersion, wasmListVersions, wasmReadVersionGraph, wasmRestoreCheckpoint, wasmRestoreVersion, wasmRevertToVersion, } from "./wasm";
 /**
  * Restore the full document state at a specific version number.
  *
@@ -82,3 +82,35 @@ export const getCurrentSchemaVersion = () => __awaiter(void 0, void 0, void 0, f
     yield ensureWasm();
     return wasmGetCurrentSchemaVersion();
 });
+/**
+ * Compute a checkpoint-relative binary diff changeset using bsdiff.
+ *
+ * `baseState` is the checkpoint's full data blob (the snapshot at the
+ * base checkpoint version). `currentState` is the full document state
+ * at the new version being saved as a delta.
+ *
+ * Returns an encoded changeset (`Uint8Array`) suitable for use as
+ * `Delta.payload`. bsdiff finds matching blocks even when they shift
+ * offsets, which is critical for SQLite databases where internal page
+ * reordering makes simple byte-level diffs ineffective.
+ *
+ * Use this when constructing `Delta` objects for the `VersionGraph`
+ * before calling `serializeDuc()`.
+ */
+export const createDeltaChangeset = (baseState, currentState) => __awaiter(void 0, void 0, void 0, function* () {
+    yield ensureWasm();
+    return wasmCreateDeltaChangeset(baseState, currentState);
+});
+/**
+ * Apply a changeset to reconstruct document state.
+ *
+ * `baseState` must be the exact checkpoint data used when the changeset
+ * was created. Returns the full document state as `Uint8Array`.
+ *
+ * Handles all changeset formats transparently:
+ *   - v3 (bsdiff), v2 (XOR diff), v1 (zlib full snapshot)
+ */
+export const applyDeltaChangeset = (baseState, changeset) => __awaiter(void 0, void 0, void 0, function* () {
+    yield ensureWasm();
+    return wasmApplyDeltaChangeset(baseState, changeset);
+});

package/dist/wasm.d.ts

@@ -1,4 +1,4 @@
-import { getCurrentSchemaVersion as _getCurrentSchemaVersion, getExternalFile as _getExternalFile, listExternalFiles as _listExternalFiles, listVersions as _listVersions, parseDuc as _parseDuc, parseDucLazy as _parseDucLazy, readVersionGraph as _readVersionGraph, restoreCheckpoint as _restoreCheckpoint, restoreVersion as _restoreVersion, revertToVersion as _revertToVersion, serializeDuc as _serializeDuc } from "../dist/ducjs_wasm";
+import { applyDeltaChangeset as _applyDeltaChangeset, createDeltaChangeset as _createDeltaChangeset, getCurrentSchemaVersion as _getCurrentSchemaVersion, getExternalFile as _getExternalFile, listExternalFiles as _listExternalFiles, listVersions as _listVersions, parseDuc as _parseDuc, parseDucLazy as _parseDucLazy, readVersionGraph as _readVersionGraph, restoreCheckpoint as _restoreCheckpoint, restoreVersion as _restoreVersion, revertToVersion as _revertToVersion, serializeDuc as _serializeDuc } from "../dist/ducjs_wasm";
 export declare function ensureWasm(wasmUrl?: string | URL | BufferSource): Promise<void>;
 /**
  * Fetch the raw WASM binary as an ArrayBuffer.
@@ -18,3 +18,5 @@ export declare const wasmListVersions: typeof _listVersions;
 export declare const wasmReadVersionGraph: typeof _readVersionGraph;
 export declare const wasmRevertToVersion: typeof _revertToVersion;
 export declare const wasmGetCurrentSchemaVersion: typeof _getCurrentSchemaVersion;
+export declare const wasmCreateDeltaChangeset: typeof _createDeltaChangeset;
+export declare const wasmApplyDeltaChangeset: typeof _applyDeltaChangeset;

package/dist/wasm.js

@@ -7,7 +7,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import init, { getCurrentSchemaVersion as _getCurrentSchemaVersion, getExternalFile as _getExternalFile, listExternalFiles as _listExternalFiles, listVersions as _listVersions, parseDuc as _parseDuc, parseDucLazy as _parseDucLazy, readVersionGraph as _readVersionGraph, restoreCheckpoint as _restoreCheckpoint, restoreVersion as _restoreVersion, revertToVersion as _revertToVersion, serializeDuc as _serializeDuc, } from "../dist/ducjs_wasm";
+import init, { applyDeltaChangeset as _applyDeltaChangeset, createDeltaChangeset as _createDeltaChangeset, getCurrentSchemaVersion as _getCurrentSchemaVersion, getExternalFile as _getExternalFile, listExternalFiles as _listExternalFiles, listVersions as _listVersions, parseDuc as _parseDuc, parseDucLazy as _parseDucLazy, readVersionGraph as _readVersionGraph, restoreCheckpoint as _restoreCheckpoint, restoreVersion as _restoreVersion, revertToVersion as _revertToVersion, serializeDuc as _serializeDuc, } from "../dist/ducjs_wasm";
 let initialized = false;
 let initPromise = null;
 export function ensureWasm(wasmUrl) {
@@ -50,3 +50,5 @@ export const wasmListVersions = _listVersions;
 export const wasmReadVersionGraph = _readVersionGraph;
 export const wasmRevertToVersion = _revertToVersion;
 export const wasmGetCurrentSchemaVersion = _getCurrentSchemaVersion;
+export const wasmCreateDeltaChangeset = _createDeltaChangeset;
+export const wasmApplyDeltaChangeset = _applyDeltaChangeset;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ducjs",
-  "version": "3.0.4",
+  "version": "3.1.0",
   "description": "The duc 2D CAD file format is a cornerstone of our advanced design system, conceived to cater to professionals seeking precision and efficiency in their design work.",
   "type": "module",
   "main": "dist/index.js",