march-hare 0.11.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.
@@ -252,7 +252,7 @@ function useActions() {
 }
 ```
 
-See the [`useContext` recipe](./recipes/use-context.md) for the full pattern.
+See the [`app.useContext` recipe](./recipes/use-controller.md) for the full pattern.
 
 The model defaults to `void`, so a component that only coordinates via events — forwarding broadcasts, triggering side-effects, bridging external systems — can call `context.useActions()` with no initial model:
 
@@ -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,10 +814,25 @@ export const app = App();
 
 ## Reusable components
 
-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. `useApp<S>()` returns a typed handle to the **nearest `<app.Boundary>`** at runtime: same `useContext` / `useEnv` surface as an App-bound handle, with the Env shape (or union of shapes) declared at the call site.
+> **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.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.
 
 ```tsx
-import { useApp, Action } from "march-hare";
+import { Action, shared } from "march-hare";
+
+type WebEnv = { session: Session | null; locale: string };
+type MobileEnv = { session: Session | null; platform: "ios" | "android" };
+type Envs = WebEnv | MobileEnv;
 
 type Model = { name: string | null };
 const model: Model = { name: null };
@@ -813,8 +842,7 @@ class Actions {
 }
 
 function useProfileActions() {
-  const app = useApp<{ session: Session | null }>();
-  const context = app.useContext<Model, typeof Actions>();
+  const context = shared.useContext<Envs, Model, typeof Actions>();
   const actions = context.useActions(model);
 
   actions.useAction(Actions.Sign, (context, name) =>
@@ -837,22 +865,24 @@ export default function Profile(): React.ReactElement {
 
 Drop `<Profile />` inside `<web.Boundary>` and it reads the web app's env; drop it inside `<mobile.Boundary>` and it reads the mobile app's env. The component never references either `App()` handle.
 
-When more than one `App` lives in your repo, declare a union of every Env once and parameterise every reusable component against it. TypeScript narrows `app.useEnv()` to the union &mdash; keys present on every member resolve directly, keys on a subset need an `in` / `typeof` guard:
+When more than one `App` lives in your repo, declare a union of every Env once and parameterise every reusable component against it. Keys present on every member resolve directly; keys on a subset need an `in` / `typeof` guard:
 
 ```ts
-// shared/apps.ts
+// shared/envs.ts
 export type WebEnv = { session: Session | null; locale: string };
 export type MobileEnv = {
   session: Session | null;
   platform: "ios" | "android";
 };
-export type Apps = WebEnv | MobileEnv;
+export type Envs = WebEnv | MobileEnv;
 ```
 
 ```tsx
+import { shared } from "march-hare";
+import type { Envs } from "../shared/envs";
+
 function Where(): React.ReactElement {
-  const app = useApp<Apps>();
-  const env = app.useEnv();
+  const env = shared.useEnv<Envs>();
 
   const signedIn = env.session !== null;
   const where = "locale" in env ? env.locale : env.platform;
@@ -861,6 +891,8 @@ function Where(): React.ReactElement {
 }
 ```
 
-The handle exposes `useContext` and `useEnv` &mdash; the same surface as `App<S>` minus `Boundary` (rendered once at the App declaration site) and `Scope` / `Resource` (module-scope, not per-render). 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, UseAppHandle } 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, UseAppHandle, } from './types';
+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,37 +72,40 @@ 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>;
 /**
- * Returns a typed handle to the nearest `<app.Boundary>`, for use
- * inside reusable components that aren't tied to a single `App` import.
- * The generic `S` declares the Env shape (or union of shapes) the
- * component expects &mdash; `useApp<WebEnv | MobileEnv>()` lets the
- * component run under either App and read keys common to both. For
- * fields that only exist on a subset, narrow with an `in` check on
- * the value returned from `app.useEnv()`.
- *
- * The returned handle exposes `useContext` and `useEnv` &mdash; the
- * same surface as `App<S>` minus `Boundary` (rendered once at the App
- * declaration site) and `Scope` (declared at module scope so its
- * multicast surface stays explicit).
- *
- * Recommended monorepo pattern: declare a `type Apps = WebEnv |
- * MobileEnv | AdminEnv` union of every Env shape your reusable
- * components might run under, and have shared components reach for
- * `useApp<Apps>()`. Library code can then read keys present on every
- * member directly, with type-guards bridging the rest.
+ * Standalone counterpart to `app.useContext`, exported as
+ * `shared.useContext` &mdash; same call shape, but takes the **Env
+ * shape `E` as a mandatory first generic** so the caller can be a
+ * reusable component that isn't tied to a single `App` import.
+ *
+ * `E` is the Env type your component expects to see &mdash; usually
+ * a union of every App's Env shape it might run under. Inside the
+ * handler, `context.env` is typed as `E`; reach for `in` / `typeof`
+ * narrowing for keys present on only a subset.
+ *
+ * Pass `app` directly if you only need to talk to one App &mdash;
+ * `app.useContext<Model, typeof Actions>()` is shorter and infers the
+ * Env from the value. Reach for the standalone form only when a
+ * component must support more than one App.
+ *
+ * @template E The Env shape (or union) the component supports.
+ * @template M The model type, or `void`.
+ * @template AC The Actions class, or `void`.
+ * @template D The reactive data type returned from the `useActions`
+ *   data callback.
  *
  * @example
  * ```tsx
- * import { useApp, Action } from "march-hare";
+ * import { Action, shared } from "march-hare";
  *
  * type WebEnv = { session: Session | null; locale: string };
  * type MobileEnv = { session: Session | null; platform: "ios" | "android" };
- * type Apps = WebEnv | MobileEnv;
+ * type Envs = WebEnv | MobileEnv;
  *
  * type Model = { name: string | null };
  * const model: Model = { name: null };
@@ -166,20 +114,39 @@ export declare function App<S extends object = Env>(config?: {
  *   static Sign = Action<string>("Sign");
  * }
  *
- * export default function Profile() {
- *   const app = useApp<Apps>();
- *   const env = app.useEnv();
- *   const context = app.useContext<Model, typeof Actions>();
- *   const [view, actions] = context.useActions(model);
- *
- *   const where = "locale" in env ? env.locale : env.platform;
+ * function useProfileActions() {
+ *   const context = shared.useContext<Envs, Model, typeof Actions>();
+ *   const actions = context.useActions(model);
  *
- *   return (
- *     <button onClick={() => actions.dispatch(Actions.Sign, "Adam")}>
- *       Hey {view.name} ({where})
- *     </button>
+ *   actions.useAction(Actions.Sign, (context, name) =>
+ *     context.actions.produce(({ model }) => void (model.name = name)),
  *   );
+ *
+ *   return actions;
+ * }
+ * ```
+ */
+export declare function useContext<E extends object, M extends Model | void = void, A extends Actions | void = void, D extends Props = Props>(): AppContextHandle<M, A, D, E>;
+/**
+ * Standalone counterpart to `app.useEnv`, exported as `shared.useEnv`
+ * &mdash; reads the nearest `<app.Boundary>`'s Env, typed against the
+ * Env shape `E` supplied at the call site. For reusable components
+ * that need an Env read outside any action handler (e.g. to hand a
+ * closure to an external library at module bridge time).
+ *
+ * @template E The Env shape (or union) the component supports.
+ *
+ * @example
+ * ```tsx
+ * import { shared } from "march-hare";
+ *
+ * type WebEnv = { session: Session | null };
+ * type MobileEnv = { session: Session | null };
+ *
+ * function SessionBadge() {
+ *   const env = shared.useEnv<WebEnv | MobileEnv>();
+ *   return <span>{env.session ? env.session.user.name : "Signed out"}</span>;
  * }
  * ```
  */
-export declare function useApp<S extends object = Env>(): UseAppHandle<S>;
+export declare function useEnv<E extends object>(): Readonly<E>;

package/dist/app/types.d.ts

@@ -1,72 +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>;
 /**
- * Handle returned by {@link useApp}. Same surface as {@link App} minus
- * `Boundary` (which can only be rendered from the App declaration site)
- * and `Scope` (which is module-level, not per-render). Use this inside
- * reusable components that need to run under more than one App.
- *
- * The generic `S` is the Env shape (or union of shapes) the component
- * expects. Pass a union of every App's Env type in your monorepo and
- * read keys that exist on every member directly; reach for `in` /
- * `typeof` type-guards when accessing keys that only exist on a subset.
- *
- * @template S The Env shape (or union) the caller expects to be in scope.
+ * Returned from {@link App}. Bundles the Boundary, hooks, and Resource
+ * factory bound to a single typed Env shape `E`.
  */
-export type UseAppHandle<S extends object> = {
+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>;
     /**
-     * Same as `app.useContext` &mdash; reads the nearest `<app.Boundary>`'s
-     * dispatch surface, with `context.env` typed against `S`.
+     * `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 useContext: <M extends Model | void = void, AC extends Actions | void = void, D extends Props = Props>() => AppContextHandle<M, AC, D, S>;
+    readonly Resource: AppResource<E>;
     /**
-     * Same as `app.useEnv` &mdash; read-only Proxy over the nearest
-     * `<app.Boundary>`'s Env, typed as `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 useEnv: () => Readonly<S>;
+    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`.
@@ -74,9 +102,9 @@ export type UseAppHandle<S extends object> = {
  *   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
@@ -102,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 {};