@sovereignbase/convergent-replicated-list 1.0.3 → 1.0.5

package/dist/index.d.cts

@@ -114,7 +114,7 @@ declare class CRList<T> {
     private readonly state;
     private readonly eventTarget;
     /**
-     * Creates a replicated list from an optional serializable snapshot.
+     * Creates a replicated list from an optional detached structured-clone-compatible snapshot.
      *
      * @param snapshot - A previously emitted CRList snapshot.
      */
@@ -166,7 +166,7 @@ declare class CRList<T> {
      */
     garbageCollect(frontiers: Array<CRListAck>): void;
     /**
-     * Emits the current serializable list snapshot.
+     * Emits the current detached structured-clone-compatible list snapshot.
      */
     snapshot(): void;
     /**
@@ -186,13 +186,15 @@ declare class CRList<T> {
      */
     removeEventListener<K extends keyof CRListEventMap<T>>(type: K, listener: CRListEventListenerFor<T, K> | null, options?: boolean | EventListenerOptions): void;
     /**
-     * Returns a serializable snapshot representation of this list.
+     * Returns a detached structured-clone-compatible snapshot of this list.
      *
      * Called automatically by `JSON.stringify`.
      */
     toJSON(): CRListSnapshot<T>;
     /**
-     * Returns this list as a JSON string.
+     * Attempts to return this list snapshot as a JSON string.
+     *
+     * This can fail when list values are not JSON-compatible.
      */
     toString(): string;
     /**
@@ -215,6 +217,22 @@ declare class CRList<T> {
  * Error codes thrown by {@link CRList}.
  */
 type CRListErrorCode = 'VALUE_NOT_CLONEABLE' | 'INDEX_OUT_OF_BOUNDS' | 'LIST_EMPTY' | 'LIST_INTEGRITY_VIOLATION' | 'UPDATE_EXPECTED_AN_ARRAY';
+/**
+ * Represents a typed CRList runtime error.
+ */
+declare class CRListError extends Error {
+    /**
+     * The semantic error code for the failure.
+     */
+    readonly code: CRListErrorCode;
+    /**
+     * Creates a typed CRList error.
+     *
+     * @param code - The semantic error code.
+     * @param message - An optional human-readable detail message.
+     */
+    constructor(code: CRListErrorCode, message?: string);
+}
 
 /**
  * Creates a local CRList replica from an optional snapshot.
@@ -223,8 +241,8 @@ type CRListErrorCode = 'VALUE_NOT_CLONEABLE' | 'INDEX_OUT_OF_BOUNDS' | 'LIST_EMP
  * UUIDv7, linked through their predecessor buckets, and exposed as a live
  * doubly-linked list.
  *
- * @param snapshot Optional serializable CRList state.
- * @returns A hydrated CRList replica.
+ * @param snapshot - Optional detached structured-clone-compatible CRList snapshot.
+ * @returns - A hydrated CRList replica.
  *
  * Time complexity: O(n log n + t + c), worst case O(n^2 + t + c)
  * - n = snapshot value entry count
@@ -243,9 +261,9 @@ declare function __create<T>(snapshot?: CRListSnapshot<T>): CRListState<T>;
  * value does not mutate the replica itself. Out-of-bounds and empty list reads
  * resolve to `undefined` instead of throwing.
  *
- * @param targetIndex Index in the live list.
- * @param crListReplica Replica to read from.
- * @returns A detached copy of the value at `targetIndex`, or `undefined` when
+ * @param targetIndex - Index in the live list.
+ * @param crListReplica - Replica to read from.
+ * @returns - A detached copy of the value at `targetIndex`, or `undefined` when
  * no value is present.
  *
  * Time complexity: O(d), worst case O(n)
@@ -263,11 +281,11 @@ declare function __read<T>(targetIndex: number, crListReplica: CRListState<T>):
  * before it, or insert values after it. The returned delta is suitable for
  * gossip and the returned change describes the local live-view patch.
  *
- * @param listIndex Target index in the live list.
- * @param listValues Values to insert or overwrite.
- * @param crListReplica Replica to mutate.
- * @param mode Mutation mode relative to `listIndex`.
- * @returns A local change and gossip delta, or `false` if no mutation occurred.
+ * @param listIndex - Target index in the live list.
+ * @param listValues - Values to insert or overwrite.
+ * @param crListReplica - Replica to mutate.
+ * @param mode - Mutation mode relative to `listIndex`.
+ * @returns - A local change and gossip delta, or `false` if no mutation occurred.
  *
  * Time complexity: O(d + v + r + vk + c), worst case O(vn + c)
  * - d = distance from cursor to target index
@@ -290,10 +308,10 @@ declare function __update<T>(listIndex: number, listValues: Array<T>, crListRepl
  * from `startIndex` onward are deleted. With both indexes, the deleted range is
  * `[startIndex, endIndex)`.
  *
- * @param crListReplica Replica to mutate.
- * @param startIndex Inclusive start index. Defaults to `0`.
- * @param endIndex Exclusive end index. Defaults to the current list size.
- * @returns A local change and gossip delta, or `false` if nothing was deleted.
+ * @param crListReplica - Replica to mutate.
+ * @param startIndex - Inclusive start index. Defaults to `0`.
+ * @param endIndex - Exclusive end index. Defaults to the current list size.
+ * @returns - A local change and gossip delta, or `false` if nothing was deleted.
  *
  * Time complexity: O(d + qk + r), worst case O(n^2)
  * - d = distance from cursor to target index
@@ -315,9 +333,9 @@ declare function __delete<T>(crListReplica: CRListState<T>, startIndex?: number,
  * to the predecessor tree. Tail-append deltas are linked incrementally; deltas
  * that can affect ordering fall back to deterministic relinking.
  *
- * @param crListReplica Replica to mutate.
- * @param crListDelta Remote gossip delta.
- * @returns A minimal local change patch, or `false` when the delta is ignored.
+ * @param crListReplica - Replica to mutate.
+ * @param crListDelta - Remote gossip delta.
+ * @returns - A minimal local change patch, or `false` when the delta is ignored.
  *
  * Time complexity: O(v + t + c) for tail-append deltas; O(n + t + qk) for tombstone-only deletes; otherwise O(n log n + v + t + m*k + c)
  * Worst case: O(n^2 + (v + t)n + c)
@@ -339,8 +357,8 @@ declare function __merge<T>(crListReplica: CRListState<T>, crListDelta: CRListDe
  * The frontier is the greatest tombstone identifier currently retained by the
  * replica. Peers can use it as input for tombstone garbage collection.
  *
- * @param crListReplica Replica to acknowledge.
- * @returns The acknowledgement frontier, or `false` when there are no tombstones.
+ * @param crListReplica - Replica to acknowledge.
+ * @returns - The acknowledgement frontier, or `false` when there are no tombstones.
  *
  * Time complexity: O(t)
  * - t = replica tombstone count
@@ -355,8 +373,8 @@ declare function __acknowledge<T>(crListReplica: CRListState<T>): CRListAck | fa
  * The minimum frontier is used as the safe collection boundary. Tombstones less
  * than or equal to that boundary are removed from the local replica.
  *
- * @param frontiers Acknowledgement frontiers received from peers.
- * @param crListReplica Replica whose tombstones will be collected.
+ * @param frontiers - Acknowledgement frontiers received from peers.
+ * @param crListReplica - Replica whose tombstones will be collected.
  *
  * Time complexity: O(f log f + t)
  * - f = frontier count
@@ -367,13 +385,13 @@ declare function __acknowledge<T>(crListReplica: CRListState<T>): CRListAck | fa
 declare function __garbageCollect<T>(frontiers: Array<CRListAck>, crListReplica: CRListState<T>): void;
 
 /**
- * Creates a full serializable CRList snapshot from the current replica state.
+ * Creates a full detached structured-clone-compatible CRList snapshot from the current replica state.
  *
  * The snapshot contains every live value entry and all retained tombstones. Value
  * payloads are cloned so callers cannot mutate the replica through the snapshot.
  *
- * @param crListReplica Replica to snapshot.
- * @returns A full snapshot suitable for hydration or transport.
+ * @param crListReplica - Replica to snapshot.
+ * @returns - A full snapshot suitable for hydration or transport.
  *
  * Time complexity: O(n + t + c)
  * - n = replica value entry count
@@ -384,4 +402,4 @@ declare function __garbageCollect<T>(frontiers: Array<CRListAck>, crListReplica:
  */
 declare function __snapshot<T>(crListReplica: CRListState<T>): CRListSnapshot<T>;
 
-export { CRList, type CRListAck, type CRListChange, type CRListDelta, type CRListErrorCode, type CRListEventListener, type CRListEventListenerFor, type CRListEventMap, type CRListSnapshot, type CRListSnapshotEntry, type CRListState, type CRListStateEntry, __acknowledge, __create, __delete, __garbageCollect, __merge, __read, __snapshot, __update };
+export { CRList, type CRListAck, type CRListChange, type CRListDelta, CRListError, type CRListErrorCode, type CRListEventListener, type CRListEventListenerFor, type CRListEventMap, type CRListSnapshot, type CRListSnapshotEntry, type CRListState, type CRListStateEntry, __acknowledge, __create, __delete, __garbageCollect, __merge, __read, __snapshot, __update };

package/dist/index.d.ts

@@ -114,7 +114,7 @@ declare class CRList<T> {
     private readonly state;
     private readonly eventTarget;
     /**
-     * Creates a replicated list from an optional serializable snapshot.
+     * Creates a replicated list from an optional detached structured-clone-compatible snapshot.
      *
      * @param snapshot - A previously emitted CRList snapshot.
      */
@@ -166,7 +166,7 @@ declare class CRList<T> {
      */
     garbageCollect(frontiers: Array<CRListAck>): void;
     /**
-     * Emits the current serializable list snapshot.
+     * Emits the current detached structured-clone-compatible list snapshot.
      */
     snapshot(): void;
     /**
@@ -186,13 +186,15 @@ declare class CRList<T> {
      */
     removeEventListener<K extends keyof CRListEventMap<T>>(type: K, listener: CRListEventListenerFor<T, K> | null, options?: boolean | EventListenerOptions): void;
     /**
-     * Returns a serializable snapshot representation of this list.
+     * Returns a detached structured-clone-compatible snapshot of this list.
      *
      * Called automatically by `JSON.stringify`.
      */
     toJSON(): CRListSnapshot<T>;
     /**
-     * Returns this list as a JSON string.
+     * Attempts to return this list snapshot as a JSON string.
+     *
+     * This can fail when list values are not JSON-compatible.
      */
     toString(): string;
     /**
@@ -215,6 +217,22 @@ declare class CRList<T> {
  * Error codes thrown by {@link CRList}.
  */
 type CRListErrorCode = 'VALUE_NOT_CLONEABLE' | 'INDEX_OUT_OF_BOUNDS' | 'LIST_EMPTY' | 'LIST_INTEGRITY_VIOLATION' | 'UPDATE_EXPECTED_AN_ARRAY';
+/**
+ * Represents a typed CRList runtime error.
+ */
+declare class CRListError extends Error {
+    /**
+     * The semantic error code for the failure.
+     */
+    readonly code: CRListErrorCode;
+    /**
+     * Creates a typed CRList error.
+     *
+     * @param code - The semantic error code.
+     * @param message - An optional human-readable detail message.
+     */
+    constructor(code: CRListErrorCode, message?: string);
+}
 
 /**
  * Creates a local CRList replica from an optional snapshot.
@@ -223,8 +241,8 @@ type CRListErrorCode = 'VALUE_NOT_CLONEABLE' | 'INDEX_OUT_OF_BOUNDS' | 'LIST_EMP
  * UUIDv7, linked through their predecessor buckets, and exposed as a live
  * doubly-linked list.
  *
- * @param snapshot Optional serializable CRList state.
- * @returns A hydrated CRList replica.
+ * @param snapshot - Optional detached structured-clone-compatible CRList snapshot.
+ * @returns - A hydrated CRList replica.
  *
  * Time complexity: O(n log n + t + c), worst case O(n^2 + t + c)
  * - n = snapshot value entry count
@@ -243,9 +261,9 @@ declare function __create<T>(snapshot?: CRListSnapshot<T>): CRListState<T>;
  * value does not mutate the replica itself. Out-of-bounds and empty list reads
  * resolve to `undefined` instead of throwing.
  *
- * @param targetIndex Index in the live list.
- * @param crListReplica Replica to read from.
- * @returns A detached copy of the value at `targetIndex`, or `undefined` when
+ * @param targetIndex - Index in the live list.
+ * @param crListReplica - Replica to read from.
+ * @returns - A detached copy of the value at `targetIndex`, or `undefined` when
  * no value is present.
  *
  * Time complexity: O(d), worst case O(n)
@@ -263,11 +281,11 @@ declare function __read<T>(targetIndex: number, crListReplica: CRListState<T>):
  * before it, or insert values after it. The returned delta is suitable for
  * gossip and the returned change describes the local live-view patch.
  *
- * @param listIndex Target index in the live list.
- * @param listValues Values to insert or overwrite.
- * @param crListReplica Replica to mutate.
- * @param mode Mutation mode relative to `listIndex`.
- * @returns A local change and gossip delta, or `false` if no mutation occurred.
+ * @param listIndex - Target index in the live list.
+ * @param listValues - Values to insert or overwrite.
+ * @param crListReplica - Replica to mutate.
+ * @param mode - Mutation mode relative to `listIndex`.
+ * @returns - A local change and gossip delta, or `false` if no mutation occurred.
  *
  * Time complexity: O(d + v + r + vk + c), worst case O(vn + c)
  * - d = distance from cursor to target index
@@ -290,10 +308,10 @@ declare function __update<T>(listIndex: number, listValues: Array<T>, crListRepl
  * from `startIndex` onward are deleted. With both indexes, the deleted range is
  * `[startIndex, endIndex)`.
  *
- * @param crListReplica Replica to mutate.
- * @param startIndex Inclusive start index. Defaults to `0`.
- * @param endIndex Exclusive end index. Defaults to the current list size.
- * @returns A local change and gossip delta, or `false` if nothing was deleted.
+ * @param crListReplica - Replica to mutate.
+ * @param startIndex - Inclusive start index. Defaults to `0`.
+ * @param endIndex - Exclusive end index. Defaults to the current list size.
+ * @returns - A local change and gossip delta, or `false` if nothing was deleted.
  *
  * Time complexity: O(d + qk + r), worst case O(n^2)
  * - d = distance from cursor to target index
@@ -315,9 +333,9 @@ declare function __delete<T>(crListReplica: CRListState<T>, startIndex?: number,
  * to the predecessor tree. Tail-append deltas are linked incrementally; deltas
  * that can affect ordering fall back to deterministic relinking.
  *
- * @param crListReplica Replica to mutate.
- * @param crListDelta Remote gossip delta.
- * @returns A minimal local change patch, or `false` when the delta is ignored.
+ * @param crListReplica - Replica to mutate.
+ * @param crListDelta - Remote gossip delta.
+ * @returns - A minimal local change patch, or `false` when the delta is ignored.
  *
  * Time complexity: O(v + t + c) for tail-append deltas; O(n + t + qk) for tombstone-only deletes; otherwise O(n log n + v + t + m*k + c)
  * Worst case: O(n^2 + (v + t)n + c)
@@ -339,8 +357,8 @@ declare function __merge<T>(crListReplica: CRListState<T>, crListDelta: CRListDe
  * The frontier is the greatest tombstone identifier currently retained by the
  * replica. Peers can use it as input for tombstone garbage collection.
  *
- * @param crListReplica Replica to acknowledge.
- * @returns The acknowledgement frontier, or `false` when there are no tombstones.
+ * @param crListReplica - Replica to acknowledge.
+ * @returns - The acknowledgement frontier, or `false` when there are no tombstones.
  *
  * Time complexity: O(t)
  * - t = replica tombstone count
@@ -355,8 +373,8 @@ declare function __acknowledge<T>(crListReplica: CRListState<T>): CRListAck | fa
  * The minimum frontier is used as the safe collection boundary. Tombstones less
  * than or equal to that boundary are removed from the local replica.
  *
- * @param frontiers Acknowledgement frontiers received from peers.
- * @param crListReplica Replica whose tombstones will be collected.
+ * @param frontiers - Acknowledgement frontiers received from peers.
+ * @param crListReplica - Replica whose tombstones will be collected.
  *
  * Time complexity: O(f log f + t)
  * - f = frontier count
@@ -367,13 +385,13 @@ declare function __acknowledge<T>(crListReplica: CRListState<T>): CRListAck | fa
 declare function __garbageCollect<T>(frontiers: Array<CRListAck>, crListReplica: CRListState<T>): void;
 
 /**
- * Creates a full serializable CRList snapshot from the current replica state.
+ * Creates a full detached structured-clone-compatible CRList snapshot from the current replica state.
  *
  * The snapshot contains every live value entry and all retained tombstones. Value
  * payloads are cloned so callers cannot mutate the replica through the snapshot.
  *
- * @param crListReplica Replica to snapshot.
- * @returns A full snapshot suitable for hydration or transport.
+ * @param crListReplica - Replica to snapshot.
+ * @returns - A full snapshot suitable for hydration or transport.
  *
  * Time complexity: O(n + t + c)
  * - n = replica value entry count
@@ -384,4 +402,4 @@ declare function __garbageCollect<T>(frontiers: Array<CRListAck>, crListReplica:
  */
 declare function __snapshot<T>(crListReplica: CRListState<T>): CRListSnapshot<T>;
 
-export { CRList, type CRListAck, type CRListChange, type CRListDelta, type CRListErrorCode, type CRListEventListener, type CRListEventListenerFor, type CRListEventMap, type CRListSnapshot, type CRListSnapshotEntry, type CRListState, type CRListStateEntry, __acknowledge, __create, __delete, __garbageCollect, __merge, __read, __snapshot, __update };
+export { CRList, type CRListAck, type CRListChange, type CRListDelta, CRListError, type CRListErrorCode, type CRListEventListener, type CRListEventListenerFor, type CRListEventMap, type CRListSnapshot, type CRListSnapshotEntry, type CRListState, type CRListStateEntry, __acknowledge, __create, __delete, __garbageCollect, __merge, __read, __snapshot, __update };

package/dist/index.js

@@ -134,9 +134,10 @@ function flattenAndLinkTrustedState(crListReplica) {
   crListReplica.size = crListReplica.parentMap.size;
 }
 
-// src/.helpers/snapshotValueToLinkedListValue/index.ts
+// src/.helpers/transformSnapshotEntryToStateEntry/index.ts
 import { isUuidV7, safeStructuredClone } from "@sovereignbase/utils";
-function snapshotValueToLinkedListValue(valueEntry, crListReplica) {
+function transformSnapshotEntryToStateEntry(valueEntry, crListReplica) {
+  if (valueEntry === null || valueEntry === void 0) return void 0;
   if (!isUuidV7(valueEntry.uuidv7) || crListReplica.tombstones.has(valueEntry.uuidv7) || crListReplica.parentMap.has(valueEntry.uuidv7) || !isUuidV7(valueEntry.predecessor) && valueEntry.predecessor !== "\0" && !crListReplica.tombstones.has(valueEntry.predecessor))
     return void 0;
   const [cloned, copiedValue] = safeStructuredClone(valueEntry.value);
@@ -235,7 +236,7 @@ function __create(snapshot) {
   if (!Object.hasOwn(snapshot, "values") || !Array.isArray(snapshot.values))
     return crListReplica;
   for (const valueEntry of snapshot.values) {
-    const linkedListEntry = snapshotValueToLinkedListValue(
+    const linkedListEntry = transformSnapshotEntryToStateEntry(
       valueEntry,
       crListReplica
     );
@@ -300,7 +301,7 @@ function __update(listIndex, listValues, crListReplica, mode) {
           insertBetween(crListReplica.cursor, linkedListEntry, void 0);
           void updateEntryToMaps(crListReplica, linkedListEntry, delta);
           crListReplica.cursor = linkedListEntry;
-          change[linkedListEntry.index] = linkedListEntry.value;
+          change[linkedListEntry.index] = structuredClone(linkedListEntry.value);
           break;
         }
         void walkToIndex(listIndex, crListReplica);
@@ -330,14 +331,14 @@ function __update(listIndex, listValues, crListReplica, mode) {
         entryToOverwrite.next = void 0;
         entryToOverwrite.prev = void 0;
         crListReplica.cursor = linkedListEntry;
-        change[linkedListEntry.index] = linkedListEntry.value;
+        change[linkedListEntry.index] = structuredClone(linkedListEntry.value);
         break;
       }
       case "after": {
         if (crListReplica.size === 0 && listIndex === 0) {
           crListReplica.cursor = linkedListEntry;
           void updateEntryToMaps(crListReplica, linkedListEntry, delta);
-          change[linkedListEntry.index] = linkedListEntry.value;
+          change[linkedListEntry.index] = structuredClone(linkedListEntry.value);
           break;
         }
         if (listIndex === crListReplica.size) {
@@ -363,14 +364,14 @@ function __update(listIndex, listValues, crListReplica, mode) {
         }
         void updateEntryToMaps(crListReplica, linkedListEntry, delta);
         crListReplica.cursor = linkedListEntry;
-        change[linkedListEntry.index] = linkedListEntry.value;
+        change[linkedListEntry.index] = structuredClone(linkedListEntry.value);
         break;
       }
       case "before": {
         if (crListReplica.size === 0 && listIndex === 0) {
           crListReplica.cursor = linkedListEntry;
           void updateEntryToMaps(crListReplica, linkedListEntry, delta);
-          change[linkedListEntry.index] = linkedListEntry.value;
+          change[linkedListEntry.index] = structuredClone(linkedListEntry.value);
           mode = "after";
           listIndex = linkedListEntry.index - 1;
           break;
@@ -392,7 +393,7 @@ function __update(listIndex, listValues, crListReplica, mode) {
         }
         void updateEntryToMaps(crListReplica, linkedListEntry, delta);
         crListReplica.cursor = linkedListEntry;
-        change[linkedListEntry.index] = linkedListEntry.value;
+        change[linkedListEntry.index] = structuredClone(linkedListEntry.value);
         mode = "after";
         listIndex = linkedListEntry.index - 1;
         break;
@@ -468,6 +469,7 @@ function __merge(crListReplica, crListDelta) {
     return change;
   }
   for (const valueEntry of crListDelta.values) {
+    if (valueEntry === null || valueEntry === void 0) continue;
     const existingEntry = crListReplica.parentMap.get(valueEntry.uuidv7);
     if (existingEntry) {
       if (crListReplica.tombstones.has(valueEntry.uuidv7) || !isUuidV73(valueEntry.predecessor) && valueEntry.predecessor !== "\0")
@@ -482,7 +484,7 @@ function __merge(crListReplica, crListDelta) {
       void newVals.push(existingEntry);
       continue;
     }
-    const linkedListEntry = snapshotValueToLinkedListValue(
+    const linkedListEntry = transformSnapshotEntryToStateEntry(
       valueEntry,
       crListReplica
     );
@@ -516,28 +518,30 @@ function __merge(crListReplica, crListDelta) {
     change[index] = void 0;
   }
   for (const val of newVals) {
-    change[val.index] = val.value;
+    change[val.index] = structuredClone(val.value);
   }
   return change;
 }
 
 // src/core/mags/acknowledge/index.ts
 function __acknowledge(crListReplica) {
-  let frontier = false;
+  let largest = false;
   crListReplica.tombstones.forEach((tombstone) => {
-    if (frontier === false || frontier < tombstone) frontier = tombstone;
+    if (largest === false || largest < tombstone) largest = tombstone;
   });
-  if (typeof frontier === "string") return frontier;
+  if (typeof largest === "string") return largest;
   return false;
 }
 
 // src/core/mags/garbageCollect/index.ts
+import { isUuidV7 as isUuidV74 } from "@sovereignbase/utils";
 function __garbageCollect(frontiers, crListReplica) {
   if (!Array.isArray(frontiers)) return;
-  const frontier = frontiers.sort().shift();
-  if (typeof frontier !== "string") return;
+  frontiers.sort();
+  const smallest = frontiers.find((frontier) => isUuidV74(frontier));
+  if (typeof smallest !== "string") return;
   crListReplica.tombstones.forEach((tombstone, __, tombstones) => {
-    if (tombstone <= frontier) {
+    if (tombstone <= smallest) {
       tombstones.delete(tombstone);
     }
   });
@@ -563,7 +567,7 @@ function __snapshot(crListReplica) {
 // src/CRList/class.ts
 var CRList = class {
   /**
-   * Creates a replicated list from an optional serializable snapshot.
+   * Creates a replicated list from an optional detached structured-clone-compatible snapshot.
    *
    * @param snapshot - A previously emitted CRList snapshot.
    */
@@ -609,7 +613,8 @@ var CRList = class {
               new CustomEvent("change", { detail: change })
             );
           return true;
-        } catch {
+        } catch (error) {
+          if (error instanceof CRListError) throw error;
           return false;
         }
       },
@@ -631,7 +636,8 @@ var CRList = class {
             );
           }
           return true;
-        } catch {
+        } catch (error) {
+          if (error instanceof CRListError) throw error;
           return false;
         }
       },
@@ -759,7 +765,7 @@ var CRList = class {
     void __garbageCollect(frontiers, this.state);
   }
   /**
-   * Emits the current serializable list snapshot.
+   * Emits the current detached structured-clone-compatible list snapshot.
    */
   snapshot() {
     const snapshot = __snapshot(this.state);
@@ -797,7 +803,7 @@ var CRList = class {
     );
   }
   /**
-   * Returns a serializable snapshot representation of this list.
+   * Returns a detached structured-clone-compatible snapshot of this list.
    *
    * Called automatically by `JSON.stringify`.
    */
@@ -805,7 +811,9 @@ var CRList = class {
     return __snapshot(this.state);
   }
   /**
-   * Returns this list as a JSON string.
+   * Attempts to return this list snapshot as a JSON string.
+   *
+   * This can fail when list values are not JSON-compatible.
    */
   toString() {
     return JSON.stringify(this);
@@ -848,6 +856,7 @@ var CRList = class {
 };
 export {
   CRList,
+  CRListError,
   __acknowledge,
   __create,
   __delete,