march-hare 0.8.0 → 0.9.0

package/README.md

@@ -19,6 +19,14 @@
 
 1. [Benefits](#benefits)
 1. [Getting started](#getting-started)
+1. [Async resources](#async-resources)
+1. [Reactive data](#reactive-data)
+1. [Broadcast actions](#broadcast-actions)
+1. [Remote data with `Resource`](#remote-data-with-resource)
+1. [Channeled actions](#channeled-actions)
+1. [Multicast actions](#multicast-actions)
+1. [Global data](#global-data)
+1. [Toggling boolean state](#toggling-boolean-state)
 
 For advanced topics, see the [recipes directory](./recipes/).
 
@@ -38,15 +46,34 @@ For advanced topics, see the [recipes directory](./recipes/).
 - Granular async state tracking per model field.
 - Declarative lifecycle hooks without `useEffect`.
 - Centralised error handling via the global `Lifecycle.Fault` broadcast.
-- View-side reactivity for the per-`<Boundary>` Store via the global `Lifecycle.Store` broadcast.
+- View-side reactivity for the per-`<app.Boundary>` Env via the global `Lifecycle.Env` broadcast.
 - React Native compatible &ndash; uses [eventemitter3](https://github.com/primus/eventemitter3) for cross-platform pub/sub.
 
 ## Getting started
 
-We dispatch the `Actions.Name` event upon clicking the "Sign in" button and within the component we subscribe to that same event via `useContext` so that when it's triggered it updates the model with the payload &ndash; in the React component we render `model.name`. The `With.Update` helper binds the action's payload directly to a model property.
+Declare your app once via `App()` &ndash; the returned handle is the entrypoint for every typed primitive: `app.Boundary`, `app.useContext`, `app.useEnv`, `app.Resource`. Render `<app.Boundary>` once at the root and import `app` wherever you need it. Pass `{ env }` only when your app needs ambient state ([see Global data below](#global-data)):
+
+```ts
+// app.ts
+import { App } from "march-hare";
+
+export const app = App();
+```
 
 ```tsx
-import { useContext, Action, With } from "march-hare";
+// index.tsx
+import { app } from "./app";
+
+<app.Boundary>
+  <Root />
+</app.Boundary>;
+```
+
+Inside a feature, define the model + actions, write a `useActions` hook that wires handlers, and destructure `[model, actions]` from it in the component. We dispatch the `Actions.Name` event on click, subscribe to it via `app.useContext`, and `With.Update` binds the payload directly to a model property:
+
+```tsx
+import { Action, With } from "march-hare";
+import { app } from "./app";
 
 type Model = {
   name: string | null;
@@ -61,7 +88,7 @@ export class Actions {
 }
 
 function useActions() {
-  const context = useContext<Model, typeof Actions>();
+  const context = app.useContext<Model, typeof Actions>();
   const actions = context.useActions(model);
 
   actions.useAction(Actions.Name, With.Update("name"));
@@ -84,151 +111,231 @@ export default function Profile(): React.ReactElement {
 }
 ```
 
-When you need to do more than just assign the payload &ndash; such as making an API request &ndash; expand `useAction` to a full function. It can be synchronous, asynchronous, or even a generator. Remote data goes through `Resource` rather than a bare `fetch` &ndash; declare the resource at module scope, fetch from handlers via `context.actions.resource(...)`:
+This shape &ndash; `useActions` hook, `[model, actions]` destructure in the component &ndash; is the canonical pattern used throughout this README.
+
+## Async resources
+
+When the handler needs to do more than assign the payload &ndash; an API call, for example &ndash; expand `useAction` to a full function. Remote data goes through `app.Resource` rather than a bare `fetch`: declare the resource at module scope, fetch via `context.actions.resource(...)`:
 
 ```ts
 // resources.ts
-import { Resource } from "march-hare";
+import { app } from "./app";
 
-export const user = Resource(({ controller }) =>
-  ky.get(api.user(), { signal: controller.signal }).json<User>(),
+export const user = app.Resource<User>((context) =>
+  ky.get(api.user(), { signal: context.controller.signal }).json<User>(),
 );
 ```
 
 ```tsx
-actions.useAction(Actions.Name, async (context) => {
-  context.actions.produce(
-    ({ model }) =>
-      void (model.name = context.actions.annotate(model.name, Op.Update)),
-  );
+import { Action, Op } from "march-hare";
+import { app } from "./app";
+import * as resource from "./resources";
 
-  // Auto-threads context.task.controller and the Store snapshot.
-  const data = await context.actions.resource(user());
+type Model = { name: string | null };
+const model: Model = { name: null };
 
-  context.actions.produce(({ model }) => void (model.name = data.name));
-});
+export class Actions {
+  static Name = Action<string>("Name");
+}
+
+function useActions() {
+  const context = app.useContext<Model, typeof Actions>();
+  const actions = context.useActions(model);
+
+  actions.useAction(Actions.Name, async (context) => {
+    context.actions.produce(
+      ({ model }) =>
+        void (model.name = context.actions.annotate(model.name, Op.Update)),
+    );
+
+    // Auto-threads context.task.controller and the Env snapshot.
+    const user = await context.actions.resource(resource.user());
+
+    context.actions.produce(({ model }) => void (model.name = user.name));
+  });
+
+  return actions;
+}
+
+export default function Profile(): React.ReactElement {
+  const [model, actions] = useActions();
+  return <p>Hey {model.name}</p>;
+}
 ```
 
-Notice we're using `annotate` which you can read more about in the [Immertation documentation](https://github.com/Wildhoney/Immertation). Once the request is finished we update the model again with the name fetched from the response and re-render the React component. `Resource` caches the most recent successful payload and exposes typed params &ndash; the full API is covered [further down](#remote-data).
+`annotate` is covered in the [Immertation documentation](https://github.com/Wildhoney/Immertation). Once the request resolves we update the model again with the fetched name. `app.Resource` caches the most recent successful payload and exposes typed params &ndash; the full API is covered [further down](#remote-data-with-resource).
+
+## Reactive data
 
-If you need to access external reactive values (like props or `useState` from parent components) that always reflect the latest value even after `await` operations, pass a data callback to `context.useActions`. The same snapshot is exposed as the third tuple element so JSX and handlers read from a single named source:
+If you need to access external reactive values (props or `useState` from parent components) that always reflect the latest value even after `await` operations, pass a data callback as the second argument to `context.useActions`. The same snapshot is exposed as the third tuple element so JSX and handlers read from a single named source:
 
 ```tsx
-const context = useContext<Model, typeof Actions, { query: string }>();
-const actions = context.useActions(
-  model,
-  () => ({
-    query: props.query,
-  }),
-);
+import { Action } from "march-hare";
+import { app } from "./app";
+import * as resource from "./resources";
 
-actions.useAction(Actions.Search, async (context) => {
-  const results = await context.actions.resource(
-    search({ query: context.data.query }),
-  );
-  // context.data.query is always the latest value, even after await
-  console.log(context.data.query, results);
-});
+type Model = { results: Result[] };
+const model: Model = { results: [] };
 
-return <input value={data.query} onChange={…} />;
-```
+type Props = { query: string };
 
-`data` is read-only from the view side &ndash; handlers read fresh values via `context.data` (Proxy delegating to a ref kept current across `await`s), JSX reads via the third tuple element (the same Proxy, refreshed synchronously each render). If a handler needs to _react_ to a change in `data`, subscribe to `Lifecycle.Update()` &mdash; it fires whenever `getData`'s result differs from the previous render. For more details, see the [referential equality recipe](./recipes/referential-equality.md) and the [React context in handlers recipe](./recipes/react-context-in-handlers.md).
+export class Actions {
+  static Search = Action<string>("Search");
+}
 
-When an external library needs the dispatch callback at construction time (form libraries, animation engines) _and_ its return value must flow back into `context.useActions` via the data callback, there's a chicken-and-egg &mdash; each side wants the other to exist first. `useContext` resolves this by returning a stable handle up-front: `context.actions.dispatch` is callable from the first line, the external library closes over it, and `context.useActions(initialModel, getData?)` completes the binding once the external value is in scope. See the [`useContext` recipe](./recipes/use-context.md) for the full pattern.
+function useActions(props: Props) {
+  const context = app.useContext<Model, typeof Actions, Props>();
+  const actions = context.useActions(model, () => ({ query: props.query }));
+
+  actions.useAction(Actions.Search, async (context) => {
+    const search = await context.actions.resource(
+      resource.search({ query: context.data.query }),
+    );
+    // context.data.query is always the latest value, even after await.
+    context.actions.produce(({ model }) => void (model.results = search));
+  });
+
+  return actions;
+}
 
-The model defaults to `void`, so you can call `context.useActions()` with no generics or initial state when only handlers are needed:
+export default function Search(props: { query: string }): React.ReactElement {
+  const [, actions, data] = useActions(props);
+
+  return (
+    <input
+      value={data.query}
+      onChange={(event) => actions.dispatch(Actions.Search, event.target.value)}
+    />
+  );
+}
+```
+
+`data` is read-only from the view side &ndash; handlers read fresh values via `context.data` (Proxy delegating to a ref kept current across `await`s); JSX reads via the third tuple element (the same Proxy, refreshed synchronously each render). If a handler needs to _react_ to a change in `data`, subscribe to `Lifecycle.Update()` &mdash; it fires whenever `getData`'s result differs from the previous render. See the [referential equality recipe](./recipes/referential-equality.md) and the [React context in handlers recipe](./recipes/react-context-in-handlers.md) for more.
+
+When an external library needs the dispatch callback at construction time (form libraries, animation engines) _and_ its return value must flow back into `context.useActions` via the data callback, there's a chicken-and-egg &mdash; each side wants the other to exist first. `app.useContext` resolves this by returning a stable handle up-front: `context.actions.dispatch` is callable from the first line, the external library closes over it, and `context.useActions(initialModel, getData?)` completes the binding once the external value is in scope:
 
 ```tsx
-import { useContext, Lifecycle } from "march-hare";
+import { Action } from "march-hare";
+import { app } from "./app";
+import * as resource from "./resources";
+import { useForm } from "some-form-library";
 
-class Actions {
-  static Mount = Lifecycle.Mount();
+type Model = { saving: boolean };
+
+export class Actions {
+  static Submit = Action("Submit");
 }
 
-const context = useContext<void, typeof Actions>();
-const actions = context.useActions();
+function useActions() {
+  // 1. The handle is ready immediately — `context.actions.dispatch` is callable
+  //    before `context.useActions(...)` runs.
+  const context = app.useContext<Model, typeof Actions, { form: FormApi }>();
+
+  // 2. The external library closes over `context.actions.dispatch` at
+  //    construction time. The form's `onSubmit` fires a Submit action.
+  const form = useForm({
+    onSubmit: () => void context.actions.dispatch(Actions.Submit),
+  });
 
-actions.useAction(Actions.Mount, () => {
-  console.log("Mounted!");
-});
+  // 3. The form value (`form`) flows back into the data callback so handlers
+  //    read it via `context.data.form`.
+  const actions = context.useActions({ saving: false }, () => ({ form }));
+
+  actions.useAction(Actions.Submit, async (context) => {
+    context.actions.produce(({ model }) => void (model.saving = true));
+    await context.actions.resource(resource.save(context.data.form.values));
+    context.actions.produce(({ model }) => void (model.saving = false));
+  });
+
+  return actions;
+}
 ```
 
-If your component doesn't need local state but still needs to dispatch or listen to typed actions, call `context.useActions()` with no initial model. No state is allocated:
+See the [`useContext` recipe](./recipes/use-context.md) for the full pattern.
+
+The model defaults to `void`, so a component that only coordinates via events &mdash; forwarding broadcasts, triggering side-effects, bridging external systems &mdash; can call `context.useActions()` with no initial model:
 
 ```tsx
-import { useContext, Action, Lifecycle } from "march-hare";
+import { Action } from "march-hare";
+import { app } from "./app";
 
 export class Actions {
   static Ping = Action("Ping");
 }
 
-export default function Pinger(): React.ReactElement {
-  const context = useContext<void, typeof Actions>();
+function useActions() {
+  const context = app.useContext<void, typeof Actions>();
   const actions = context.useActions();
 
   actions.useAction(Actions.Ping, () => {
     console.log("Pinged!");
   });
 
+  return actions;
+}
+
+export default function Pinger(): React.ReactElement {
+  const [, actions] = useActions();
   return <button onClick={() => actions.dispatch(Actions.Ping)}>Ping</button>;
 }
 ```
 
-This is useful for components that only coordinate via events &ndash; forwarding broadcasts, triggering side-effects, or bridging external systems. You can still use lifecycle hooks, `context.data`, and `dispatch` as normal. See the [void model recipe](./recipes/void-model.md) for more details.
+You can still use lifecycle hooks, `context.data`, and `dispatch` as normal. See the [void model recipe](./recipes/void-model.md) for more.
 
-Each action should be responsible for managing its own data &ndash; in this case our `Profile` action handles fetching the user but other components may want to consume it &ndash; for that we should use a broadcast action:
+## Broadcast actions
+
+Each action should be responsible for its own data &mdash; in the `Profile` example above, the handler fetches the user but other components may want to consume the result. For that, use a broadcast action:
+
+```ts
+// actions.ts (excerpt)
+import { Action, Distribution } from "march-hare";
 
-```tsx
 class BroadcastActions {
   static Name = Action<string>("Name", Distribution.Broadcast);
 }
 
-class Actions {
+export class Actions {
   static Broadcast = BroadcastActions;
   static Profile = Action<string>("Profile");
 }
 ```
 
-```tsx
+Inside `useActions`, the handler fetches the user and then dispatches the broadcast so siblings see the result:
+
+```ts
 actions.useAction(Actions.Profile, async (context) => {
   context.actions.produce(
     ({ model }) =>
       void (model.name = context.actions.annotate(model.name, Op.Update)),
   );
 
-  const data = await context.actions.resource(user());
+  const user = await context.actions.resource(resource.user());
 
-  context.actions.produce(({ model }) => void (model.name = data.name));
+  context.actions.produce(({ model }) => void (model.name = user.name));
 
-  context.actions.dispatch(Actions.Broadcast.Name, data.name);
+  context.actions.dispatch(Actions.Broadcast.Name, user.name);
 });
 ```
 
-Once we have the broadcast action, if we want to listen for it and perform another operation in our local component we can do that via `useAction`:
+Any component whose `useActions` subscribes to the broadcast receives it:
 
-```tsx
+```ts
 actions.useAction(Actions.Broadcast.Name, async (context, name) => {
-  const data = await context.actions.resource(friends({ name }));
-
-  context.actions.produce(({ model }) => void (model.friends = data));
+  const friends = await context.actions.resource(resource.friends({ name }));
+  context.actions.produce(({ model }) => void (model.friends = friends));
 });
 ```
 
-Both `read` and `peek` access the latest cached broadcast value without subscribing via `useAction`. The difference is that `read` waits for any pending annotations on the corresponding model field to settle before resolving, whereas `peek` returns the value immediately:
+`context.actions.final(...)` and `context.actions.peek(...)` access the latest cached broadcast value without subscribing via `useAction`. `final` waits for any pending annotations on the corresponding model field to settle; `peek` returns immediately:
 
-```tsx
+```ts
 actions.useAction(Actions.FetchFriends, async (context) => {
-  const name = await context.actions.resolution(Actions.Broadcast.Name);
+  const name = await context.actions.final(Actions.Broadcast.Name);
   if (!name) return;
-  const data = await context.actions.resource(friends({ name }));
-  context.actions.produce(({ model }) => void (model.friends = data));
+  const friends = await context.actions.resource(resource.friends({ name }));
+  context.actions.produce(({ model }) => void (model.friends = friends));
 });
-```
-
-`peek` is useful for guard checks or synchronous reads where you don't need to wait for settled state:
 
-```tsx
 actions.useAction(Actions.Check, (context) => {
   const name = context.actions.peek(Actions.Broadcast.Name);
   if (!name) return;
@@ -236,9 +343,9 @@ actions.useAction(Actions.Check, (context) => {
 });
 ```
 
-Dispatch is awaitable &ndash; `context.actions.dispatch` returns a `Promise<void>` that resolves when all triggered handlers have completed. This prevents UI flashes where local state changes before upstream handlers finish:
+Dispatch is awaitable &ndash; `context.actions.dispatch` returns a `Promise<void>` that resolves when every triggered handler has completed. This prevents UI flashes where local state changes before upstream handlers finish:
 
-```tsx
+```ts
 actions.useAction(Actions.Mount, async (context) => {
   // Wait for all PaymentSent handlers across the app to finish.
   await context.actions.dispatch(Actions.Broadcast.PaymentSent);
@@ -253,13 +360,27 @@ Generator handlers are excluded from the await &mdash; they run in the backgroun
 You can also render broadcast values declaratively in JSX with `actions.stream`. The renderer callback receives `(value, inspect)` and returns React nodes:
 
 ```tsx
-function Dashboard() {
-  const context = useContext<Model, typeof Actions>();
-  const actions = context.useActions(initialModel);
+import { app } from "./app";
+
+type Model = {
+  /* ... */
+};
+const model: Model = {
+  /* ... */
+};
+
+function useActions() {
+  const context = app.useContext<Model, typeof Actions>();
+  const actions = context.useActions(model);
+  return actions;
+}
+
+export default function Dashboard(): React.ReactElement {
+  const [, actions] = useActions();
 
   return (
     <div>
-      {actions.stream(Actions.Broadcast.User, (user, inspect) => (
+      {actions.stream(Actions.Broadcast.User, (user) => (
         <span>Welcome, {user.name}</span>
       ))}
     </div>
@@ -269,88 +390,126 @@ function Dashboard() {
 
 Components that mount after a broadcast has already been dispatched automatically receive the cached value via their `useAction` handler. If you also fetch data in `Lifecycle.Mount()`, see the [mount deduplication recipe](./recipes/mount-broadcast-deduplication.md) to avoid duplicate requests.
 
-<a id="remote-data"></a>
+## Remote data with `Resource`
 
-For remote data, declare a `Resource` at module scope and use it directly. `user(params)` is the unified call form &mdash; it returns the sync cache read (`User | null`) and primes a slot that `context.actions.resource(user(params))` consumes for the fetch path (with auto-threaded abort controller and Store snapshot). 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 them in with named imports:
+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 Env snapshot). 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
-import { Resource } from "march-hare";
+import { app } from "./app";
 
-export const user = Resource(({ controller }) =>
-  ky.get("/api/user", { signal: controller.signal }).json<User>(),
+export const user = app.Resource<User>((context) =>
+  ky.get("/api/user", { signal: context.controller.signal }).json<User>(),
 );
 
-export const pay = Resource<Receipt, Body>(({ controller, params }) =>
+export const pay = app.Resource<Receipt, Body>((context) =>
   ky
-    .post("/api/pay", { json: params, signal: controller.signal })
+    .post("/api/pay", {
+      json: context.params,
+      signal: context.controller.signal,
+    })
     .json<Receipt>(),
 );
 ```
 
 ```tsx
-// actions.ts
-import { useContext } from "march-hare";
-import { user, pay } from "./resources";
+// profile/actions.ts
+import { Action, Lifecycle, type Maybe } from "march-hare";
+import { app } from "../app";
+import * as resource from "../resources";
 
-export function useActions() {
-  const context = useContext<Model, typeof Actions>();
+type Model = { user: Maybe<User>; receipt: Maybe<Receipt> };
 
+export class Actions {
+  static Mount = Lifecycle.Mount();
+  static Submit = Action<Body>("Submit");
+}
+
+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: user(),
+    user: resource.user(),
     receipt: null,
   });
 
   actions.useAction(Actions.Mount, async (context) => {
-    const data = await context.controller
-      .resource(user())
+    const user = await context.actions
+      .resource(resource.user())
       .exceeds({ minutes: 5 });
-    context.actions.produce(({ model }) => void (model.user = data));
+    context.actions.produce(({ model }) => void (model.user = user));
   });
 
   actions.useAction(Actions.Submit, async (context, body) => {
-    const receipt = await context.actions.resource(pay(body));
-    context.actions.produce(({ model }) => void (model.receipt = receipt));
+    const pay = await context.actions.resource(resource.pay(body));
+    context.actions.produce(({ model }) => void (model.receipt = pay));
   });
 
   return actions;
 }
+
+export default function Profile(): React.ReactElement {
+  const [model, actions] = useActions();
+  // ...
+}
 ```
 
-`context.actions.resource(invocation)` returns a thenable. Awaiting it fires the fetch unconditionally; chaining `.exceeds({ minutes: 5 })` short-circuits when the per-params cache age does not yet exceed the supplied freshness window. `.exceeds(duration)` accepts a `Temporal.Duration`, a `DurationLike` object, or an ISO 8601 duration string. `Temporal` is read from the host runtime &ndash; bring a polyfill (e.g. [`@js-temporal/polyfill`](https://github.com/js-temporal/temporal-polyfill)) if your target environment does not yet expose it natively.
+`context.actions.resource(invocation)` returns a chainable thenable:
 
-`Resource` takes a single fetcher argument. The fetcher receives `{ store, controller, params }` &mdash; destructure whichever you need. There are no callbacks &ndash; no `onSuccess`, no `onError`, no injected `dispatch`. Side-effects after a run (broadcasting, analytics, model writes) live in the `useAction` handler that awaited the call, next to the rest of the flow:
+- `.exceeds({ minutes: 5 })` &mdash; short-circuits when the per-params cache age is within the freshness window. Accepts a `Temporal.Duration`, a `DurationLike` object, or an ISO 8601 duration string. `Temporal` is read from the host runtime &ndash; bring a polyfill (e.g. [`@js-temporal/polyfill`](https://github.com/js-temporal/temporal-polyfill)) if your target doesn't expose it natively.
+- `.coalesce()` &mdash; opts the call into in-flight sharing. Any other caller with the same Resource and same structural params receives the same promise. The shared fetch uses a detached `AbortController` so a single caller's abort never cancels work other callers are waiting on; each caller still sees its own `context.task.controller` abort as a rejection of its personal await.
 
 ```ts
-export const user = Resource(({ controller }) =>
-  ky.get("/api/user", { signal: controller.signal }).json<User>(),
-);
-
+// Mount and a broadcast handler both fire on mount — only one network request.
 actions.useAction(Actions.Mount, async (context) => {
-  const data = await context.actions.resource(user());
-  await context.actions.dispatch(Actions.Broadcast.UserUpdated, data);
-  context.actions.produce(({ model }) => void (model.user = data));
+  const user = await context.actions.resource(resource.user()).coalesce();
+  context.actions.produce(({ model }) => void (model.user = user));
+});
+
+actions.useAction(Actions.Broadcast.UserId, async (context, id) => {
+  const user = await context.actions.resource(resource.user({ id })).coalesce();
+  context.actions.produce(({ model }) => void (model.user = user));
+});
+```
+
+For finer-grained control &mdash; separating concurrent fetches into distinct coalesce groups via a token argument &mdash; see the [coalesce tokens recipe](./recipes/coalesce-tokens.md).
+
+The fetcher receives a `context` object &mdash; read fields via `context.env`, `context.controller`, `context.params`. There are no callbacks &ndash; no `onSuccess`, no `onError`. The `context.dispatch` field can fire broadcast or multicast actions from inside the fetcher (unicast is rejected at compile time), but most side-effects (model writes, analytics) belong in the `useAction` handler that awaited the call:
+
+```ts
+// resources.ts
+export const user = app.Resource<User>(async (context) => {
+  const data = await ky
+    .get("/api/user", { signal: context.controller.signal })
+    .json<User>();
+  await context.dispatch(Actions.Broadcast.UserUpdated, data);
+  return data;
 });
 ```
 
-`params` is the second generic on `Resource` and defaults to `{}`. Declare it when the fetcher needs call-time inputs &ndash; cursors, ids, query strings, request bodies. `params` is a single object (not positional args), which keeps call sites self-documenting:
+`params` is the second generic on `app.Resource` and defaults to `{}`. Declare it when the fetcher needs call-time inputs &ndash; cursors, ids, query strings, request bodies:
 
 ```ts
 type Params = { cursor: string | null };
 
-export const feed = Resource<Page<Item>, Params>(({ controller, params }) =>
+export const feed = app.Resource<Page<Item>, Params>((context) =>
   http
     .get("feed", {
-      searchParams: { cursor: params.cursor ?? "" },
-      signal: controller.signal,
+      searchParams: { cursor: context.params.cursor ?? "" },
+      signal: context.controller.signal,
     })
     .json<Page<Item>>(),
 );
+```
 
-const page = await context.actions.resource(
-  feed({ cursor: context.model.cursor }),
-);
+```ts
+// Inside useActions:
+actions.useAction(Actions.LoadMore, async (context) => {
+  const feed = await context.actions.resource(
+    resource.feed({ cursor: context.model.cursor }),
+  );
+  // ...
+});
 ```
 
 A complete IntersectionObserver-driven infinite-scroll demo lives at [`src/example/transactions/`](./src/example/transactions/) &ndash; mock paginated API, scroll-triggered `LoadMore`, `pending()` guard, broadcast on success.
@@ -360,8 +519,8 @@ For typed failure routing, wrap the call in `try/catch` and use `instanceof` &nd
 ```ts
 actions.useAction(Actions.Mount, async (context) => {
   try {
-    const data = await context.actions.resource(user());
-    context.actions.produce(({ model }) => void (model.user = data));
+    const user = await context.actions.resource(resource.user());
+    context.actions.produce(({ model }) => void (model.user = user));
   } catch (error) {
     if (error instanceof RateLimitedError) {
       await context.actions.dispatch(
@@ -376,13 +535,12 @@ 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.
 
-### Persisting resources across reloads
-
-By default a `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` instance to the `Resource` definition. The Cache writes through to its adapter on every successful run and seeds the per-params slot from storage on first read, so call sites stay free of explicit `store.set` / `store.get` ceremony.
+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:
 
 ```ts
 // resources.ts
-import { Cache, Resource } from "march-hare";
+import { Cache } from "march-hare";
+import { app } from "./app";
 
 const cache = Cache({
   get: (key) => localStorage.getItem(key),
@@ -391,140 +549,204 @@ const cache = Cache({
   clear: () => localStorage.clear(),
 });
 
-export const cat = Resource(
-  async ({ controller }) => fetchCat(controller.signal),
-  cache,
+export const cat = app.Resource.Cachable(cache, (context) =>
+  fetchCat(context.controller.signal),
 );
 ```
 
-```ts
-// actions.ts
-const context = useContext<Model, typeof Actions>();
-const actions = context.useActions({
-  // First render reads the Cache automatically.
-  cat: cat(),
-});
+```tsx
+// cats/actions.ts
+import { Lifecycle, type Maybe } from "march-hare";
+import { app } from "../app";
+import * as resource from "../resources";
 
-actions.useAction(Actions.Mount, async (context) => {
-  // Short-circuits when the persisted payload is < 5 minutes old.
-  // The Cache writes through automatically on success.
-  const fresh = await context.controller
-    .resource(cat())
-    .exceeds({ minutes: 5 });
-  context.actions.produce(({ model }) => void (model.cat = fresh));
-});
+type Model = { cat: Maybe<Cat> };
+
+export class Actions {
+  static Mount = Lifecycle.Mount();
+}
+
+function useActions() {
+  const context = app.useContext<Model, typeof Actions>();
+  const actions = context.useActions({
+    // First render reads the Cache automatically.
+    cat: resource.cat(),
+  });
+
+  actions.useAction(Actions.Mount, async (context) => {
+    // Short-circuits when the persisted payload is < 5 minutes old.
+    // The Cache writes through automatically on success.
+    const cat = await context.actions
+      .resource(resource.cat())
+      .exceeds({ minutes: 5 });
+    context.actions.produce(({ model }) => void (model.cat = cat));
+  });
+
+  return actions;
+}
+
+export default function CatCard(): React.ReactElement {
+  const [model] = useActions();
+  return model.cat ? <img src={model.cat.url} /> : null;
+}
 ```
 
 `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".
 
-For targeted event delivery, use channeled actions. Define a controller type as the second generic argument and call the action with a controller object &ndash; handlers fire when the dispatch controller matches:
+## Channeled actions
+
+For targeted event delivery, use channeled actions. Define a controller type as the second generic argument and call the action with a controller object &ndash; handlers fire only when the dispatch controller matches:
 
 ```tsx
-class Actions {
-  // Second generic arg defines the controller type
+import { Action } from "march-hare";
+import { app } from "./app";
+
+export class Actions {
+  // Second generic arg defines the controller type.
   static UserUpdated = Action<User, { UserId: number }>("UserUpdated");
 }
 
-// Subscribe to updates for a specific user
-actions.useAction(
-  Actions.UserUpdated({ UserId: props.userId }),
-  (context, user) => {
-    // Only fires when dispatched with matching UserId
-  },
-);
+function useActions(props: { userId: number }) {
+  const context = app.useContext<Model, typeof Actions, { userId: number }>();
+  const actions = context.useActions(model, () => ({ userId: props.userId }));
 
-// Subscribe to all admin user updates
-actions.useAction(
-  Actions.UserUpdated({ Role: Role.Admin }),
-  (context, user) => {
-    // Fires for {Role: Role.Admin}, {Role: Role.Admin, UserId: 5}, etc.
-  },
-);
+  // Subscribe to updates for a specific user.
+  actions.useAction(
+    Actions.UserUpdated({ UserId: props.userId }),
+    (context, user) => {
+      // Only fires when dispatched with matching UserId.
+    },
+  );
 
-// Dispatch to specific user
-actions.dispatch(Actions.UserUpdated({ UserId: user.id }), user);
+  return actions;
+}
 
-// Dispatch to all admin handlers
-actions.dispatch(Actions.UserUpdated({ Role: Role.Admin }), user);
+// Dispatch to specific user.
+actions.dispatch(Actions.UserUpdated({ UserId: user.id }), user);
 
-// Dispatch to plain action - ALL handlers fire (plain + all channeled)
+// Dispatch to plain action — ALL handlers fire (plain + all channeled).
 actions.dispatch(Actions.UserUpdated, user);
 ```
 
 Channel values support non-nullable primitives: `string`, `number`, `boolean`, or `symbol`. By convention, use uppercase keys like `{UserId: 4}` to distinguish controller keys from payload properties.
 
-For scoped communication between component groups, use multicast actions with the `withScope` HOC. Each multicast action defines its own scope &ndash; pass the same action to `withScope` and to `dispatch`, no separate scope name required:
+## Multicast actions
 
-```tsx
-import { Action, Distribution, withScope } from "march-hare";
+For scoped communication between component groups, declare a multicast action class and open a scope via `app.Scope<typeof MulticastActions>()`. The generic carries the multicast surface at the type level &mdash; `scope.useContext().actions.dispatch` widens to include those actions on top of the local `Actions` class, the same way `Actions.Broadcast = BroadcastActions` widens for broadcasts. Render `<scope.Boundary>` once at the root of the subtree the scope governs:
 
-// Group multicast actions on a class named `Scope`.
-class Scope {
+```ts
+// scope/types.ts — multicast action class, kept separate from the local Actions.
+import { Action, Distribution } from "march-hare";
+
+export class MulticastActions {
   static Update = Action<number>("Update", Distribution.Multicast);
 }
+```
 
-class Actions {
-  static Increment = Action("Increment");
-}
+```tsx
+// scope/index.tsx — open the scope once.
+import { app } from "../app";
+import type { MulticastActions } from "./types";
+import ScoreBoard from "./components/score-board";
+import PlayerList from "./components/player-list";
+
+export const scope = app.Scope<typeof MulticastActions>();
 
-function ScoreArea() {
+export default function ScoreArea(): React.ReactElement {
   return (
-    <>
+    <scope.Boundary>
       <ScoreBoard />
       <PlayerList />
-    </>
+    </scope.Boundary>
   );
 }
+```
 
-// Wrap the subtree where the scope applies.
-export default withScope(Scope.Update, ScoreArea);
+```tsx
+// scope/components/score-board/actions.ts — subscribe and dispatch from inside.
+import { Action } from "march-hare";
+import { scope } from "../../index";
+import { MulticastActions } from "../../types";
 
-// Dispatch to every component inside the scope.
-actions.dispatch(Scope.Update, 42);
+type Model = { score: number };
+
+// Like `Broadcast`, you also list the multicast surface on the local
+// Actions class so the bound dispatch sees it on `Actions.Multicast.*`.
+export class Actions {
+  static Multicast = MulticastActions;
+  static Increment = Action("Increment");
+}
+
+export function useActions() {
+  const context = scope.useContext<Model, typeof Actions>();
+  const actions = context.useActions({ score: 0 });
+
+  actions.useAction(MulticastActions.Update, (context, score) => {
+    context.actions.produce(({ model }) => void (model.score = score));
+  });
+
+  actions.useAction(Actions.Increment, (context) => {
+    context.actions.dispatch(MulticastActions.Update, context.model.score + 1);
+  });
+
+  return actions;
+}
 ```
 
-Unlike broadcast which reaches all mounted components, multicast is confined to the wrapped subtree &ndash; perfect for isolated widget groups, form sections, or distinct UI regions. Like broadcast, multicast caches dispatched values per scope &ndash; components that mount later automatically receive the cached value. See the [mount deduplication recipe](./recipes/mount-broadcast-deduplication.md) if you also fetch data in `Lifecycle.Mount()`.
+A few rules worth knowing:
+
+- **Scope is confined to the subtree.** Multicast dispatches inside `<scope.Boundary>` reach every subscriber inside the same boundary, and only those subscribers. Sibling boundaries don't see each other; nothing outside any boundary sees them either.
+- **Nesting shadows.** `<scope.Boundary>` is a React context provider, so an inner boundary fully shadows an outer one for its subtree. If you need a single scope to dispatch actions from multiple multicast classes, declare them as a union at the call site &mdash; e.g. `app.Scope<typeof PaymentMulticast | typeof RoomMulticast>()`.
+- **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.
 
-For coordinating between async handlers and threading ambient values (session tokens, locale, feature flags, current operational mode) without re-rendering the JSX tree on every dot read, use the per-`<Boundary>` `Store`. Declare your app's Store shape once via module augmentation, supply the initial value to `<Boundary store={...}>`, read via dot notation (`store.session`, `context.store.locale`), and write via `context.actions.produce(({ store }) => { ... })` &mdash; the same Immer-style recipe used for the model. Every `Resource` fetcher also receives a snapshot of the Store on its args object. When the view side needs to react to Store changes, subscribe to the global `Lifecycle.Store` broadcast &mdash; `actions.useAction(Lifecycle.Store, handler)` for handler-level work and `actions.stream(Lifecycle.Store, (store) => ...)` for JSX. Both seed from the initial Store on mount.
+## Global data
+
+For coordinating between async handlers and threading ambient values (session tokens, locale, feature flags, current operational mode) without re-rendering the JSX tree on every dot read, use the per-`<app.Boundary>` `Env`. Declare your env shape inline on `App({ env })`, read via dot notation (`env.session`, `context.env.locale`), and write via `context.actions.produce(({ env }) => { ... })` &mdash; the same Immer-style recipe used for the model. Every `app.Resource` fetcher also receives a snapshot of the Env on its args object. When the view side needs to react to Env changes, subscribe to the global `Lifecycle.Env` broadcast &mdash; `actions.useAction(Lifecycle.Env, handler)` for handler-level work and `actions.stream(Lifecycle.Env, (env) => ...)` for JSX. Both seed from the initial Env on mount.
 
 ```ts
-import { useContext } from "march-hare";
-
-// Declare your Store's shape once. Every read/write is typed against this.
-declare module "march-hare" {
-  // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
-  interface Store {
-    session: Session | null;
-    operating: "idle" | "signing-out";
-  }
-}
+// app.ts
+import { App, type Maybe } from "march-hare";
 
-// Wire the initial Store into Boundary at app root.
-<Boundary store={{ session: null, operating: "idle" }}>
-  <App />
-</Boundary>;
+export const app = App({
+  env: {
+    session: null as Maybe<Session>,
+    operating: "idle" as "idle" | "signing-out",
+  },
+});
+```
+
+```ts
+// auth/actions.ts — every read/write is typed against the App's env shape.
+import { Action } from "march-hare";
+import { app } from "../app";
+
+export class Actions {
+  static SignOut = Action("SignOut");
+  static Refresh = Action("Refresh");
+}
 
-export function useAuthActions() {
-  const context = useContext<void, typeof Actions>();
+function useActions() {
+  const context = app.useContext<void, typeof Actions>();
   const actions = context.useActions();
 
   actions.useAction(Actions.SignOut, async (context) => {
-    context.actions.produce(({ store }) => {
-      store.operating = "signing-out";
+    context.actions.produce(({ env }) => {
+      env.operating = "signing-out";
     });
     await api.signOut();
-    context.actions.produce(({ store }) => {
-      store.session = null;
-      store.operating = "idle";
+    context.actions.produce(({ env }) => {
+      env.session = null;
+      env.operating = "idle";
     });
   });
 
   actions.useAction(Actions.Refresh, async (context) => {
-    if (context.store.operating === "signing-out") return;
+    if (context.env.operating === "signing-out") return;
     // ...
   });
 
@@ -532,35 +754,84 @@ export function useAuthActions() {
 }
 ```
 
+For the view side, render against `Lifecycle.Env` with `actions.stream` &mdash; the renderer receives the latest Env snapshot and re-runs whenever a `produce(({ env }) => ...)` mutation lands:
+
+```tsx
+import { Lifecycle } from "march-hare";
+import { app } from "./app";
+
+export class Actions {}
+
+function useActions() {
+  const context = app.useContext<void, typeof Actions>();
+  return context.useActions();
+}
+
+export default function Header(): React.ReactElement {
+  const [, actions] = useActions();
+
+  return (
+    <header>
+      {actions.stream(Lifecycle.Env, (env) =>
+        env.session ? (
+          <span>Hi, {env.session.user.name}</span>
+        ) : (
+          <span>Signed out</span>
+        ),
+      )}
+    </header>
+  );
+}
+```
+
+`Lifecycle.Env` seeds with the initial Env on mount, so late-mounting components paint the current value immediately instead of flashing through a null state. Pair `actions.stream` with `actions.useAction(Lifecycle.Env, ...)` when a handler-side reaction is also required.
+
+Multiple `App` instances can coexist in the same tree &mdash; each `<app.Boundary>` owns its own Env with its own type.
+
+## Toggling boolean state
+
 Toggling boolean UI state &ndash; modals, sidebars, drawers &ndash; is one of the most common patterns. Bind a unicast action to a boolean field on the model with `With.Invert`:
 
 ```tsx
-import { useContext, Action, With } from "march-hare";
+import { Action, With } from "march-hare";
+import { app } from "./app";
 
 type Model = {
   paymentDialog: boolean;
   sidebar: boolean;
 };
 
+const model: Model = {
+  paymentDialog: false,
+  sidebar: false,
+};
+
 export class Actions {
   static TogglePaymentDialog = Action("TogglePaymentDialog");
   static ToggleSidebar = Action("ToggleSidebar");
 }
 
-const context = useContext<Model, typeof Actions>();
-const actions = context.useActions({
-  paymentDialog: false,
-  sidebar: false,
-});
+function useActions() {
+  const context = app.useContext<Model, typeof Actions>();
+  const actions = context.useActions(model);
+
+  actions.useAction(Actions.TogglePaymentDialog, With.Invert("paymentDialog"));
+  actions.useAction(Actions.ToggleSidebar, With.Invert("sidebar"));
 
-actions.useAction(Actions.TogglePaymentDialog, With.Invert("paymentDialog"));
-actions.useAction(Actions.ToggleSidebar, With.Invert("sidebar"));
+  return actions;
+}
 
-// Dispatch from anywhere with access to the actions object.
-actions.dispatch(Actions.TogglePaymentDialog);
+export default function Shell(): React.ReactElement {
+  const [model, actions] = useActions();
 
-{
-  model.paymentDialog && <PaymentDialog />;
+  return (
+    <>
+      <button onClick={() => actions.dispatch(Actions.TogglePaymentDialog)}>
+        Pay
+      </button>
+      {model.paymentDialog && <PaymentDialog />}
+    </>
+  );
 }
 ```