@owlmeans/client 0.1.18-rc.4 → 0.1.18-rc.40

package/README.md

@@ -1,92 +1,269 @@
 # @owlmeans/client
 
-Core React client framework providing hooks, context, navigation, and state management for OwlMeans frontends.
-
-## Overview
-
-- React hooks for subscribing to state stores (`useStoreModel`, `useStoreList`) and async data (`useValue`)
-- `useNavigate()` — module-aware navigation that resolves URLs and calls the router
-- `useContext()` — access the application's `ClientContext` from any React component
-- `useToggle()` — boolean state toggle hook
-- Used by every React frontend in the OwlMeans ecosystem
+The platform-agnostic React client framework that [`@owlmeans/web-client`](../web-client) (browser)
+and the native client are built on. It provides the client context factory, the `App`/`Router`
+mounts, alias-free navigation, the screen hooks (`useEntrypoint`, `useStoreModel`, `useStoreList`,
+`useValue`, `useToggle`), and the modal and debug services. A browser application normally builds
+its context with `makeContext` from [`@owlmeans/web-panel`](../web-panel) and mounts it with
+`renderApp` from `@owlmeans/web-client`. `@owlmeans/web-client` does not re-export the hooks
+listed here. `web-panel` re-exports `useNavigate`, `useValue` and `useEntrypoint`, while
+`useStoreModel` and `useStoreList` are available only from this package. A cross-platform package
+imports everything from here. Server code never uses this package; its equivalent is
+[`@owlmeans/server-context`](../server-context).
 
 ## Installation
 
 ```bash
-bun add @owlmeans/client
+bun add @owlmeans/client@^0.1.18-rc.40
 ```
 
+`react` and `@remix-run/router` are peer dependencies.
+
+## Concepts
+
+- **Client context**: `makeClientContext(cfg)` builds on `@owlmeans/client-context` and adds the
+  default state resource, the config and plugin resources, the modal and debug services, the
+  rerender hook and `context.router()`. Platform factories (`web-client`, `web-panel`) compose it,
+  and an app's own `makeContext` composes theirs.
+- **Screen**: a frontend entrypoint protocol (`route(alias, path, frontend(...))`) bound to a
+  component with `bindScreen(protocol, handler(Component))`. The router mounts only frontend
+  entrypoints, and each nests under its `parent`.
+- **Routed component**: a `RoutedComponent` receives `{ alias, path, params, context }`, and
+  `useEntrypoint()` reads the same values anywhere below it.
+- **Navigator**: `useNavigate()` addresses entrypoints, not URLs. The target entrypoint builds its
+  own `url(request)`, and the active router plugin performs the navigation.
+- **Store hooks**: `useStoreModel` and `useStoreList` subscribe to a [`@owlmeans/state`](../state)
+  resource through `useSyncExternalStore`. `useValue` renders an async result.
+- **Modal stack**: `context.modal().request(Body)` pushes a body onto a stack rendered by a surface
+  the app mounts once, and resolves when the body answers.
+
 ## Usage
 
-Subscribe to a state store record:
+### Declare screens, bind them, mount the app
 
-```typescript
-import { useStoreModel, useStoreList } from '@owlmeans/client'
+Screen protocols are declared in the shared `common` package and bound in the web app:
 
-function ProjectView({ projectId }: { projectId: string }) {
-  const model = useStoreModel<ProjectState>(projectId, 'project-state')
-  return <div>{model.record.title}</div>
-}
-```
+```ts
+// common: entrypoints.ts
+import { openProtocol } from '@owlmeans/entrypoint'
+import { DEFAULT_GUARD } from '@owlmeans/auth-common'
+import { frontend, route } from '@owlmeans/route'
+
+const projectBase = openProtocol(route('app:project', '/project/:projectId', frontend()), { guards: DEFAULT_GUARD })
 
-Load async data:
+export const appScreens = {
+  project: {
+    base: projectBase,
+    dashboard: openProtocol(route('app:project:dashboard', '/dashboard', frontend({ parent: projectBase }))),
+    settings: openProtocol(route('app:project:settings', '/settings', frontend({ parent: projectBase }))),
+  },
+} as const
+```
 
-```typescript
-import { useValue } from '@owlmeans/client'
+```tsx
+// web: entrypoints.ts and main.tsx
+import { bindAll, bindScreen, handler, renderApp } from '@owlmeans/web-client'
 
-function StoryList({ projectId }: { projectId: string }) {
-  const stories = useValue(async () => {
-    return await ctx.story().list({ criteria: { projectId } })
-  }, [projectId])
+export const entrypoints = [
+  ...bindAll({ project: appProtocols.project }),                    // backend calls
+  bindScreen(appScreens.project.base, handler(ProjectLayout)),
+  bindScreen(appScreens.project.dashboard, handler(DashboardScreen)),
+  bindScreen(appScreens.project.settings, handler(SettingsScreen)),
+]
 
-  return stories ? <List items={stories.items} /> : <Loading />
-}
+const context = makeContext(config)                               // the app's single factory
+context.registerEntrypoints(entrypoints)
+renderApp(context, undefined, <ModalSurface />)                   // children render before the router
 ```
 
-Navigate to a module:
+Outside the browser (a native shell, a test harness) the platform-agnostic mount is
+`<App context={context} />`. `noRouter` skips the router, and `provide` overrides how routes are
+compiled.
 
-```typescript
-import { useNavigate } from '@owlmeans/client'
+### A routed screen that loads, stores and renders
+
+```tsx
+import { useEntrypoint, useStoreModel, useValue } from '@owlmeans/client'
+import type { RoutedComponent } from '@owlmeans/client'
+
+export const DashboardScreen: RoutedComponent = () => {
+  const context = useContext()                                    // the app's typed wrapper
+  const { params } = useEntrypoint<{ projectId?: string }>()
+  const projectId = params.projectId
 
-function CreateButton() {
-  const navigate = useNavigate()
-  return <button onClick={() => navigate.go('project-create')}>Create</button>
+  // Load once per id, write the answer into the store, render from the store.
+  useValue(async cancel => {
+    if (projectId == null) {
+      return null
+    }
+    const project = await context.entrypoint(appProtocols.project.get).call({ params: { id: projectId } })
+    if (cancel?.current !== true) {
+      await context.getStateResource(PROJECTS).save(project)
+    }
+
+    return project
+  }, [projectId])
+
+  const project = useStoreModel<Project>(projectId, PROJECTS)
+  if (project.empty) {
+    return <Spinner />
+  }
+
+  return <ProjectBoard project={project.record} onRename={title => project.update({ title })} />
 }
 ```
 
-## API
-
-### `useStoreModel<T>(id?, opts?): StateModel<T>`
+The app's `useContext` is typically `() => useBasicContext<Config, Context>()` over the one exported
+here (or re-exported by `web-panel`), so app-level accessors are typed.
 
-Returns a single `StateModel` from a state resource. Creates the record if it doesn't exist.
+### Navigate by protocol
 
-### `useStoreList<T>(ids?, opts?): StateModel<T>[]`
+```tsx
+import { useNavigate } from '@owlmeans/client'
 
-Returns multiple `StateModel` instances from a state resource.
+export const ProjectTabs: FC<{ projectId: string }> = ({ projectId }) => {
+  const nav = useNavigate()
 
-### `useValue<T>(loader, deps?, forceDefault?): T | null`
+  return <nav>
+    <button onClick={nav.press(appScreens.project.dashboard, { params: { projectId } })}>Dashboard</button>
+    <button onClick={nav.press(appScreens.project.settings, { params: { projectId }, query: { tab: 'members' } })}>
+      Members
+    </button>
+    <button onClick={nav.pressBack()}>Back</button>
+  </nav>
+}
 
-Async data loader hook. Re-runs when `deps` change. Returns `null` while loading.
+// imperatively, replacing the history entry
+await nav.go(appScreens.project.dashboard, { params: { projectId }, replace: true })
+```
 
-### `useNavigate(): Navigator`
+A URL that resolves to another service (`http…`) is assigned to `location.href` instead of being
+pushed onto the history.
 
-Returns a navigator with:
-- `navigate(module, request?)` — navigate to a `ClientModule`
-- `go(alias, request?)` — navigate by module alias
+### A modal request
 
-### `useContext<T>(): T`
+```tsx
+import type { ModalBodyProps } from '@owlmeans/client'
+import { createElement } from 'react'
 
-Returns the current `ClientContext` cast to `T`.
+const ConfirmDelete: FC<ModalBodyProps & { storyId: string }> = ({ modal, storyId }) =>
+  <Dialog.Body>
+    <Button onClick={() => modal?.response(true)}>Delete {storyId}</Button>
+    <Button onClick={() => modal?.cancel()}>Cancel</Button>
+  </Dialog.Body>
 
-### `useToggle(initial?): [boolean, () => void]`
+const onDelete = async () => {
+  const confirmed = await context.modal().request<boolean>(
+    ({ modal }) => createElement(ConfirmDelete, { modal, storyId })
+  )
+  if (confirmed === true) {                                     // null when cancelled
+    await context.entrypoint(appProtocols.story.delete).call({ params: { id: storyId } })
+  }
+}
+```
 
-Simple boolean toggle hook.
+The surface is mounted once. It calls `useSetupModalNavigator()`, links a `useToggle()` to
+`context.modal().link(toggle)` after `waitForInitialized()`, and renders
+`context.modal().layer()?.Com` with `modal={context.modal()}`.
 
-## Related Packages
+## API
 
-- [`@owlmeans/state`](../state) — `StateModel`, `StateResource` used by `useStoreModel`
-- [`@owlmeans/client-module`](../client-module) — `ClientModule` used by `useNavigate`
-- [`@owlmeans/client-context`](../client-context) — `ClientContext` returned by `useContext`
+### Context and mounting
+
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `makeClientContext<C, T>(cfg)` | function | Build the React client context (state, config/plugin resources, modal, debug, router accessor) |
+| `ClientContext<C>` | type | Adds `router()`, `registerRerenderer(fn)`, `rerender()`, `modal()`, `debug()`, `getStateResource` |
+| `App` / `AppProps` | component / type | Provide the context and, unless `noRouter`, mount the router; `children` render first |
+| `Context`, `ClientContextContainer` | React context | The provider and the container behind it |
+| `useContext<C, T>()` | hook | Read the current client context |
+| `Router` / `RouterProps` | component / type | Resolve frontend entrypoints into routes; `provide` is optional |
+| `makeRouterModel()`, `RouterModel`, `RouterProvider` | function / type | The route model and the router-provider signature |
+| `handler(Component, preprender?)` | function | Wrap a component as an entrypoint handler for `bindScreen` |
+
+### Screens and navigation
+
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `RoutedComponent<Extra>` | type | A component bound to a frontend protocol |
+| `EntrypointContextParams<T>` | type | `{ alias, params, path, context }` |
+| `useEntrypoint<T>()` | hook | The params of the screen currently rendering |
+| `useNavigate()` | hook | The `Navigator` |
+| `Navigator` | type | `navigate(entrypoint, req?)`, `go(target, req?)`, `press(target, req?)`, `back()`, `pressBack()`, `location()` |
+| `NavRequest<T>` | type | A partial `AbstractRequest` plus `replace` and `silent` |
+| `EntrypointTarget` | type | `EntrypointReference \| string`; application code passes protocol objects |
+
+### State and values
+
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `useStoreModel<T>(id?, alias?)` | hook | One record from a state resource, live; never throws for missing data |
+| `useStoreList<T>(opts?)` | hook | A live query `{ query?, sort?, resource? }` returning `StateModel<T>[]` |
+| `UseStoreListOptions<T>` | type | The `useStoreList` options |
+| `useValue<T>(loader, deps?, forceDefault?)` | hook | Render an async result; `null` (or the default) until it resolves |
+| `UseValueParams<T>` | type | `{ default?, deps? }` |
+| `useToggle(opened?)`, `Toggleable` | hook / type | `{ opened, open, close, set, toggle }` |
+
+### Modal and debug services
+
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `appendModalService(ctx, alias?)`, `createModalService(alias?)` | function | Register or create the modal stack (`context.modal()`) |
+| `ModalService`, `ModalStackLayer`, `ModalBodyProps`, `ModalServiceAppend` | type | `request`, `response`, `cancel`, `error`, `layer`, `link`, `stack`, `toggle` |
+| `useSetupModalNavigator()` | hook | Give modal bodies a navigator; call once in the surface |
+| `appendDebugService(ctx, alias?)`, `createDebugService(alias?)` | function | The debug menu, registered only when `cfg.debug.all` or `cfg.debug.debugger` is set |
+| `appendStateDebug(ctx, alias)` | function | List a client resource under "Reset states" in the debug menu |
+| `DebugService`, `DebugMenuItem`, `DebugServiceAppend`, `DebugConfigRecord` | type | Debug menu contracts; `context.debug()` may be `undefined` |
+
+### Errors and constants
+
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `ClientError`, `ComponentError`, `ComponentPropError`, `ComponentPropUndefined` | class | The client error family, registered with `ResilientError` |
+| `DEF_MODAL_ALIAS`, `DEF_DEBUG_ALIAS` | const | `'modal'`, `'debug'` |
+| `DEBUGGER_FLAG`, `DEBUG_CONFIG_KEY` | const | `'debugger'` |
+
+### Subpath `@owlmeans/client/utils`
+
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `buildEntrypointTree`, `visitEntrypointTree`, `EntrypointTreeVisitor` | function / type | Build and walk the frontend entrypoint tree |
+| `initializeRouter(context)` | function | Initialize the router for a context |
+| `createRouteRenderer`, `HandledRenderer` | function / type | Render one route with guards applied |
+| `EntrypointContext` | React context | What `useEntrypoint` reads |
+
+These are the pieces the router is assembled from. A package building its own routing surface
+uses them; an application does not.
+
+## Common pitfalls
+
+- **Building URLs or passing alias strings in components.** Navigate with protocol objects
+  (`nav.go(protocol, { params })`) and let the entrypoint build the URL.
+- **Resolving route params in nested components.** Read `params` from the screen props or
+  `useEntrypoint()` and pass them down.
+- **Reading `useValue`'s second argument as a default.** An array is the dependency list, and an
+  object uses `{ default, deps }`. A bare non-array value is the default and gives no deps.
+- **Committing after unmount in a multi-await loader.** Check `cancel.current` before writing.
+- **Assigning into `model.record`.** Nothing re-renders. Use `model.update({ ... })`.
+- **Importing `useNavigate`, `useEntrypoint`, `useStoreModel`, `useStoreList` or `useValue` from
+  `@owlmeans/web-client`.** It does not re-export them; import them from this package.
+- **Requesting a modal from inside another modal body.** Closing the child also pops the parent,
+  and the parent's request never resolves. Await the first request, then issue the next.
+- **Mounting global overlays inside a route.** They are torn down on every navigation. Pass them
+  as `App`/`renderApp` children.
+- **Assuming `context.debug()` exists.** It is `undefined` unless the debug flags are set.
+- **A screen whose guards all fail.** The renderer throws `AuthorizationError('frontend-guard')`, so
+  bind a login flow for guarded screens.
+
+## Related packages
+
+- [`@owlmeans/web-client`](../web-client): the browser layer (`renderApp`, `WebApp`, `makeContext`)
+- [`@owlmeans/web-panel`](../web-panel): the shadcn UI context factory and navigation shell most web apps start from
+- [`@owlmeans/state`](../state): the store `useStoreModel` / `useStoreList` read
+- [`@owlmeans/client-entrypoint`](../client-entrypoint): `bind`, `bindAll`, `bindScreen`, typed `call`/`invoke`/`url`
+- [`@owlmeans/client-context`](../client-context): the base client context and config
+- [`@owlmeans/router`](../router): the router plugin `context.router()` resolves
+- [`@owlmeans/route`](../route): `route()` and `frontend()` for screen declarations
 
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance
@@ -96,7 +273,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills
+npx @owlmeans/agent-skills@^0.1.18-rc.38
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/client",
-  "version": "0.1.18-rc.0",
-  "generatedAt": "2026-08-16T22:20:50.506Z",
+  "version": "0.1.18-rc.40",
+  "generatedAt": "2026-09-23T19:57:40.682Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/client/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: client
-description: How to use @owlmeans/client — platform-agnostic React client framework (works with web and React Native) providing context, components, services, navigate, store. Auto-invoked when importing client framework primitives.
+description: How to use @owlmeans/client — the platform-agnostic React client framework (web and native) — makeClientContext, App/Router, useNavigate/Navigator, useEntrypoint/RoutedComponent, useStoreModel/useStoreList, useValue, the modal and debug services. Auto-invoked when importing client framework primitives, navigating between screens, or reading client state from React.
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,37 +8,212 @@ user-invocable: false
 # @owlmeans/client
 
 **Layer:** Client
-**Install:** `"@owlmeans/client": "^0.1.18-rc.0"` in `dependencies`
+**Install:** `"@owlmeans/client": "^0.1.18-rc.40"` in `dependencies`
+
+The React substrate `@owlmeans/web-client` (browser) and the native equivalent are built on. A
+cross-platform package imports from here; an application normally imports from the platform
+package, which re-exports what it needs — **except the hooks below, which are only here**.
+
+## What lives where
+
+| Import from `@owlmeans/client` | Import from `@owlmeans/web-client` |
+|---|---|
+| `useNavigate`, `useEntrypoint`, `useStoreModel`, `useStoreList`, `useValue`, `useToggle`, `useSetupModalNavigator` — none of these are re-exported | `renderApp`, `makeContext`, `useAuthenticated`, and protocol binding helpers from `@owlmeans/client-entrypoint` |
+| `RoutedComponent`, `EntrypointContextParams`, `Navigator`, `NavRequest`, `ClientContext` | `AppConfig`, `AppContext` |
+| `App`, `Router`, `makeClientContext` — the platform-agnostic mounts | `WebApp`, `renderApp` — the browser mounts that wrap them |
 
 ## Key Exports
 
 | Export | Description |
 |--------|-------------|
-| `App` / context helpers | Mount the React app, provide context |
-| `navigate` helpers | Programmatic navigation via the router service |
-| `module` helpers | Resolve modules by alias |
-| `store` helpers | Client store integration |
-| `components` | Cross-platform components (e.g. error boundaries) |
-| `value`, `debug` | Render-time helpers |
-| Errors | Client-side typed errors |
-| Constants | Default aliases |
+| `makeClientContext(cfg)` | The React client context: `@owlmeans/client-context` plus the state resource, both config resources, the modal and debug services, the rerender hook and `context.router()` |
+| `ClientContext<C>` | That context's interface — adds `router()`, `registerRerenderer(fn)`, `rerender()`, `modal()`, `debug()` |
+| `App` / `AppProps` | Mount: provides the context and, unless `noRouter`, the router. `children` render inside the provider and before the router |
+| `Context` / `ClientContextContainer` / `useContext()` | The React context container and the hook that reads it |
+| `Router` / `RouterProps` / `RouterProvider` / `makeRouterModel()` | Route rendering. `provide` is optional — omitted, the active router plugin's `compile` is used |
+| `useNavigate()` | The `Navigator` — programmatic navigation by entrypoint alias |
+| `Navigator` / `NavRequest` | `navigate` `go` `press` `back` `pressBack` `location`; a request adds `replace` and `silent` to an `AbstractRequest` |
+| `useEntrypoint<T>()` | The `EntrypointContextParams` of the screen currently rendering — `{ alias, path, params, context }` |
+| `RoutedComponent<Extra>` | Type of a component bound to a frontend protocol |
+| `handler(Component, preprender?)` | Wrap a React component as an entrypoint handler |
+| `useStoreModel` / `useStoreList` | React hooks over a `@owlmeans/state` resource — one record by id, or a live query |
+| `useValue(loader, deps?, forceDefault?)` / `UseValueParams<T>` | Render an async result. The second argument is the **dependency list**, not a default — see Async values |
+| `useToggle(opened?)` / `Toggleable` | An open/close/toggle handle, which is what a modal surface binds to |
+| `appendModalService` / `createModalService` / `ModalService` / `ModalStackLayer` | The modal stack — `context.modal()`: `request` `response` `cancel` `error` `layer()` `link(toggle)` |
+| `ModalBodyProps` / `useSetupModalNavigator()` | `{ modal?: ModalService }` — the props a modal body is rendered with; and the hook that lets a body navigate |
+| `appendDebugService` / `createDebugService` / `appendStateDebug(ctx, alias)` / `DebugService` | The debug menu — `context.debug()` |
+| `ClientError`, `ComponentError`, `ComponentPropError`, `ComponentPropUndefined` | The client error family, registered with `ResilientError` |
+| `DEF_MODAL_ALIAS` (`modal`), `DEF_DEBUG_ALIAS` (`debug`), `DEBUGGER_FLAG` / `DEBUG_CONFIG_KEY` (`debugger`) | Constants |
 
 ## Subpath Exports
 
-- `./utils` — generic client utilities
+- `./utils` — `buildEntrypointTree`, `visitEntrypointTree`, `initializeRouter`, `createRouteRenderer`,
+  `EntrypointContext`. What the router is assembled from; a package building its own routing surface
+  uses these, an application does not.
+
+## Navigation
+
+Navigation addresses an ALIAS, never a URL — the path lives in the entrypoint declaration, so a
+component never builds one. `useNavigate()` returns the `Navigator`, which asks the target
+entrypoint for its `url(request)` and hands that to the active router plugin:
+
+```typescript
+import { useNavigate } from '@owlmeans/client'
+import type { RoutedComponent } from '@owlmeans/client'
+
+export const ProjectScreen: RoutedComponent = ({ params }) => {
+  const nav = useNavigate()
+
+  // `go` navigates; `press` returns the handler for an onClick. `params` fills the path
+  // parameters of the target entrypoint, `query` the query string, `replace` swaps the
+  // history entry instead of pushing one.
+  void nav.go(PROJECT_ITEM, { params: { id: params.id }, query: { tab: 'files' } })
+
+  return <a onClick={nav.press(PROJECT_LIST)}>Back to the list</a>
+}
+```
+
+A URL that comes back starting with `http` belongs to another service, and the navigator assigns
+`location.href` rather than pushing a history entry. `nav.navigate(entrypoint, request)` takes the
+entrypoint itself when you already hold it; `nav.back()` / `nav.pressBack()` go one entry back, and
+`nav.location()` reads the current one.
+
+A bound screen receives `{ alias, path, params, context }` as props, and `useEntrypoint()`
+reads the same values from anywhere below it — read path parameters from `params` and pass them
+down; a nested component never resolves route parameters itself.
+
+## Routing and guards
+
+`App` mounts `Router`, which resolves the frontend entrypoints the context holds into a nested
+route tree. Only entrypoints whose route is `AppType.Frontend` are mounted, and among those only
+the ones that name no service at all, name this app's service, or are `sticky`. Each node
+contributes **only its own segment** — its ancestors already carry theirs, so a declaration nests
+by naming a `parent`.
+
+A screen's guards are its own plus every ancestor's, taken from `getGuards()`. An empty list is an
+open screen; when the list is non-empty and no guard matches, the renderer throws
+`AuthorizationError('frontend-guard')`.
+
+## Client state
+
+State lives on the context as a `@owlmeans/state` resource; these hooks subscribe to it.
+
+```typescript
+import { useStoreList, useStoreModel } from '@owlmeans/client'
+
+const task = useStoreModel<Task>(id, TASKS)                              // one record
+const open = useStoreList<Task>({ query: { status: 'open' }, resource: TASKS })  // live query
+```
+
+`useStoreModel` returns a `StateModel` — read `model.record`, write with `model.update({ ... })`.
+Never assign into `model.record` — it is not a snapshot. On a model the store backs, it IS the
+object the store holds: a field assignment mutates what every other holder of that key reads, and
+the next `update()`/`commit()` carries the mutation through, while nothing notifies and nothing
+re-renders. The hook never throws for missing data either — an id the store knows nothing about
+yields a model whose `empty` is true, and nothing is written into the store on the way.
+`useStoreList` takes `{ query?, sort?, resource? }` and matches everything when `query` is omitted.
+Full contract: [[state]].
+
+Both hooks go through `useSyncExternalStore`, and the live subscription React installs is torn down
+with the component. The FIRST snapshot is taken during render, by subscribing and unsubscribing
+again in one statement — a state resource seeds its listener synchronously, so no render runs
+without a value and that momentary subscription never outlives the call. The value is then cached
+and the same reference is returned until something actually changes, which is what keeps React from
+re-rendering forever.
+
+## Async values
+
+`useValue(loader, deps?, forceDefault?)` runs an async loader in an effect and answers with the
+default — `null` when there is none — until it resolves. Its second argument is overloaded, and
+reading it as "a default" is the standard mistake:
+
+```typescript
+useValue(async () => api.load(id), [id])                       // a DependencyList — re-runs on id
+useValue(async () => api.load(id), { default: EMPTY, deps: [id] })   // both, via UseValueParams
+useValue(async () => api.load(id))                             // no deps — the loader runs once
+useValue(async () => api.count(), 0)                           // a bare non-array value IS the default
+```
+
+The deps always come from the argument's SHAPE: an array is the dependency list itself, an object
+with a `deps` key gives `deps ?? []`, and anything else gives `[]`. The default is read from the
+same argument: `default` off a `UseValueParams` object, `null` when an array was passed, the value
+itself otherwise. `forceDefault: true` changes only the second half — the argument is then taken as
+the default whatever its shape, while still deciding the deps.
+
+The loader is handed a `MutableRefObject<boolean>` cancel ref, which the effect's cleanup sets to
+`true`, so a loader that awaits more than once checks `cancel.current` before it commits. A loader that resolves to a **function** is kept aside and returned as it is, rather than
+being run as a state updater — which is what lets a component be an async value.
+
+## Modals
+
+`context.modal()` owns a STACK of body components and one surface. The surface is a component the
+app mounts once: it links a toggle to the service, reads the top layer through `layer()`, and
+renders it with the service as a prop.
 
-## Usage
+```tsx
+import { useContext, useSetupModalNavigator, useToggle, useValue } from '@owlmeans/client'
+import type { ModalBodyProps } from '@owlmeans/client'
+import { useEffect } from 'react'
+import type { FC } from 'react'
 
-This is the platform-agnostic substrate that `@owlmeans/web-client` (browser) and the native equivalent build on. Most apps import from `@owlmeans/web-client` directly; use `@owlmeans/client` only for cross-platform code.
+export const Modal: FC = () => {
+  useSetupModalNavigator()                     // lets a body navigate; call it once
+  const context = useContext()
+  const toggle = useToggle(false)
+
+  useEffect(() => {
+    void context.waitForInitialized().then(() => context.modal().link(toggle))
+  }, [])
+
+  const Com = useValue<FC<ModalBodyProps> | undefined>(
+    async () => toggle.opened ? context.modal().layer()?.Com : undefined,
+    [toggle.opened]
+  )
+
+  return <Dialog open={toggle.opened} onOpenChange={toggle.set}>
+    {Com != null ? <Com modal={context.modal()} /> : undefined}
+  </Dialog>
+}
+```
+
+A **body is an `FC<ModalBodyProps>`** — it receives the service as an optional `modal` prop, and
+that prop is how it answers. Nothing else reaches it, so whatever a body needs travels in the
+closure of the component that requested it.
 
 ```typescript
-import { navigate } from '@owlmeans/client'
-const navigateTo = navigate(context)
-navigateTo('/projects')
+const result = await context.modal().request<Answer>(ConfirmBody)   // null when cancelled
 ```
 
+`request` pushes the body onto the stack, opens the linked toggle, and resolves when the body calls
+`modal.response(value)`, `modal.cancel()` (which resolves `null`) or `modal.error(e)` (which
+rejects). All three settle the promise first, then pop the layer and close the surface — and
+`request` pops a SECOND time when its own `await` resumes. One completed request therefore removes
+two layers.
+
+**Keep the stack one deep.** A lone body ends on an empty stack and the second pop costs nothing.
+A body requested from inside another body takes its parent down with it: closing the child pops the
+child, sees a layer still there and schedules the surface to reopen 500 ms later, and then the
+child's continuation pops the parent in the microtask before that timer fires. The surface reopens
+with `layer()` answering `undefined` and nothing to render, and the parent's own `request` — whose
+deferred no one is left to settle — never resolves. Chain from the caller instead: await the first
+request, then issue the next.
+
+## Debug menu
+
+`appendDebugService` registers the menu only when `cfg.debug.all` or `cfg.debug.debugger` is set,
+so `context.debug()` answers `undefined` in a normal build and a caller must handle that. A package
+that owns a client resource calls `appendStateDebug(context, alias)` at wiring time to have it
+listed under "Reset states"; "Reset app" erases the whole client DB.
+
 ## Depends On
 
-- `@owlmeans/client-context`, `@owlmeans/client-entrypoint`, `@owlmeans/client-route`
-- `@owlmeans/router`, `@owlmeans/auth-common`
-- `react` (peer)
+- `@owlmeans/client-context`, `@owlmeans/client-entrypoint`, `@owlmeans/client-resource`
+- `@owlmeans/router` (the routing plugin surface), `@owlmeans/state`, `@owlmeans/entrypoint`,
+  `@owlmeans/resource`, `@owlmeans/config`, `@owlmeans/context`, `@owlmeans/auth`, `@owlmeans/error`
+- `react` and `@remix-run/router` (peer)
+
+## Related
+
+- [[web-client]] — the browser layer built on this
+- [[state]] — the store the two state hooks read
+- [[router]] — the routing plugin `context.router()` resolves

package/build/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,OAAO,CAAA;AAEpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAE5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAoB/C,eAAO,MAAM,iBAAiB,GAAI,CAAC,SAAS,YAAY,EAAE,CAAC,SAAS,aAAa,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,KAAG,CA8BjH,CAAA;AAED,eAAO,MAAM,sBAAsB,2CAA+C,CAAA;AAElF,eAAO,MAAM,OAAO,uDAAkC,CAAA;AAEtD,eAAO,MAAM,UAAU,GAAI,CAAC,SAAS,YAAY,EAAE,CAAC,SAAS,aAAa,CAAC,CAAC,CAAC,QAE5E,CAAA"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,OAAO,CAAA;AAEpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAE5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAmB/C,eAAO,MAAM,iBAAiB,GAAI,CAAC,SAAS,YAAY,EAAE,CAAC,SAAS,aAAa,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,KAAG,CA4BjH,CAAA;AAED,eAAO,MAAM,sBAAsB,2CAA+C,CAAA;AAElF,eAAO,MAAM,OAAO,uDAAkC,CAAA;AAEtD,eAAO,MAAM,UAAU,GAAI,CAAC,SAAS,YAAY,EAAE,CAAC,SAAS,aAAa,CAAC,CAAC,CAAC,QAE5E,CAAA"}

package/build/context.js

@@ -1,6 +1,6 @@
 import { createContext, useContext as useCtx } from 'react';
 import { makeClientContext as makeBasicContext, PLUGINS } from '@owlmeans/client-context';
-import { AppType, CONFIG_RECORD, Layer } from '@owlmeans/context';
+import { AppType, CONFIG_RECORD } from '@owlmeans/context';
 import { appendStateResource } from '@owlmeans/state';
 import { appendModalService } from './components/modal.js';
 import { appendDebugService } from './services/debug.js';
@@ -9,7 +9,6 @@ import { ROUTER_SERVICE } from '@owlmeans/router';
 const defaultCfg = {
     services: {},
     brand: {},
-    layer: Layer.Service,
     trusted: [],
     [CONFIG_RECORD]: [],
     ready: false,
@@ -40,7 +39,6 @@ export const makeClientContext = (cfg) => {
         };
     }
     context.router = () => context.service(ROUTER_SERVICE);
-    context.makeContext = makeClientContext;
     return context;
 };
 export const ClientContextContainer = createContext(makeClientContext(defaultCfg));

package/build/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,UAAU,IAAI,MAAM,EAAE,MAAM,OAAO,CAAA;AAE3D,OAAO,EAAE,iBAAiB,IAAI,gBAAgB,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAA;AAEzF,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAEjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AACrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AACxD,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAEtE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAEjD,MAAM,UAAU,GAAiB;IAC/B,QAAQ,EAAE,EAAE;IACZ,KAAK,EAAE,EAAE;IACT,KAAK,EAAE,KAAK,CAAC,OAAO;IACpB,OAAO,EAAE,EAAE;IACX,CAAC,aAAa,CAAC,EAAE,EAAE;IACnB,KAAK,EAAE,KAAK;IACZ,OAAO,EAAE,EAAE;IACX,KAAK,EAAE,EAAE;IACT,IAAI,EAAE,OAAO,CAAC,QAAQ;CACvB,CAAA;AAED,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAwE,GAAM,EAAK,EAAE;IACpH,MAAM,OAAO,GAAG,gBAAgB,CAAC,GAAG,CAAM,CAAA;IAC1C,mBAAmB,CAAO,OAAO,CAAC,CAAA;IAClC,kBAAkB,CAAO,OAAO,CAAC,CAAA;IACjC,oBAAoB,CAAO,OAAO,CAAC,CAAA;IACnC,oBAAoB,CAAO,OAAO,EAAE,OAAO,EAAE,aAAa,CAAC,CAAA;IAC3D,kBAAkB,CAAO,OAAO,CAAC,CAAA;IAEjC,IAAI,OAAO,CAAC,kBAAkB,IAAI,IAAI,EAAE,CAAC;QACvC,MAAM,WAAW,GAAuB,EAAE,CAAA;QAE1C,OAAO,CAAC,kBAAkB,GAAG,QAAQ,CAAC,EAAE;YACtC,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;YAC1B,OAAO,GAAG,EAAE;gBACV,MAAM,KAAK,GAAG,WAAW,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;gBAC3C,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;oBACf,WAAW,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAA;gBAC9B,CAAC;YACH,CAAC,CAAA;QACH,CAAC,CAAA;QACD,OAAO,CAAC,QAAQ,GAAG,GAAG,EAAE;YACtB,WAAW,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAA;QAC7C,CAAC,CAAA;IACH,CAAC;IAED,OAAO,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAgB,cAAc,CAAC,CAAA;IAErE,OAAO,CAAC,WAAW,GAAG,iBAA+C,CAAA;IAErE,OAAO,OAAO,CAAA;AAChB,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,sBAAsB,GAAG,aAAa,CAAC,iBAAiB,CAAC,UAAU,CAAC,CAAC,CAAA;AAElF,MAAM,CAAC,MAAM,OAAO,GAAG,sBAAsB,CAAC,QAAQ,CAAA;AAEtD,MAAM,CAAC,MAAM,UAAU,GAAG,GAAuD,EAAE,CAAC,MAAM,CACxF,sBAAoD,CACrD,CAAA"}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,UAAU,IAAI,MAAM,EAAE,MAAM,OAAO,CAAA;AAE3D,OAAO,EAAE,iBAAiB,IAAI,gBAAgB,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAA;AAEzF,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAE1D,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AACrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AACxD,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAEtE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAEjD,MAAM,UAAU,GAAiB;IAC/B,QAAQ,EAAE,EAAE;IACZ,KAAK,EAAE,EAAE;IACT,OAAO,EAAE,EAAE;IACX,CAAC,aAAa,CAAC,EAAE,EAAE;IACnB,KAAK,EAAE,KAAK;IACZ,OAAO,EAAE,EAAE;IACX,KAAK,EAAE,EAAE;IACT,IAAI,EAAE,OAAO,CAAC,QAAQ;CACvB,CAAA;AAED,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAwE,GAAM,EAAK,EAAE;IACpH,MAAM,OAAO,GAAG,gBAAgB,CAAC,GAAG,CAAM,CAAA;IAC1C,mBAAmB,CAAO,OAAO,CAAC,CAAA;IAClC,kBAAkB,CAAO,OAAO,CAAC,CAAA;IACjC,oBAAoB,CAAO,OAAO,CAAC,CAAA;IACnC,oBAAoB,CAAO,OAAO,EAAE,OAAO,EAAE,aAAa,CAAC,CAAA;IAC3D,kBAAkB,CAAO,OAAO,CAAC,CAAA;IAEjC,IAAI,OAAO,CAAC,kBAAkB,IAAI,IAAI,EAAE,CAAC;QACvC,MAAM,WAAW,GAAuB,EAAE,CAAA;QAE1C,OAAO,CAAC,kBAAkB,GAAG,QAAQ,CAAC,EAAE;YACtC,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;YAC1B,OAAO,GAAG,EAAE;gBACV,MAAM,KAAK,GAAG,WAAW,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;gBAC3C,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;oBACf,WAAW,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAA;gBAC9B,CAAC;YACH,CAAC,CAAA;QACH,CAAC,CAAA;QACD,OAAO,CAAC,QAAQ,GAAG,GAAG,EAAE;YACtB,WAAW,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAA;QAC7C,CAAC,CAAA;IACH,CAAC;IAED,OAAO,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAgB,cAAc,CAAC,CAAA;IAErE,OAAO,OAAO,CAAA;AAChB,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,sBAAsB,GAAG,aAAa,CAAC,iBAAiB,CAAC,UAAU,CAAC,CAAC,CAAA;AAElF,MAAM,CAAC,MAAM,OAAO,GAAG,sBAAsB,CAAC,QAAQ,CAAA;AAEtD,MAAM,CAAC,MAAM,UAAU,GAAG,GAAuD,EAAE,CAAC,MAAM,CACxF,sBAAoD,CACrD,CAAA"}

package/build/entrypoint.d.ts

@@ -0,0 +1,3 @@
+import type { EntrypointContextParams } from './types.js';
+export declare const useEntrypoint: <T extends {} = {}>() => EntrypointContextParams<T>;
+//# sourceMappingURL=entrypoint.d.ts.map

package/build/entrypoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entrypoint.d.ts","sourceRoot":"","sources":["../src/entrypoint.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAA;AAEzD,eAAO,MAAM,aAAa,GAAI,CAAC,SAAS,EAAE,GAAG,EAAE,OAAwC,uBAAuB,CAAC,CAAC,CAAC,CAAA"}

package/build/entrypoint.js

@@ -0,0 +1,4 @@
+import { useContext } from 'react';
+import { EntrypointContext } from './utils/index.js';
+export const useEntrypoint = () => useContext(EntrypointContext);
+//# sourceMappingURL=entrypoint.js.map