@studiometa/js-toolkit 4.0.0-alpha.0 → 4.0.0-alpha.2

package/skills/studiometa-js-toolkit/references/api/scheduler/viewTransition.md

@@ -0,0 +1,53 @@
+# viewTransition
+
+```ts
+viewTransition(update: () => void | Promise<void>): Promise<void>
+```
+
+Runs a DOM update inside a native view transition, with a progressive-enhancement contract: where the platform has no `startViewTransition`, the update simply runs.
+
+## Usage
+
+```ts
+import { viewTransition } from '@studiometa/js-toolkit';
+
+async function replace(el: Element, html: string) {
+  await viewTransition(() => {
+    el.innerHTML = html;
+  });
+}
+```
+
+## Batching
+
+**Updates queued in the same flush batch into one `startViewTransition()` call**, so a backdrop and a panel animate as one transition rather than two fighting each other.
+
+Each later batch is appended to **one promise tail**, so several flushes during one running transition stay serialized instead of interleaving.
+
+The scheduler flushes the pending `write` tasks **before the snapshot**, so a pending write is part of the "before" state rather than landing mid-transition. Writes scheduled _inside_ the update callback run within the transition.
+
+## It is standalone
+
+`Base` has no view-transition method and no import of one. The helper is a free function, and the whole view-transition graph stays out of the `Base` module graph — a page that never calls it never downloads it.
+
+## Composing it
+
+It is a `DomUpdateRunner`, so an ancestor can claim a [negotiated update](../dom/domUpdate.md) with it:
+
+```js
+this.$on(EVENTS.dom.update, ({ detail }) => detail.wrap(viewTransition));
+```
+
+and it is a `SwapWrap`, so a [`swap()`](../dom/swap.md) can play as one transition:
+
+```js
+await swap(el, html, { wrap: (mutate) => viewTransition(mutate) });
+```
+
+Neither is the default. **The ancestor chooses the lane, because it knows whether the region animates.**
+
+## `exit`, `layout` and `layoutId`
+
+They are not an animation engine's job. Native view transitions solve them, which is why this is in core while `tween` and `animate` are not shipped at all.
+
+`@studiometa/ui` keeps a declarative `ViewTransition` component, rebuilt on this helper.

package/skills/studiometa-js-toolkit/references/api/services/createService.md

@@ -0,0 +1,95 @@
+# createService
+
+```ts
+createService<T, R = void>(definition: ServiceDefinition<T>): Service<T, R>
+```
+
+The primitive every built-in service is built on.
+
+## The definition
+
+```ts
+interface ServiceDefinition<T> {
+  props: () => T;
+  hasProps?: () => boolean;
+  start: (emit: (props: T) => void) => Unsubscribe;
+}
+```
+
+| Field      | Does                                                                                |
+| ---------- | ----------------------------------------------------------------------------------- |
+| `props`    | reads the current props                                                             |
+| `hasProps` | says whether there **is** a current value, which is what `{ immediate: true }` asks |
+| `start`    | starts the source on the first subscriber, and returns its teardown                 |
+
+## Usage
+
+```ts
+import { createService } from '@studiometa/js-toolkit';
+
+interface OnlineProps {
+  readonly isOnline: boolean;
+}
+
+const useOnline = createService<OnlineProps>({
+  props: () => ({ isOnline: navigator.onLine }),
+  start(emit) {
+    const publish = () => emit({ isOnline: navigator.onLine });
+    window.addEventListener('online', publish);
+    window.addEventListener('offline', publish);
+    return () => {
+      window.removeEventListener('online', publish);
+      window.removeEventListener('offline', publish);
+    };
+  },
+});
+```
+
+## What you get for free
+
+- **Lazy and reference-counted.** `start` runs on the first subscriber and its teardown on the last. With no subscriber there is no listener, no observer and no frame.
+- **Symmetric subscriptions.** `subscribe(callback)` returns the unsubscribe function. A subscription is a **record**, not a key in a set, so two holders of one function are two subscribers.
+- **A safe fan-out.** The fan-out walks a snapshot and each record carries an `isActive` flag, so a subscriber that unsubscribes during a delivery is not called.
+- **Error isolation.** A subscriber that throws is skipped and reported as `callback.service-failed`.
+
+Publishing is **re-entrant**, so any code that changes state after a publication must check first that the service is still alive.
+
+## `hasProps`
+
+Omit it and the service is assumed to have a current value. Declare it when it does not:
+
+```ts
+import { createService } from '@studiometa/js-toolkit';
+
+interface BatchProps {
+  readonly records: readonly unknown[];
+}
+let current: readonly unknown[] = [];
+createService<BatchProps>({
+  props: () => ({ records: current }),
+  hasProps: () => current.length > 0, // nothing to deliver between batches
+  start: (emit) => () => {},
+});
+```
+
+This is what makes `{ immediate: true }` honest: the frame tick has no current value between two frames, the pointer has none before it is seen, a drag has none outside a gesture, and a mutation service has none between batches.
+
+## What a callback may return
+
+`R` is a type parameter, so a service can require its callbacks to return something. `useRaf()` uses it to enforce `RafRender`:
+
+```ts
+type RafService = Service<RafProps, void | RafRender>;
+```
+
+## Scoping it to a target
+
+Wrap it in [`perTarget()`](perTarget.md) to get one instance per target and per options, keyed in a `WeakMap` — the caching every built-in service has.
+
+## Making a mixin over it
+
+See [`createServiceMixin()`](createServiceMixin.md).
+
+**A consumer's service is owned by the consumer**
+
+The shared runtime coordinates the **built-in** service caches across duplicate copies of the package. A `createService()` or `perTarget()` call of a consumer stays owned by that consumer.

package/skills/studiometa-js-toolkit/references/api/services/createServiceMixin.md

@@ -0,0 +1,81 @@
+# createServiceMixin
+
+```ts
+createServiceMixin<Instance, Target, Options extends object = object>(
+  definition: ServiceMixinDefinition<Target, Options>,
+): ServiceMixin<Instance, Target, Options>
+```
+
+Builds the mixin-and-decorator pair over a service. Every built-in `with*` is one of these.
+
+## The definition
+
+```ts
+interface ServiceMixinDefinition<Target, Options> {
+  hook: string;
+  target: (instance: Base) => Target;
+  defaultImmediate?: boolean;
+  use: (target: Target, options: Options) => Service<unknown, unknown>;
+  handleResult?: (instance: Base, result: unknown) => void;
+}
+```
+
+| Field              | Does                                                                      |
+| ------------------ | ------------------------------------------------------------------------- |
+| `hook`             | the one method name the service owns                                      |
+| `target`           | the default target resolver                                               |
+| `defaultImmediate` | whether the first delivery is asked for unless the caller says otherwise  |
+| `use`              | calls the service factory                                                 |
+| `handleResult`     | does something with what the hook returned — `withRaf` schedules a render |
+
+## Usage
+
+```ts
+import { createService, createServiceMixin, perTarget } from '@studiometa/js-toolkit';
+
+interface FocusProps {
+  readonly hasFocus: boolean;
+}
+const useFocus = perTarget((target: Element) =>
+  createService<FocusProps>({
+    props: () => ({ hasFocus: target.contains(document.activeElement) }),
+    start: () => () => {},
+  }),
+);
+interface FocusHook {
+  focused?(props: FocusProps): void;
+}
+
+export const withFocus = createServiceMixin<FocusHook, Element>({
+  hook: 'focused',
+  target: (instance) => instance.$el,
+  use: (target) => useFocus(target),
+});
+```
+
+```js
+class Field extends withFocus(Base) {
+  focused({ hasFocus }) {}
+}
+```
+
+## `use` receives the service's options only
+
+`target`, `manual` and `immediate` are removed before `use` is called and they are absent from its `Options` type — which is why `use: (target, options) => useDrag(target, options)` is correct and needs no filtering.
+
+## Override `$mount()`, not `mounted()`
+
+`createServiceMixin()` overrides `$mount()` and `$unmount()`, which is what lets a component write its own `mounted()` without `super.mounted()` and still subscribe.
+
+**The rule is about what a mixin overrides, not who wrote it.** A userland mixin that puts its work in `mounted()` needs its subclasses to call `super.mounted()`. The way not to need that is to override `$mount()` — or to use this function, which already does.
+
+## What it gives the class
+
+- the hook, bound for each mount cycle;
+- `$services.<hook>` as a [`Toggle`](toggle.md), typed through `ServiceHandles<'<hook>'>`;
+- the two call forms, mixin and class decorator;
+- the `service.missing-target` check on a caller-supplied resolver.
+
+## One hook per class
+
+A mixin names one hook and binds one subscription per cycle. That is its limit, and a component with a dynamic set of subscriptions calls `subscribe()` itself. See [Mixins](mixins.md).

package/skills/studiometa-js-toolkit/references/api/services/index.md

@@ -0,0 +1,94 @@
+# Services
+
+A service is a shared source of props that components subscribe to. Every one of them is **lazy and reference-counted**.
+
+## The sources
+
+| Service                                                           | Hook             | Target                             |
+| ----------------------------------------------------------------- | ---------------- | ---------------------------------- |
+| [`useRaf()`](useRaf.md)                                       | `ticked`         | —                                  |
+| [`useScroll(target?)`](useScroll.md)                          | `scrolled`       | an element or the window           |
+| [`useWindowScroll()`](useWindowScroll.md)                     | `scrolled`       | the named default                  |
+| [`useScrollProgress(target, options?)`](useScrollProgress.md) | `scrolledInView` | an element                         |
+| [`useResize(target?)`](useResize.md)                          | `resized`        | an element                         |
+| [`useWindowSize()`](useWindowSize.md)                         | `resized`        | the named default                  |
+| [`usePointer(target?)`](usePointer.md)                        | `moved`          | an element, or the viewport        |
+| [`useDrag(target, options?)`](useDrag.md)                     | `dragged`        | an `HTMLElement` or `SVGElement`   |
+| [`useKey(target?)`](useKey.md)                                | `keyed`          | the document, an element or window |
+| [`useInView(target, init?)`](useInView.md)                    | `intersected`    | an element                         |
+| [`useMutation(target, init?)`](useMutation.md)                | `mutated`        | any node                           |
+| [`useBreakpoint()`](useBreakpoint.md)                         | —                | —                                  |
+| [`useMediaQuery(query)`](useMediaQuery.md)                    | —                | —                                  |
+| [`usePrefersReducedMotion()`](usePrefersReducedMotion.md)     | —                | the named case                     |
+
+`LoadService` is not ported.
+
+## The mixins
+
+[`withRaf`, `withScroll`, `withResize`, `withScrollProgress`, `withPointer`, `withDrag`, `withInView`, `withMutation` and `withKey`](mixins.md) bind one subscription per mount cycle under the one method name the service owns.
+
+## The combinators
+
+- [`toggle(subscribe)`](toggle.md) — a subscription you can switch on and off
+- [`until(service, predicate)`](until.md) — a one-shot wait
+
+## Writing your own
+
+- [`createService(definition)`](createService.md) — the primitive
+- [`perTarget(create, keyOf?)`](perTarget.md) — one instance per target and per options
+- [`createServiceMixin(definition)`](createServiceMixin.md) — the mixin over it
+
+## The service surface
+
+```ts
+interface Service<T, R = void> {
+  subscribe(callback: (props: T) => R, options?: { immediate?: boolean }): () => void;
+  props(): T;
+}
+```
+
+`subscribe()` returns the unsubscribe function. **Lazy and reference-counted**: the source starts on the first subscriber and stops on the last, so with no subscriber there is no listener, no observer and no frame.
+
+**Every prop field is `readonly`, and the props object belongs to its service.** It is valid for the duration of the call that received it — use `{ ...props }` to keep one.
+
+## Asking for the first delivery
+
+```js
+useScroll().subscribe(callback, { immediate: true });
+```
+
+The sources that have a current value honour it. The ones that do not, do nothing, and each service states which it is through `hasProps()`:
+
+| Has a current value between deliveries                   | Does not                                                                                  |
+| -------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| scroll, resize, breakpoint, media query, scroll progress | the frame tick, the pointer before it is seen, a drag outside a gesture, a mutation batch |
+
+Only the new subscriber is called, and the first props of a run carry no movement.
+
+## One instance per target and per options
+
+Keyed in a `WeakMap` by [`perTarget()`](perTarget.md). **The options are read by meaning, not by spelling**: object keys are sorted at every depth and the keys holding `undefined` are dropped, while arrays keep their order.
+
+```js
+// The same service.
+useInView(el, { threshold: 0.5, rootMargin: '0px' });
+useInView(el, { rootMargin: '0px', threshold: 0.5 });
+```
+
+Only what the platform owns needs a key of its own: `useInView()` gives its root a weak id, and `useMutation()` keeps a canonical init for the DOM contract. **Nothing groups observers across targets.**
+
+## Props are flat
+
+**One field per axis, and nothing derivable is a field.** `lastX` is `x - deltaX`; `changedX` is `deltaX !== 0`. The grouped objects of v3 — `last`, `delta`, `max`, `progress`, `direction`, `changed` — are removed.
+
+`directionX` and `directionY` are `-1 | 0 | 1`: one signed value that multiplies.
+
+## No service owns a loop
+
+The raf service and an active drag inertia subscribe to `scheduler.tick()`. The scroll service coalesces its events into one `read` per frame. The resize service is a `ResizeObserver`. See [The scheduler](../../guide/going-further/scheduling-work.md).
+
+## Failures
+
+A subscriber that throws is skipped and reported as `callback.service-failed`. Core dispatches the diagnostic first and calls `reportError()` only when no listener cancelled the event.
+
+Publishing is **re-entrant**, so any code that changes state after a publication checks first that the service is still alive.

package/skills/studiometa-js-toolkit/references/api/services/mixins.md

@@ -0,0 +1,148 @@
+# Service mixins
+
+A mixin binds one subscription per mount cycle, under the **one method name the service owns**.
+
+| Mixin                | Hook             | Service                                           |
+| -------------------- | ---------------- | ------------------------------------------------- |
+| `withRaf`            | `ticked`         | [`useRaf()`](useRaf.md)                       |
+| `withScroll`         | `scrolled`       | [`useScroll()`](useScroll.md)                 |
+| `withResize`         | `resized`        | [`useResize()`](useResize.md)                 |
+| `withPointer`        | `moved`          | [`usePointer()`](usePointer.md)               |
+| `withDrag`           | `dragged`        | [`useDrag()`](useDrag.md)                     |
+| `withKey`            | `keyed`          | [`useKey()`](useKey.md)                       |
+| `withInView`         | `intersected`    | [`useInView()`](useInView.md)                 |
+| `withMutation`       | `mutated`        | [`useMutation()`](useMutation.md)             |
+| `withScrollProgress` | `scrolledInView` | [`useScrollProgress()`](useScrollProgress.md) |
+
+## Two call forms
+
+```ts
+withScroll(BaseClass, options?)   // a mixin
+withScroll(options?)              // a class decorator
+```
+
+```js
+import { Base, withScroll } from '@studiometa/js-toolkit';
+
+class Header extends withScroll(Base) {
+  static config = { name: 'Header' };
+
+  scrolled({ y, directionY }) {
+    this.$el.classList.toggle('is-hidden', directionY > 0 && y > 100);
+  }
+}
+```
+
+```ts
+import { Base, component, withScroll } from '@studiometa/js-toolkit';
+
+@component({ name: 'Header' })
+@withScroll()
+class Header extends Base {
+  scrolled() {}
+}
+```
+
+**The mixin is the primitive**, because it needs no build step. The decorator is sugar over it.
+
+## Stacking
+
+```js
+import { Base, withRaf, withResize } from '@studiometa/js-toolkit';
+
+class Parallax extends withRaf(withResize(Base)) {
+  static config = { name: 'Parallax' };
+
+  resized({ height }) {}
+
+  ticked({ delta }) {}
+}
+```
+
+`$services` keys accumulate through the intersection, so `$services.ticked` and `$services.resized` both complete.
+
+## Options
+
+```ts
+interface ServiceMixinOptions<Target, Host = Base> {
+  target?: (instance: Host) => Target;
+  manual?: boolean;
+  immediate?: boolean;
+}
+```
+
+**The options of a mixin are not the options of the service.** `target`, `manual` and `immediate` describe the subscription; they are removed before the `use*()` call and they are absent from its options type. A service's own options go in the same object and are forwarded:
+
+```js
+withDrag(Base, { axis: 'x', inertia: false, immediate: true, manual: true });
+```
+
+### `target`
+
+```js
+withScroll(Base, { target: (instance) => instance.$refs.scroller });
+```
+
+A resolver that comes back with `undefined` or `null` reports `service.missing-target` and starts **no** subscription — because a renamed ref arrives here as nothing, and a service with a default target would otherwise observe the wrong thing and look like it worked.
+
+A service whose **own** default target is nothing, like `withRaf`, is untouched: that is its contract, and only a caller's resolver can be wrong about it.
+
+**The resolver is typed against the host as declared**
+
+A mixin is applied while the extends clause of its class is still being evaluated, so `withDrag(Base, …)` types its resolver against `Base`. A component reaching further names the shape it needs — `(instance as Base & { readonly target: HTMLElement }).target` — which is an assertion rather than a check. v3 wrote the same line as an `@ts-expect-error`. That is why core checks the result at runtime.
+
+### `manual`
+
+Declares the hook without running it, and `$services.<hook>` becomes the switch:
+
+```js
+import { Base, withRaf } from '@studiometa/js-toolkit';
+
+class SliderItem extends withRaf(Base, { manual: true }) {
+  static config = { name: 'SliderItem' };
+
+  ticked({ delta }) {}
+
+  onSelected() {
+    this.$services.ticked.start();
+  }
+
+  onSettled() {
+    this.$services.ticked.stop();
+  }
+}
+```
+
+Each handle is a [`Toggle`](toggle.md): `start()` is idempotent and `stop()` is safe to repeat.
+
+### `immediate`
+
+Asks for the first delivery at subscribe time. `withInView` defaults it to `true`.
+
+## It never occupies a lifecycle hook
+
+`mounted()` and `unmounted()` belong to the component author, so **nothing has to be chained**. A class that mixes a service in and writes its own `mounted()` without `super.mounted()` still subscribes: the framework's own `$mount()`/`$unmount()` pair carries the subscription.
+
+- The subscription starts **once the whole of `mounted()` has run** — including an `immediate` first delivery, which therefore reaches a component that is fully set up.
+- It is released **before `unmounted()`**, exactly where the mount cleanup used to release it.
+- `$unmount()` releases unconditionally, so a manual subscription started outside a mount cycle is released too.
+
+**A userland mixin still chains**
+
+The rule is about what the mixin **overrides**, not who wrote it. A mixin that puts its work in `mounted()` needs its subclasses to call `super.mounted()` — and the way not to need that is to override `$mount()`. See [`createServiceMixin()`](createServiceMixin.md).
+
+## One hook per class, and that is the limit
+
+A mixin binds one subscription, under one name, for each mount cycle. There is **no `hook` option**.
+
+A component whose subscriptions are **one per markup declaration** — one per attribute, with its own modifiers and its own threshold, known only when the element is read — has no method to name and no fixed count. It subscribes itself:
+
+```js
+mounted() {
+  return useScroll(this.$refs.panel).subscribe((props) => {});
+}
+```
+
+`on<Event>` has the same shape: a handler name belongs to the class, while a set of events can be data. Both sugars are keyed on a name a class declares, and both leave the same escape open — bind it yourself, own the cleanup.
+
+Neither limit is about a build step: `withRaf(Base)` is an ordinary call, and the name is fixed by how the class is written.

package/skills/studiometa-js-toolkit/references/api/services/perTarget.md

@@ -0,0 +1,65 @@
+# perTarget
+
+```ts
+perTarget<Target extends WeakKey, Args extends unknown[], T, R = void>(
+  create: (target: Target, ...args: Args) => Service<T, R>,
+  keyOf?: (...args: Args) => string,
+): (target: Target, ...args: Args) => Service<T, R>
+```
+
+Gives a service factory the **one instance per target and per options** caching every built-in service has.
+
+## Usage
+
+```ts
+import { createService, perTarget } from '@studiometa/js-toolkit';
+
+interface FocusProps {
+  readonly hasFocus: boolean;
+}
+
+const useFocus = perTarget((target: Element) =>
+  createService<FocusProps>({
+    props: () => ({ hasFocus: target.contains(document.activeElement) }),
+    start(emit) {
+      const publish = () => emit({ hasFocus: target.contains(document.activeElement) });
+      document.addEventListener('focusin', publish);
+      document.addEventListener('focusout', publish);
+      return () => {
+        document.removeEventListener('focusin', publish);
+        document.removeEventListener('focusout', publish);
+      };
+    },
+  }),
+);
+
+// The same service, twice.
+useFocus(document.body);
+useFocus(document.body);
+```
+
+## The key is read by meaning, not by spelling
+
+`perTarget()` **sorts object keys at every depth and drops the keys holding `undefined`**. Arrays keep their order.
+
+```js
+// One service.
+useInView(el, { threshold: 0.5, rootMargin: '0px' });
+useInView(el, { rootMargin: '0px', threshold: 0.5 });
+useInView(el, { threshold: 0.5, rootMargin: '0px', root: undefined });
+```
+
+That is deliberate: two callers who mean the same thing should share a source, and an options object written in a different order means the same thing.
+
+## When you need a `keyOf`
+
+Only what the **platform** owns:
+
+- `useInView()` gives an object root a stable weak identity, because an element cannot be serialized into a key.
+- `useMutation()` keeps a canonical init, because the DOM's own rules about which fields imply which are not a plain sort.
+
+Everything else is covered by the default.
+
+## The target is a `WeakKey`
+
+The cache is a `WeakMap`, so a target that is collected takes its entry with it. Nothing has to be cleaned up, and **nothing groups observers across targets**.

package/skills/studiometa-js-toolkit/references/api/services/toggle.md

@@ -0,0 +1,80 @@
+# toggle
+
+```ts
+toggle(subscribe: () => Unsubscribe): Toggle
+```
+
+Turns anything that returns its own unsubscribe function into a switch.
+
+```ts
+interface Toggle {
+  readonly isActive: boolean;
+  start: () => void;
+  stop: () => void;
+}
+```
+
+`start` and `stop` are **bound**, so each is a callback as it is.
+
+## Usage
+
+```js
+import { Base, toggle, useRaf } from '@studiometa/js-toolkit';
+
+class SliderItem extends Base {
+  static config = { name: 'SliderItem' };
+
+  #frame = toggle(() => useRaf().subscribe(({ delta }) => this.follow(delta)));
+
+  mounted() {
+    // `stop` is bound, so it is a cleanup as it is.
+    return this.#frame.stop;
+  }
+
+  follow(delta) {}
+
+  onIndexChange() {
+    this.#frame.start();
+  }
+
+  onSettled() {
+    this.#frame.stop();
+  }
+}
+```
+
+`start()` is idempotent and `stop()` is safe to repeat.
+
+## What it works on
+
+Anything whose subscribe call returns a release:
+
+```js
+import { signal, toggle, useScroll } from '@studiometa/js-toolkit';
+
+const count = signal(0);
+const el = document.body;
+
+// a service
+toggle(() => useScroll().subscribe(() => {}));
+
+// a signal
+toggle(() => count.subscribe(() => {}));
+
+// a bare listener
+toggle(() => {
+  const handler = () => {};
+  el.addEventListener('click', handler);
+  return () => el.removeEventListener('click', handler);
+});
+```
+
+It knows nothing about `Base`, so it works outside a component too.
+
+## Why it exists
+
+The scheduler has no permanent rAF loop: it requests the next frame while a tick subscriber stays. So **a component that needs the loop for part of a cycle should not hold a subscription for the whole cycle** — and hand-rolling "unsubscribe if subscribed, and remember which" at every call site is the bug this removes.
+
+`{ manual: true }` on a service mixin gives you the same object under `$services.<hook>`. See [Mixins](mixins.md#manual).
+
+`smoothTo()` is a `toggle()` over `useRaf()`: one subscription however many times the target is set, started when the value has somewhere to go, released when it arrives.

package/skills/studiometa-js-toolkit/references/api/services/until.md

@@ -0,0 +1,44 @@
+# until
+
+```ts
+until<T>(service: Service<T>, predicate: (props: T) => boolean): Promise<T>
+```
+
+A one-shot wait on a service.
+
+## Usage
+
+```ts
+import { until, useScroll } from '@studiometa/js-toolkit';
+
+async function afterScroll() {
+  const props = await until(useScroll(), ({ isScrolling }) => !isScrolling);
+  return props.y;
+}
+```
+
+**Parameters**
+
+- `service` — a `Service<T>`, and nothing else.
+- `predicate` — called with each update.
+
+**Return value**
+
+- a promise resolving with **a copy of the props** on the first update that matches.
+
+## The contract
+
+- It **releases the subscription before it resolves**, so an awaiting caller never holds a source open.
+- It resolves with a copy, because the props object belongs to its service and is only valid for the duration of the call that received it.
+- **It resolves on the current props when they already match**, through the service's `hasProps()` — so `await until(useScroll(), ({ isScrolling }) => !isScrolling)` on a still page returns immediately rather than waiting for a scroll that never comes.
+
+## When to reach for it
+
+When the code reads as a step in a sequence rather than a reaction:
+
+```js
+await until(useScroll(), ({ isScrolling }) => !isScrolling);
+this.measure();
+```
+
+For a reaction, subscribe. For an ongoing condition, subscribe and act on each delivery.