march-hare 0.12.1 → 0.13.1

package/README.md

@@ -27,8 +27,9 @@
 1. [Multicast actions](#multicast-actions)
 1. [Global data](#global-data)
 1. [Reusable components](#reusable-components)
+1. [Scaffolding CLI](#scaffolding-cli)
 
-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). To scaffold a new project that mirrors that example, see [`src/cli/`](./src/cli/README.md).
 
 ## Benefits
 
@@ -40,7 +41,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 +394,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 +436,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 +542,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(),
+  }),
 });
+```
+
+```ts
+// resources.ts
+import { app } from "./app";
 
-export const cat = app.Resource.Cachable(cache, (context) =>
+export const cat = app.Resource((context) =>
   fetchCat(context.controller.signal),
 );
 ```
@@ -571,7 +584,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 +607,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 +718,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 +815,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 +892,31 @@ 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.
+
+## Scaffolding CLI
+
+A [Hygen](https://github.com/jondot/hygen)-style scaffolder ships under [`src/cli/`](./src/cli/) as the `mh` binary. It mirrors the layout of [`src/example/`](./src/example/) and the FSD layering rules enforced by `eslint-plugin-boundaries` &mdash; imports flow strictly downward (`app → features → shared`).
+
+```bash
+cd src/cli
+npm install
+npm link          # creates the global `mh` binary
+```
+
+Run it with no arguments for an interactive menu, or drive any leaf command directly:
+
+```bash
+mh                            # banner + interactive menu
+mh init my-project            # bootstrap a new project
+mh feature new add-cat        # add a stateful feature
+mh app new dashboard          # add a page
+mh shared component card      # add a shared component
+mh feature action counter Reset   # inject an Action + handler stub
+```
+
+Every command lives in a tree &mdash; typing `mh feature` opens a sub-menu, typing `mh feature new` prompts for a name, typing `mh feature new add-cat` runs non-interactively. See [`src/cli/README.md`](./src/cli/README.md) for the full command surface, the template format, and instructions for adding your own generators.

package/dist/action/index.d.ts

@@ -1,5 +1,5 @@
-import { HandlerPayload, BroadcastPayload, MulticastPayload, Distribution, Filter } from '../types/index';
-export { getActionSymbol, getLifecycleType, isBroadcastAction, isMulticastAction, getName, isChanneledAction, } from './utils';
+import { HandlerPayload, BroadcastPayload, MulticastPayload, Distribution, Filter } from '../types/index.js';
+export { getActionSymbol, getLifecycleType, isBroadcastAction, isMulticastAction, getName, isChanneledAction, } from './utils.js';
 /**
  * Interface for the Action factory function.
  */

package/dist/action/utils.d.ts

@@ -1,5 +1,5 @@
-import { ChanneledAction, AnyAction } from '../types/index';
-import { ActionId } from '../boundary/components/tasks/types';
+import { ChanneledAction, AnyAction } from '../types/index.js';
+import { ActionId } from '../boundary/components/tasks/types.js';
 /**
  * Extracts the underlying symbol from an action or channeled action.
  * This symbol is used as the event emitter key for dispatching.

package/dist/actions/index.d.ts

@@ -1,5 +1,5 @@
-import { Data } from './types';
-import { Model, Props, Actions, UseActions } from '../types/index';
+import { Data } from './types.js';
+import { Model, Props, Actions, UseActions } from '../types/index.js';
 /**
  * A hook for managing state with actions.
  *

package/dist/actions/types.d.ts

@@ -1,8 +1,8 @@
 import { default as EventEmitter } from 'eventemitter3';
 import { RefObject } from 'react';
-import { Model, HandlerContext, Actions, Props, Tasks, ActionId, Phase, Filter } from '../types/index';
-import { BroadcastEmitter } from '../boundary/components/broadcast/utils';
-import { ScopeContext } from '../boundary/components/scope/types';
+import { Model, HandlerContext, Actions, Props, Tasks, ActionId, Phase, Filter } from '../types/index.js';
+import { BroadcastEmitter } from '../boundary/components/broadcast/utils.js';
+import { ScopeContext } from '../boundary/components/scope/types.js';
 /**
  * Function signature for action handlers registered via `useAction`.
  * Receives the reactive context and payload, returning void or a promise/generator.

package/dist/actions/utils.d.ts

@@ -1,8 +1,8 @@
 import { RefObject } from 'react';
-import { Props, Model, Actions, Filter, ActionId, HandlerPayload, ChanneledAction, HandlerContext } from '../types/index';
+import { Props, Model, Actions, Filter, ActionId, HandlerPayload, ChanneledAction, HandlerContext } from '../types/index.js';
 import { default as EventEmitter } from 'eventemitter3';
-import { Dispatchers, LifecycleConfig, Scope } from './types';
-import { isChanneledAction, getActionSymbol } from '../action/index';
+import { Dispatchers, LifecycleConfig, Scope } from './types.js';
+import { isChanneledAction, getActionSymbol } from '../action/index.js';
 import * as React from "react";
 /**
  * Creates a new object with getters for each property of the input object.

package/dist/app/index.d.ts

@@ -1,67 +1,13 @@
-import { Env } from '../boundary/components/env/index';
-import { Actions, Model, Props } from '../types/index';
-import { Scope } from '../scope/index';
-import { AppContextHandle, AppResource } from './types';
-import { Tap } from '../boundary/components/tap/types';
-import * as React from "react";
-export type { AppArgs, AppContextHandle, AppFetcher, AppResource, } from './types';
+import { Env } from '../boundary/components/env/types.js';
+import { Cache } from '../cache/index.js';
+import { Actions, Model, Props } from '../types/index.js';
+import { AppHandle, AppContextHandle } from './types.js';
+import { Tap } from '../boundary/components/tap/types.js';
+export type { AppArgs, AppContextHandle, AppFetcher, AppResource, } from './types.js';
+export type { AppHandle } from './types.js';
 /**
- * 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 { Args, ResourceHandle } from '../resource/types.js';
+import { Actions, Context, Model, Props, UseActions } from '../types/index.js';
+import { Data } from '../actions/types.js';
+import { Env } from '../boundary/components/env/types.js';
+import { WithHandle } from '../with/types.js';
 /**
  * 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/broadcast/index.d.ts

@@ -1,6 +1,6 @@
-import { Props } from './types';
+import { Props } from './types.js';
 import * as React from "react";
-export { useBroadcast, BroadcastEmitter } from './utils';
+export { useBroadcast, BroadcastEmitter } from './utils.js';
 /**
  * Creates a new broadcast context for distributed actions. Only needed if you
  * want to isolate a broadcast context, useful for libraries that want to provide

package/dist/boundary/components/broadcast/types.d.ts

@@ -1,4 +1,4 @@
-import { BroadcastEmitter } from './utils';
+import { BroadcastEmitter } from './utils.js';
 import * as React from "react";
 /**
  * The broadcast context is a BroadcastEmitter used for distributed actions across components.

package/dist/boundary/components/consumer/components/partition/index.d.ts

@@ -1,4 +1,4 @@
-import { Props } from './types';
+import { Props } from './types.js';
 import * as React from "react";
 /**
  * Renders output for the `stream()` method by subscribing to distributed action events.

package/dist/boundary/components/consumer/components/partition/types.d.ts

@@ -1,4 +1,4 @@
-import { ConsumerRenderer } from '../../types';
+import { ConsumerRenderer } from '../../types.js';
 /**
  * Props for the Partition component.
  * @internal

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

@@ -1,9 +1,9 @@
-import { Props } from './types';
+import { Props } from './types.js';
 import * as React from "react";
-export { useConsumer } from './utils';
-export { Partition } from './components/partition/index';
-export type { Props as PartitionProps } from './components/partition/types';
-export type { ConsumerRenderer, Entry, ConsumerContext } from './types';
+export { useConsumer } from './utils.js';
+export { Partition } from './components/partition/index.js';
+export type { Props as PartitionProps } from './components/partition/types.js';
+export type { ConsumerRenderer, Entry, ConsumerContext } from './types.js';
 /**
  * Creates a new consumer context for storing distributed action values. Only needed if you
  * want to isolate a consumer context, useful for libraries that want to provide

package/dist/boundary/components/consumer/types.d.ts

@@ -1,5 +1,5 @@
 import { Inspect, State } from 'immertation';
-import { ActionId } from '../tasks/types';
+import { ActionId } from '../tasks/types.js';
 import * as React from "react";
 /**
  * Callback function for the stream() method.

package/dist/boundary/components/consumer/utils.d.ts

@@ -1,4 +1,4 @@
-import { ConsumerContext } from './types';
+import { ConsumerContext } from './types.js';
 import * as React from "react";
 /**
  * React context for the consumer store.

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

@@ -1,21 +1,8 @@
-import { Props } from './types';
+import { Props } from './types.js';
 import * as React from "react";
-export { useEnv } from './utils';
+export { useEnv } from './utils.js';
 /**
- * Loose runtime shape for the per-`<Boundary>` Env. Each {@link App}
- * narrows this to its own typed env via `App<S>({ 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.
- *
- * Consumers should declare their Env shape inline via `App({ env })`
- * &mdash; the inferred `S` 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>;
-/**
- * Provides a per-Boundary {@link Env} value to every component inside
+ * Provides a per-Boundary {@link EnvType} value to every component inside
  * the boundary. Usually wired in via the `<Boundary env={initial}>`
  * prop rather than used directly.
  *