march-hare 0.7.5 → 0.9.0

package/dist/scope/index.d.ts

@@ -0,0 +1,63 @@
+import { AppContextHandle, AppResource } from '../app/types';
+import { Actions, Model, Props } from '../types/index';
+import * as React from "react";
+/**
+ * Handle returned by `app.Scope<MulticastActions>()`. Mirrors the {@link App}
+ * surface (`Boundary`, `useContext`, `useEnv`, `Resource`) but typed
+ * against a specific multicast action surface `MulticastActions` and the
+ * enclosing App's Env shape `S`.
+ *
+ * Notably absent: a nested `Scope` method. Nesting scopes is supported
+ * at the React-tree level &mdash; just render two `<scope.Boundary>`s
+ * &mdash; but each scope must come from a distinct
+ * `app.Scope<MulticastActions>()` call so that its multicast surface is
+ * declared up-front.
+ *
+ * @template S The enclosing App's Env shape.
+ * @template MulticastActions The multicast Actions class (or union of
+ *  classes) this scope's `useContext().actions.dispatch` is allowed
+ *  to fire.
+ */
+export type Scope<S extends object, MulticastActions> = {
+    /**
+     * Boundary component. Wrap a subtree to open a fresh multicast scope
+     * &mdash; every `Distribution.Multicast` action dispatched inside this
+     * subtree routes through this boundary's emitter, and every handler
+     * subscribed via `scope.useContext().useActions(...)` on that subtree
+     * receives the event.
+     *
+     * Each render of `<scope.Boundary>` opens a distinct scope instance;
+     * unmounting tears the emitter down.
+     */
+    readonly Boundary: React.FC<{
+        children: React.ReactNode;
+    }>;
+    /**
+     * Hook returning a stable `Context` handle. Identical to
+     * `app.useContext` except `actions.dispatch` accepts the multicast
+     * surface `MulticastActions` in addition to the local `AC` &mdash; mirroring
+     * the way `Actions.Broadcast = BroadcastActions` already widens the
+     * dispatch surface for broadcasts.
+     */
+    readonly useContext: <LocalModel extends Model | void = void, AC extends Actions | void = void, D extends Props = Props>() => AppContextHandle<LocalModel, MulticastActions extends Actions ? AC extends Actions ? AC & MulticastActions : MulticastActions : AC, D, S>;
+    /**
+     * Read-only Proxy over the enclosing App's Env. Identical to
+     * `app.useEnv` &mdash; the Scope does not introduce its own Env;
+     * scopes are about multicast routing, not ambient state.
+     */
+    readonly useEnv: () => Readonly<S>;
+    /**
+     * Resource factory bound to the enclosing App's Env. Identical to
+     * `app.Resource`; provided on the scope handle for convenience so a
+     * scoped feature can keep all its primitives in one place.
+     */
+    readonly Resource: AppResource<S>;
+};
+/**
+ * Internal constructor for a {@link Scope} handle. Called from inside
+ * `App<S>()` so the enclosing Env shape `S` is captured at the type
+ * level.
+ *
+ * @internal
+ */
+export declare function createScope<S extends object, MulticastActions>(): Scope<S, MulticastActions>;

package/dist/scope/types.d.ts

@@ -0,0 +1,55 @@
+import { AppContextHandle, AppResource } from '../app/types';
+import { Actions, Model, Props } from '../types/index';
+import type * as React from "react";
+/**
+ * Handle returned by `app.Scope<MulticastActions>()`. Mirrors the
+ * `App` surface (`Boundary`, `useContext`, `useEnv`, `Resource`) but
+ * typed against a specific multicast action surface `MulticastActions`
+ * and the enclosing App's Env shape `S`.
+ *
+ * Notably absent: a nested `Scope` method. Nesting scopes is supported
+ * at the React-tree level &mdash; just render two `<scope.Boundary>`s
+ * &mdash; but each scope must come from a distinct
+ * `app.Scope<MulticastActions>()` call so that its multicast surface is
+ * declared up-front.
+ *
+ * @template S The enclosing App's Env shape.
+ * @template MulticastActions The multicast Actions class (or union of
+ *  classes) this scope's `useContext().actions.dispatch` is allowed
+ *  to fire.
+ */
+export type Scope<S extends object, MulticastActions> = {
+    /**
+     * Boundary component. Wrap a subtree to open a fresh multicast scope
+     * &mdash; every `Distribution.Multicast` action dispatched inside this
+     * subtree routes through this boundary's emitter, and every handler
+     * subscribed via `scope.useContext().useActions(...)` on that subtree
+     * receives the event.
+     *
+     * Each render of `<scope.Boundary>` opens a distinct scope instance;
+     * unmounting tears the emitter down.
+     */
+    readonly Boundary: React.FC<{
+        children: React.ReactNode;
+    }>;
+    /**
+     * Hook returning a stable `Context` handle. Identical to
+     * `app.useContext` except `actions.dispatch` accepts the multicast
+     * surface `MulticastActions` in addition to the local `AC` &mdash;
+     * mirroring the way `Actions.Broadcast = BroadcastActions` already
+     * widens the dispatch surface for broadcasts.
+     */
+    readonly useContext: <LocalModel extends Model | void = void, AC extends Actions | void = void, D extends Props = Props>() => AppContextHandle<LocalModel, MulticastActions extends Actions ? AC extends Actions ? AC & MulticastActions : MulticastActions : AC, D, S>;
+    /**
+     * Read-only Proxy over the enclosing App's Env. Identical to
+     * `app.useEnv` &mdash; the Scope does not introduce its own Env;
+     * scopes are about multicast routing, not ambient state.
+     */
+    readonly useEnv: () => Readonly<S>;
+    /**
+     * Resource factory bound to the enclosing App's Env. Identical to
+     * `app.Resource`; provided on the scope handle for convenience so a
+     * scoped feature can keep all its primitives in one place.
+     */
+    readonly Resource: AppResource<S>;
+};

package/dist/types/index.d.ts

@@ -1,8 +1,40 @@
 import { Operation, Process, Inspect, Box } from 'immertation';
 import { ActionId, Task, Tasks } from '../boundary/components/tasks/types';
 import { Fault } from '../error/types';
-import { Store } from '../boundary/components/store/index';
+import { Env } from '../boundary/components/env/index';
+import { Coalesce } from '../resource/types';
 import * as React from "react";
+/**
+ * Chainable handle returned from `context.actions.resource(invocation)`.
+ *
+ * - `.exceeds(duration)` short-circuits the fetch when the per-params
+ *   cache age is within the supplied freshness window.
+ * - `.coalesce(token)` opts the call into in-flight sharing: any other
+ *   caller with the same Resource, same structural params, and equal
+ *   `token` joins the same promise.
+ *
+ * Awaiting the handle (`await context.actions.resource(...)`) triggers
+ * the fetch with whichever options have been set on the chain.
+ */
+export type ResourceCall<T> = PromiseLike<T> & {
+    /**
+     * Skip the fetch when the cached payload is within `duration`.
+     * Accepts a `Temporal.Duration`, a `DurationLike` object
+     * (`{ minutes: 5 }`), or an ISO 8601 string (`"PT5M"`).
+     */
+    readonly exceeds: (duration: Temporal.DurationLike) => ResourceCall<T>;
+    /**
+     * Join an in-flight fetch for the same `(resource, params, token)`
+     * tuple. The shared fetch runs against a detached `AbortController`
+     * so a single caller's abort never cancels work other callers are
+     * waiting on; each caller still sees its own `context.task.controller`
+     * abort as a rejection of its personal await.
+     *
+     * `token` is optional &mdash; omit it to share with every other
+     * untokened caller for the same `(resource, params)` slot.
+     */
+    readonly coalesce: (token?: Coalesce) => ResourceCall<T>;
+};
 export type { ActionId, Box, Task, Tasks };
 /**
  * Type for objects with a Brand.Action symbol property.
@@ -34,7 +66,7 @@ export type BrandedObject = {
 };
 /**
  * Recursive readonly. Locks every nested property so that read-only
- * projections on `context` (model, data, store) reject direct assignment
+ * projections on `context` (model, data, env) reject direct assignment
  * &mdash; mutation must go through `context.actions.produce(...)`.
  *
  * Function types pass through untouched so method calls (e.g.
@@ -85,13 +117,13 @@ export declare class Brand {
  */
 export declare const FaultSymbol: unique symbol;
 /**
- * Internal symbol for the global `Lifecycle.Store` broadcast. The store
+ * Internal symbol for the global `Lifecycle.Env` broadcast. The env
  * mutation path in `useActions` fires this symbol whenever a
- * `produce({ store })` call changes the slot reference.
+ * `produce({ env })` call changes the slot reference.
  *
  * @internal
  */
-export declare const StoreSymbol: unique symbol;
+export declare const EnvSymbol: unique symbol;
 /**
  * Factory functions for lifecycle actions.
  *
@@ -111,10 +143,10 @@ export declare const StoreSymbol: unique symbol;
  * }
  * ```
  *
- * `Lifecycle.Fault` and `Lifecycle.Store` are singleton broadcasts (not
+ * `Lifecycle.Fault` and `Lifecycle.Env` are singleton broadcasts (not
  * factories). All components subscribe to the same shared symbol &mdash;
- * `Fault` delivers global fault notifications, `Store` delivers per-`Boundary`
- * store-change notifications.
+ * `Fault` delivers global fault notifications, `Env` delivers per-`Boundary`
+ * env-change notifications.
  */
 export declare class Lifecycle {
     /** Creates a Mount lifecycle action. Triggered once on component mount (`useLayoutEffect`). */
@@ -146,30 +178,30 @@ export declare class Lifecycle {
      */
     static Fault: BroadcastPayload<Fault, never, "Fault">;
     /**
-     * Global store-change broadcast. Receives the latest {@link Store}
-     * snapshot whenever a `context.actions.produce(({ store }) => ...)` call
+     * Global env-change broadcast. Receives the latest {@link Env}
+     * snapshot whenever a `context.actions.produce(({ env }) => ...)` call
      * mutates the slot. Subscribe via
-     * `actions.useAction(Lifecycle.Store, handler)` &mdash; or render against
-     * it directly with `actions.stream(Lifecycle.Store, (store) => ...)`.
+     * `actions.useAction(Lifecycle.Env, handler)` &mdash; or render against
+     * it directly with `actions.stream(Lifecycle.Env, (env) => ...)`.
      *
      * Like `Lifecycle.Fault`, this is a singleton broadcast (not a factory):
      * every subscriber points at the same shared symbol. The latest value is
      * cached on the broadcast emitter so that late-mounting handlers and
-     * streams receive the current store on mount.
+     * streams receive the current env on mount.
      *
      * @example
      * ```tsx
-     * actions.useAction(Lifecycle.Store, (context, store) => {
-     *   console.log("store changed", store);
+     * actions.useAction(Lifecycle.Env, (context, env) => {
+     *   console.log("env changed", env);
      * });
      *
      * // In JSX:
-     * {actions.stream(Lifecycle.Store, (store) => (
-     *   <span>{store.locale}</span>
+     * {actions.stream(Lifecycle.Env, (env) => (
+     *   <span>{env.locale}</span>
      * ))}
      * ```
      */
-    static Store: BroadcastPayload<Store, never, "Store">;
+    static Env: BroadcastPayload<Env, never, "Env">;
 }
 /**
  * Distribution modes for actions.
@@ -179,21 +211,29 @@ export declare class Lifecycle {
  * - **Broadcast** &ndash; Action is distributed to all mounted components that have
  *   defined a handler for it. Values are cached for late-mounting components.
  * - **Multicast** &ndash; Action defines its own scope. Components reach it by
- *   wrapping a subtree in `withScope(<theMulticastAction>, Component)`.
+ *   rendering inside a `<scope.Boundary>` produced by `app.Scope<MulticastActions>()`.
  *
  * @example
  * ```ts
- * export class Scope {
- *   // The action itself acts as the scope identifier.
+ * export class MulticastActions {
  *   static Mood = Action<Mood>("Mood", Distribution.Multicast);
  * }
  *
+ * export const scope = app.Scope<typeof MulticastActions>();
+ *
  * // Wrap the subtree where the scope applies.
- * export default withScope(Scope.Mood, Component);
+ * export default function Mood() {
+ *   return (
+ *     <scope.Boundary>
+ *       <Happy />
+ *       <Sad />
+ *     </scope.Boundary>
+ *   );
+ * }
  *
  * // Dispatch / subscribe — no extra options.
- * actions.dispatch(Scope.Mood, mood);
- * actions.useAction(Scope.Mood, (context, mood) => { ... });
+ * actions.dispatch(MulticastActions.Mood, mood);
+ * actions.useAction(MulticastActions.Mood, (context, mood) => { ... });
  * ```
  */
 export declare enum Distribution {
@@ -201,7 +241,7 @@ export declare enum Distribution {
     Unicast = "unicast",
     /** Action is broadcast to all mounted components and can be consumed. */
     Broadcast = "broadcast",
-    /** Action is multicast to every component inside its `withScope` boundary. */
+    /** Action is multicast to every component inside its `<scope.Boundary>`. */
     Multicast = "multicast"
 }
 /**
@@ -237,6 +277,15 @@ export declare enum Phase {
  * @template T - The concrete primary key type (e.g., string, number)
  */
 export type Pk<T> = undefined | symbol | T;
+/**
+ * Maybe-present field type &mdash; a value that may be a concrete `T`,
+ * or `null` / `undefined` while loading, awaiting a fetch, or before
+ * upstream data has arrived. Use this for model fields whose presence
+ * is determined by async or external state.
+ *
+ * @template T - The concrete value type
+ */
+export type Maybe<T> = T | null | undefined;
 /**
  * Base constraint type for model state objects.
  * Models must be plain objects with string keys.
@@ -306,7 +355,7 @@ export type ChanneledAction<P = unknown, C = unknown, Name extends string = stri
  * to check whether a cached value exists before performing default fetches.
  *
  * This type extends `HandlerPayload<P, C>` with an additional brand to enforce at compile-time
- * that only broadcast actions can be passed to `context.actions.resolution()`.
+ * that only broadcast actions can be passed to `context.actions.final()`.
  *
  * @template P - The payload type for the action
  * @template C - The channel type for channeled dispatches (defaults to never)
@@ -316,7 +365,7 @@ export type ChanneledAction<P = unknown, C = unknown, Name extends string = stri
  * const SignedOut = Action<User>("SignedOut", Distribution.Broadcast);
  *
  * // Resolve the latest value inside a handler
- * const user = await context.actions.resolution(SignedOut);
+ * const user = await context.actions.final(SignedOut);
  * ```
  */
 export type BroadcastPayload<P = unknown, C extends Filter = never, Name extends string = string> = HandlerPayload<P, C, Name> & {
@@ -462,217 +511,25 @@ export type Result = {
 };
 export type HandlerContext<M extends Model | void, AC extends Actions | void, D extends Props = Props> = {
     readonly model: DeepReadonly<M>;
-    /**
-     * The current lifecycle phase of the component.
-     * Useful for determining if the handler was called during mount (e.g., from a cached
-     * distributed action value) vs after the component is fully mounted.
-     *
-     * @example
-     * ```ts
-     * actions.useAction(Actions.Broadcast.Counter, (context, payload) => {
-     *   if (context.phase === Phase.Mounting) {
-     *     // Called with cached value during mount
-     *     console.log("Received cached value:", payload);
-     *   }
-     * });
-     * ```
-     */
     readonly phase: Phase;
-    /**
-     * The current task for the executing action handler.
-     * Contains the AbortController, action identifier, and payload for this specific invocation.
-     *
-     * Use `task.controller.signal` to check if the action was aborted, or `task.controller.abort()` to cancel it.
-     * The `task.action` and `task.payload` properties identify which action triggered this handler.
-     *
-     * @example
-     * ```ts
-     * actions.useAction(Actions.Fetch, async (context) => {
-     *   const response = await fetch("/api", {
-     *     signal: context.task.controller.signal,
-     *   });
-     *
-     *   if (context.task.controller.signal.aborted) return;
-     *
-     *   context.actions.produce((draft) => {
-     *     draft.model.data = response;
-     *   });
-     * });
-     * ```
-     */
     readonly task: Task;
-    /**
-     * Reactive data values passed to useActions.
-     * Always returns the latest values, even after awaits in async handlers.
-     *
-     * @example
-     * ```ts
-     * const [name, setName] = useState("Adam");
-     * const actions = useActions<Model, typeof Actions>(model, () => ({ name }));
-     *
-     * actions.useAction(Actions.Fetch, async (context) => {
-     *   await fetch("/api");
-     *   // context.data.name is always the latest value
-     *   console.log(context.data.name);
-     * });
-     * ```
-     */
     readonly data: DeepReadonly<D>;
-    /**
-     * Set of all running tasks across all components in the context.
-     * Tasks are ordered by creation time (oldest first).
-     *
-     * Each task contains:
-     * - `controller`: The AbortController to cancel this task
-     * - `action`: The action identifier that triggered this task
-     * - `payload`: The payload passed when the action was dispatched
-     *
-     * @example
-     * ```ts
-     * // Abort all tasks for a specific action
-     * for (const runningTask of context.tasks) {
-     *   if (runningTask.action === Actions.Fetch) {
-     *     runningTask.controller.abort();
-     *   }
-     * }
-     *
-     * // Abort the oldest task
-     * const oldest = context.tasks.values().next().value;
-     * oldest?.controller.abort();
-     *
-     * // Abort all tasks except the current one
-     * for (const runningTask of context.tasks) {
-     *   if (runningTask !== context.task) {
-     *     runningTask.controller.abort();
-     *   }
-     * }
-     * ```
-     */
     readonly tasks: ReadonlySet<Task>;
-    /**
-     * Read-only view of the per-`<Boundary>` Store &mdash; ambient,
-     * cross-cutting state (session, locale, feature flags, etc.) typed
-     * via module augmentation on the library's `Store` interface.
-     * Identical to the value returned by `useStore()` at the hook level.
-     *
-     * Reads use plain dot notation and always reflect the latest value,
-     * even after `await` boundaries. Writes go through
-     * `context.actions.produce(({ store }) => { store.x = ... })`
-     * &mdash; the same Immer-style recipe used for the model.
-     *
-     * @example
-     * ```ts
-     * actions.useAction(Actions.SignIn, async (context, credentials) => {
-     *   const result = await context.actions.resource(signIn(credentials));
-     *   context.actions.produce(({ store }) => {
-     *     store.session = result;
-     *   });
-     * });
-     *
-     * actions.useAction(Actions.Refresh, async (context) => {
-     *   if (context.store.session === null) return;
-     *   // ...
-     * });
-     * ```
-     */
-    readonly store: DeepReadonly<Store>;
+    readonly env: DeepReadonly<Env>;
     readonly actions: {
         produce<F extends (draft: {
             model: M;
-            store: Store;
+            env: Env;
             readonly inspect: Readonly<Inspect<M>>;
         }) => void>(ƒ: F & AssertSync<F>): void;
         dispatch(action: NoPayloadActions<Dispatchable<AC>>): Promise<void>;
         dispatch<A extends WithPayloadActions<Dispatchable<AC>>>(action: A, payload: Payload<A>): Promise<void>;
         annotate<T>(value: T, operation?: Operation): T;
-        /**
-         * Fetches a {@link Resource} with the abort controller and Store
-         * snapshot auto-threaded from the current handler context. The
-         * argument is a resource invocation (`cat({ id: 5 })`) &mdash; the
-         * call primes a slot with the resource and params, and
-         * `.resource(...)` reads it. The return value is a thenable &mdash;
-         * `await` it to fire the fetch unconditionally, or use
-         * `.exceeds(duration)` to short-circuit when the per-params cache
-         * slot is still within the supplied freshness window (i.e. fetch
-         * only when the cache age *exceeds* the duration).
-         *
-         * @example
-         * ```ts
-         * actions.useAction(Actions.Mount, async (context) => {
-         *   // Always fetch.
-         *   const fresh = await context.actions.resource(user({ id: 5 }));
-         *
-         *   // Reuse cache when < 5 minutes old.
-         *   const maybe = await context.actions
-         *     .resource(user({ id: 5 }))
-         *     .exceeds({ minutes: 5 });
-         *
-         *   context.actions.produce(({ model }) => void (model.user = fresh));
-         * });
-         * ```
-         */
-        resource: (<T>(invocation: T | null) => PromiseLike<T> & {
-            readonly exceeds: (duration: Temporal.DurationLike) => Promise<T>;
-        }) & {
-            /**
-             * Writes `data` into the per-params cache slot of the resource
-             * invocation passed as the first argument, with a fresh timestamp.
-             * Use this when payloads arrive out-of-band (SSE, WebSocket,
-             * postMessage) and need to be reflected in the Resource cache
-             * without a fetcher round-trip.
-             *
-             * @example
-             * ```ts
-             * actions.useAction(Actions.Broadcast.UserSSE, (context, payload) => {
-             *   context.actions.resource.set(user({ id: payload.id }), payload);
-             * });
-             * ```
-             */
+        readonly inspect: Readonly<Inspect<M>>;
+        resource: (<T>(invocation: T | null) => ResourceCall<T>) & {
             set<T>(invocation: T | null, data: T): void;
         };
-        /**
-         * Returns the resolved broadcast or multicast value, waiting for any
-         * pending annotations to settle before resolving.
-         *
-         * If a value has already been dispatched it resolves immediately.
-         * Otherwise it waits until the next dispatch of the action.
-         * Resolves with `null` if the task is aborted before a value arrives.
-         *
-         * @param action - The broadcast or multicast action to resolve. Multicast
-         *   actions read their scope from the action declaration.
-         * @returns The dispatched value, or `null` if aborted.
-         *
-         * @example
-         * ```ts
-         * actions.useAction(Actions.FetchPosts, async (context) => {
-         *   const user = await context.actions.resolution(Actions.Broadcast.User);
-         *   if (!user) return;
-         *   const posts = await fetchPosts(user.id, {
-         *     signal: context.task.controller.signal,
-         *   });
-         *   context.actions.produce(({ model }) => { model.posts = posts; });
-         * });
-         * ```
-         */
-        resolution<T>(action: BroadcastPayload<T> | MulticastPayload<T>): Promise<T | null>;
-        /**
-         * Returns the latest broadcast or multicast value immediately without
-         * waiting for annotations to settle. Use this when you need the current
-         * cached value and do not need to wait for pending operations to complete.
-         *
-         * @param action - The broadcast or multicast action to peek at. Multicast
-         *   actions read their scope from the action declaration.
-         * @returns The cached value, or `null` if no value has been dispatched.
-         *
-         * @example
-         * ```ts
-         * actions.useAction(Actions.Check, (context) => {
-         *   const user = context.actions.peek(Actions.Broadcast.User);
-         *   if (!user) return;
-         *   console.log(user.name);
-         * });
-         * ```
-         */
+        final<T>(action: BroadcastPayload<T> | MulticastPayload<T>): Promise<T | null>;
         peek<T>(action: BroadcastPayload<T> | MulticastPayload<T>): T | null;
     };
 };
@@ -738,7 +595,7 @@ type OwnKeys<AC> = Exclude<keyof AC & string, "prototype">;
  *
  * Used to constrain `dispatch` and `useAction` so that only actions owned by
  * the component's `AC` (plus the global `Lifecycle.Fault` /
- * `Lifecycle.Store`) can be referenced.
+ * `Lifecycle.Env`) can be referenced.
  */
 export type LeafActions<AC> = AC extends void ? never : {
     [K in OwnKeys<AC>]: OwnKeys<AC[K]> extends never ? AC[K] : LeafActions<AC[K]>;
@@ -757,10 +614,10 @@ export type ChanneledOf<A> = A extends HandlerPayload<infer P, infer C> ? [C] ex
 export type Dispatchable<AC> = LeafActions<AC> | ChanneledOf<LeafActions<AC>>;
 /**
  * Everything `useAction` will subscribe to for a given `AC`: same as
- * `Dispatchable<AC>` plus the shared `Lifecycle.Fault` and `Lifecycle.Store`
+ * `Dispatchable<AC>` plus the shared `Lifecycle.Fault` and `Lifecycle.Env`
  * broadcasts which live outside `AC` but are subscribable by any component.
  */
-export type Subscribable<AC> = Dispatchable<AC> | typeof Lifecycle.Fault | typeof Lifecycle.Store;
+export type Subscribable<AC> = Dispatchable<AC> | typeof Lifecycle.Fault | typeof Lifecycle.Env;
 /**
  * Subset of a union of actions whose payload type is `never`. Used to split
  * `dispatch`/`useAction` into a no-payload and a with-payload overload so
@@ -860,7 +717,8 @@ export type UseActions<M extends Model | void, AC extends Actions | void, D exte
     dispatch<A extends WithPayloadActions<Dispatchable<AC>>>(action: A, payload: Payload<A>): Promise<void>;
     /**
      * Registers an action handler with the current scope.
-     * Types are pre-baked from the useActions call, so no type parameter is needed.
+     * Types are pre-baked from the `channel.use(...)` call, so no type
+     * parameter is needed.
      *
      * Supports two subscription patterns:
      * 1. **Plain action** - Receives ALL dispatches for that action (including channeled ones)
@@ -871,7 +729,8 @@ export type UseActions<M extends Model | void, AC extends Actions | void, D exte
      *
      * @example
      * ```ts
-     * const actions = useActions<typeof Actions>(model);
+     * const context = useContext<Model, typeof Actions>();
+     * const actions = context.useActions(model);
      *
      * // Subscribe to ALL UserUpdated events
      * actions.useAction(Actions.UserUpdated, (context, user) => {
@@ -887,3 +746,31 @@ export type UseActions<M extends Model | void, AC extends Actions | void, D exte
     useAction(action: NoPayloadActions<Subscribable<AC>>, handler: (context: HandlerContext<M, AC, D>) => void | Promise<void> | AsyncGenerator | Generator): void;
     useAction<A extends WithPayloadActions<Subscribable<AC>>>(action: A, handler: (context: HandlerContext<M, AC, D>, payload: Payload<A>) => void | Promise<void> | AsyncGenerator | Generator): void;
 };
+/**
+ * Stable, typed dispatch function for the actions class `AC`. Same call
+ * signatures as `actions.dispatch` returned by `useActions`, available
+ * before the paired `useActions` has run via {@link Context}.
+ */
+export type Dispatch<AC extends Actions | void> = {
+    (action: NoPayloadActions<Dispatchable<AC>>): Promise<void>;
+    <A extends WithPayloadActions<Dispatchable<AC>>>(action: A, payload: Payload<A>): Promise<void>;
+};
+/**
+ * Handle returned by `useContext<M, AC, D>()`. Exposes
+ * `dispatch(action, payload?)` and a `useActions` method that materialises
+ * the component-local model and reactive data against the same dispatch
+ * target. Generics are declared on `useContext`; `useActions` inherits
+ * them &mdash; the call site does not re-state `Model` / `Actions` /
+ * `Data`.
+ *
+ * Note: this `Context` type is distinct from React's `useContext` /
+ * `React.Context` &mdash; it's the March Hare action surface returned by
+ * the `useContext` hook of this library.
+ */
+export type Context<M extends Model | void, AC extends Actions | void, D extends Props = Props> = {
+    readonly actions: {
+        dispatch: Dispatch<AC>;
+    };
+    useActions(getData?: () => D): UseActions<M, AC, D>;
+    useActions(initialModel: M extends void ? never : M, getData?: () => D): UseActions<M, AC, D>;
+};

package/dist/utils/index.d.ts

@@ -3,15 +3,15 @@ export { unset } from './utils';
 export type { Stored, Unset } from './types';
 /**
  * Returns a promise that resolves after the specified number of
- * milliseconds, or rejects with an {@link AbortError} when the signal is
- * aborted. Use to inject a cancellable delay into an action handler.
+ * milliseconds, or rejects with an {@link Aborted} when the signal is aborted. Use to inject a cancellable
+ * delay into an action handler.
  *
  * @param ms How long to wait before resolving.
  * @param signal Optional {@link AbortSignal} that cancels the sleep early.
  *               Pass `context.task.controller.signal` to tie the wait to
  *               the lifetime of the current action.
  * @returns A promise that resolves after `ms` milliseconds or rejects with
- *          an {@link AbortError} if `signal` aborts first.
+ *          an {@link Aborted} if `signal` aborts first.
  */
 export declare function sleep(ms: number, signal: AbortSignal | undefined): Promise<void>;
 /**
@@ -21,12 +21,13 @@ export declare function sleep(ms: number, signal: AbortSignal | undefined): Prom
  *
  * @param ms Interval in milliseconds between invocations of `fn`.
  * @param signal Optional {@link AbortSignal} that cancels polling early.
- *               Aborts propagate as an {@link AbortError} rejection.
+ *               Aborts propagate as an {@link Aborted} rejection.
  * @param fn Predicate invoked each iteration. Return `true` to stop
  *           polling, `false` to schedule another invocation after `ms`.
  *           May be sync or async.
  * @returns A promise that resolves when `fn` returns `true`, or rejects
- *          with an {@link AbortError} if `signal` aborts first.
+ *          with a `DOMException("aborted", "Aborted")` if `signal`
+ *          aborts first.
  */
 export declare function poll(ms: number, signal: AbortSignal | undefined, fn: () => boolean | Promise<boolean>): Promise<void>;
 /**