@mmstack/primitives 22.8.0 → 22.8.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmstack/primitives",
-  "version": "22.8.0",
+  "version": "22.8.2",
   "keywords": [
     "angular",
     "signals",

package/types/mmstack-primitives.d.ts

@@ -3101,10 +3101,14 @@ declare const STORE_SHARED_GLOBALS: unique symbol;
 type ProxyCache = WeakMap<object, Map<PropertyKey, WeakRef<Signal<any>>>>;
 /**
  * @internal
- * Prunes a cache entry once its proxy is reclaimed by the GC.
+ * Prunes a cache entry once its proxy is reclaimed by the GC. The held value must reference
+ * `target` only weakly: held values are retained by the registry until its cleanup callbacks
+ * run (host tasks — they never run inside a synchronous burst), so a strong `target` here
+ * keeps every dropped subtree's backing-signal ancestry alive across GCs. If `target` is
+ * already dead its whole cache entry died with it (WeakMap), and there is nothing to prune.
  */
 type ProxyCleanupRegistry = FinalizationRegistry<{
-    target: object;
+    targetRef: WeakRef<object>;
     prop: PropertyKey;
 }>;
 /**
@@ -3774,6 +3778,12 @@ type StoreHistory = {
     undo(): void;
     /** Re-apply the most recently undone change. */
     redo(): void;
+    /**
+     * Close the current coalescing run: the next tracked change starts a NEW undo entry even if
+     * it lands inside the `coalesce` window. Call it on the boundaries your UX considers an
+     * action — a field blur, a selection change, a drag drop. A no-op without `coalesce`.
+     */
+    checkpoint(): void;
     /** Forget all tracked history (e.g. after a save boundary). */
     clear(): void;
     destroy(): void;
@@ -3785,11 +3795,29 @@ type StoreHistoryOptions = CreateOpLogOptions & {
      * The change stream to track. Defaults to self-diffing `source` (every change to the store
      * becomes undoable). For collaborative-safe undo, pass a sync client's LOCAL envelope stream
      * (e.g. an `opSync`'s `subscribe`, which fires only for this peer's own writes) — remote
-     * peers' changes then never land on your undo stack.
+     * peers' changes then never land on your undo stack. When the stream exposes `flush` (an
+     * `opSync` does), undo/redo drain it synchronously so their own emissions never echo back
+     * onto the stack as fresh entries.
      */
     readonly track?: {
         subscribe(cb: (batch: OpBatch) => void): () => void;
+        flush?(): void;
+    };
+    /**
+     * Merge rapid consecutive edits into ONE undo entry, so a typing run undoes as a unit
+     * instead of per keystroke. A tracked change arriving within `ms` of the previous one AND
+     * touching the same paths with the same op kinds extends the previous entry (set
+     * `samePath: false` to merge on time alone); anything else — a different field, a kind
+     * change, a pause longer than `ms`, a `checkpoint()`, an undo/redo — starts a new entry.
+     * The window is measured between consecutive changes, so an unbroken run keeps merging.
+     * Undoing a merged entry is exactly equivalent to undoing its changes one by one.
+     */
+    readonly coalesce?: {
+        readonly ms: number;
+        readonly samePath?: boolean;
     };
+    /** Clock for the coalescing window (injectable for tests; default `Date.now`). */
+    readonly now?: () => number;
 };
 /**
  * Undo/redo for a copy-on-write store, built on the op-log: each tracked change is stored as
@@ -3799,7 +3827,8 @@ type StoreHistoryOptions = CreateOpLogOptions & {
  *
  * Composes with sync for collaborative undo: pass `track: syncClient` so only YOUR writes are
  * undoable, while `undo()` emits a normal op that propagates to peers (it writes through the
- * store, which the sync client picks up).
+ * store, which the sync client picks up). Coalescing groups only this stack's entries — what
+ * goes over the wire is untouched.
  */
 declare function storeHistory<T extends object>(source: WritableSignal<T>, opt?: StoreHistoryOptions): StoreHistory;