@mmstack/primitives 22.6.0 → 22.7.0

package/package.json

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

package/types/mmstack-primitives.d.ts

@@ -2283,7 +2283,7 @@ type PointerDragState = {
     /**
      * The element the gesture started on: the `handleSelector` match when one is
      * set (so a single delegated listener can tell which child started the drag),
-     * otherwise the listener's element. `null` when idle.
+     * otherwise the pressed element itself (`event.target`). `null` when idle.
      */
     origin: HTMLElement | null;
     /**
@@ -3313,7 +3313,7 @@ declare function createHlcClock(now?: () => number): HlcClock;
 declare const OP_PROTO_VERSION = 1;
 type Key = string | number;
 /**
- * The wire/journal record (op-protocol RFC §3). `writer` is an opaque principal pseudonym —
+ * The wire/journal recor. `writer` is an opaque principal pseudonym —
  * natural identity never enters the envelope; `origin` identifies the emitting log instance.
  */
 type OpEnvelope = {
@@ -3354,7 +3354,7 @@ declare const lww: MergeFn;
 declare const mergeThree: MergeFn;
 declare const preserve: MergeFn;
 /**
- * Identity-aware array merge (op-protocol RFC §12 v0): reconciles two concurrent versions of
+ * Identity-aware array merge: reconciles two concurrent versions of
  * an array item-wise by a user-provided identity, instead of last-writer-wins on the whole
  * array. Items are matched by key; per-item fields merge via `merge3` against the ancestor
  * item; items added on either side survive; an item removed on either side and unedited on
@@ -3379,7 +3379,7 @@ type ConvergingApply = {
     reset(): void;
 };
 /**
- * The unsequenced-topology convergence core (op-protocol RFC §4): a per-path last-writer-wins
+ * The unsequenced-topology convergence core: a per-path last-writer-wins
  * register map over the total order (hlc, writer), with subtree dominance. Order-independent:
  * any arrival order of the same envelope set yields the same state.
  */
@@ -3392,7 +3392,7 @@ type RebaseResult<T = unknown> = {
     pending: StoreOp[][];
 };
 /**
- * The shared rebase routine (op-protocol RFC §5): invert pending, apply remote, re-apply
+ * The shared rebase routine: invert pending, apply remote, re-apply
  * pending through the merge policies. Pure — branching's `rebase()` and the sequenced relay
  * client both call this.
  */
@@ -3406,7 +3406,7 @@ declare function rebaseOps<T>(root: T, pending: readonly (readonly StoreOp[])[],
  */
 declare function policyStrategy<T>(policies: readonly MergePolicyEntry[]): (ancestor: T, mine: T, theirs: T) => T;
 type OpSyncOptions = {
-    /** Opaque principal pseudonym — provided by the app, never minted here (RFC §3). */
+    /** Opaque principal pseudonym — provided by the app, never minted here. */
     readonly writer: string;
     readonly origin?: string;
     readonly policyVersion?: number;
@@ -3443,6 +3443,16 @@ type OpSync<T = unknown> = {
      * top, so writes made before hydration are never silently lost.
      */
     hydrate(root: T, wm?: Record<string, number>): void;
+    /**
+     * Re-inject this origin's persisted local envelopes on boot (a durable outbox), WITHOUT minting
+     * new versions: each is applied to the store (echo-free), registered as a local winner, and handed
+     * to subscribers so a transport can resend the unacknowledged tail. `highWater` is the highest
+     * version this origin ever emitted (>= every `env.version`); the next mint continues past it, so a
+     * version acked before the reboot but dropped from a debounced outbox never collides. Call on a
+     * FRESH instance, before any `receive`/`hydrate` — restoring onto already-ingested remote winners
+     * would wrongly let a stale local op override them.
+     */
+    restore(envs: readonly OpEnvelope[], highWater?: number): void;
     destroy(): void;
 };
 declare function opSync<T extends object>(source: WritableSignal<T>, opt: OpSyncOptions): OpSync<T>;
@@ -3498,6 +3508,23 @@ type MaybePromise<T> = T | Promise<T>;
  *   del: (k) => table.delete(k),
  * };
  * ```
+ *
+ * The backend is also the seam for cross-cutting storage concerns like encryption: wrap any
+ * backend in a decorator (get/set may be async, so WebCrypto fits here — `serialize` is sync
+ * by design and is for shape, not for the storage medium). Versioning and migration still work
+ * because the version envelope is inspected on what the backend RETURNS, i.e. after decryption:
+ *
+ * ```ts
+ * const encrypted = (inner: AsyncStore, cipher: MyCipher): AsyncStore => ({
+ *   get: async (k) => {
+ *     const raw = await inner.get(k);
+ *     return raw === undefined ? undefined : cipher.decrypt(raw);
+ *   },
+ *   set: async (k, v) => inner.set(k, await cipher.encrypt(v)),
+ *   del: (k) => inner.del(k),
+ * });
+ * providePersistedStoreOptions({ store: encrypted(idbKeyval, cipher) });
+ * ```
  */
 type AsyncStore = {
     get(key: string): MaybePromise<unknown>;
@@ -3790,6 +3817,18 @@ type StoredSignal<T> = WritableSignal<T> & {
  */
 declare function stored<T>(fallback: T, { key, store: providedStore, serialize, deserialize, syncTabs, equal, onKeyChange, cleanupOldKey, validate, pause, injector: providedInjector, ...rest }: CreateStoredOptions<T>): StoredSignal<T>;
 
+/**
+ * The cross-tab transport `tabSync` rides. The default is {@link MessageBus} (a `BroadcastChannel`);
+ * pass a custom one through `tabSync`'s `bus` option to route over a different channel, or to drive
+ * tabs deterministically in a test. `subscribe` returns an unsubscribe handle plus a `post` that
+ * fans the value to every OTHER tab on the same `id`.
+ */
+type TabSyncBus = {
+    subscribe<T>(id: string, listener: (data: T) => void): {
+        unsub: () => void;
+        post: (value: T) => void;
+    };
+};
 type LegacySyncSignalOptions = {
     id?: string;
 };
@@ -3803,11 +3842,13 @@ type SyncSignalOptions = {
      * it — a cross-tab consistency gap not worth the negligible saving. The channel stays live.
      */
     injector?: Injector;
+    /** Cross-tab transport. Defaults to the injected {@link MessageBus} (a `BroadcastChannel`). */
+    bus?: TabSyncBus;
 };
 /**
  * Store mode (`tabSync(store, …)`): syncs structural OPS instead of whole values — concurrent
  * edits to different leaves merge instead of clobbering, and a joining tab hydrates from a
- * peer via the hello exchange (up-to-date / snapshot; op-protocol RFC §6).
+ * peer via the hello exchange.
  */
 type StoreTabSyncOptions = SyncSignalOptions & {
     /** Principal pseudonym on emitted envelopes. Tabs share one user, so a default is fine. */
@@ -4113,4 +4154,4 @@ type CreateHistoryOptions<T> = Omit<CreateSignalOptions<T[]>, 'equal'> & {
 declare function withHistory<T>(sourceOrValue: WritableSignal<T> | T, opt?: CreateHistoryOptions<T>): SignalWithHistory<T>;
 
 export { CONCURRENCY_INSTRUMENTATION, MmActivity, MmTransition, MmViewTransitionName, OP_PROTO_VERSION, PAUSABLE_OPTIONS, PERSISTED_STORE_OPTIONS, SuspenseBoundary, SuspenseBoundaryBase, UnscopedSuspenseBoundary, activeTransaction, applyOps, batteryStatus, bridgeScopeToPendingTasks, chunked, clipboard, combineWith, compareHlc, compareTotal, createAttributedPending, createConvergingApply, createForwardingScope, createHlcClock, createStoreContext, createTransaction, createTransitionScope, debounce, debounced, deferredValue, derived, diffOps, distinct, elementSize, elementVisibility, extendStore, filter, filterWith, focusWithin, forkStore, geolocation, getTransitionScope, holdUntilReady, idle, indexArray, injectPaused, injectRegisterResource, injectStartTransaction, injectStartTransition, injectTransitionScope, invertBatch, isConflicted, isDerivation, isLeaf, isMutable, isOpaque, isStore, keepPrevious, keyArray, keyedArray, latest, lww, map, mapArray, mapObject, mediaQuery, merge3, mergeThree, mousePosition, mutable, mutableStore, nestedEffect, networkStatus, opLog, opSync, opaque, orientation, pageVisibility, pairwise, pausableComputed, pausableEffect, pausableSignal, perfCustomTracks, persist, persistedStore, pipeable, piped, pointerDrag, policyStrategy, pooled, pooledArray, pooledMap, pooledSet, prefersDarkMode, prefersReducedMotion, preserve, projection, provideConcurrencyInstrumentation, provideForwardingTransitionScope, providePausableOptions, providePaused, providePersistedStoreOptions, provideTransitionScope, rebaseOps, reconcile, registerResource, resolvePause, scan, scrollPosition, select, sensor, sensors, signalFromEvent, startWith, store, storeHistory, stored, tabSync, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toStore, toWritable, until, use, windowSize, withHistory };
-export type { AsyncStore, BatteryStatus, ClipboardSignal, Computation, ConcurrencyInstrumentation, Conflicted, ConvergingApply, CreateChunkedOptions, CreateDebouncedOptions, CreateHistoryOptions, CreateLatestOptions, CreateOpLogOptions, CreatePooledOptions, CreateProvidedPooledOptions, CreateStoredOptions, CreateThrottledOptions, CreateTransitionScopeOptions, DebouncedSignal, DeferStrategy, DeferredSignal, DeferredValueOptions, DerivedSignal, ElementSize, ElementSizeOptions, ElementSizeSignal, ElementVisibilityOptions, ElementVisibilitySignal, ExtendStoreOptions, Fork, ForkStoreOptions, ForkStrategy, ForwardingTransitionScope, Frame, GeolocationOptions, GeolocationSignal, Hlc, HlcClock, IdleOptions, IdleSignal, LatestSignal, MergeContext, MergeFn, MergePolicyEntry, MmTransitionContext, MousePositionOptions, MousePositionSignal, MutableSignal, MutableSignalStore, NetworkStatusSignal, OpBatch, OpEnvelope, OpLog, OpLogDriver, OpSync, OpSyncOptions, Opaque, PausableOptions, PauseOption, PersistHandle, PersistOptions, PersistedStore, PersistedStoreDefaults, PersistedStoreOptions, PipeableSignal, PointerDragOptions, PointerDragSignal, PointerDragState, PointerModifiers, PointerPoint, ProjectionOptions, RebaseResult, ReconcileFn, ReconcileKey, RegisterOptions, ResourceLike, ScreenOrientation, ScreenOrientationState, ScrollPosition, ScrollPositionOptions, ScrollPositionSignal, SensorRunOptions, SignalFromEventOptions, SignalStore, SignalWithHistory, StoreHistory, StoreHistoryOptions, StoreOp, StoreOptions, StoreTabSyncOptions, StoredSignal, SuspendType, SyncSignalOptions, ThrottledSignal, Transaction, TransactionRef, TransitionRef, TransitionScope, UntilOptions, UseSource, Vivify, WindowSize, WindowSizeOptions, WindowSizeSignal, WithVivify, WritableSignalStore, toStoreOptions };
+export type { AsyncStore, BatteryStatus, ClipboardSignal, Computation, ConcurrencyInstrumentation, Conflicted, ConvergingApply, CreateChunkedOptions, CreateDebouncedOptions, CreateHistoryOptions, CreateLatestOptions, CreateOpLogOptions, CreatePooledOptions, CreateProvidedPooledOptions, CreateStoredOptions, CreateThrottledOptions, CreateTransitionScopeOptions, DebouncedSignal, DeferStrategy, DeferredSignal, DeferredValueOptions, DerivedSignal, ElementSize, ElementSizeOptions, ElementSizeSignal, ElementVisibilityOptions, ElementVisibilitySignal, ExtendStoreOptions, Fork, ForkStoreOptions, ForkStrategy, ForwardingTransitionScope, Frame, GeolocationOptions, GeolocationSignal, Hlc, HlcClock, IdleOptions, IdleSignal, LatestSignal, MergeContext, MergeFn, MergePolicyEntry, MmTransitionContext, MousePositionOptions, MousePositionSignal, MutableSignal, MutableSignalStore, NetworkStatusSignal, OpBatch, OpEnvelope, OpLog, OpLogDriver, OpSync, OpSyncOptions, Opaque, PausableOptions, PauseOption, PersistHandle, PersistOptions, PersistedStore, PersistedStoreDefaults, PersistedStoreOptions, PipeableSignal, PointerDragOptions, PointerDragSignal, PointerDragState, PointerModifiers, PointerPoint, ProjectionOptions, RebaseResult, ReconcileFn, ReconcileKey, RegisterOptions, ResourceLike, ScreenOrientation, ScreenOrientationState, ScrollPosition, ScrollPositionOptions, ScrollPositionSignal, SensorRunOptions, SignalFromEventOptions, SignalStore, SignalWithHistory, StoreHistory, StoreHistoryOptions, StoreOp, StoreOptions, StoreTabSyncOptions, StoredSignal, SuspendType, SyncSignalOptions, TabSyncBus, ThrottledSignal, Transaction, TransactionRef, TransitionRef, TransitionScope, UntilOptions, UseSource, Vivify, WindowSize, WindowSizeOptions, WindowSizeSignal, WithVivify, WritableSignalStore, toStoreOptions };