chizu 0.2.71 → 0.3.0

package/dist/types/index.d.ts

@@ -1,7 +1,5 @@
 import { Operation, Process, Inspect, Box } from 'immertation';
 import { ActionId, Task, Tasks } from '../boundary/components/tasks/types.ts';
-import { Option } from '@mobily/ts-belt/Option';
-import { Result as TsBeltResult } from '@mobily/ts-belt/Result';
 import { Regulator } from '../boundary/components/regulators/types.ts';
 import { Fault } from '../error/types.ts';
 import * as React from "react";
@@ -58,43 +56,15 @@ export declare class Brand {
     static readonly Channel: unique symbol;
     /** Node capture events used by Lifecycle.Node */
     static readonly Node: unique symbol;
-    /** Identifies cache entry identifiers created with Entry() */
-    static readonly Cache: unique symbol;
 }
 /**
- * Phantom brand symbol for value type tracking on cache entry identifiers.
- * Uses a function type `(t: T) => T` to enforce invariance, preventing
- * a cache entry declared for one type from being used with a different type.
- * @internal
- */
-declare const CacheValueBrand: unique symbol;
-/**
- * A branded cache entry identifier.
- *
- * When the second type parameter `C` is provided, the entry becomes callable
- * to produce channeled identifiers for independent cache slots per channel.
- *
- * @template T - The cached value type.
- * @template C - The channel type for channeled entries (defaults to never).
- */
-export type CacheId<T = unknown, C extends Filter = never> = {
-    readonly [Brand.Cache]: symbol;
-    readonly [CacheValueBrand]?: (t: T) => T;
-} & ([C] extends [never] ? unknown : {
-    (channel: C): ChanneledCacheId<T, C>;
-});
-/**
- * Result of calling a channeled cache entry with a channel argument.
- * Contains the entry identity and the channel data for scoped cache access.
+ * Internal symbol for the global `Lifecycle.Fault` broadcast. Exposed so the
+ * dispatch pipeline can fire faults and short-circuit the regulator policy
+ * without depending on the `Lifecycle` class at runtime.
  *
- * @template T - The cached value type.
- * @template C - The channel type.
+ * @internal
  */
-export type ChanneledCacheId<T = unknown, C = unknown> = {
-    readonly [Brand.Cache]: symbol;
-    readonly [CacheValueBrand]?: (t: T) => T;
-    readonly channel: C;
-};
+export declare const FaultSymbol: unique symbol;
 /**
  * Factory functions for lifecycle actions.
  *
@@ -116,6 +86,9 @@ export type ChanneledCacheId<T = unknown, C = unknown> = {
  * // Now regulating Lifecycle.Mount only blocks THIS component's mount:
  * context.regulator.disallow(Actions.Mount);
  * ```
+ *
+ * `Lifecycle.Fault` is a singleton broadcast (not a factory). All components
+ * subscribe to the same shared symbol to receive global fault notifications.
  */
 export declare class Lifecycle {
     /** Creates a Mount lifecycle action. Triggered once on component mount (`useLayoutEffect`). */
@@ -151,6 +124,28 @@ export declare class Lifecycle {
     static Node(): HandlerPayload<unknown, {
         Name: string;
     }>;
+    /**
+     * Global fault broadcast. Receives a `Fault` whenever any action in the
+     * `<Boundary>` errors, times out, is supplanted, or is blocked by the
+     * regulator. Subscribe via `actions.useAction(Lifecycle.Fault, handler)`.
+     *
+     * Unlike the per-component `Lifecycle.Error()` factory, `Fault` is a single
+     * shared broadcast — every subscriber points at the same symbol. The
+     * regulator policy does not apply to `Fault`; faults always reach
+     * subscribers so error visibility cannot be silenced.
+     *
+     * @example
+     * ```tsx
+     * const actions = useActions<void, typeof Actions>();
+     *
+     * actions.useAction(Lifecycle.Fault, (context, fault) => {
+     *   if (fault.reason === Reason.Errored) {
+     *     console.error(`Action "${fault.action}" failed`, fault.error);
+     *   }
+     * });
+     * ```
+     */
+    static Fault: BroadcastPayload<Fault>;
 }
 /**
  * Distribution modes for actions.
@@ -205,24 +200,6 @@ export declare enum Phase {
     /** Component has fully unmounted. */
     Unmounted = "unmounted"
 }
-/**
- * Operations for toggling boolean feature flags via `actions.feature()`.
- *
- * @example
- * ```ts
- * actions.feature("sidebar", Feature.Toggle);
- * actions.feature("sidebar", Feature.On);
- * actions.feature("sidebar", Feature.Off);
- * ```
- */
-export declare enum Feature {
-    /** Sets the feature to `true`. */
-    On = "on",
-    /** Sets the feature to `false`. */
-    Off = "off",
-    /** Inverts the current boolean value. */
-    Toggle = "toggle"
-}
 /**
  * Primary key type for identifying entities in collections.
  * Can be undefined (not yet assigned), a symbol (temporary/local), or a concrete value T.
@@ -292,8 +269,12 @@ export type ChanneledAction<P = unknown, C = unknown> = {
  * Broadcast actions are sent to all mounted components. Values are cached so that
  * late-mounting components receive the most recent payload.
  *
+ * Late-mounting components receive the most recent cached payload via their
+ * `useAction` handler during mount. Use `peek()` in a `Lifecycle.Mount` handler
+ * 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.read()`.
+ * that only broadcast actions can be passed to `context.actions.resolution()`.
  *
  * @template P - The payload type for the action
  * @template C - The channel type for channeled dispatches (defaults to never)
@@ -302,8 +283,8 @@ export type ChanneledAction<P = unknown, C = unknown> = {
  * ```ts
  * const SignedOut = Action<User>("SignedOut", Distribution.Broadcast);
  *
- * // Read the latest value inside a handler
- * const user = await context.actions.read(SignedOut);
+ * // Resolve the latest value inside a handler
+ * const user = await context.actions.resolution(SignedOut);
  * ```
  */
 export type BroadcastPayload<P = unknown, C extends Filter = never> = HandlerPayload<P, C> & {
@@ -313,20 +294,21 @@ export type BroadcastPayload<P = unknown, C extends Filter = never> = HandlerPay
  * Branded type for multicast action objects created with `Action()` and `Distribution.Multicast`.
  * Multicast actions are dispatched to all components within a named scope boundary.
  *
- * When dispatching a multicast action, you MUST provide the scope name as the third argument:
+ * When dispatching a multicast action, you MUST provide the scope carrier as the third argument:
  * ```ts
- * actions.dispatch(Actions.Multicast.Update, payload, { scope: "MyScope" });
+ * actions.dispatch(Actions.Multicast.Update, payload, { scope: Actions.Multicast });
  * ```
  *
- * Components receive multicast events only if they are descendants of a `<Scope name="...">`.
+ * Components receive multicast events only if they are descendants of a `<Scope of={...}>`.
  *
  * @template P - The payload type for the action
  * @template C - The channel type for channeled dispatches (defaults to never)
  *
  * @example
  * ```tsx
- * // Define multicast actions in a shared class
+ * // Define multicast actions and their scope together
  * class MulticastActions {
+ *   static Scope = "Counter" as const;
  *   static Update = Action<number>("Update", Distribution.Multicast);
  * }
  *
@@ -336,26 +318,47 @@ export type BroadcastPayload<P = unknown, C extends Filter = never> = HandlerPay
  * }
  *
  * // In JSX - create a named scope boundary
- * <Scope name="Counter">
+ * <Scope of={MulticastActions}>
  *   <CounterA />
  *   <CounterB />
  * </Scope>
  *
- * // Inside CounterA - dispatch to all components in "Counter" scope
- * actions.dispatch(Actions.Multicast.Update, 42, { scope: "Counter" });
+ * // Inside CounterA - dispatch to all components in the scope
+ * actions.dispatch(Actions.Multicast.Update, 42, { scope: Actions.Multicast });
  * // CounterA and CounterB both receive the event
  * ```
  */
 export type MulticastPayload<P = unknown, C extends Filter = never> = HandlerPayload<P, C> & {
     readonly [Brand.Multicast]: true;
 };
+/**
+ * A scope carrier — any object exposing a `Scope` string literal.
+ *
+ * By convention this is the feature's `MulticastActions` class, which owns
+ * the scope name alongside its multicast action declarations:
+ *
+ * ```ts
+ * export class MulticastActions {
+ *   static Scope = "my-feature" as const;
+ *   static Update = Action<T>("Update", Distribution.Multicast);
+ * }
+ * ```
+ *
+ * Requiring a carrier (rather than a bare string) prevents typos and enforces
+ * a single source of truth for each scope name.
+ *
+ * @template S - The scope name literal type.
+ */
+export type ScopeCarrier<S extends string = string> = {
+    readonly Scope: S;
+};
 /**
  * Options for multicast dispatch.
  * Required when dispatching a multicast action.
  */
 export type MulticastOptions = {
-    /** The name of the scope to multicast to. Must match a `<Scope name="...">` ancestor. */
-    scope: string;
+    /** Carrier object exposing the scope name via `.Scope`. Typically the feature's `MulticastActions` class. */
+    scope: ScopeCarrier;
 };
 /**
  * Extracts the payload type `P` from a `HandlerPayload<P>` or `ChanneledAction<P, C>`.
@@ -439,38 +442,106 @@ type AssertSync<F> = IsAsync<F> extends true ? "Error: async functions are not a
 export type Props = Record<string, unknown>;
 /**
  * Extracts the nodes type from a Model.
- * If the model has a `nodes` property, returns its type.
+ * If the model has a `meta.nodes` property, returns its type.
  * Otherwise returns an empty record.
  *
  * @example
  * ```ts
  * type Model = {
  *   count: number;
- *   nodes: { button: HTMLButtonElement | null };
+ *   meta: { nodes: { container: HTMLButtonElement | null } };
  * };
  *
- * type N = Nodes<Model>; // { button: HTMLButtonElement | null }
+ * type N = ExtractNodes<Model>; // { container: HTMLButtonElement | null }
  * ```
  */
-export type Nodes<M> = M extends {
-    nodes: infer N extends Record<string, unknown>;
+export type ExtractNodes<M> = M extends {
+    meta: {
+        nodes: infer N extends Record<string, unknown>;
+    };
 } ? N : Record<never, unknown>;
 /**
- * Extracts the `features` property from a Model type.
- * If the model has a `features` property whose values are all booleans,
+ * Transforms `meta.nodes` values to include `| null`, reflecting
+ * that node refs are initially `null` until a DOM element is captured.
+ * Models without `meta.nodes` pass through unchanged.
+ *
+ * @internal
+ */
+export type NullableNodes<M> = M extends {
+    meta: infer Meta & {
+        nodes: infer N extends Record<string, unknown>;
+    };
+} ? Omit<M, "meta"> & {
+    meta: Omit<Meta, "nodes"> & {
+        nodes: {
+            [K in keyof N]: N[K] | null;
+        };
+    };
+} : M;
+/**
+ * Extracts the `meta.features` property from a Model type.
+ * If the model has a `meta.features` property whose values are all booleans,
  * returns its type. Otherwise returns an empty record, making the
- * `feature()` method effectively uncallable.
+ * `features` methods effectively uncallable.
  *
  * @example
  * ```ts
- * enum Feature { Sidebar = 'Sidebar', Modal = 'Modal' }
- * type Model = { count: number; features: { [K in Feature]: boolean } };
- * type F = Features<Model>; // { Sidebar: boolean; Modal: boolean }
+ * type Model = { count: number; meta: { features: { sidebar: boolean; modal: boolean } } };
+ * type F = FeatureFlags<Model>; // { sidebar: boolean; modal: boolean }
  * ```
  */
 export type FeatureFlags<M> = M extends {
-    features: infer F extends Record<string, boolean>;
+    meta: {
+        features: infer F extends Record<string, boolean>;
+    };
 } ? F : Record<never, boolean>;
+/**
+ * Resolves to `unknown` when the model has no `meta.features` or all
+ * feature values are booleans. Resolves to a descriptive string literal when
+ * any value is not a boolean, causing an intersection with the model type
+ * to become `never` and producing a compile-time error.
+ *
+ * @internal
+ */
+export type ValidateFeatures<M> = M extends {
+    meta: {
+        features: infer F;
+    };
+} ? F extends Record<string, boolean> ? unknown : "meta.features values must all be boolean" : unknown;
+/**
+ * Utility type for the `meta` model property. Combines optional `nodes`
+ * and `features` sub-objects into a single meta shape.
+ *
+ * - When `N` is provided, produces `{ nodes: { [K in keyof N]: N[K] | null } }`.
+ * - When `F` is provided, produces `{ features: F }`.
+ * - Pass `void` to omit either sub-object.
+ *
+ * @template N - Node type record (e.g. `{ input: HTMLInputElement }`)
+ * @template F - Feature flags record (e.g. `{ sidebar: boolean }`)
+ *
+ * @example
+ * ```ts
+ * import type { Meta } from "chizu";
+ *
+ * type Model = {
+ *   count: number;
+ *   meta: Meta<{ input: HTMLInputElement }, { sidebar: boolean }>;
+ * };
+ * // Equivalent to:
+ * // meta: { nodes: { input: HTMLInputElement | null }; features: { sidebar: boolean } }
+ * ```
+ */
+export type Meta<N extends Record<string, unknown> | void = void, F extends Record<string, boolean> | void = void> = ([N] extends [void] ? unknown : {
+    nodes: {
+        [K in keyof N]: N[K] | null;
+    };
+}) & ([F] extends [void] ? unknown : {
+    features: F;
+});
+export declare namespace Meta {
+    type Nodes<N extends Record<string, unknown>> = Meta<N>;
+    type Features<F extends Record<string, boolean>> = Meta<void, F>;
+}
 /**
  * Constraint type for action containers.
  * Actions are symbols grouped in an object (typically a class with static properties).
@@ -573,18 +644,20 @@ export type HandlerContext<M extends Model | void, _AC extends Actions | void, D
      */
     readonly tasks: ReadonlySet<Task>;
     /**
-     * Captured DOM nodes registered via `actions.node()`.
-     * Nodes may be `null` if not yet captured or if the node was unmounted.
+     * Meta properties including captured DOM nodes and feature flags.
      *
      * @example
      * ```ts
      * actions.useAction(Actions.Focus, (context) => {
-     *   context.nodes.input?.focus();
+     *   context.meta.nodes.input?.focus();
      * });
      * ```
      */
-    readonly nodes: {
-        [K in keyof Nodes<M>]: Nodes<M>[K] | null;
+    readonly meta: {
+        readonly nodes: {
+            [K in keyof ExtractNodes<M>]: ExtractNodes<M>[K] | null;
+        };
+        readonly features: Readonly<FeatureFlags<M>>;
     };
     /**
      * The regulator API for controlling which actions may be dispatched.
@@ -608,78 +681,42 @@ export type HandlerContext<M extends Model | void, _AC extends Actions | void, D
     readonly regulator: Regulator;
     readonly actions: {
         produce<F extends (draft: {
-            model: M;
+            model: Omit<M, "meta">;
             readonly inspect: Readonly<Inspect<M>>;
         }) => void>(ƒ: F & AssertSync<F>): void;
         dispatch(action: ActionOrChanneled, payload?: unknown, options?: MulticastOptions): Promise<void>;
         annotate<T>(operation: Operation, value: T): T;
         /**
-         * Fetches a value from the cache or executes the callback if not cached / expired.
-         *
-         * The callback must return an `Option<T>` or `Result<T, E>`. Only `Some` / `Ok`
-         * values are stored; `None` / `Error` results are skipped and `{ data: null }`
-         * is returned. Exactly one layer of `Option` / `Result` is unwrapped.
-         *
-         * @param entry - The cache entry identifier (from `Entry()`).
-         * @param ttl - Time-to-live in milliseconds.
-         * @param fn - Async callback that produces the value to cache.
-         * @returns An object with `data` set to the cached or freshly-fetched value, or `null`.
-         *
-         * @example
-         * ```ts
-         * const { data } = await context.actions.cacheable(
-         *   CacheStore.Pairs,
-         *   30_000,
-         *   async () => Some(await api.fetchPairs()),
-         * );
-         * ```
-         */
-        cacheable<T>(entry: CacheId<T> | ChanneledCacheId<T>, ttl: number, fn: () => Promise<Option<T>>): Promise<{
-            data: T | null;
-        }>;
-        cacheable<T>(entry: CacheId<T> | ChanneledCacheId<T>, ttl: number, fn: () => Promise<TsBeltResult<T, unknown>>): Promise<{
-            data: T | null;
-        }>;
-        /**
-         * Removes a cached value from the store.
-         *
-         * @param entry - The cache entry identifier to invalidate.
+         * Feature toggle methods for mutating boolean flags on the model.
          *
          * @example
          * ```ts
-         * context.actions.invalidate(CacheStore.Pairs);
-         * context.actions.invalidate(CacheStore.User({ UserId: 5 }));
+         * context.actions.features.on("sidebar");
+         * context.actions.features.off("sidebar");
+         * context.actions.features.invert("sidebar");
          * ```
          */
-        invalidate(entry: CacheId<unknown> | ChanneledCacheId<unknown>): void;
-        /**
-         * Mutates a boolean feature flag on the model and triggers a re-render.
-         *
-         * Requires the model to have a `features` property whose keys are the feature names.
-         * Read feature state from `model.features` directly.
-         *
-         * @example
-         * ```ts
-         * context.actions.feature(Feature.Sidebar, Feature.Toggle);
-         * context.actions.feature(Feature.Sidebar, Feature.Off);
-         * ```
-         */
-        feature<K extends keyof FeatureFlags<M>>(name: K, operation: Feature): void;
+        features: {
+            on<K extends keyof FeatureFlags<M>>(name: K): void;
+            off<K extends keyof FeatureFlags<M>>(name: K): void;
+            invert<K extends keyof FeatureFlags<M>>(name: K): void;
+        };
         /**
-         * Reads the latest broadcast or multicast value, waiting for annotations to settle.
+         * 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 read.
-         * @param options - For multicast actions, must include `{ scope: "ScopeName" }`.
+         * @param action - The broadcast or multicast action to resolve.
+         * @param options - For multicast actions, must include `{ scope: MulticastActions }`.
          * @returns The dispatched value, or `null` if aborted.
          *
          * @example
          * ```ts
          * actions.useAction(Actions.FetchPosts, async (context) => {
-         *   const user = await context.actions.read(Actions.Broadcast.User);
+         *   const user = await context.actions.resolution(Actions.Broadcast.User);
          *   if (!user) return;
          *   const posts = await fetchPosts(user.id, {
          *     signal: context.task.controller.signal,
@@ -688,15 +725,15 @@ export type HandlerContext<M extends Model | void, _AC extends Actions | void, D
          * });
          * ```
          */
-        read<T>(action: BroadcastPayload<T>): Promise<T | null>;
-        read<T>(action: MulticastPayload<T>, options: MulticastOptions): Promise<T | null>;
+        resolution<T>(action: BroadcastPayload<T>): Promise<T | null>;
+        resolution<T>(action: MulticastPayload<T>, options: MulticastOptions): 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.
-         * @param options - For multicast actions, must include `{ scope: "ScopeName" }`.
+         * @param options - For multicast actions, must include `{ scope: MulticastActions }`.
          * @returns The cached value, or `null` if no value has been dispatched.
          *
          * @example
@@ -795,19 +832,19 @@ export type Handlers<M extends Model | void, AC extends Actions | void, D extend
     [K in OwnKeys<AC>]: OwnKeys<AC[K]> extends never ? (context: HandlerContext<M, AC, D>, ...args: [Payload<AC[K] & HandlerPayload<unknown>>] extends [never] ? [] : [payload: Payload<AC[K] & HandlerPayload<unknown>>]) => void | Promise<void> | AsyncGenerator | Generator : Handlers<M, AC[K] & Actions, D>;
 };
 export type UseActions<M extends Model | void, AC extends Actions | void, D extends Props = Props> = [
-    Readonly<M>,
+    Readonly<NullableNodes<M>>,
     {
         /**
          * Dispatches an action with an optional payload.
          *
-         * For multicast actions, you MUST provide the scope as the third argument:
+         * For multicast actions, you MUST provide the scope carrier as the third argument:
          * ```ts
-         * actions.dispatch(Actions.Multicast.Update, payload, { scope: "MyScope" });
+         * actions.dispatch(Actions.Multicast.Update, payload, { scope: Actions.Multicast });
          * ```
          *
          * @param action - The action to dispatch
          * @param payload - The payload to send with the action
-         * @param options - For multicast actions, must include `{ scope: "ScopeName" }`
+         * @param options - For multicast actions, must include `{ scope: MulticastActions }`
          */
         dispatch<P>(action: HandlerPayload<P>, payload?: P, options?: MulticastOptions): Promise<void>;
         dispatch<P>(action: BroadcastPayload<P>, payload?: P, options?: MulticastOptions): Promise<void>;
@@ -815,39 +852,32 @@ export type UseActions<M extends Model | void, AC extends Actions | void, D exte
         dispatch<P, C extends Filter>(action: ChanneledAction<P, C>, payload?: P, options?: MulticastOptions): Promise<void>;
         inspect: Inspect<M>;
         /**
-         * Captured DOM nodes registered via `node()`.
-         * Nodes may be `null` if not yet captured or if the node was unmounted.
+         * Meta properties including captured DOM nodes and feature flags.
          *
          * @example
          * ```tsx
-         * type Model = {
-         *   count: number;
-         *   nodes: { input: HTMLInputElement };
-         * };
-         * const [model, actions] = useActions<Model, typeof Actions>(model);
-         *
-         * // Access captured nodes
-         * actions.nodes.input?.focus();
+         * actions.meta.nodes.input?.focus();
+         * actions.meta.features.sidebar; // boolean
          * ```
          */
-        nodes: {
-            [K in keyof Nodes<M>]: Nodes<M>[K] | null;
+        meta: {
+            readonly nodes: {
+                [K in keyof ExtractNodes<M>]: ExtractNodes<M>[K] | null;
+            };
+            readonly features: Readonly<FeatureFlags<M>>;
         };
         /**
-         * Captures a DOM node for later access via `nodes` or `context.nodes`.
-         * Use as a ref callback on JSX nodes.
+         * Captures a DOM node for later access via `meta.nodes`.
+         * Use as a ref callback on JSX elements.
          *
-         * @param name - The node key (must match a key in Model['nodes'])
+         * @param name - The node key (must match a key in the model's `meta.nodes`)
          * @param node - The DOM node or null (when unmounting)
          *
          * @example
          * ```tsx
          * type Model = {
          *   count: number;
-         *   nodes: {
-         *     container: HTMLDivElement;
-         *     input: HTMLInputElement;
-         *   };
+         *   meta: Meta<{ container: HTMLDivElement; input: HTMLInputElement }>;
          * };
          *
          * const [model, actions] = useActions<Model, typeof Actions>(model);
@@ -859,20 +889,23 @@ export type UseActions<M extends Model | void, AC extends Actions | void, D exte
          * );
          * ```
          */
-        node<K extends keyof Nodes<M>>(name: K, node: Nodes<M>[K] | null): void;
+        node<K extends keyof ExtractNodes<M>>(name: K, node: ExtractNodes<M>[K] | null): void;
         /**
-         * Mutates a boolean feature flag on the model and triggers a re-render.
-         *
-         * Read feature state from `model.features` directly.
+         * Feature toggle methods for mutating boolean flags on the model.
          *
          * @example
          * ```tsx
-         * actions.feature(Feature.Sidebar, Feature.Toggle);
+         * actions.features.on("sidebar");
+         * actions.features.invert("sidebar");
          *
-         * {model.features.Sidebar && <Sidebar />}
+         * {model.meta.features.sidebar && <Sidebar />}
          * ```
          */
-        feature<K extends keyof FeatureFlags<M>>(name: K, operation: Feature): void;
+        features: {
+            on<K extends keyof FeatureFlags<M>>(name: K): void;
+            off<K extends keyof FeatureFlags<M>>(name: K): void;
+            invert<K extends keyof FeatureFlags<M>>(name: K): void;
+        };
         /**
          * Streams broadcast values declaratively in JSX using a render-prop pattern.
          *
@@ -925,4 +958,22 @@ export type UseActions<M extends Model | void, AC extends Actions | void, D exte
      * ```
      */
     useAction<A extends ActionId | HandlerPayload | ChanneledAction>(action: A, handler: (context: HandlerContext<M, AC, D>, ...args: [Payload<A>] extends [never] ? [] : [payload: Payload<A>]) => void | Promise<void> | AsyncGenerator | Generator): void;
+    /**
+     * Connects a {@link Resource} declared at module scope to this component.
+     * Returns a thunk that fetches fresh data on every call &ndash; concurrent
+     * calls share the in-flight promise. The Resource's `onSuccess` and
+     * `onError` callbacks receive `(response, data, dispatch)` where `data`
+     * is this component's reactive `data` proxy.
+     *
+     * @example
+     * ```ts
+     * const fetchUser = actions.useResource(resources.user);
+     *
+     * actions.useAction(Actions.Mount, async (context) => {
+     *   const data = await fetchUser();
+     *   context.actions.produce(({ model }) => { model.user = data; });
+     * });
+     * ```
+     */
+    useResource<T, E, Args extends readonly unknown[]>(resource: import('../resource/index.ts').ResourceHandle<T, E, Args>): (...args: Args) => Promise<T>;
 };

package/dist/utils/index.d.ts

@@ -1,21 +1,4 @@
 import { Pk } from '../types/index.ts';
-/**
- * Configuration constants for Chizu action symbols.
- */
-export declare const config: {
-    /** Prefix for all Chizu action symbols. */
-    actionPrefix: string;
-    /** Prefix for broadcast action symbols. */
-    broadcastActionPrefix: string;
-    /** Prefix for multicast action symbols. */
-    multicastActionPrefix: string;
-    /** Prefix for channeled action symbols. */
-    channelPrefix: string;
-    /** Prefix for cache operation symbols. */
-    cachePrefix: string;
-    /** Prefix for lifecycle action symbols. */
-    lifecyclePrefix: string;
-};
 /**
  * Returns a promise that resolves after the specified number of milliseconds.
  * The sleep will reject with an AbortError when the signal is aborted,

package/dist/utils.d.ts

@@ -1,3 +1,29 @@
+/**
+ * Internal symbol description factories. Each function returns a namespaced
+ * string suitable for `Symbol()` descriptions or `startsWith` checks.
+ *
+ * @internal
+ */
+export declare const describe: {
+    /** Unicast action description. `describe.action("Fetch")` → `"chizu.action/Fetch"` */
+    action: (name?: string) => string;
+    /** Broadcast action description. `describe.broadcast("User")` → `"chizu.action/broadcast/User"` */
+    broadcast: (name?: string) => string;
+    /** Multicast action description. `describe.multicast("Update")` → `"chizu.action/multicast/Update"` */
+    multicast: (name?: string) => string;
+    /** Channeled action description. `describe.channel("user")` → `"chizu.channel/user"` */
+    channel: (name?: string) => string;
+    /** Cache entry description. `describe.cache("users")` → `"chizu.cache/users"` */
+    cache: (name?: string) => string;
+    /** Lifecycle action description. `describe.lifecycle("Mount")` → `"chizu.action.lifecycle/Mount"` */
+    lifecycle: (name?: string) => string;
+    /** Mount replay sentinel description. Used to create the {@link replay} symbol. */
+    replay: (name?: string) => string;
+};
+/**
+ * Flat record used for shallow property comparison in {@link changes}.
+ * @internal
+ */
 type Changes = Record<string, unknown>;
 /**
  * Get high-level changed paths between two objects.