march-hare 0.12.1 → 0.13.1

package/dist/types/index.d.ts

@@ -1,9 +1,9 @@
 import { Operation, Process, Inspect, Box } from 'immertation';
-import { ActionId, Task, Tasks } from '../boundary/components/tasks/types';
-import { Fault } from '../error/types';
-import { Env } from '../boundary/components/env/index';
-import { Coalesce } from '../resource/types';
-import { WithHandle } from '../with/index';
+import { ActionId, Task, Tasks } from '../boundary/components/tasks/types.js';
+import { Fault } from '../error/types.js';
+import { Env } from '../boundary/components/env/types.js';
+import { Coalesce, Invocation } from '../resource/types.js';
+import { WithHandle } from '../with/types.js';
 import * as React from "react";
 /**
  * Chainable handle returned from `context.actions.resource(invocation)`.
@@ -17,13 +17,21 @@ import * as React from "react";
  * 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> & {
+/**
+ * Fetch-configured chain returned from `.exceeds(...)` and
+ * `.coalesce(...)`. Awaiting the chain runs the fetch with whichever
+ * options are set; `.evict()` is intentionally absent because the
+ * "configured a fetch then evicted instead" sequence has no coherent
+ * meaning &mdash; eviction is always available off the bare
+ * `context.actions.resource(...)` call.
+ */
+export type ResourceFetch<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>;
+    readonly exceeds: (duration: Temporal.DurationLike) => ResourceFetch<T>;
     /**
      * Join an in-flight fetch for the same `(resource, params, token)`
      * tuple. The shared fetch runs against a detached `AbortController`
@@ -34,7 +42,43 @@ export type ResourceCall<T> = PromiseLike<T> & {
      * `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>;
+    readonly coalesce: (token?: Coalesce) => ResourceFetch<T>;
+};
+/**
+ * Chainable handle returned from `context.actions.resource(invocation)`.
+ * Either resolve to the fetched value (`.exceeds`/`.coalesce` + await)
+ * or drop the cache slot (`.evict`) &mdash; the two paths are mutually
+ * exclusive, so once `.exceeds` or `.coalesce` runs the chain narrows
+ * to {@link ResourceFetch} and `.evict` is no longer available.
+ */
+export type ResourceCall<T> = ResourceFetch<T> & {
+    /**
+     * Drop cache entries for the primed resource without fetching. With
+     * no argument, uses the params from the originating call as the
+     * pattern. With an argument, evicts every stored entry whose params
+     * satisfy the pattern's keys (partial match &mdash; extra keys in
+     * the stored params are ignored).
+     *
+     * Strictly synchronous &mdash; the Adapter contract is sync, so the
+     * warm-start `Map` and the user adapter both settle in the current
+     * tick. Async backends fire-and-forget their underlying delete from
+     * inside the adapter body; the call site doesn't `await` anything.
+     *
+     * The `where` pattern is typed as `Record<string, unknown>` rather
+     * than `Partial<P>` because the resource's params type `P` isn't
+     * threaded through the chain. Pass the literal you'd pass to the
+     * underlying fetcher &mdash; TypeScript won't catch typos in pattern
+     * keys, so prefer the no-argument form when possible.
+     *
+     * ```ts
+     * // Drop the {id: 5} slot.
+     * context.actions.resource(resource.user({ id: 5 })).evict();
+     *
+     * // Drop every user slot whose stored params include name "Adam".
+     * context.actions.resource(resource.user()).evict({ name: "Adam" });
+     * ```
+     */
+    readonly evict: (where?: Record<string, unknown>) => void;
 };
 export type { ActionId, Box, Task, Tasks };
 /**
@@ -108,6 +152,18 @@ export declare class Brand {
      * symbols imported from a class outside `AC`.
      */
     static readonly Name: unique symbol;
+    /**
+     * Phantom brand identifying lifecycle actions returned by
+     * `Lifecycle.Mount()`, `Lifecycle.Unmount()`, `Lifecycle.Error()`, and
+     * `Lifecycle.Update()`. Carries the lifecycle's literal kind so that
+     * `useAction` can pick distinct overloads &mdash; in particular,
+     * `Lifecycle.Update` resolves its payload to `Partial<DeepReadonly<D>>`
+     * against the surrounding `useActions` data generic instead of the
+     * factory-level `Record<string, unknown>` placeholder. Without this
+     * brand a user-defined `Action<P>("Update")` would collide with the
+     * lifecycle overload.
+     */
+    static readonly Lifecycle: unique symbol;
 }
 /**
  * Internal symbol for the global `Lifecycle.Fault` broadcast. Exposed so the
@@ -151,13 +207,18 @@ export declare const EnvSymbol: unique symbol;
  */
 export declare class Lifecycle {
     /** Creates a Mount lifecycle action. Triggered once on component mount (`useLayoutEffect`). */
-    static Mount(): HandlerPayload<never, never, "Mount">;
+    static Mount(): LifecyclePayload<never, never, "Mount">;
     /** Creates an Unmount lifecycle action. Triggered when the component unmounts. */
-    static Unmount(): HandlerPayload<never, never, "Unmount">;
+    static Unmount(): LifecyclePayload<never, never, "Unmount">;
     /** Creates an Error lifecycle action. Triggered when an action throws. Receives `Fault` as payload. */
-    static Error(): HandlerPayload<Fault, never, "Error">;
-    /** Creates an Update lifecycle action. Triggered when `context.data` changes (not on initial mount). */
-    static Update(): HandlerPayload<Record<string, unknown>, never, "Update">;
+    static Error(): LifecyclePayload<Fault, never, "Error">;
+    /**
+     * Creates an Update lifecycle action. Triggered when `context.data` changes
+     * (not on initial mount). The handler payload is typed as
+     * `Partial<DeepReadonly<D>>` at the subscription site &mdash; only the keys
+     * whose values changed between the previous and current render are present.
+     */
+    static Update(): LifecyclePayload<Record<string, unknown>, never, "Update">;
     /**
      * Global fault broadcast. Receives a `Fault` whenever any action in the
      * `<Boundary>` errors, times out, or is supplanted. Subscribe via
@@ -324,6 +385,25 @@ export type HandlerPayload<P = unknown, C extends Filter = never, Name extends s
 } & ([C] extends [never] ? unknown : {
     (channel: C): ChanneledAction<P, C, Name>;
 });
+/**
+ * Branded type returned by `Lifecycle.Mount`, `Lifecycle.Unmount`,
+ * `Lifecycle.Error`, and `Lifecycle.Update`. Structurally identical to a
+ * `HandlerPayload` but carries a phantom `Brand.Lifecycle` brand whose value
+ * is the lifecycle's literal kind. The brand is what lets `useAction` and
+ * `Handlers` resolve `Lifecycle.Update`'s payload to `Partial<DeepReadonly<D>>`
+ * (against the surrounding `useActions` data generic) instead of the
+ * factory-level `Record<string, unknown>` placeholder &mdash; a user-defined
+ * `Action<P>("Update")` would have `Name = "Update"` but no `Brand.Lifecycle`,
+ * so it falls into the generic payload overload as expected.
+ *
+ * @template P Payload type for the lifecycle.
+ * @template C Channel filter (always `never` for lifecycles &mdash; they are
+ *   not channeled).
+ * @template Name Literal name (`"Mount"`, `"Unmount"`, `"Error"`, `"Update"`).
+ */
+export type LifecyclePayload<P = unknown, C extends Filter = never, Name extends string = string> = HandlerPayload<P, C, Name> & {
+    readonly [Brand.Lifecycle]: Name;
+};
 /**
  * Result of calling an action with a channel argument.
  * Contains the action reference and the channel data for filtered dispatch.
@@ -513,25 +593,25 @@ export type Actions = object;
 export type Result = {
     processes: Set<Process>;
 };
-export type HandlerContext<M extends Model | void, AC extends Actions | void, D extends Props = Props, S extends Env = Env> = {
+export type HandlerContext<M extends Model | void, AC extends Actions | void, D extends Props = Props, E extends Env = Env> = {
     readonly model: DeepReadonly<M>;
     readonly phase: Phase;
     readonly task: Task;
     readonly data: DeepReadonly<D>;
     readonly tasks: ReadonlySet<Task>;
-    readonly env: Readonly<S>;
+    readonly env: Readonly<E>;
     readonly actions: {
         produce<F extends (draft: {
             model: M;
-            env: S;
+            env: E;
             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;
         readonly inspect: Readonly<Inspect<M>>;
-        resource: (<T>(invocation: T | null) => ResourceCall<T>) & {
-            set<T>(invocation: T | null, data: T): void;
+        resource: (<T, P extends object>(invocation: Invocation<T, P>) => ResourceCall<T>) & {
+            nuke(where?: Record<string, unknown>): void;
         };
         final<T>(action: BroadcastPayload<T> | MulticastPayload<T>): Promise<T | null>;
         peek<T>(action: BroadcastPayload<T> | MulticastPayload<T>): T | null;
@@ -582,7 +662,7 @@ export type HandlerContext<M extends Model | void, AC extends Actions | void, D
  *
  * @see {@link Handlers} for the recommended HKT pattern
  */
-export type Handler<M extends Model | void, AC extends Actions | void, K extends keyof AC & string, D extends Props = Props, S extends Env = Env> = (context: HandlerContext<M, AC, D, S>, ...args: [Payload<AC[K] & HandlerPayload<unknown>>] extends [never] ? [] : [payload: Payload<AC[K] & HandlerPayload<unknown>>]) => void | Promise<void> | AsyncGenerator | Generator;
+export type Handler<M extends Model | void, AC extends Actions | void, K extends keyof AC & string, D extends Props = Props, E extends Env = Env> = (context: HandlerContext<M, AC, D, E>, ...args: [Payload<AC[K] & HandlerPayload<unknown>>] extends [never] ? [] : [payload: Payload<AC[K] & HandlerPayload<unknown>>]) => void | Promise<void> | AsyncGenerator | Generator;
 /**
  * String keys of `AC` excluding inherited `prototype` from class constructors.
  * When action containers are classes (`typeof MyActions`), TypeScript includes
@@ -674,10 +754,12 @@ export type WithPayloadActions<U> = Exclude<U, {
  * export const handlePaymentSent: H["Broadcast"]["PaymentSent"] = (context) => { ... };
  * ```
  */
-export type Handlers<M extends Model | void, AC extends Actions | void, D extends Props = Props, RootAC extends Actions | void = AC, S extends Env = Env> = {
-    [K in OwnKeys<AC>]: OwnKeys<AC[K]> extends never ? (context: HandlerContext<M, RootAC, D, S>, ...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, RootAC, S>;
+export type Handlers<M extends Model | void, AC extends Actions | void, D extends Props = Props, RootAC extends Actions | void = AC, E extends Env = Env> = {
+    [K in OwnKeys<AC>]: OwnKeys<AC[K]> extends never ? AC[K] extends {
+        readonly [Brand.Lifecycle]: "Update";
+    } ? (context: HandlerContext<M, RootAC, D, E>, changes: Partial<DeepReadonly<D>>) => void | Promise<void> | AsyncGenerator | Generator : (context: HandlerContext<M, RootAC, D, E>, ...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, RootAC, E>;
 };
-export type UseActions<M extends Model | void, AC extends Actions | void, D extends Props = Props, S extends Env = Env> = [
+export type UseActions<M extends Model | void, AC extends Actions | void, D extends Props = Props, E extends Env = Env> = [
     Readonly<M>,
     {
         /**
@@ -710,7 +792,7 @@ export type UseActions<M extends Model | void, AC extends Actions | void, D exte
          * );
          * ```
          */
-        stream(action: typeof Lifecycle.Env, renderer: (value: Readonly<S>, inspect: Inspect<S>) => React.ReactNode): React.ReactNode;
+        stream(action: typeof Lifecycle.Env, renderer: (value: Readonly<E>, inspect: Inspect<E>) => React.ReactNode): React.ReactNode;
         stream<T extends object>(action: BroadcastPayload<T>, renderer: (value: T, inspect: Inspect<T>) => React.ReactNode): React.ReactNode;
     },
     DeepReadonly<D>
@@ -751,9 +833,12 @@ export type UseActions<M extends Model | void, AC extends Actions | void, D exte
      * });
      * ```
      */
-    useAction(action: NoPayloadActions<Subscribable<AC>>, handler: (context: HandlerContext<M, AC, D, S>) => void | Promise<void> | AsyncGenerator | Generator): void;
-    useAction(action: typeof Lifecycle.Env, handler: (context: HandlerContext<M, AC, D, S>, env: Readonly<S>) => void | Promise<void> | AsyncGenerator | Generator): void;
-    useAction<A extends WithPayloadActions<Subscribable<AC>>>(action: A, handler: (context: HandlerContext<M, AC, D, S>, payload: Payload<A>) => void | Promise<void> | AsyncGenerator | Generator): void;
+    useAction(action: NoPayloadActions<Subscribable<AC>>, handler: (context: HandlerContext<M, AC, D, E>) => void | Promise<void> | AsyncGenerator | Generator): void;
+    useAction(action: typeof Lifecycle.Env, handler: (context: HandlerContext<M, AC, D, E>, env: Readonly<E>) => void | Promise<void> | AsyncGenerator | Generator): void;
+    useAction<A extends Extract<Subscribable<AC>, {
+        readonly [Brand.Lifecycle]: "Update";
+    }>>(action: A, handler: (context: HandlerContext<M, AC, D, E>, changes: Partial<DeepReadonly<D>>) => void | Promise<void> | AsyncGenerator | Generator): void;
+    useAction<A extends WithPayloadActions<Subscribable<AC>>>(action: A, handler: (context: HandlerContext<M, AC, D, E>, payload: Payload<A>) => void | Promise<void> | AsyncGenerator | Generator): void;
 };
 /**
  * Stable, typed dispatch function for the actions class `AC`. Same call
@@ -776,7 +861,7 @@ export type Dispatch<AC extends Actions | void> = {
  * `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, S extends Env = Env> = {
+export type Context<M extends Model | void, AC extends Actions | void, D extends Props = Props, E extends Env = Env> = {
     readonly actions: {
         dispatch: Dispatch<AC>;
     };
@@ -786,6 +871,6 @@ export type Context<M extends Model | void, AC extends Actions | void, D extends
      * autocomplete from the model. See {@link WithHandle}.
      */
     readonly with: WithHandle<M>;
-    useActions(getData?: () => D): UseActions<M, AC, D, S>;
-    useActions(model: M extends void ? never : M, getData?: () => D): UseActions<M, AC, D, S>;
+    useActions(getData?: () => D): UseActions<M, AC, D, E>;
+    useActions(model: M extends void ? never : M, getData?: () => D): UseActions<M, AC, D, E>;
 };

package/dist/utils/index.d.ts

@@ -1,6 +1,6 @@
-import { Pk } from '../types/index';
-export { unset } from './utils';
-export type { Stored, Unset } from './types';
+import { Pk } from '../types/index.js';
+export { unset } from './utils.js';
+export type { Stored, Unset } from './types.js';
 /**
  * Returns a promise that resolves after the specified number of
  * milliseconds, or rejects with an {@link Aborted} when the signal is aborted. Use to inject a cancellable

package/dist/utils/types.d.ts

@@ -1,4 +1,4 @@
-import { unset } from './utils';
+import { unset } from './utils.js';
 /** Nominal type of the {@link unset} sentinel. */
 export type Unset = typeof unset;
 /**
@@ -13,6 +13,4 @@ export type Stored<T> = {
     readonly data: T | Unset;
     /** When the payload was recorded, or `null` when nothing is recorded. */
     readonly at: Temporal.Instant | null;
-    /** Returns {@link data} when present, otherwise the supplied fallback. */
-    readonly else: <U>(fallback: U) => T | U;
 };

package/dist/utils/utils.d.ts

@@ -1,4 +1,4 @@
-import { Stored } from './types';
+import { Stored } from './types.js';
 /**
  * Sentinel symbol marking "no value present yet". Shared by the Resource
  * cache and by storage handles so callers can distinguish "nothing has been
@@ -19,7 +19,6 @@ export declare function useRerender(): () => void;
  *
  * @template T The payload type the resulting Stored would carry if populated.
  * @returns A Stored with `data` set to {@link unset} and `at` set to `null`.
- *          Its `.else(fallback)` returns the fallback unchanged.
  * @internal
  */
 export declare function empty<T>(): Stored<T>;
@@ -30,7 +29,6 @@ export declare function empty<T>(): Stored<T>;
  * @param data The payload value to wrap.
  * @param at The instant the payload was recorded — flows through to the
  *           Resource cache as the entry's `at` timestamp.
- * @returns A Stored whose `.else(fallback)` returns `data` unchanged.
  * @internal
  */
 export declare function present<T>(data: T, at: Temporal.Instant): Stored<T>;

package/dist/with/index.d.ts

@@ -1,61 +1,6 @@
-import { Actions, HandlerContext, Maybe, Model, Props } from '../types/index';
-import { Env } from '../boundary/components/env/index';
-type Primitive = Maybe<string | number | bigint | boolean | symbol>;
-type Depth = [never, 0, 1, 2, 3, 4, 5];
-/**
- * Lodash-style dotted paths reachable from `T`. Yields `"a"`, `"a.b"`,
- * `"items.0"`, `"items.0.name"`, etc. Recursion is capped at depth 5 to
- * keep the type-checker tractable on deeply nested models.
- *
- * @template T The object type to enumerate paths from.
- * @template D Recursion budget (internal).
- */
-export type Paths<T, D extends number = 5> = [D] extends [never] ? never : T extends Primitive ? never : T extends ReadonlyArray<infer U> ? `${number}` | (U extends Primitive ? never : `${number}.${Paths<U, Depth[D]>}`) : T extends object ? {
-    [K in Extract<keyof T, string>]: T[K] extends Primitive ? K : K | `${K}.${Paths<T[K], Depth[D]>}`;
-}[Extract<keyof T, string>] : never;
-/**
- * Subset of {@link Paths} whose leaf type is `boolean`. Used by
- * `context.with.invert` (and the legacy {@link With.Invert}) to restrict the
- * key to togglable fields only.
- *
- * @template T The object type to enumerate boolean leaves from.
- * @template D Recursion budget (internal).
- */
-export type BooleanPaths<T, D extends number = 5> = [D] extends [never] ? never : T extends Primitive ? never : T extends ReadonlyArray<infer U> ? (U extends boolean ? `${number}` : never) | (U extends Primitive ? never : `${number}.${BooleanPaths<U, Depth[D]>}`) : T extends object ? {
-    [K in Extract<keyof T, string>]: T[K] extends boolean ? K : T[K] extends Primitive ? never : `${K}.${BooleanPaths<T[K], Depth[D]>}`;
-}[Extract<keyof T, string>] : never;
-/**
- * Resolves the leaf type at a dotted path on `T`. `Get<{a:{b:number}},"a.b">`
- * is `number`; `Get<{items: string[]},"items.0">` is `string`.
- *
- * @template T The object type to walk.
- * @template P The dotted path string.
- */
-export type Get<T, P extends string> = P extends `${infer Head}.${infer Tail}` ? T extends ReadonlyArray<infer U> ? Head extends `${number}` ? Get<U, Tail> : never : Head extends keyof T ? Get<T[Head], Tail> : never : T extends ReadonlyArray<infer U> ? P extends `${number}` ? U : never : P extends keyof T ? T[P] : never;
-/**
- * Returned by `context.with` &mdash; a typed bag of handler factories
- * bound to the model `M` declared in `useContext<M, …>()`. Methods accept
- * lodash-style dotted paths (`"a.b.c"`) with array indices (`"items.0.id"`).
- *
- * - `update(key)` &mdash; assigns the dispatched payload to `model[key]`.
- * - `invert(key)` &mdash; flips a boolean leaf at `model[key]`.
- * - `always(key, value)` &mdash; assigns a fixed `value` to `model[key]`,
- *   ignoring any dispatched payload.
- *
- * @template M The model type to bind keys against.
- */
-export type WithHandle<M> = M extends Model ? {
-    update<K extends Paths<M>>(key: K): <A extends Actions | void, D extends Props, S extends Env = Env>(context: HandlerContext<M, A, D, S>, payload: Get<M, K>) => void;
-    invert<K extends BooleanPaths<M>>(key: K): <A extends Actions | void, D extends Props, S extends Env = Env>(context: HandlerContext<M, A, D, S>) => void;
-    always<K extends Paths<M>>(key: K, value: Get<M, K>): <A extends Actions | void, D extends Props, S extends Env = Env>(context: HandlerContext<M, A, D, S>) => void;
-} : Record<string, never>;
-/**
- * Builds the {@link WithHandle} object returned via `context.with`. The
- * runtime is identical for any model &mdash; only the call-site types differ.
- *
- * @internal
- */
-export declare function bindWith<M extends Model | void>(): WithHandle<M>;
+import { Actions, HandlerContext, Model, Props } from '../types/index.js';
+import { Env } from '../boundary/components/env/types.js';
+import { BooleanPaths, Get, Paths } from './types.js';
 /**
  * Handler factories that wire an action directly to a model field. Prefer
  * `context.with` from `useContext<Model>()` for first-class autocompletion
@@ -95,17 +40,27 @@ export declare const With: {
      * Returns a handler that assigns the action payload to the model leaf at
      * the given lodash-style path. The payload type must match `Get<M, K>`,
      * and the path must exist on the model.
+     *
+     * @template K The dotted-path string indexing into the model.
+     * @param key The lodash-style path to the model leaf being assigned.
      */
-    Update<K extends string>(key: K): <M extends Model, A extends Actions | void, D extends Props, P extends K extends Paths<M> ? Get<M, K> : never, S extends Env = Env>(context: HandlerContext<M, A, D, S>, payload: P) => void;
+    Update<K extends string>(key: K): <M extends Model, A extends Actions | void, D extends Props, P extends K extends Paths<M> ? Get<M, K> : never, E extends Env = Env>(context: HandlerContext<M, A, D, E>, payload: P) => void;
     /**
      * Returns a handler that inverts a boolean leaf at the given lodash-style
      * path. The leaf must be a `boolean` on the model.
+     *
+     * @template K The dotted-path string indexing into a boolean leaf.
+     * @param key The lodash-style path to the boolean leaf being toggled.
      */
-    Invert<K extends string>(key: K): <M extends Model, A extends Actions | void, D extends Props, S extends Env = Env>(context: K extends BooleanPaths<M> ? HandlerContext<M, A, D, S> : never) => void;
+    Invert<K extends string>(key: K): <M extends Model, A extends Actions | void, D extends Props, E extends Env = Env>(context: K extends BooleanPaths<M> ? HandlerContext<M, A, D, E> : never) => void;
     /**
      * Returns a handler that assigns a fixed `value` to the model leaf at the
      * given lodash-style path. The dispatched payload (if any) is ignored.
+     *
+     * @template K The dotted-path string indexing into the model.
+     * @template V The constant value type; must be assignable to the leaf at `K`.
+     * @param key The lodash-style path to the model leaf being assigned.
+     * @param value The constant value pinned to the leaf.
      */
-    Always<K extends string, V>(key: K, value: V): <M extends Model, A extends Actions | void, D extends Props, S extends Env = Env>(context: K extends Paths<M> ? V extends Get<M, K> ? HandlerContext<M, A, D, S> : never : never) => void;
+    Always<K extends string, V>(key: K, value: V): <M extends Model, A extends Actions | void, D extends Props, E extends Env = Env>(context: K extends Paths<M> ? V extends Get<M, K> ? HandlerContext<M, A, D, E> : never : never) => void;
 };
-export {};

package/dist/with/types.d.ts

@@ -0,0 +1,66 @@
+import { Actions, HandlerContext, Maybe, Model, Props } from '../types/index.js';
+import { Env } from '../boundary/components/env/types.js';
+/**
+ * Non-nullable primitive leaves that {@link Paths} can terminate on. Used
+ * internally to stop the recursive walk at scalar boundaries; consumers
+ * shouldn't reach for this directly.
+ *
+ * @internal
+ */
+export type Primitive = Maybe<string | number | bigint | boolean | symbol>;
+/**
+ * Decrement table used to cap {@link Paths} / {@link BooleanPaths}
+ * recursion depth. Indexing `Depth[N]` produces `N - 1` (or `never`
+ * once the budget is exhausted), keeping the type-checker tractable
+ * on deeply nested models.
+ *
+ * @internal
+ */
+export type Depth = [never, 0, 1, 2, 3, 4, 5];
+/**
+ * Lodash-style dotted paths reachable from `T`. Yields `"a"`, `"a.b"`,
+ * `"items.0"`, `"items.0.name"`, etc. Recursion is capped at depth 5 to
+ * keep the type-checker tractable on deeply nested models.
+ *
+ * @template T The object type to enumerate paths from.
+ * @template D Recursion budget (internal).
+ */
+export type Paths<T, D extends number = 5> = [D] extends [never] ? never : T extends Primitive ? never : T extends ReadonlyArray<infer U> ? `${number}` | (U extends Primitive ? never : `${number}.${Paths<U, Depth[D]>}`) : T extends object ? {
+    [K in Extract<keyof T, string>]: T[K] extends Primitive ? K : K | `${K}.${Paths<T[K], Depth[D]>}`;
+}[Extract<keyof T, string>] : never;
+/**
+ * Subset of {@link Paths} whose leaf type is `boolean`. Used by
+ * `context.with.invert` (and the legacy {@link With.Invert}) to restrict the
+ * key to togglable fields only.
+ *
+ * @template T The object type to enumerate boolean leaves from.
+ * @template D Recursion budget (internal).
+ */
+export type BooleanPaths<T, D extends number = 5> = [D] extends [never] ? never : T extends Primitive ? never : T extends ReadonlyArray<infer U> ? (U extends boolean ? `${number}` : never) | (U extends Primitive ? never : `${number}.${BooleanPaths<U, Depth[D]>}`) : T extends object ? {
+    [K in Extract<keyof T, string>]: T[K] extends boolean ? K : T[K] extends Primitive ? never : `${K}.${BooleanPaths<T[K], Depth[D]>}`;
+}[Extract<keyof T, string>] : never;
+/**
+ * Resolves the leaf type at a dotted path on `T`. `Get<{a:{b:number}},"a.b">`
+ * is `number`; `Get<{items: string[]},"items.0">` is `string`.
+ *
+ * @template T The object type to walk.
+ * @template P The dotted path string.
+ */
+export type Get<T, P extends string> = P extends `${infer Head}.${infer Tail}` ? T extends ReadonlyArray<infer U> ? Head extends `${number}` ? Get<U, Tail> : never : Head extends keyof T ? Get<T[Head], Tail> : never : T extends ReadonlyArray<infer U> ? P extends `${number}` ? U : never : P extends keyof T ? T[P] : never;
+/**
+ * Returned by `context.with` &mdash; a typed bag of handler factories
+ * bound to the model `M` declared in `useContext<M, …>()`. Methods accept
+ * lodash-style dotted paths (`"a.b.c"`) with array indices (`"items.0.id"`).
+ *
+ * - `update(key)` &mdash; assigns the dispatched payload to `model[key]`.
+ * - `invert(key)` &mdash; flips a boolean leaf at `model[key]`.
+ * - `always(key, value)` &mdash; assigns a fixed `value` to `model[key]`,
+ *   ignoring any dispatched payload.
+ *
+ * @template M The model type to bind keys against.
+ */
+export type WithHandle<M> = M extends Model ? {
+    update<K extends Paths<M>>(key: K): <A extends Actions | void, D extends Props, E extends Env = Env>(context: HandlerContext<M, A, D, E>, payload: Get<M, K>) => void;
+    invert<K extends BooleanPaths<M>>(key: K): <A extends Actions | void, D extends Props, E extends Env = Env>(context: HandlerContext<M, A, D, E>) => void;
+    always<K extends Paths<M>>(key: K, value: Get<M, K>): <A extends Actions | void, D extends Props, E extends Env = Env>(context: HandlerContext<M, A, D, E>) => void;
+} : Record<string, never>;

package/dist/with/utils.d.ts

@@ -0,0 +1,61 @@
+import { Actions, HandlerContext, Model, Props } from '../types/index.js';
+import { Env } from '../boundary/components/env/types.js';
+import { WithHandle } from './types.js';
+/**
+ * Walks the lodash-style dotted `path` on `target`, stopping one segment
+ * short so callers can mutate or read the leaf via the returned `cursor`
+ * and `key`. Used by every assignment helper below to avoid duplicating
+ * the per-segment descent.
+ *
+ * @internal
+ */
+export declare function walk(target: unknown, path: string): {
+    cursor: Record<string, unknown>;
+    key: string;
+};
+/**
+ * Assigns `value` to the leaf of `target` reached by lodash-style `path`.
+ * Mutates in place &mdash; expected to be called from inside an Immer
+ * `produce` draft.
+ *
+ * @internal
+ */
+export declare function setPath(target: unknown, path: string, value: unknown): void;
+/**
+ * Flips the boolean leaf of `target` reached by lodash-style `path`.
+ * Mutates in place &mdash; expected to be called from inside an Immer
+ * `produce` draft.
+ *
+ * @internal
+ */
+export declare function invertPath(target: unknown, path: string): void;
+/**
+ * Returns a handler that assigns the dispatched payload to the model
+ * leaf at lodash-style `key`. Underlies both `context.with.update` and
+ * the top-level `With.Update`.
+ *
+ * @internal
+ */
+export declare function makeUpdate(key: string): (context: HandlerContext<Model, Actions, Props, Env>, payload: unknown) => void;
+/**
+ * Returns a handler that flips the boolean model leaf at lodash-style
+ * `key`. Underlies both `context.with.invert` and `With.Invert`.
+ *
+ * @internal
+ */
+export declare function makeInvert(key: string): (context: HandlerContext<Model, Actions, Props, Env>) => void;
+/**
+ * Returns a handler that assigns the constant `value` to the model
+ * leaf at lodash-style `key`, ignoring any dispatched payload.
+ * Underlies both `context.with.always` and `With.Always`.
+ *
+ * @internal
+ */
+export declare function makeAlways(key: string, value: unknown): (context: HandlerContext<Model, Actions, Props, Env>) => void;
+/**
+ * Builds the {@link WithHandle} object returned via `context.with`. The
+ * runtime is identical for any model &mdash; only the call-site types differ.
+ *
+ * @internal
+ */
+export declare function bindWith<M extends Model | void>(): WithHandle<M>;

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "march-hare",
-  "version": "0.12.1",
+  "version": "0.13.1",
   "type": "module",
   "license": "MIT",
   "packageManager": "yarn@1.22.22",
   "main": "./dist/march-hare.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "mh": "./dist/cli/bin/mh.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -14,8 +17,16 @@
     }
   },
   "dependencies": {
+    "@inquirer/prompts": "^7.2.0",
+    "change-case": "^5.4.4",
+    "ejs": "^3.1.10",
     "eventemitter3": "^5.0.4",
-    "immertation": "^0.1.26"
+    "figlet": "^1.7.0",
+    "find-up": "^8.0.0",
+    "gray-matter": "^4.0.3",
+    "immertation": "^0.1.26",
+    "kleur": "^4.1.5",
+    "tinyglobby": "^0.2.17"
   },
   "peerDependencies": {
     "@mobily/ts-belt": "^3.0.0",
@@ -26,10 +37,12 @@
     "vitest/vite": "^7.3.1"
   },
   "files": [
-    "dist"
+    "dist",
+    "src/cli/README.md"
   ],
   "scripts": {
-    "build": "vite build",
+    "build": "vite build && npm run build:cli",
+    "build:cli": "tsc -p tsconfig.cli.json && rm -rf dist/cli/templates && cp -R src/cli/templates dist/cli/templates && chmod +x dist/cli/bin/mh.js",
     "build:example": "vite build --mode example --outDir dist-example --base /MarchHare/ && mv dist-example/src/example/index.html dist-example/index.html && rm -rf dist-example/src",
     "dev": "vite",
     "preview": "vite preview",
@@ -44,6 +57,7 @@
     "@emotion/css": "^11.13.5",
     "@eslint/js": "^9.39.3",
     "@faker-js/faker": "^10.3.0",
+    "@feature-sliced/eslint-config": "^0.1.1",
     "@jest/globals": "^30.2.0",
     "@js-temporal/polyfill": "^0.5.1",
     "@mobily/ts-belt": "4.0.0-rc.5",
@@ -52,6 +66,7 @@
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
     "@types/dom-navigation": "^1.0.7",
+    "@types/ejs": "^3.1.5",
     "@types/lodash": "^4.17.23",
     "@types/ms": "^2.1.0",
     "@types/ramda": "^0.31.1",
@@ -64,6 +79,8 @@
     "dayjs": "^1.11.19",
     "dexie": "^4.3.0",
     "eslint": "^9.39.3",
+    "eslint-import-resolver-typescript": "^4.4.5",
+    "eslint-plugin-boundaries": "^6.0.2",
     "eslint-plugin-fp": "^2.3.0",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-react": "^7.37.5",