march-hare 0.12.1 → 0.13.0

package/README.md

@@ -28,7 +28,7 @@
 1. [Global data](#global-data)
 1. [Reusable components](#reusable-components)
 
-For advanced topics, see the [recipes directory](./recipes/).
+For advanced topics, see the [recipes directory](./recipes/). For a worked end-to-end example with the FSD layout, see [`src/example/`](./src/example/README.md).
 
 ## Benefits
 
@@ -40,7 +40,7 @@ For advanced topics, see the [recipes directory](./recipes/).
 - Reduces context proliferation – events replace many contexts.
 - No need to memoize callbacks – handlers are stable references with fresh closure access.
 - Clear separation between business logic and markup.
-- Complements [Feature Slice Design](https://feature-sliced.design/) architecture.
+- Complements [Feature Sliced Design](https://feature-sliced.design/) architecture — **App = host, Scope = feature**; see [Reusable components](#reusable-components).
 - Strongly typed dispatches, models, payloads, etc.
 - Built-in request cancellation with `AbortController`.
 - Granular async state tracking per model field.
@@ -393,7 +393,12 @@ Components that mount after a broadcast has already been dispatched automaticall
 
 ## Resource handling
 
-For remote data, declare an `app.Resource` at module scope. `resource.user(params)` is the unified call form &mdash; it returns the sync cache read (`User | null`) and primes a slot that `context.actions.resource(resource.user(params))` consumes for the fetch path (with auto-threaded abort controller and a live handle to the per-`<Boundary>` Env). Every successful fetch caches the response in a module-level slot keyed by the fetcher and the stringified params, so different param-sets are independent. Keep all resources in `resources.ts` and pull the whole module in as a namespace (`import * as resource from "./resources"`):
+For remote data, declare an `app.Resource` at module scope. The resulting handle has two call forms:
+
+- `resource.user.get(params)` &mdash; synchronous cache read, returns `User | null`. Use it in model literals, JSX, or anywhere you need the cached value without triggering a fetch.
+- `resource.user(params)` &mdash; produces an `Invocation` you pass to `context.actions.resource(...)` for the fetch path (with auto-threaded abort controller and a live handle to the per-`<Boundary>` Env).
+
+Every successful fetch caches the response in a module-level slot keyed by the fetcher and the stringified params, so different param-sets are independent. Keep all resources in `resources.ts` and pull the whole module in as a namespace (`import * as resource from "./resources"`):
 
 ```ts
 // resources.ts
@@ -430,7 +435,7 @@ function useActions() {
   const context = app.useContext<Model, typeof Actions>();
   const actions = context.useActions({
     // Sync cache read at the model literal — returns null when nothing is cached.
-    user: resource.user(),
+    user: resource.user.get(),
     receipt: null,
   });
 
@@ -536,21 +541,28 @@ actions.useAction(Actions.Mount, async (context) => {
 
 See the [Resource recipe](./recipes/use-resource.md) for the three-tier error handling model, parameterised resources, and limitations.
 
-By default an `app.Resource`'s cache is in-memory only &ndash; it resets on every page load. To keep the most recent successful payload around between sessions, switch to `app.Resource.Cachable(cache, fetcher)`. The cache is the **first** argument &mdash; persistence is the headline of this form, the fetcher is the operation. Every successful fetch writes through to the Cache; first reads via the call form auto-seed from the Cache's adapter:
+By default an `app.Resource`'s cache is in-memory only &ndash; it resets on every page load. To keep the most recent successful payload around between sessions, wire a `Cache` into `App({ cache })`. Every `app.Resource` declared on that App writes through to the shared Cache and seeds from it on the next reload; resources are namespaced internally so they don't collide on shared params keys:
 
 ```ts
-// resources.ts
-import { Cache } from "march-hare";
-import { app } from "./app";
+// app.ts
+import { App, Cache } from "march-hare";
 
-const cache = Cache({
-  get: (key) => localStorage.getItem(key),
-  set: (key, value) => localStorage.setItem(key, value),
-  remove: (key) => localStorage.removeItem(key),
-  clear: () => localStorage.clear(),
+export const app = App({
+  env: { session: null as Session | null },
+  cache: Cache({
+    get: (key) => localStorage.getItem(key),
+    set: (key, value) => localStorage.setItem(key, value),
+    remove: (key) => localStorage.removeItem(key),
+    clear: () => localStorage.clear(),
+  }),
 });
+```
 
-export const cat = app.Resource.Cachable(cache, (context) =>
+```ts
+// resources.ts
+import { app } from "./app";
+
+export const cat = app.Resource((context) =>
   fetchCat(context.controller.signal),
 );
 ```
@@ -571,7 +583,7 @@ function useActions() {
   const context = app.useContext<Model, typeof Actions>();
   const actions = context.useActions({
     // First render reads the Cache automatically.
-    cat: resource.cat(),
+    cat: resource.cat.get(),
   });
 
   actions.useAction(Actions.Mount, async (context) => {
@@ -594,7 +606,9 @@ export default function CatCard(): React.ReactElement {
 
 `Cache()` with no adapter is an in-memory scope &ndash; useful in tests or when you want a holdable cache without persistence. Per-params keying via `JSON.stringify(params)` is automatic, so `user({ id: 5 })` and `user({ id: 6 })` are distinct slots.
 
-See the [storage recipe](./recipes/storage.md) for backend adapters (React Native MMKV, browser extension `chrome.storage`), sign-out purge, and the `unset` sentinel that keeps "nothing stored" distinct from "a legitimately stored null".
+The adapter contract is **strictly synchronous** &ndash; `get` / `set` / `remove` / `clear` all return immediately, with no `Promise`. The model-literal read (`{ user: resource.user.get() }`) is evaluated during render and has no place to wait. React Native projects should use [`react-native-mmkv`](https://github.com/mrousavy/react-native-mmkv), which is sync out of the box and drops straight into the contract; `AsyncStorage` is incompatible. Truly async backends (IndexedDB, `chrome.storage.local`) need a sync facade hydrated at app entry &ndash; see the [storage recipe](./recipes/storage.md).
+
+See the [storage recipe](./recipes/storage.md) for backend adapters (React Native `react-native-mmkv`, browser `localStorage`, browser extension `chrome.storage`), sign-out purge, and the `unset` sentinel that keeps "nothing stored" distinct from "a legitimately stored null".
 
 ## Channeled actions
 
@@ -703,7 +717,7 @@ A few rules worth knowing:
 - **No `scope.Scope()`.** The handle deliberately omits a nested factory. Open another scope by calling `app.Scope<...>()` again and rendering its `<Boundary>` &mdash; that way the multicast surface stays declared at the call site.
 - **Replay on late-mount is per-scope.** Like broadcast, multicast caches its most recent payload per action symbol; components that mount later inside the same boundary pick up the cached value through their `useAction` handler. See the [mount deduplication recipe](./recipes/mount-broadcast-deduplication.md) if you also fetch in `Lifecycle.Mount()`.
 
-See the [multicast recipe](./recipes/multicast-actions.md) for more details.
+See the [multicast recipe](./recipes/multicast-actions.md) for more details. When the scope itself needs to be reusable across multiple hosts, reach for `shared.Scope<HostEnvs, typeof MulticastActions>()` &mdash; the standalone form covered in [Reusable components](#reusable-components). The rule of thumb: never reach for a second `App()` to get a private channel; that's what multicast scopes exist for.
 
 ## Global data
 
@@ -800,15 +814,16 @@ export const app = App();
 
 ## Reusable components
 
+> **App = host, Scope = feature.** One `App<HostEnv>()` per deployable; everything inside it is a component. A component that needs a private channel reaches for `shared.Scope<HostEnvs, _>()`, never another `App()`. A component that runs under more than one `App` reaches for `shared.useContext<HostEnvs, M, A>()` instead of binding to a specific `app`. That one rule keeps the dependency graph acyclic, lets cross-cutting state (session, locale, permissions) live in a single Env, and gives [Feature Sliced Design](https://feature-sliced.design/) a 1:1 runtime expression &mdash; shared layer reuses `shared.X` against a `HostEnvs` union, features open `shared.Scope`s, hosts declare the App.
+
 Importing `app` from a single location is fine inside a feature, but it breaks when a component needs to run under **more than one** `App` &mdash; a shared `<Profile />` used by both a web app and a mobile shell, for example. For that case, every `app.X` factory has a **standalone counterpart** on the `shared` namespace that takes the Env shape `E` as its mandatory first generic:
 
-| Bound to an App              | Standalone (`shared.X`)                  |
-| ---------------------------- | ---------------------------------------- |
-| `app.useContext<M, A, D>()`  | `shared.useContext<E, M, A, D>()`        |
-| `app.useEnv()`               | `shared.useEnv<E>()`                     |
-| `app.Resource<T, P>(...)`    | `shared.Resource<E, T, P>(...)`          |
-| `app.Resource.Cachable(...)` | `shared.Resource.Cachable<E, T, P>(...)` |
-| `app.Scope<A>()`             | `shared.Scope<E, A>()`                   |
+| Bound to an App             | Standalone (`shared.X`)           |
+| --------------------------- | --------------------------------- |
+| `app.useContext<M, A, D>()` | `shared.useContext<E, M, A, D>()` |
+| `app.useEnv()`              | `shared.useEnv<E>()`              |
+| `app.Resource<T, P>(...)`   | `shared.Resource<E, T, P>(...)`   |
+| `app.Scope<A>()`            | `shared.Scope<E, A>()`            |
 
 The standalone forms take the same runtime path as the App-bound ones &mdash; `E` is purely a type-level binding the caller supplies so reusable code stays App-agnostic.
 
@@ -876,6 +891,8 @@ function Where(): React.ReactElement {
 }
 ```
 
-`shared.Resource<E, T, P>` and `shared.Resource.Cachable<E, T, P>` are the same story for shared resources &mdash; declare them at module scope, pass the Env union as the first generic, and the fetcher's `context.env` is typed against it. `shared.Scope<E, A>()` opens a multicast scope without going through an App handle. See the [reusable components recipe](./recipes/reusable-components.md) for the full pattern including discriminator-keyed switches and the `App()`-with-no-env case.
+`shared.Resource<E, T, P>` is the same story for shared resources &mdash; declare them at module scope, pass the Env union as the first generic, and the fetcher's `context.env` is typed against it. Shared resources always use an isolated in-memory cache; reach for `app.Resource` when persistence is required, since the cache is wired into the App via `App({ cache })`. `shared.Scope<E, A>()` opens a multicast scope without going through an App handle. See the [reusable components recipe](./recipes/reusable-components.md) for the full pattern including discriminator-keyed switches and the `App()`-with-no-env case.
+
+When a reusable component or resource is genuinely Env-agnostic &mdash; the fetcher never touches `context.env`, the hook never calls `shared.useEnv` &mdash; pass `Envless` as `E` instead of spelling out `Record<never, never>`: `shared.Resource<Envless, T>`, `shared.useContext<Envless, M, A>()`. It's a named alias for the empty-record shape exported from `march-hare`, kept around purely for legibility at the call site.
 
 For one-line handler binding &mdash; flipping a boolean, assigning a payload to a leaf, pinning a field to a fixed value &mdash; reach for `context.with.{update,invert,always}`. See the [`With` helpers recipe](./recipes/with-helpers.md) for the full surface.

package/dist/app/index.d.ts

@@ -1,67 +1,13 @@
 import { Env } from '../boundary/components/env/index';
+import { Cache } from '../cache/index';
 import { Actions, Model, Props } from '../types/index';
-import { Scope } from '../scope/index';
-import { AppContextHandle, AppResource } from './types';
+import { AppHandle, AppContextHandle } from './types';
 import { Tap } from '../boundary/components/tap/types';
-import * as React from "react";
 export type { AppArgs, AppContextHandle, AppFetcher, AppResource, } from './types';
+export type { AppHandle } from './types';
 /**
- * Returned from {@link App}. Bundles the Boundary, hooks, and Resource
- * factory bound to a single typed Env shape `S`.
- */
-export type App<S extends object> = {
-    /**
-     * Boundary component for this App. Wraps the subtree with the `env`
-     * and `tap` declared on {@link App} &mdash; both are fixed at App
-     * construction time and cannot be overridden at the render site.
-     * Runtime mutations to the Env flow through
-     * `context.actions.produce(({ env }) => { ... })`; if a test or
-     * storybook needs a different initial Env, declare a separate `App`.
-     */
-    readonly Boundary: React.FC<{
-        children: React.ReactNode;
-    }>;
-    /**
-     * Hook returning a stable `Context` handle. The handle's
-     * `context.useActions(model?, getData?)` materialises the
-     * component's `[model, actions, data]` tuple. Every handler's
-     * `context.env` is typed as `S`.
-     */
-    readonly useContext: <M extends Model | void = void, AC extends Actions | void = void, D extends Props = Props>() => AppContextHandle<M, AC, D, S>;
-    /**
-     * Read-only Proxy over the per-Boundary Env, typed as `S`. Reads use
-     * dot notation (`env.session`) and always reflect the latest value
-     * across `await` boundaries. Writes flow through
-     * `context.actions.produce(({ env }) => { ... })`.
-     */
-    readonly useEnv: () => Readonly<S>;
-    /**
-     * `Resource` factory bound to this App's Env. Same shape as the
-     * top-level `Resource`: call directly for an in-memory cache, or use
-     * `app.Resource.Cachable(cache, fetcher)` for persistence.
-     */
-    readonly Resource: AppResource<S>;
-    /**
-     * Opens a typed multicast scope. The generic `MulticastActions` declares
-     * the `Distribution.Multicast` action class (or union of classes)
-     * whose dispatches are routed through this scope &mdash; the
-     * returned handle mirrors the App surface but widens
-     * `useContext().actions.dispatch` to accept actions from `MulticastActions`
-     * on top of the local `AC` class.
-     *
-     * Render `<scope.Boundary>` to open the scope at runtime; nesting
-     * multiple boundaries from different `app.Scope()` calls is fine,
-     * each runs as an independent emitter shadowed for its subtree.
-     *
-     * The Scope handle deliberately does NOT expose a further `Scope`
-     * method &mdash; the multicast surface must be declared at the
-     * `app.Scope<MulticastActions>()` call site so the type union is explicit.
-     */
-    readonly Scope: <MulticastActions>() => Scope<S, MulticastActions>;
-};
-/**
- * Creates an `App` &mdash; the entrypoint for a typed Env shape `S`,
- * inferred from `config.env`. `App<S>` exposes `Boundary`, hooks, and
+ * Creates an `App` &mdash; the entrypoint for a typed Env shape `E`,
+ * inferred from `config.env`. `App<E>` exposes `Boundary`, hooks, and
  * a `Resource` factory all wired against the same shape.
  *
  * Each `<app.Boundary>` instance owns its own Env, so different `App`s
@@ -69,15 +15,22 @@ export type App<S extends object> = {
  *
  * Pass `tap` to subscribe to every action handler's dispatch / settle /
  * error inside the boundary &mdash; useful for analytics, audit logging,
- * Sentry breadcrumbs. See `recipes/tap.md`. Both `env` and `tap` are
- * fixed at `App()` time; `<app.Boundary>` does not accept overrides.
- * Mutate the live Env through `context.actions.produce(({ env }) => …)`,
- * and declare a separate `App` when a test or storybook needs a
- * different initial value.
+ * Sentry breadcrumbs. See `recipes/tap.md`. Pass `cache` to persist
+ * every `app.Resource(fetcher)` declaration through a single
+ * {@link Cache} &mdash; each resource is namespaced inside the cache by
+ * its declaration order, so reloads seed from storage automatically and
+ * resources do not collide on shared params keys. Omit `cache` to keep
+ * each resource's payloads in an isolated in-memory slot.
+ *
+ * `env`, `tap`, and `cache` are all fixed at `App()` time;
+ * `<app.Boundary>` does not accept overrides. Mutate the live Env
+ * through `context.actions.produce(({ env }) => …)`, and declare a
+ * separate `App` when a test or storybook needs a different initial
+ * value.
  *
  * @example
  * ```tsx
- * import { App, type Taps } from "march-hare";
+ * import { App, Cache, type Taps } from "march-hare";
  *
  * type Session = { accessToken: string };
  *
@@ -93,6 +46,12 @@ export type App<S extends object> = {
  *     operating: "idle" as "idle" | "signing-out",
  *   },
  *   tap,
+ *   cache: Cache({
+ *     get: (key) => localStorage.getItem(key),
+ *     set: (key, value) => localStorage.setItem(key, value),
+ *     remove: (key) => localStorage.removeItem(key),
+ *     clear: () => localStorage.clear(),
+ *   }),
  * });
  *
  * // Root render.
@@ -100,21 +59,7 @@ export type App<S extends object> = {
  *   <Root />
  * </app.Boundary>;
  *
- * // In a feature's actions.ts:
- * export function useAuthActions() {
- *   const context = app.useContext<void, typeof Actions>();
- *   const actions = context.useActions();
- *
- *   actions.useAction(Actions.SignOut, async (context) => {
- *     context.actions.produce(({ env }) => {
- *       env.session = null;
- *     });
- *   });
- *
- *   return actions;
- * }
- *
- * // In resources.ts:
+ * // In resources.ts &mdash; persisted via the App's cache.
  * export const user = app.Resource<User>((context) =>
  *   ky
  *     .get("/api/user", {
@@ -127,10 +72,11 @@ export type App<S extends object> = {
  * );
  * ```
  */
-export declare function App<S extends object = Env>(config?: {
-    env?: S;
+export declare function App<E extends object = Env>(config?: {
+    env?: E;
     tap?: Tap;
-}): App<S>;
+    cache?: Cache;
+}): AppHandle<E>;
 /**
  * Standalone counterpart to `app.useContext`, exported as
  * `shared.useContext` &mdash; same call shape, but takes the **Env

package/dist/app/types.d.ts

@@ -1,47 +1,100 @@
 import { Args, ResourceHandle } from '../resource/types';
-import { Cache } from '../cache/index';
 import { Actions, Context, Model, Props, UseActions } from '../types/index';
 import { Data } from '../actions/types';
 import { Env } from '../boundary/components/env/index';
-import { WithHandle } from '../with/index';
+import { WithHandle } from '../with/types';
 /**
  * Args object passed to an `app.Resource` fetcher. Same shape as the
- * base `Resource` fetcher's args but with `env` typed as `S`.
+ * base `Resource` fetcher's args but with `env` typed as `E`.
  */
-export type AppArgs<S, P extends object = Record<never, never>> = Omit<Args<P>, "env"> & {
-    readonly env: Readonly<S>;
+export type AppArgs<E, P extends object = Record<never, never>> = Omit<Args<P>, "env"> & {
+    readonly env: Readonly<E>;
 };
 /**
  * Fetcher signature for an `app.Resource` declaration. The fetcher's
- * `context.env` is typed against the App's inferred Env shape `S`.
+ * `context.env` is typed against the App's inferred Env shape `E`.
  */
-export type AppFetcher<S, T, P extends object = Record<never, never>> = (context: AppArgs<S, P>) => Promise<T>;
+export type AppFetcher<E, T, P extends object = Record<never, never>> = (context: AppArgs<E, P>) => Promise<T>;
 /**
- * `app.Resource(fetcher)` &mdash; in-memory cache, no persistence.
- * `app.Resource.Cachable(cache, fetcher)` &mdash; persistent cache wired
- * to the supplied `Cache` adapter. Both forms type `context.env` as
- * the App's Env shape.
+ * `app.Resource(fetcher)` declares a remote interaction bound to the
+ * App's Env shape. Cache behaviour is decided at App construction:
+ * pass `App({ cache })` to share a single {@link Cache} (typically
+ * backed by `localStorage`/MMKV) across every resource on the App, or
+ * omit it to keep each resource's payloads in an isolated in-memory
+ * slot.
  */
-export type AppResource<S> = {
-    <T, P extends object = Record<never, never>>(fetcher: AppFetcher<S, T, P>): ResourceHandle<T, P>;
-    readonly Cachable: <T, P extends object = Record<never, never>>(cache: Cache, fetcher: AppFetcher<S, T, P>) => ResourceHandle<T, P>;
-};
+export type AppResource<E> = <T, P extends object = Record<never, never>>(fetcher: AppFetcher<E, T, P>) => ResourceHandle<T, P>;
 /**
  * Tuple shape returned by `context.useActions(...)` on an App-bound
- * Context. Re-exports the base {@link UseActions} with the App's `S`
+ * Context. Re-exports the base {@link UseActions} with the App's `E`
  * threaded through every `HandlerContext` and produce draft.
  */
-type AppActionsResult<M, AC, D, S> = UseActions<M extends Model | void ? M : void, AC extends Actions | void ? AC : void, D extends Props ? D : Props, S extends Env ? S : Env>;
+type AppActionsResult<M, AC, D, E> = UseActions<M extends Model | void ? M : void, AC extends Actions | void ? AC : void, D extends Props ? D : Props, E extends Env ? E : Env>;
 /**
  * `useActions(...)` signature on the App-bound Context. Has two forms:
  * void-model components omit the model argument entirely; everyone else
  * passes their initial model as the first argument and an optional data
  * callback as the second.
  */
-type AppUseActions<M, AC, D, S> = M extends void ? (getData?: Data<D & Props>) => AppActionsResult<M, AC, D, S> : (model: M, getData?: Data<D & Props>) => AppActionsResult<M, AC, D, S>;
+type AppUseActions<M, AC, D, E> = M extends void ? (getData?: Data<D & Props>) => AppActionsResult<M, AC, D, E> : (model: M, getData?: Data<D & Props>) => AppActionsResult<M, AC, D, E>;
+/**
+ * Returned from {@link App}. Bundles the Boundary, hooks, and Resource
+ * factory bound to a single typed Env shape `E`.
+ */
+export type AppHandle<E extends object> = {
+    /**
+     * Boundary component for this App. Wraps the subtree with the `env`
+     * and `tap` declared on {@link App} &mdash; both are fixed at App
+     * construction time and cannot be overridden at the render site.
+     * Runtime mutations to the Env flow through
+     * `context.actions.produce(({ env }) => { ... })`; if a test or
+     * storybook needs a different initial Env, declare a separate `App`.
+     */
+    readonly Boundary: import('react').FC<{
+        children: import('react').ReactNode;
+    }>;
+    /**
+     * Hook returning a stable `Context` handle. The handle's
+     * `context.useActions(model?, getData?)` materialises the
+     * component's `[model, actions, data]` tuple. Every handler's
+     * `context.env` is typed as `E`.
+     */
+    readonly useContext: <M extends Model | void = void, AC extends Actions | void = void, D extends Props = Props>() => AppContextHandle<M, AC, D, E>;
+    /**
+     * Read-only Proxy over the per-Boundary Env, typed as `E`. Reads use
+     * dot notation (`env.session`) and always reflect the latest value
+     * across `await` boundaries. Writes flow through
+     * `context.actions.produce(({ env }) => { ... })`.
+     */
+    readonly useEnv: () => Readonly<E>;
+    /**
+     * `Resource` factory bound to this App's Env. Resources declared
+     * through this factory share the cache passed to `App({ cache })`
+     * &mdash; or fall back to a per-resource in-memory slot when no
+     * cache is configured on the App.
+     */
+    readonly Resource: AppResource<E>;
+    /**
+     * Opens a typed multicast scope. The generic `MulticastActions` declares
+     * the `Distribution.Multicast` action class (or union of classes)
+     * whose dispatches are routed through this scope &mdash; the
+     * returned handle mirrors the App surface but widens
+     * `useContext().actions.dispatch` to accept actions from `MulticastActions`
+     * on top of the local `AC` class.
+     *
+     * Render `<scope.Boundary>` to open the scope at runtime; nesting
+     * multiple boundaries from different `app.Scope()` calls is fine,
+     * each runs as an independent emitter shadowed for its subtree.
+     *
+     * The Scope handle deliberately does NOT expose a further `Scope`
+     * method &mdash; the multicast surface must be declared at the
+     * `app.Scope<MulticastActions>()` call site so the type union is explicit.
+     */
+    readonly Scope: <MulticastActions>() => import('../scope/types.ts').ScopeHandle<E, MulticastActions>;
+};
 /**
  * `Context` handle returned by `app.useContext()`. Mirrors the base
- * {@link Context} but threads the App's Env shape `S` through every
+ * {@link Context} but threads the App's Env shape `E` through every
  * handler's `context.env` and produce draft.
  *
  * @template M The model type for the component's state, or `void`.
@@ -49,9 +102,9 @@ type AppUseActions<M, AC, D, S> = M extends void ? (getData?: Data<D & Props>) =
  *   definitions, or `void` for actions-only consumers.
  * @template D The reactive data type returned from the `useActions(...)`
  *   data callback.
- * @template S The App's Env shape, supplied at `App({env})` time.
+ * @template E The App's Env shape, supplied at `App({env})` time.
  */
-export type AppContextHandle<M, AC, D, S> = {
+export type AppContextHandle<M, AC, D, E> = {
     /**
      * Stable dispatch surface available before `useActions(...)` runs.
      * Exposes only `dispatch(action, payload?)` &mdash; useful when an
@@ -77,6 +130,6 @@ export type AppContextHandle<M, AC, D, S> = {
      * second &mdash; the callback re-runs every render so handlers reading
      * `context.data` always see fresh values across `await` boundaries.
      */
-    readonly useActions: AppUseActions<M, AC, D, S>;
+    readonly useActions: AppUseActions<M, AC, D, E>;
 };
 export {};

package/dist/boundary/components/env/index.d.ts

@@ -3,17 +3,28 @@ import * as React from "react";
 export { useEnv } from './utils';
 /**
  * Loose runtime shape for the per-`<Boundary>` Env. Each {@link App}
- * narrows this to its own typed env via `App<S>({ env })`; the
+ * narrows this to its own typed env via `App<E>({ env })`; the
  * loose type exists so the framework's internal plumbing
  * (`<Boundary>`, `useEnv`, handler `context.env`, Resource
- * fetcher `context.env`) does not need to be parametric over S.
+ * fetcher `context.env`) does not need to be parametric over E.
  *
  * Consumers should declare their Env shape inline via `App({ env })`
- * &mdash; the inferred `S` is what flows through `app.useContext`,
+ * &mdash; the inferred `E` is what flows through `app.useContext`,
  * `app.useEnv`, and `app.Resource`. Module augmentation of `Env`
  * is no longer required.
  */
 export type Env = Record<string, unknown>;
+/**
+ * `E` generic for `shared.X<E, ...>` factories whose callers don't read
+ * anything off the Env. Equivalent to `Record<never, never>` &mdash; the
+ * named alias keeps consumer sites legible (`shared.Resource<Envless, T>`
+ * over `shared.Resource<Record<never, never>, T>`) and signals intent.
+ *
+ * Reach for `Envless` only when the component or resource is genuinely
+ * Env-agnostic. Anything that reads `context.env.x` should declare the
+ * required shape (or a union of host Envs) as `E` instead.
+ */
+export type Envless = Record<never, never>;
 /**
  * Provides a per-Boundary {@link Env} value to every component inside
  * the boundary. Usually wired in via the `<Boundary env={initial}>`

package/dist/boundary/components/sharing/index.d.ts

@@ -1,8 +1,8 @@
-import { PendingCall } from '../../../resource/index';
+import { Invocation } from '../../../resource/index';
 import * as React from "react";
 /**
  * Per-`<Boundary>` registry for `.coalesce(token)` sharing. Outer map
- * keys on the `PendingCall.run` function identity (stable per Resource
+ * keys on the `Invocation.run` function identity (stable per Resource
  * via the `build()` closure); inner map keys on
  * `${paramsKey}|${coalesceKey(token)}`. While an entry exists every
  * caller awaiting `.coalesce(token)` for the same Resource + params +
@@ -14,7 +14,7 @@ import * as React from "react";
  *
  * @internal
  */
-export type Sharing = WeakMap<PendingCall["run"], Map<string, Promise<unknown>>>;
+export type Sharing = WeakMap<Invocation<unknown, object>["run"], Map<string, Promise<unknown>>>;
 /**
  * React context exposing the per-Boundary sharing registry. The
  * fallback is a fresh `WeakMap` used when `useSharing()` is read

package/dist/boundary/index.d.ts

@@ -5,9 +5,9 @@ import * as React from "react";
  * Env, and Tasks providers required by every March Hare hook.
  *
  * Most applications should reach for {@link App} instead —
- * `App<S>({ env })` returns a typed `app.Boundary` along with
+ * `App<E>({ env })` returns a typed `app.Boundary` along with
  * matching `useContext` / `useEnv` / `Resource` factories that all
- * close over the App's inferred env shape `S`. The bare `Boundary`
+ * close over the App's inferred env shape `E`. The bare `Boundary`
  * is exposed for advanced or library-internal use where the loose
  * Env record type is sufficient.
  *

package/dist/boundary/types.d.ts

@@ -18,7 +18,7 @@ import type * as React from "react";
 export type Props = {
     /**
      * Initial value of the per-Boundary {@link Env}. Prefer `App({ env })`
-     * — it infers the Env shape `S` and threads it through
+     * — it infers the Env shape `E` and threads it through
      * `app.useContext`, `app.useEnv`, and `app.Resource`, so handler
      * `context.env` is typed accordingly. Pass `env` directly here only
      * for advanced cases where the loose record type is sufficient.

package/dist/cache/index.d.ts

@@ -2,18 +2,28 @@ import { Adapter, Stored } from './types';
 export type { Adapter, Encoded } from './types';
 /**
  * Persistence-aware cache for a single {@link Resource}. Wraps a
- * synchronous {@link Adapter} (localStorage, MMKV, chrome.storage with a
- * sync facade, etc.) and traffics in {@link Stored} envelopes —
- * storage entries serialise as {@link Encoded}`<T>` so the
- * `Temporal.Instant` timestamp survives the string round-trip and
- * `.exceeds({...})` can short-circuit on the persisted timestamp after
- * a reload.
+ * **strictly synchronous** {@link Adapter} (localStorage, MMKV,
+ * chrome.storage with a sync facade, etc.) and traffics in {@link
+ * Stored} envelopes &mdash; storage entries serialise as {@link
+ * Encoded}`<T>` so the `Temporal.Instant` timestamp survives the
+ * string round-trip and `.exceeds({...})` can short-circuit on the
+ * persisted timestamp after a reload.
+ *
+ * Every method on the Cache is sync &mdash; the model-literal sync
+ * read has no place to wait, so the adapter contract foregoes
+ * `Promise` entirely. Async backends (IndexedDB, AsyncStorage,
+ * `chrome.storage.local`) need a sync facade hydrated at app entry;
+ * see `recipes/storage.md` for the pattern. React Native projects
+ * should reach for {@link https://github.com/mrousavy/react-native-mmkv
+ * `react-native-mmkv`} &mdash; it's synchronous out of the box and
+ * drops straight into the Adapter contract.
  *
  * Call with no arguments for an in-memory cache scoped to this
- * instance &mdash; useful for tests, ephemeral state, or when you want a
- * first-class cache object to share between Resources without
+ * instance &mdash; useful for tests, ephemeral state, or when you
+ * want a first-class cache object to share between Resources without
  * persistence. Pass an {@link Adapter} to back the cache with a
- * persistent store.
+ * persistent store; when supplied, the adapter is the **only** tier
+ * &mdash; the Cache does not maintain a separate in-memory mirror.
  *
  * @example
  * ```ts
@@ -36,9 +46,55 @@ export type { Adapter, Encoded } from './types';
  * ```
  */
 export type Cache = {
+    /**
+     * Returns the {@link Stored} envelope for `key`. The envelope is
+     * `empty()` when nothing is persisted; otherwise it carries the
+     * decoded payload and the timestamp recorded at write-time.
+     *
+     * @template T The payload type expected at `key`.
+     * @param key Cache slot identifier &mdash; usually the JSON-stringified
+     *   call-site params, prefixed by the Resource's namespace.
+     */
     get<T>(key: string): Stored<T>;
-    set<T>(key: string, value: Stored<T>): boolean;
+    /**
+     * Writes `value` to `key`. Skipped when the envelope has no concrete
+     * payload (e.g. an `empty()` slot), since there is nothing meaningful
+     * to persist. Serialisation, quota errors, and unserialisable payloads
+     * are swallowed &mdash; writes are best-effort.
+     *
+     * @template T The payload type contained in `value`.
+     * @param key Cache slot identifier &mdash; usually the JSON-stringified
+     *   call-site params, prefixed by the Resource's namespace.
+     * @param value Stored envelope carrying the payload and its
+     *   write-time `Temporal.Instant`.
+     */
+    set<T>(key: string, value: Stored<T>): void;
+    /**
+     * Drops a single cache slot. Best-effort &mdash; backing-store errors
+     * are swallowed.
+     *
+     * @param key Cache slot identifier.
+     */
     remove(key: string): void;
+    /**
+     * Drops every cache slot in the backing store. Best-effort &mdash;
+     * backing-store errors are swallowed.
+     */
     clear(): void;
+    /**
+     * Returns every key currently held by the backing store. Used by
+     * partial-match eviction (`evict(where)`) to iterate slots whose
+     * stored params satisfy a `where` pattern.
+     */
+    keys(): Iterable<string>;
 };
+/**
+ * Constructs a {@link Cache} backed by `adapter`, or by an in-memory
+ * `Map` when none is supplied. The returned object is the same shape
+ * regardless &mdash; only the durability differs.
+ *
+ * @param adapter Optional synchronous backing store (localStorage, MMKV,
+ *   or a custom sync facade). Omit for an in-memory cache scoped to
+ *   this instance.
+ */
 export declare function Cache(adapter?: Adapter): Cache;