@mmstack/primitives 22.2.1 → 22.3.0

package/README.md

@@ -19,7 +19,7 @@ npm install @mmstack/primitives
 - [Timing & propagation](#timing--propagation) — `debounced`, `throttled`, `until`
 - [Reactive collections](#reactive-collections) — `indexArray`, `keyArray`, `mapObject`
 - [Effects](#effects) — `nestedEffect`
-- [Concurrency & transitions](#concurrency--transitions) — `keepPrevious`, keep-alive (`MmActivity`), `pausable*`, Suspense (`mm-suspense`), `startTransition` / `startTransaction`, `holdUntilReady`
+- [Concurrency & transitions](#concurrency--transitions) — `keepPrevious`, keep-alive (`MmActivity`), `pausable*` / `providePausableOptions`, Suspense (`mm-suspense`), `startTransition` / `startTransaction`, `holdUntilReady`
 - [History & persistence](#history--persistence) — `withHistory`, `stored`, `tabSync`
 - [Performance helpers](#performance-helpers) — `chunked`, `pooled` / `pooledArray` / `pooledMap` / `pooledSet`
 - [Sensors](#sensors) — `sensor()` facade + browser-state signals
@@ -117,14 +117,18 @@ 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.
 
-### `extend` (scoped overlay)
+**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.
 
-`store.extend(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.
+### `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.
 
 ```typescript
+import { extendStore, store } from '@mmstack/primitives';
+
 const app = store({ user: { name: 'Alice' }, theme: 'dark' });
 
-const scope = app.extend({ draft: '' }); // inherits user + theme, adds a local draft
+const scope = extendStore(app, { draft: '' }); // inherits user + theme, adds a local draft
 
 scope.user === app.user; // true — the same signal (shared, two-way)
 scope.user.name.set('Bob'); // writes through to the parent
@@ -132,19 +136,19 @@ scope.draft.set('hello'); // local only — `app` never gains `draft`
 scope(); // { user: { name: 'Bob' }, theme: 'dark', draft: 'hello' }
 ```
 
-Resolution per key is **local → parent → local**: a seed key (or one set on the scope before it exists on the parent) is local and _shadows_ the parent — and keeps shadowing even if the parent later grows that key; a key that exists only on the parent writes through to it; a brand-new key lands locally. `scope()` is the merged view (local shadowing), and `Object.keys(scope)` / `key in scope` are the union of both layers. `extend` composes — `a.extend(x).extend(y)` chains parents.
+Resolution per key is **local → parent → local**: a seed key (or one set on the scope before it exists on the parent) is local and _shadows_ the parent — and keeps shadowing even if the parent later grows that key; a key that exists only on the parent writes through to it; a brand-new key lands locally. `scope()` is the merged view (local shadowing), and `Object.keys(scope)` / `key in scope` are the union of both layers. It composes — `extendStore(extendStore(app, x), y)` chains parents.
 
 The seed may also be a **signal** of the matching kind, so an existing (externally-owned, reactive) signal becomes the local layer:
 
 ```typescript
 const draft = signal({ title: '' });
-const scope = app.extend(draft); // writes to scope.title flow out to `draft`, and back in
+const scope = extendStore(app, draft); // writes to scope.title flow out to `draft`, and back in
 ```
 
 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 — `app.extend(store(seed, { vivify: 'auto' }))`.
-- Reserved names — `extend`, `asReadonlyStore`, and the signal methods (`set` / `update` / `mutate` / `inline` / `asReadonly`) — shadow same-named data keys, as on any store.
+- 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.
 
 ### `forkStore`
@@ -165,13 +169,13 @@ base.user.name(); // 'Bob'
 // draft.discard();    // …or throw the edits away
 ```
 
-The fork is a full store (`draft.store.user.name(...)`, `extend`, deep reads/writes — everything `store` gives you). It's built on `linkedSignal`: it holds local writes until the **base changes underneath it**, then runs a `strategy` to reconcile:
+The fork is a full store (`draft.store.user.name(...)`, `extendStore`, deep reads/writes — everything `store` gives you). It's built on `linkedSignal`: it holds local writes until the **base changes underneath it**, then runs a `strategy` to reconcile:
 
 - **`'fine'`** (default for immutable stores) — per-path 3-way merge: keep the paths the fork edited, take the base's live values for the paths it didn't. Survives concurrent base changes. Relies on copy-on-write reference identity, so it's **unsupported on a mutable base** (in-place mutation defeats it — `fork` warns and falls back to `'coarse'`).
 - **`'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`
 
@@ -365,6 +369,19 @@ pausableEffect(() => poll(url())); // body skipped while paused; deps collapse s
 
 While paused each one **collapses its dependency set to just the pause predicate**, so an upstream change can't trigger work; on resume it re-tracks and re-runs / recomputes with the latest values. SSR never pauses.
 
+#### `providePausableOptions`
+
+Sets an app-wide default pause source for every pausable-aware primitive — the `pausable*` family above plus the opt-in integrations (`stored`, `chunked`). A call-site `pause` always wins; this only fills in when the call didn't specify one. Use it to make everything honour the ambient `*mmActivity` boundary from one place:
+
+```typescript
+import { providePausableOptions } from '@mmstack/primitives';
+
+// e.g. in app.config.ts
+providers: [providePausableOptions({ pause: true })];
+```
+
+With this provided, `stored(...)` / `chunked(...)` (off by default) start reading the ambient paused context; pass `pause: false` at an individual call site to opt that one back out.
+
 ### Suspense — `<mm-suspense>` and the transition scope
 
 A **transition scope** is a per-boundary registry of resources whose async state a boundary coordinates. `<mm-suspense>` provides its own scope, so resources created in its subtree register into it automatically (via `@mmstack/resource`'s `register` option, or `registerResource(ref)` for a hand-rolled `ResourceRef`):
@@ -631,6 +648,7 @@ const mouse = sensor('mousePosition', {
 | `windowSize`        | `windowSize()`               | `Signal<{ width, height }>` + `.unthrottled`           | Throttled to 100ms by default.                                             |
 | `scrollPosition`    | `scrollPosition()`           | `Signal<{ x, y }>` + `.unthrottled`                    | Window or element scroll, throttled 100ms.                                 |
 | `mousePosition`     | `mousePosition()`            | `Signal<{ x, y }>` + `.unthrottled`                    | Throttled 100ms. `coordinateSpace: 'client' \| 'page'`, optional `touch`.  |
+| `pointerDrag`       | `pointerDrag()`              | `Signal<PointerDragState>` + `.unthrottled` + `.cancel()` | Pointer gesture (down→move→up) with `activationThreshold`, `delta`, modifiers, pointer capture, Escape-cancel. |
 | `elementVisibility` | `elementVisibility(target?)` | `Signal<IntersectionObserverEntry?>` + `.visible`      | IntersectionObserver-based, `.visible` is a boolean shorthand.             |
 | `elementSize`       | `elementSize(target?)`       | `Signal<{ width, height }?>`                           | ResizeObserver-based. Defaults to `border-box`.                            |
 | `geolocation`       | `geolocation(opt?)`          | `Signal<GeolocationPosition?>` + `.error` + `.loading` | One-shot by default; pass `watch: true` for `watchPosition`.               |
@@ -640,7 +658,37 @@ const mouse = sensor('mousePosition', {
 | `idle`              | `idle({ ms })`               | `Signal<boolean>` + `.since`                           | Flips to `true` after `ms` of inactivity. Configurable activity events.    |
 | `focusWithin`       | `focusWithin(target?)`       | `Signal<boolean>`                                      | Mirrors the `:focus-within` CSS pseudo-class.                              |
 
-Element-targeting sensors (`elementSize`, `elementVisibility`, `focusWithin`) default `target` to `inject(ElementRef)` so they're drop-in inside a component.
+Element-targeting sensors (`elementSize`, `elementVisibility`, `focusWithin`, `pointerDrag`) default `target` to `inject(ElementRef)` so they're drop-in inside a component.
+
+### `pointerDrag`
+
+Tracks a pointer **gesture** (pointerdown → capture → move → up) as a signal — the
+foundation for pointer-based move/resize/marquee on a canvas. Unlike native HTML5
+drag, pointer events fire continuously and coordinates stay reliable; `delta` is
+computed on the same update as `current` (never torn). `active` only flips true
+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.
+
+```typescript
+import { sensor } from '@mmstack/primitives';
+
+const drag = sensor('pointerDrag', { activationThreshold: 4 });
+
+// derive position from the gesture — no effects
+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().origin → the handle · drag.cancel() → revert
+```
 
 ### `signalFromEvent`