@mmstack/primitives 22.2.2 → 22.4.0

package/README.md

@@ -117,6 +117,12 @@ Each level's shape is resolved from what's known: a value that is currently an o
 
 Top-level array support isn't exposed yet — use `indexArray` / `keyArray` for those.
 
+**Union leaves (perf opt-in).** `noUnionLeaves: true` promises no node ever flips between a leaf and a sub-store, so each node's leaf-ness is resolved once on first access and cached instead of staying reactive. Off by default — leave it off if a value can switch between a primitive and an object/array.
+
+**Unions are fully supported by default.** A node may flip between array ↔ record ↔ primitive ↔ `null` freely: routing (`keys`/iteration/prototype) follows the live kind, and a child signal you grabbed **before** a flip stays correct after it — reads resolve against the new shape (`undefined` through a `null` parent, no throw) and writes copy by the container's live shape, so writing through a pre-flip child never turns an array into a plain object.
+
+> Reserved keys: `set`, `update`, `mutate`, `inline`, `asReadonly` (and `extend`, until its removal next minor) resolve to the signal's own methods, so record keys with those names aren't reachable as child stores — read them off the value (`s().set`) instead.
+
 ### `extendStore` (scoped overlay)
 
 `extendStore(store, seed)` (on any store kind) creates a **scoped overlay** — a child store that **shares** the parent's signals for inherited keys (the same `WritableSignal`: writes go through to the parent and parent changes flow down) while keeping the seed and any new keys in a **local layer** that never propagates upward. No diffing, no syncing — local keys simply aren't wired to the parent.
@@ -145,7 +151,7 @@ const scope = extendStore(app, draft); // writes to scope.title flow out to `dra
 
 A few release notes:
 
-- The local layer is a plain store (vivify off). Inherited paths vivify when the _parent_ was created with `vivify`; to autovivify local keys, seed with a vivify-enabled store — `extendStore(app, store(seed, { vivify: 'auto' }))`.
+- The scope inherits the parent's config (`vivify` / `noUnionLeaves`) and its injector-scoped proxy cache, so **both** inherited and local paths vivify when the parent was created with `vivify`. `extendStore` doesn't accept `vivify` / `noUnionLeaves` — they always come from the parent.
 - Reserved names — `asReadonlyStore` and the signal methods (`set` / `update` / `mutate` / `inline` / `asReadonly`) — shadow same-named data keys, as on any store.
 - `scope.asReadonlyStore()` returns a read-only **snapshot view** of the merge (reactive reads, no writes); it does not share sub-store identity.
 
@@ -173,7 +179,7 @@ The fork is a full store (`draft.store.user.name(...)`, `extendStore`, deep read
 - **`'coarse'`** — any base change resets the whole fork. Cheapest; correct when the base is held for the fork's lifetime (e.g. a transition). The default for a mutable base.
 - **a `ReconcileFn<T>`** — `(ancestor, mine, theirs) => merged`, for bring-your-own merge (array-by-id, Immer patches, CRDT-ish).
 
-> Pass the same `vivify` / `noUnionLeaves` the base was created with — fork config isn't inherited (it's closed over inside the base), so mismatched config gives the fork different write semantics.
+> The fork inherits the base's `vivify` / `noUnionLeaves` and its injector-scoped proxy cache automatically, so its write semantics match the base. Pass them explicitly only to override (advanced).
 
 ### `toWritable`
 
@@ -459,6 +465,15 @@ const t = startTransaction(() => applyBulkEdit()); // live state updates; the di
 await t.done; // committed, display revealed in one frame
 ```
 
+Every exit settles: a throwing body rolls back, and if the calling context is **destroyed
+mid-flight** the hold is released (writes kept) and `done` resolves — a transaction can never
+leave a surviving ancestor scope frozen.
+
+Attribution is **per transaction**: a load already in flight when it starts is not adopted —
+it can neither commit the transaction early nor block its settle. (The same applies to
+`startTransition`.) A pre-existing flight re-triggered by the transaction's own writes counts
+once it restarts.
+
 ### `holdUntilReady`
 
 The **structural** counterpart to `keepPrevious`: where that holds a _value_ through a reload, this holds a _structure_ through a swap. Given a `target` signal and a `ready` predicate, it keeps yielding the previous value until `ready()` is true, then swaps to the current target. Mount the incoming structure off to the side so its resources can settle and flip `ready`, keep showing the held one meanwhile, and let the old one go once `ready` releases the swap. (`@mmstack/router-core`'s `<mm-transition-outlet>` is this pattern applied to routes.)
@@ -668,6 +683,18 @@ once the pointer travels past `activationThreshold`, so the same element stays
 clickable. Uses `setPointerCapture`, supports a delegated `handleSelector`, and
 cancels on Escape or via `.cancel()`.
 
+A delegated `handleSelector` reports which child actually started the drag via
+`drag().origin` (so one listener on a container can serve many handles), and
+`stopPropagation: true` lets an inner sensor claim the `pointerdown` over an
+outer one on the same tree (e.g. a nested sortable). Reads are throttled
+(`throttle`, default 16ms); `drag.unthrottled()` exposes the un-throttled view
+for logic that needs the exact release position.
+
+The idle state carries the **end reason**: `cancelled` is `true` when the gesture
+was aborted (Escape, `pointercancel`, `.cancel()`) rather than released, and stays
+set until the next `pointerdown` — so a drag consumer can tell "drop here" from
+"abort" (`@mmstack/dnd` uses this to cancel instead of committing).
+
 ```typescript
 import { sensor } from '@mmstack/primitives';
 
@@ -678,7 +705,7 @@ const position = computed(() => {
   const d = drag();
   return d.active ? { x: base.x + d.delta.x, y: base.y + d.delta.y } : base;
 });
-// drag().modifiers.shift → e.g. constrain axis · drag.cancel() → revert
+// drag().modifiers.shift → e.g. constrain axis · drag().origin → the handle · drag.cancel() → revert
 ```
 
 ### `signalFromEvent`