@cocreate/crdt 1.29.2 → 1.31.0

package/.github/workflows/automated.yml

@@ -9,33 +9,36 @@ jobs:
   about:
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout
-        uses: actions/checkout@v3
-      - name: Setup Node.js
-        uses: actions/setup-node@v3
-        with:
-          node-version: 16
-      - name: Jaid/action-sync-node-meta
-        uses: jaid/action-sync-node-meta@v1.4.0
-        with:
-          direction: overwrite-github
-          githubToken: "${{ secrets.GITHUB }}"
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Sync package.json description to GitHub About
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB }}
+        run: |
+          DESC=$(jq -r '.description // empty' package.json)
+          if [ -n "$DESC" ]; then
+            echo "Updating repository description to: $DESC"
+            gh api -X PATCH repos/${{ github.repository }} -f description="$DESC"
+          else
+            echo "No description found in package.json."
+          fi
 
   release:
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout
-        uses: actions/checkout@v4
+      - name: Checkout repository
+        uses: actions/checkout@v7
         with:
-          fetch-depth: 0 # Required so semantic-release can trace git tags/history
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB }} # Authenticates git CLI for tag/commit pushes
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v7
         with:
-          node-version: 22
+          node-version: '24'
 
       - name: Install Semantic Release & Plugins
-        # Installs semantic-release and its plugins on the runner
         run: |
           npm install -g semantic-release \
             @semantic-release/changelog \
@@ -43,12 +46,11 @@ jobs:
             @semantic-release/github \
             @semantic-release/git
 
-      - name: Run Semantic Release (Native)
+      - name: Run Semantic Release
         id: semantic
-        # This will automatically pick up your export default config file in the repository root
         run: npx semantic-release
         env:
-          GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
+          GITHUB_TOKEN: "${{ secrets.GITHUB }}"
           NPM_TOKEN: "${{ secrets.NPM_TOKEN }}"
 
     outputs:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cocreate/crdt",
-  "version": "1.29.2",
+  "version": "1.31.0",
   "description": "CoCreate crdt",
   "author": "CoCreate LLC",
   "license": "AGPL-3.0",
@@ -26,12 +26,12 @@
   },
   "main": "./src/index.js",
   "dependencies": {
-    "@cocreate/crud-client": "^1.35.0",
-    "@cocreate/local-storage": "^1.17.0",
-    "@cocreate/utils": "^1.44.0"
+    "@cocreate/crud-client": "^1.36.0",
+    "@cocreate/local-storage": "^1.18.0",
+    "@cocreate/utils": "^1.50.3"
   },
   "devDependencies": {
-    "@cocreate/webpack": "^1.6.0"
+    "@cocreate/webpack": "^1.7.0"
   },
   "allowScripts": {
     "@cocreate/actions@1.21.4": true,
@@ -48,7 +48,6 @@
     "@cocreate/render@1.46.1": true,
     "@cocreate/socket-client@1.40.5": true,
     "@cocreate/utils@1.42.2": true,
-    "@cocreate/uuid@1.12.4": true,
     "@cocreate/webpack@1.4.3": true
   }
 }

package/src/index.js

@@ -20,16 +20,54 @@
 // you must obtain a commercial license from CoCreate LLC.
 // For details, visit <https://cocreate.app/licenses/> or contact us at sales@cocreate.app.
 
-/*globals config, atob, btoa, localStorage, CustomEvent*/
 import crud from '@cocreate/crud-client';
-import uuid from '@cocreate/uuid';
+import { uuid, ulid, ulidDecode } from '@cocreate/utils';
 import localStorage from '@cocreate/local-storage';
 
-const objects = {}
-const clientId = crud.socket.clientId || uuid.generate(12);
-const frameId = crud.socket.frameId || uuid.generate(12);
+/**
+ * @typedef {Object} CRDTData
+ * @property {string} array - The collection/array name.
+ * @property {string} object - The document/object ID.
+ * @property {string} key - The specific key/field being edited.
+ * @property {string} [value] - The string value being inserted or modified.
+ * @property {number} [start] - The starting index of the change.
+ * @property {number} [length] - The length of the text being modified.
+ * @property {string} [frameId] - The browser frame origin ID.
+ * @property {string} [id] - The unique ULID for the change.
+ */
+
+const objects = {};
+const clientId = crud.socket.clientId || uuid(12);
+const frameId = crud.socket.frameId || uuid(12);
 const checkedDb = new Map();
 
+/**
+ * Pure helper function to replace String.prototype.customSplice.
+ * Prevents global prototype pollution while allowing string mutation logic.
+ * 
+ * @param {string} str - The original string.
+ * @param {number} index - The zero-based index at which to start changing the string.
+ * @param {number} count - The number of characters to remove.
+ * @param {string} [add=""] - The string to insert.
+ * @returns {string} The modified string.
+ * 
+ * @example
+ * spliceString("Hello World", 6, 5, "CRDT"); // Returns "Hello CRDT"
+ */
+function spliceString(str, index, count, add) {
+    if (index < 0) {
+        index = str.length + index;
+        if (index < 0) index = 0;
+    }
+    return str.slice(0, index) + (add || "") + str.slice(index + Math.abs(count));
+}
+
+/**
+ * Initializes a CRDT session for a specific document field.
+ * Fetches the initial text state and sets the local frame context.
+ * 
+ * @param {CRDTData} data - The document tracking configuration.
+ */
 function init(data) {
     getText(data).then(value => {
         data.value = value;
@@ -39,24 +77,31 @@ function init(data) {
     });
 }
 
+/**
+ * Retrieves the internal CRDT tracking object for a specific field.
+ * If it doesn't exist locally, it queries the database for the changelog.
+ * 
+ * @param {CRDTData} data - The document tracking configuration.
+ * @returns {Promise<Object|undefined>} The tracked object containing text and changelogs.
+ */
 async function getObject(data) {
     try {
-        if (['_id', 'organization_id'].includes(data.key))
-            return
+        if (['_id', 'organization_id'].includes(data.key)) return;
+        
         let name = getName(data);
         let object = objects[name];
 
         if (!object) {
-            objects[name] = object = {}
+            objects[name] = object = {};
         }
 
+        // Initialize logs if this is the first time touching this object
         if (!object.changeLog) {
             let changeLog = [];
-            object.undoLog = new Map()
-            object.redoLog = new Map()
+            object.undoLog = new Map();
+            object.redoLog = new Map();
 
-
-            if (data.read != 'false') {
+            if (data.read !== 'false') {
                 if (!data.newObject) {
                     let response = await crud.send({
                         method: "object.read",
@@ -72,8 +117,8 @@ async function getObject(data) {
                         changeLog = response.object[0].changeLog;
                     }
                 }
-                object.changeLog = changeLog
-                // await generateText(data, true);
+                object.changeLog = changeLog;
+                
                 if (!object.text) {
                     await generateText(data, true);
                 }
@@ -87,23 +132,37 @@ async function getObject(data) {
     }
 }
 
-String.prototype.customSplice = function (index, absIndex, string) {
-    return this.slice(0, index) + string + this.slice(index + Math.abs(absIndex));
-};
-
+/**
+ * Rebuilds the current text state from the changeLog.
+ * Now mathematically guaranteed by ULID chronological sorting.
+ * 
+ * @param {CRDTData} data - The document tracking configuration.
+ * @param {boolean} flag - Whether to fetch from DB if empty.
+ * @returns {Promise<string>} The rebuilt text string.
+ */
 async function generateText(data, flag) {
     try {
-        let name = getName(data)
-        let object = objects[name]
-        object['text'] = ''
+        let name = getName(data);
+        let object = objects[name];
+        object['text'] = '';
+        
+        // Guarantee the changelog is in perfect temporal order before replaying.
+        // ULIDs are lexicographically sortable, allowing us to perfectly sequence events.
+        object['changeLog'].sort((a, b) => a.id.localeCompare(b.id));
+
         for (let change of object['changeLog']) {
             if (change) {
-                object['text'] = object['text'].customSplice(change.start, change.length, change.value);
+                if (change.type === 'snapshot') {
+                    // Fast-forward: Skip rebuilding character-by-character and jump straight to the snapshot state
+                    object['text'] = change.value;
+                } else {
+                    object['text'] = spliceString(object['text'], change.start, change.length, change.value);
+                }
             }
         }
 
         if (object['text'] === '' && data.read !== 'false') {
-            object['text'] = await checkDb(data, flag) || ''
+            object['text'] = await checkDb(data, flag) || '';
         }
 
         return object['text'];
@@ -112,23 +171,31 @@ async function generateText(data, flag) {
     }
 }
 
+/**
+ * Checks the database for the raw document value if no changelog is available.
+ * 
+ * @param {CRDTData} data - The document tracking configuration.
+ * @param {boolean|string} flag - Whether to insert the fetched text as a base change.
+ * @returns {Promise<string>} The base text string.
+ */
 async function checkDb(data, flag) {
     let { array, object, key } = data;
-    if (checkedDb.get(`${array}${object}${key}`))
-        return;
+    if (checkedDb.get(`${array}${object}${key}`)) return;
+    
     checkedDb.set(`${array}${object}${key}`, true);
 
-    let string = ''
-    if (data.newObject)
-        string = data.newObject
-    else {
+    let string = '';
+    if (data.newObject) {
+        string = data.newObject;
+    } else {
         let response = await crud.send({ method: 'object.read', array, object: { _id: object, key } });
         string = crud.getValueFromObject(response.object[0], key);
     }
 
-    if (string && typeof string !== 'string')
-        string = ""
-    if (string && typeof string === 'string' && flag != false) {
+    if (string && typeof string !== 'string') string = "";
+    
+    // Seed the CRDT with the existing string from the database
+    if (string && typeof string === 'string' && flag !== false) {
         data.value = string;
         data.start = 0;
         data.frameId = frameId;
@@ -138,22 +205,32 @@ async function checkDb(data, flag) {
     return string || '';
 }
 
+/**
+ * The core Collaborative Editing Engine. 
+ * Handles incoming characters, out-of-order resolution, and conflict management.
+ * 
+ * @param {CRDTData} data - The payload containing the keystroke/change.
+ * @param {string} [flag] - Pass 'replace' to completely overwrite the changelog.
+ * 
+ * @example
+ * insertChange({ array: "users", object: "123", key: "bio", value: "A", start: 0 });
+ */
 function insertChange(data, flag) {
     let name = getName(data);
     let object = objects[name];
     let changeLog = object.changeLog;
-    if (!changeLog)
-        return
+    
+    if (!changeLog) return;
 
-    object.text = object.text || ''
+    object.text = object.text || '';
 
     let type = 'insert';
     if (data.start == undefined) return;
-    if (!data.value)
-        type = 'delete';
+    if (!data.value) type = 'delete';
 
+    // Core CRDT Change Object
     let change = {
-        datetime: data.datetime || new Date().toISOString(),
+        id: data.id || ulid(), 
         value: data.value || '',
         start: data.start,
         end: data.end,
@@ -164,59 +241,66 @@ function insertChange(data, flag) {
         type
     };
 
-    let lastChange = changeLog[changeLog.length - 1];
-    if (lastChange && change.datetime && lastChange.datetime) {
-        if (change.datetime < lastChange.datetime) {
-            // TODO: insert change at index position and update start and end postions for every element after insert
-            console.log('requires changeLog rebuild');
-        }
-        if (flag != 'replace') {
-            if (lastChange && change.start == lastChange.start) {
-                let date1 = new Date(lastChange.datetime);
-                let date2 = new Date(change.datetime);
-                let diff = date2.getTime() - date1.getTime();
-                if (diff < 500) {
-                    if (change.value.length == 1) {
-                        change.start = lastChange.start + lastChange.value.length;
-                        data.start = change.start;
-                    }
-                    if (change.length == 1) {
-                        change.start = lastChange.start - lastChange.length;
-                        data.start = change.start;
-                    }
-                }
-            }
-        }
-    }
     if (!change || change == null) {
-        console.log('null change')
-        return
+        console.log('null change');
+        return;
     }
-    if (change.length > 0)
+
+    // Store the removed value to enable undo functionality
+    if (change.length > 0) {
         change.removedValue = object.text.substring(change.start, change.length);
+    }
 
-    if (flag == 'replace') {
-        // TODO get current string and create new changeLog array then push new change
+    if (flag === 'replace') {
         changeLog = [change];
+        object.changeLog = changeLog;
+        object.text = spliceString("", change.start, change.length, change.value);
     } else {
-        changeLog.push(change);
-    }
-
-    object.text = object.text.customSplice(change.start, change.length, change.value);
+        // SECURITY / STALE CHECK: Ensure the incoming change isn't older than a snapshot
+        let firstChange = changeLog[0];
+        if (firstChange && firstChange.type === 'snapshot') {
+            let changeTime = ulidDecode(change.id);
+            let snapshotTime = ulidDecode(firstChange.id);
+            
+            if (changeTime < snapshotTime) {
+                console.warn(`Rejected stale edit: User's change is older than the current snapshot boundary.`);
+                if (!data.frameId || data.frameId === frameId) {
+                   // Force a local sync/refresh to the latest state
+                   localChange(data, object.text);
+                }
+                return; // Abort insertion
+            }
+        }
 
-    if (!data.frameId) {
-        data.datetime = change.datetime;
+        let lastChange = changeLog[changeLog.length - 1];
+        changeLog.push(change);
+        
         data.frameId = change.frameId;
-
         broadcastChange(data);
-        localChange(data, object.text);
-    } else
-        localChange(data, object.text);
 
-    if (data.frameId == frameId && data.save != "false")
+        // Conflict Resolution: Fast path vs Rebuild
+        if (!lastChange || change.id >= lastChange.id) {
+            // In-order delivery: apply change directly to string for high performance
+            object.text = spliceString(object.text, change.start, change.length, change.value);
+            localChange(data, object.text);
+        } else {
+            // Out-of-order delivery: rebuild the text mathematically from the log
+            generateText(data, false).then(text => {
+                localChange(data, text);
+            });
+        }
+    }
+
+    if (data.frameId === frameId && data.save !== "false") {
         persistChange(data, change);
+    }
 }
 
+/**
+ * Broadcasts a local change to other connected browser clients via WebSocket.
+ * 
+ * @param {CRDTData} data - The change payload.
+ */
 function broadcastChange(data) {
     crud.socket.send({
         method: "crdt",
@@ -226,7 +310,12 @@ function broadcastChange(data) {
     });
 }
 
-
+/**
+ * Dispatches a DOM event to update the local UI (e.g., input fields, textareas).
+ * 
+ * @param {CRDTData} data - The change payload.
+ * @param {string} string - The newly calculated full text string.
+ */
 function localChange(data, string) {
     const localChange = new CustomEvent('cocreate-crdt-update', {
         detail: { ...data, string },
@@ -234,7 +323,12 @@ function localChange(data, string) {
     window.dispatchEvent(localChange);
 }
 
-
+/**
+ * Saves the changeLog operation to the backend database for permanent storage.
+ * 
+ * @param {CRDTData} data - The change payload.
+ * @param {Object} change - The generated ULID change object.
+ */
 function persistChange(data, change) {
     let name = getName(data);
     let Data = {
@@ -260,74 +354,67 @@ function persistChange(data, change) {
         broadcastSender: data.broadcastSender,
         broadcastBrowser: false,
         metadata: 'crdt-change'
-    }
+    };
 
     crud.send(Data);
 }
 
-
+// WebSocket listener for incoming remote CRDT changes
 crud.socket.listen('crdt', function (response) {
-    let data = response.data
+    let data = response.data;
     let name = getName(data);
-    let object = objects[name]
+    let object = objects[name];
 
     if (object) {
+        // Only insert if it originated from a different frame/browser
         if (data.frameId !== frameId) {
             insertChange(data);
         }
     }
 });
 
-// crud.listen('object.update', (data) => sync(data))
-// crud.listen('object.delete', (data) => sync(data))
-
+/**
+ * Syncs entire CRDT states from a remote source, often used for initial connection.
+ * 
+ * @param {Object} data - The sync payload from the server.
+ */
 function sync(data) {
-    if (data.clientId === clientId)
-        return
+    if (data.clientId === clientId) return;
+    
     if (data.array.includes('crdt')) {
         if (data.object && data.object[0]) {
             let Data = data.object[0];
             let name = Data.name;
             let object = objects[name];
+            
             if (object && Data.crud) {
-                // let text = object['text']
-                // if (!text && text !== '') {
-                //     setTimeout(function () {
-                //         console.log("text empty timout set");
-                //         sync(data)
-                //     }, 1000); // Delayed action after 2 seconds
-                // } else {
-                Data.crud.value = Data.text
-                Data.crud.start = 0
-                Data.crud.length = object['text'].length
-
-
-                object['changeLog'] = Data.changeLog
-                object['text'] = Data.text                // TODO: compare modified dates to check if arrays need to merged and orderd by date or if we just use server
-                localChange(Data.crud, Data.text)
-                console.log('crdtSync')
-                // }
+                Data.crud.value = Data.text;
+                Data.crud.start = 0;
+                Data.crud.length = object['text'].length;
+
+                object['changeLog'] = Data.changeLog;
+                object['text'] = Data.text; 
+                
+                localChange(Data.crud, Data.text);
+                console.log('crdtSync');
             }
         }
     }
-
 }
 
-/*
-crdt.getText({
-    array: 'modules',
-    object: '5e4802ce3ed96d38e71fc7e5',
-    key: 'name'
-})
-*/
+/**
+ * Helper to fetch the current full text of a tracked field.
+ * 
+ * @param {CRDTData} data - The document tracking configuration.
+ * @returns {Promise<string>} The current text value.
+ */
 async function getText(data) {
     try {
         let object = await getObject(data);
         if (object) {
-            let value = object.text
-            return value;
+            return object.text;
         } else {
-            console.log('undefined')
+            console.log('undefined');
         }
     } catch (e) {
         console.error(e);
@@ -335,27 +422,22 @@ async function getText(data) {
     }
 }
 
-
-/*
-crdt.replaceText({
-    array: "module",
-    object: "",
-    key: "",
-    value: "",
-    crud: true | false,
-    element: dom_object,
-    metadata: "xxxx"
-})
-*/
+/**
+ * Replaces the entire contents of the text state with a new string.
+ * Used for copy/paste or programmatic overwrites.
+ * 
+ * @param {CRDTData} data - Payload containing the new replacement string.
+ */
 async function replaceText(data) {
     try {
         let object = await getObject(data);
         if (object) {
             let oldValue = await getText(data);
-            if (oldValue)
+            if (oldValue) {
                 data.length = oldValue.length;
-            else
+            } else {
                 data.length = 0;
+            }
 
             data.start = 0;
             updateText(data, 'replace');
@@ -365,26 +447,21 @@ async function replaceText(data) {
     }
 }
 
-/*
-crdt.updateText({
-    array: 'module_activities',
-    object: '5e4802ce3ed96d38e71fc7e5',
-    key: 'name',
-    value: 'T',
-    start: '8',
-    attributes: {bold: true} 
-    length: 2, // length is used to define charcters that will be deleted
-})
-*/
+/**
+ * Wraps insertChange and additionally broadcasts a standard object update 
+ * for systems not listening to raw CRDT streams.
+ * 
+ * @param {CRDTData} data - The change payload.
+ * @param {string} [flag] - Flag to pass to insertChange (e.g., 'replace').
+ */
 async function updateText(data, flag) {
     let object = await getObject(data);
     if (object) {
-
         insertChange(data, flag);
 
-        if (data.crud != 'false' && data.save != 'false') {
-            if (data.upsert === undefined)
-                data.upsert = true
+        if (data.crud !== 'false' && data.save !== 'false') {
+            if (data.upsert === undefined) data.upsert = true;
+            
             let wholestring = await getText(data);
             crud.send({
                 method: 'object.update',
@@ -405,72 +482,100 @@ async function updateText(data, flag) {
     }
 }
 
+/**
+ * Inverts an operation to facilitate undo functionality.
+ * A deletion becomes an insertion, and an insertion becomes a deletion.
+ * 
+ * @param {CRDTData} data - The data context.
+ * @param {Object} change - The change object to invert.
+ * @returns {Object} An object containing the inverted data and change payloads.
+ */
 function createChange(data, change) {
     if (change.value && change.length == 0) {
-        change.length = change.value.length
-        change.removedValue = change.value
+        change.length = change.value.length;
+        change.removedValue = change.value;
         change.value = '';
         change.type = 'delete';
     } else {
-        change.value = change.removedValue
+        change.value = change.removedValue;
         change.length = 0;
         change.type = 'insert';
     }
+    
     data = { ...data, ...change };
-    delete data.frameId
-    delete data.datetime
-    delete change.frameId
-    delete change.datetime
-    return { data, change }
+    delete data.frameId;
+    delete data.id; // Strip ULID so a fresh one is generated for the undo action
+    delete change.frameId;
+    delete change.id;
+    return { data, change };
 }
 
+/**
+ * Reverts the last local change made by the user.
+ * Skips remote changes originating from other users.
+ * 
+ * @param {CRDTData} data - The document tracking configuration.
+ */
 function undoText(data) {
     let name = getName(data);
     let object = objects[name];
     let changeLog = object.changeLog;
     let undoLog = object.undoLog;
 
+    // Traverse changelog backwards to find the last local frame modification
     for (let index = changeLog.length - 1; index >= 0; index--) {
         let change = Object.assign({}, changeLog[index]);
         if (change && change.frameId == frameId) {
-            let log = undoLog.get(index)
+            let log = undoLog.get(index);
             if (!log) {
                 if (log != 'undo') {
-                    undoLog.set(index, 'undo')
+                    undoLog.set(index, 'undo');
                     change.index = changeLog.length += 1;
                     let updated = createChange(data, change);
-                    undoLog.set(updated.change.index, updated.change)
-                    updateText(updated.data)
-                    return
+                    undoLog.set(updated.change.index, updated.change);
+                    updateText(updated.data);
+                    return;
                 }
             }
         }
     }
 }
 
+/**
+ * Re-applies a previously undone local change.
+ * 
+ * @param {CRDTData} data - The document tracking configuration.
+ */
 function redoText(data) {
     let name = getName(data);
     let object = objects[name];
-    let redoLog = object.redoLog
+    let redoLog = object.redoLog;
     let undoLog = Array.from(object.undoLog.values());
 
     for (let index = undoLog.length - 1; index >= 0; index--) {
         let change = Object.assign({}, undoLog[index]);
         if (change && change != 'undo') {
-            let log = redoLog.get(change.index)
+            let log = redoLog.get(change.index);
 
             if (!log) {
                 if (log != 'redo') {
                     let updated = createChange(data, change);
-                    redoLog.set(updated.change.index, updated.change)
-                    updateText(updated.data)
-                    return
+                    redoLog.set(updated.change.index, updated.change);
+                    updateText(updated.data);
+                    return;
                 }
             }
         }
     }
 }
 
+/**
+ * Reconstructs the document state up to a specific historical version index.
+ * Useful for time-travel debugging and version history viewing.
+ * 
+ * @param {CRDTData} data - Contains version number target.
+ * @returns {Promise<Object>} The rebuilt document state at that point in time.
+ */
 async function viewVersion(data) {
     try {
         let name = getName(data);
@@ -478,26 +583,134 @@ async function viewVersion(data) {
         let changeLog = object.changeLog;
         let string = '';
 
-        let log = changeLog.slice(0, data.version)
+        let sortedLog = [...changeLog].sort((a, b) => a.id.localeCompare(b.id));
+        
+        // If a version is explicitly requested, slice the log up to that point
+        let log = data.version !== undefined ? sortedLog.slice(0, data.version) : sortedLog;
+        
         for (let change of log) {
             if (change || change !== null) {
-                string = string.customSplice(change.start, change.length, change.value);
+                if (change.type === 'snapshot') {
+                    string = change.value;
+                } else {
+                    string = spliceString(string, change.start, change.length, change.value);
+                }
             }
         }
-        return { ...data, ...string }
+        
+        data.value = string;
+        return data;
     } catch (e) {
         console.error(e);
     }
 }
 
-// function deleteObject(name) {
-// 	if (objects[name]) {
-// 		delete objects[name];
-// 	}
-// }
+/**
+ * Intelligent Garbage Collection & Log Compaction (Watermark Strategy).
+ * Compresses history safely by respecting active users' last known states,
+ * falling back to a time limit for inactive users.
+ * 
+ * @param {CRDTData} data - The document tracking configuration.
+ * @param {number} [countThreshold=5000] - Minimum log size before triggering snapshot.
+ * @param {number} [timeGracePeriodMs=604800000] - 7 days in ms. Older offline users lose their anchor.
+ * @returns {Promise<Array|undefined>} The newly compressed changelog.
+ */
+async function createSnapshot(data, countThreshold = 5000, timeGracePeriodMs = 7 * 24 * 60 * 60 * 1000) {
+    let name = getName(data);
+    let object = objects[name];
+    
+    // Only compress if the log is large enough to warrant it
+    if (!object || !object.changeLog || object.changeLog.length < countThreshold) return;
+
+    object.changeLog.sort((a, b) => a.id.localeCompare(b.id));
+
+    const now = Date.now();
+    const latestUserChanges = new Map();
+
+    // 1. Find the high-water mark (latest change) for each unique user
+    for (let i = 0; i < object.changeLog.length; i++) {
+        let change = object.changeLog[i];
+        if (change && change.type !== 'snapshot') {
+            let identifier = change.user_id || change.clientId || 'system';
+            // Overwrites previous entries, leaving only the very last known index per user
+            latestUserChanges.set(identifier, { index: i, timestamp: ulidDecode(change.id) });
+        }
+    }
+
+    // 2. Determine the safe boundary for compression.
+    let safeCompressionIndex = object.changeLog.length - 1; 
+
+    for (const [userId, record] of latestUserChanges.entries()) {
+        let isStale = (now - record.timestamp) > timeGracePeriodMs;
+        if (!isStale) {
+            // User is active! We must protect their last known anchor point.
+            if (record.index < safeCompressionIndex) {
+                safeCompressionIndex = record.index;
+            }
+        }
+    }
+
+    if (safeCompressionIndex <= 0) return;
+
+    // 3. Split the log at the safe boundary
+    let logToCompress = object.changeLog.slice(0, safeCompressionIndex);
+    let retainedLog = object.changeLog.slice(safeCompressionIndex);
+
+    // Roll up the compressed section into a single string
+    let snapshotText = '';
+    for (let change of logToCompress) {
+        if (change) {
+            if (change.type === 'snapshot') {
+                snapshotText = change.value;
+            } else {
+                snapshotText = spliceString(snapshotText, change.start, change.length, change.value);
+            }
+        }
+    }
+
+    // 4. Create the new snapshot event, adopting the exact ID of the last compressed item
+    let lastCompressedChange = logToCompress[logToCompress.length - 1];
+    let snapshotChange = {
+        id: lastCompressedChange.id, // Inherit the ULID timestamp of the boundary
+        type: 'snapshot',
+        value: snapshotText,
+        start: 0,
+        length: 0, 
+        clientId,
+        frameId,
+        user_id: localStorage.getItem("user_id") || "system",
+        version: true // Flag to indicate this is a restorable state view
+    };
+
+    object.changeLog = [snapshotChange, ...retainedLog];
+
+    // 5. Persist the newly compressed array to the database
+    if (data.save !== "false") {
+        crud.send({
+            method: 'object.update',
+            array: 'crdt',
+            object: {
+                name,
+                changeLog: object.changeLog, 
+                crud: { array: data.array, object: data.object, key: data.key }
+            },
+            $filter: { query: { name }, limit: 1 },
+            upsert: true,
+            metadata: 'crdt-snapshot'
+        });
+    }
+    
+    return object.changeLog;
+}
 
+/**
+ * Helper to generate a unique string key representing a specific tracked document field.
+ * 
+ * @param {CRDTData} data - The routing payload.
+ * @returns {string} Concatenated namespace/document/key string.
+ */
 function getName(data) {
     return `${data.array}${data.object}${data.key}`;
 }
 
-export default { init, objects, getName, getText, updateText, replaceText, undoText, redoText, viewVersion };
+export default { init, objects, getName, getText, updateText, replaceText, undoText, redoText, viewVersion, createSnapshot };