@omerdlw/base-framework 1.0.0 → 1.0.2

package/docs/modules/error-boundary.md

@@ -0,0 +1,160 @@
+# Error Boundary — `@omerdlw/base-framework/error`
+
+> **Read this first if you need to:** stop one crash from taking down the app, wrap a risky widget, send errors to Sentry (or another sink), or understand how a runtime error becomes the dock's error card.
+
+## 1. At a glance
+
+|                  |                                                                                                                                                           |
+| :--------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Import**       | `import { ComponentError, getErrorReporter, … } from "@omerdlw/base-framework/error"`                                                                                      |
+| **Layer**        | `src/core` (frozen upstream). Client-only (`"use client"`).                                                                                               |
+| **Installed by** | `CoreProvider`: `GlobalError` wraps everything, `ModuleError` is the boundary around every module backdrop/overlay, `GlobalErrorListener` is mounted once |
+| **Emits**        | `EVENT_TYPES.APP_ERROR` (`{ error, errorInfo?, message, resetError? }`)                                                                                   |
+| **Theme**        | `errorTheme` slots `screen`, `icon`, `title`, `retryButton` (`src/config/error.core.theme.ts`)                                                            |
+| **Tests**        | `tests/core/error.test.ts`                                                                                                                                |
+
+## 2. Mental model
+
+```
+render error ──▶ nearest boundary (Component < Module < Global)
+                   ├─ onError(error, info, context)                (your hook)
+                   ├─ globalEvents.emit(APP_ERROR, …)  unless silent   → dock shows its error card
+                   ├─ ErrorReporter.captureError(error, context)       → handlers (console / Sentry / yours)
+                   └─ renders the fallback (default card with "Try again")
+
+window "error" / "unhandledrejection" ──▶ GlobalErrorListener (filtered, throttled)
+                   ├─ ErrorReporter.captureError
+                   └─ globalEvents.emit(APP_ERROR)
+
+report(scope, error) anywhere ──▶ the reporter sink installed by GlobalErrorListener
+```
+
+Boundaries are **class components** (React requires it) configured through props. Raw `Error.message` values never reach the UI: the displayed text is a fixed copy or `toUserMessage(error)`.
+
+## 3. Quick start
+
+```tsx
+// Inline: a failing widget degrades to a small card with "Try again"
+<ComponentError message="Chart failed to load">
+  <RevenueChart />
+</ComponentError>
+
+// Custom fallback (render prop)
+<ComponentError fallback={({ error, resetError }) => <MyEmpty onRetry={resetError} />}>…</ComponentError>
+
+// Reset when a key changes (e.g. the selected id) and observe errors
+<ErrorBoundaryCore resetKey={id} variant="inline" onError={(e, info, ctx) => track(ctx.route)}>…</ErrorBoundaryCore>
+```
+
+```ts
+// Wire a reporting sink once, e.g. in an app-level client component
+import * as Sentry from "@sentry/nextjs";
+getErrorReporter({ sampleRate: 0.5 })
+  .addHandler(createSentryHandler(Sentry))
+  .setContext("release", process.env.NEXT_PUBLIC_RELEASE)
+  .setTag("app", "web");
+```
+
+## 4. Boundaries
+
+| Component           | Variant  | Fallback copy                                                    | Resets when                                   | Notes                                                                                                                                        |
+| :------------------ | :------- | :--------------------------------------------------------------- | :-------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GlobalError`       | `full`   | "We ran into an unexpected problem. Please try again"            | the **pathname** changes (and on "Try again") | Outermost; also emits `APP_ERROR`.                                                                                                           |
+| `ModuleError`       | `module` | "This part of the app isn't working right now. Please try again" | "Try again"                                   | Used by `ModuleHost` around every module's backdrop and overlay and by `ModuleBoundary`; `name` identifies the module in the report context. |
+| `ComponentError`    | `inline` | `message` or "This section couldn't be loaded. Please try again" | "Try again"                                   | For widgets.                                                                                                                                 |
+| `ErrorBoundaryCore` | any      | `message` / `toUserMessage(error)`                               | "Try again" or when `resetKey` changes        | The shared implementation.                                                                                                                   |
+
+`ErrorBoundaryCore` props:
+
+| Prop                            | Meaning                                                                        |
+| :------------------------------ | :----------------------------------------------------------------------------- |
+| `fallback`                      | A node, or `({ error, resetError }) => node`.                                  |
+| `message`, `title`              | Default-card text; `title` and `name` are also recorded in the report context. |
+| `name`, `variant`               | Reported as context (`name`, `variant`).                                       |
+| `resetKey`                      | When it changes the boundary clears its error state.                           |
+| `onError(error, info, context)` | Called first; exceptions inside it are caught and logged as warnings.          |
+| `onReset`                       | Called after "Try again" / `resetError()`.                                     |
+| `silent`                        | Do **not** emit `APP_ERROR` (no dock card); the reporter is still called.      |
+
+The `context` passed to `onError` and the reporter: `{ componentStack, route, userAgent, timestamp, name, variant, source: "ErrorBoundary" }`.
+
+## 5. `GlobalErrorListener`
+
+Mounted once by `CoreProvider`. It listens to `window` `error` and `unhandledrejection`, then:
+
+1. **Ignores** noise (`shouldIgnoreError`): empty errors, Next.js not-found errors, and messages matching `ResizeObserver loop`, `Network request failed`, `Loading chunk`, `Unexpected end of input`, `Failed to fetch`, `Script error`, `HTTP 404`.
+2. **Throttles:** at most **10 errors** per page lifetime, at least **2 s** apart, and each distinct message **once**.
+3. Sends the error to the reporter (`source: "window.onerror" | "unhandledrejection"`) and emits `APP_ERROR` with `message: toUserMessage(error)`.
+
+It also installs the reporter as the **sink** of `report()` (below).
+
+## 6. `ErrorReporter`
+
+`getErrorReporter(options?)` returns a **singleton** (options apply on the first call only).
+
+| Option               | Default   | Meaning                                                                                                                                                               |
+| :------------------- | :-------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `enabled`            | `true`    | Master switch.                                                                                                                                                        |
+| `sampleRate`         | `1`       | 0–1 probability per capture.                                                                                                                                          |
+| `deduplicateWindow`  | 60 000 ms | A report with the same **fingerprint** (`componentStack top :: message[0..100] :: name :: route`) is dropped inside the window; at most 100 fingerprints are tracked. |
+| `beforeSend(report)` | —         | Return a changed report, or `null` to drop it.                                                                                                                        |
+
+Methods: `addHandler({ name, handle })`, `removeHandler(name)`, `setContext(key, value)` (max 10 keys), `setTag(key, value)`, `captureError(error, extraContext?)` → `ErrorReport | undefined`, `captureMessage(message, level?, context?)`.
+
+Default handlers are added lazily in the browser **only if you have not added any**: a console handler (silent in production) and a Sentry handler when `window.Sentry` exists. `createSentryHandler(Sentry)` falls back to the console handler when the object lacks `captureException` / `withScope`; it sets fingerprint, user, tags, `environment` and `custom` contexts and the component stack. Handler exceptions are swallowed.
+
+`ErrorReport`: `{ error: { name, message, stack }, fingerprint, timestamp, environment (route, url, userAgent, platform, language, online), componentStack, context, tags, user? }`.
+
+## 7. User-facing messages and `report()`
+
+Raw `Error.message` values (database, SDK, vendor wording) never reach the UI. `toUserMessage(error, { fallback?, codes? })` from `@omerdlw/base-framework/utils` is the single gate: only a `UserError`, a string `Result` error, or a 4xx payload from our own API is shown as written; everything else maps to a fixed sentence in `USER_MESSAGES` (`generic`, `network`, `timeout`, `unauthorized`, `forbidden`, `notFound`, `rateLimited`, `server`). Server code throws `UserError` for validation/permission text it wants shown; route handlers answer with `apiErrorResponse` from `@/infrastructure/http/api-error`.
+
+`report(scope, error, level?)` from `@omerdlw/base-framework/utils` replaces `console.*` everywhere. On the client, `GlobalErrorListener` installs the reporter as the sink; without a sink, browsers stay silent in production and servers always log. Only the reporter's dev-only console handler touches `console`.
+
+## 8. Public API
+
+| Export                                                                                                                                                                                                 | Kind            | Description                                                                                                                                                                   |
+| :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GlobalError`, `ModuleError`, `ComponentError`                                                                                                                                                         | components      | The three boundaries (§4).                                                                                                                                                    |
+| `ErrorBoundaryCore`                                                                                                                                                                                    | class component | Shared implementation.                                                                                                                                                        |
+| `GlobalErrorListener`                                                                                                                                                                                  | component       | Window error/rejection listener (§5).                                                                                                                                         |
+| `getErrorReporter(options?)`                                                                                                                                                                           | factory         | Singleton reporter (§6).                                                                                                                                                      |
+| `createConsoleHandler()`, `createSentryHandler(Sentry)`                                                                                                                                                | factories       | Sinks.                                                                                                                                                                        |
+| `createReport`, `createErrorContext`, `fingerprint`, `getErrorMessage`, `shouldIgnoreError`, `getBrowserEnvironment`, `normalizeSampleRate`, `normalizeDedupeWindow`, `getRuntimePath`, `getUserAgent` | utils           | Report construction and filtering.                                                                                                                                            |
+| `ERROR_MESSAGES`, `ERROR_LISTENER_CONFIG`, `DEFAULT_DEDUPE_WINDOW` (60 000), `MAX_CONTEXT` (10), `MAX_FINGERPRINTS` (100), `errorTheme`                                                                | constants       | Copy, limits, theme spec.                                                                                                                                                     |
+| Types                                                                                                                                                                                                  |                 | `ErrorReport`, `ErrorReporterHandler`, `ErrorReporterOptions`, `ErrorBoundaryCoreProps`, `ErrorFallbackRender`, `ErrorContextData`, `BrowserEnvironment`, `ErrorThemeSlot`, … |
+
+## 9. Recipes and gotchas
+
+| I want to…                                 | Do this                                                                 |
+| :----------------------------------------- | :---------------------------------------------------------------------- |
+| Isolate a risky widget                     | `<ComponentError>`.                                                     |
+| Handle an error myself without a dock card | `<ErrorBoundaryCore silent onError={…}>`.                               |
+| Send errors to Sentry                      | `getErrorReporter().addHandler(createSentryHandler(Sentry))`.           |
+| Report a handled error                     | `report("Checkout", error)` (and keep the UI message user-friendly).    |
+| Drop PII before sending                    | `getErrorReporter({ beforeSend: (r) => ({ ...r, user: undefined }) })`. |
+
+- Error boundaries catch **render/lifecycle** errors, not errors in event handlers or async code; those reach the `GlobalErrorListener` (or call `report`).
+- `getErrorReporter` ignores options after the first call; configure it once, early.
+- The default fallback does not render `title`; it shows `message` (or the mapped user message).
+- A `GlobalError` reset on navigation means a crash on one route does not stick to the next.
+
+## 10. File map
+
+| File           | Responsibility                                                                                            |
+| :------------- | :-------------------------------------------------------------------------------------------------------- |
+| `index.ts`     | Public barrel.                                                                                            |
+| `types.ts`     | Report, context, environment, reporter options, boundary props, Sentry scope.                             |
+| `constants.ts` | Messages, listener config (limits, ignore patterns), dedupe limits.                                       |
+| `utils.ts`     | Fingerprinting, report creation, environment capture, error normalization and ignore rules.               |
+| `boundary.tsx` | `ErrorBoundaryCore`, default fallback, `GlobalError`, `ModuleError`, `ComponentError`: the module's view. |
+| `listener.ts`  | `GlobalErrorListener`.                                                                                    |
+| `reporter.ts`  | `ErrorReporter` (sampling, dedupe, handlers) and sink factories.                                          |
+| `theme.ts`     | `errorTheme` spec.                                                                                        |
+
+`builder.ts`, `provider.tsx`, `view.tsx` and `motion.ts` are intentionally absent ([README](./README.md#42-why-some-optional-slots-are-absent)).
+
+## 11. Dependencies
+
+- **Uses:** `@omerdlw/base-framework/events` (`APP_ERROR`), `@omerdlw/base-framework/atoms` (`Button`, `Icon` for the fallback), `@omerdlw/base-framework/theme`, `@omerdlw/base-framework/utils` (`report`, `setReportSink`, `toUserMessage`), `next/navigation` (`usePathname`).
+- **Used by:** `src/core/provider.tsx`; the dock (turns `APP_ERROR` into its error status) and the notification module (toasts `APP_ERROR` with `notify: true`) react to the event without importing this module.

package/docs/modules/kernel.md

@@ -0,0 +1,266 @@
+# Kernel — `@omerdlw/base-framework/kernel`
+
+> **Read this first if you need to:** register something for the current page (`usePage`), understand how modules install and find each other, write your own module, or debug why a registration did or did not win.
+
+## 1. At a glance
+
+|                      |                                                                                                                       |
+| :------------------- | :-------------------------------------------------------------------------------------------------------------------- |
+| **Import**           | `import { usePage, defineModule, definePeer, useModule, … } from "@omerdlw/base-framework/kernel"`                                     |
+| **Layer**            | `src/core` (frozen upstream). Knows **no module by name**; never imports `@omerdlw/base-framework/modules/**`, `@/features/**`, `@/app/**`. |
+| **Mounted by**       | `CoreProvider` (`src/core/provider.tsx`) → `ModuleHost`                                                               |
+| **State**            | A scoped, subscribable **registry** (`createRegistryStore`) and a **page controller stack**                           |
+| **Extension points** | `defineModule({...})`, module augmentation of `CoreModules`, `PageConfig`, `RegistrySchema`                           |
+| **Tests**            | `tests/core/kernel.test.ts`                                                                                           |
+
+## 2. Mental model
+
+```
+CoreProvider
+ └─ GlobalError ─ Tooltip ─ ModuleHost ───────────────────────────────────────────────┐
+     │  1. sortModules(modules)           ← dependency order from `uses`, validates ids │
+     │  2. RegistryProvider               ← one registry; types come from module `registry` definitions
+     │  3. ModuleHost context             ← id → module map, boundary component
+     │  4. PageControllerProvider         ← the stack of mounted usePage() controllers
+     │  5. providers nested (module N inside the modules it `uses`)
+     │  6. <Backdrop/> per module → {children} → <Overlay/> per module   (each in an error boundary)
+     └────────────────────────────────────────────────────────────────────────────────┘
+
+usePage(config)
+  for every installed module:  page.select(config)  →  slice
+                               page.entries(slice)  →  registry entries   (applied in ONE batch)
+                               page.use(slice, {set}) → page.modules[id]  (the module's page API)
+```
+
+Three pieces:
+
+1. **Modules** — self-describing units (`defineModule`). They reach each other only through `useModule` / `useModuleState` / `definePeer`, never by importing.
+2. **The registry** — a key/value store per module type. Several _sources_ can register the same key; the kernel picks (or merges) the winner and cleans up per lifecycle.
+3. **Pages** — `usePage(config)` turns one object into every module's registrations and page API. The kernel itself only owns `title`, `registry`, `set` and `reset`.
+
+## 3. Quick start
+
+```tsx
+"use client";
+import { usePage } from "@omerdlw/base-framework/kernel";
+
+export function DashboardClient() {
+  const page = usePage({
+    title: "Dashboard", // kernel: also the dock title fallback
+    dock: { description: "Overview", icon: "solar:chart-2-bold" },
+    background: { image: "/images/dashboard.jpg", overlay: true },
+    loading: isFetching,
+    contextMenu: {
+      items: [{ key: "refresh", label: "Refresh", onSelect: refetch }],
+    },
+  });
+
+  return (
+    <Button onClick={() => page.modules.notification?.toast("Saved")}>
+      Save
+    </Button>
+  );
+}
+```
+
+```ts
+// Static route metadata: src/app/registry.tsx (registry type = module id)
+export const APP_REGISTRY_ENTRIES = [
+  {
+    type: "dock",
+    items: { "/": { title: "Home", icon: "solar:home-2-bold", path: "/" } },
+  },
+];
+```
+
+## 4. `usePage`
+
+```ts
+const page = usePage(config?: PageConfig, options?: PageOptions): PageController
+```
+
+| `PageController` member | Meaning                                                                                                                                                                                                                          |
+| :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `config`                | The effective config (your object merged with runtime `set` overrides).                                                                                                                                                          |
+| `modules`               | Each module's **page API** (`page.modules.dock`, `.background`, `.notification` …). Present only when the module is installed **and** defines `page.use`. Always use optional chaining: `page.modules.notification?.toast(...)`. |
+| `set(partial)`          | Shallow-merge runtime overrides into the config (objects one level deep). Modules expose typed wrappers (`page.modules.dock.set({...})`).                                                                                        |
+| `reset()`               | Drop all runtime overrides.                                                                                                                                                                                                      |
+| `Provider`              | A component that scopes this controller to a subtree (`usePageController()` inside it returns _this_ controller).                                                                                                                |
+
+`PageConfig` always has `title?` and `registry?`; every module **augments** it (`dock?`, `background?`, `loading?`, `modal?`, `controls?`, `contextMenu?`, `ambient?`, `media?`, `notification?`).
+
+`PageOptions` (second argument): registry metadata applied to **all** the page's registrations (`priority`, `source`, `lifecycle`, `scope`, `instanceId`, …). A module slice can override it per item with its own `registry` key.
+
+### 4.1 What happens on each render
+
+1. `config` + runtime overrides → `effectiveConfig`.
+2. Every module's `page.select` computes its slice; `createModulePayload` keeps modules that have `page.entries` and a non-null slice.
+3. **Stabilization.** The payload is walked and (a) object/array identity is reused when nothing changed, (b) function values (arrow functions, handlers) are replaced by **stable proxies** that always call the latest function, and (c) React elements are cloned with stabilized props. Result: inline `onClick`/`items: () => …` do **not** cause re-registration on every render. Functions whose name starts with a capital letter (components) and direct component values of `valueKind: "component"` types are passed through by identity.
+4. `applyRegistryConfig` validates (`definition.validate`), then registers every entry in **one batch**; the cleanup runs when the payload changes or the component unmounts.
+5. Each module's `page.use(slice, { set })` runs (it is a hook, so it must not be conditional) and the results become `page.modules`.
+
+### 4.2 Rules
+
+- Call `usePage` once per page component (or layout) at the top level. It is a hook; do not call it conditionally.
+- `usePageController()` is the read-only variant: it returns the active controller without registering anything (used by chrome that needs the current page).
+- Server components cannot call it: put it in a `"use client"` component.
+
+## 5. Registry
+
+### 5.1 Type definitions (`RegistryDefinition`, on `defineModule({ registry })`)
+
+| Field                          | Meaning                                                                                                                                                           |
+| :----------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `keyPolicy`                    | `"singleton"` (one fixed `singletonKey`), `"named"` (any non-empty string), `"path"` (must start with `/`), `"route"` (a `/…` path **or** one of `reservedKeys`). |
+| `lifecycle`                    | Default lifecycle (below).                                                                                                                                        |
+| `cleanupDelayMs`               | Default delay for delayed cleanup.                                                                                                                                |
+| `valueKind`                    | `"object"` (default: values must be plain objects) or `"component"` (functions or component objects).                                                             |
+| `merge(valuesLowToHigh)`       | Combine several sources instead of picking one (dock merges card fields and styles).                                                                              |
+| `validate(value)`              | Return `{ valid, issues }`; invalid values are skipped with a warning (`strict` mode also validates metadata).                                                    |
+| `reservedKeys`, `singletonKey` | See key policies.                                                                                                                                                 |
+
+### 5.2 Who wins
+
+For one `(type, key)` every registration is a **record** with `source`, `priority`, and a sequence number. Records are ordered by:
+
+1. `priority` — explicit number, otherwise derived from the source (`static` 100, `dynamic` 200, `user` 300);
+2. source rank (`static` < `dynamic` < `user`);
+3. recency (the later registration wins ties).
+
+The highest record is the value, **or** `definition.merge` receives all values from lowest to highest (only when all are plain objects).
+
+| Source    | Typical use                                          |
+| :-------- | :--------------------------------------------------- |
+| `static`  | `src/app/registry.tsx` initial entries.              |
+| `dynamic` | **Default** for `usePage` / `useModuleRegistration`. |
+| `user`    | User-driven overrides. Pass `{ source: "user" }`.    |
+
+`REGISTRY_SOURCES` exposes the vocabulary.
+
+### 5.3 Lifecycles
+
+| Lifecycle           | Cleanup when the registering page/component goes away                                                                                                   |
+| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `immediate`         | Entry removed in the same batch (forces a delay of 0 even if the type declares one).                                                                    |
+| `graceful`, `route` | Removed after `cleanupDelayMs` (from options or the type definition) — so route transitions do not flicker. With no delay they behave like `immediate`. |
+| `persistent`        | Never removed by the page; use `unregister`.                                                                                                            |
+
+A pending cleanup is **cancelled** if the same entry is re-registered before the timer fires.
+
+### 5.4 Metadata keys (`RegistryMetadata`)
+
+`lifecycle` (or `cleanup`), `cleanupDelayMs`, `priority`, `source`, `scope`, `instanceId`, `validation` (`"warn"` default or `"strict"`). Anything else is reported by `validateRegistryMetadata`. `scope` partitions entries (default `"app"`); `instanceId` is stamped by the kernel so a component only unregisters its own entries.
+
+### 5.5 Reading the registry
+
+| Hook                          | Returns                                                          |
+| :---------------------------- | :--------------------------------------------------------------- |
+| `useRegistryValue(type, key)` | The resolved value of one key (re-renders only when it changes). |
+| `useRegistryEntries(type)`    | `Record<key, value>` of every key of a type.                     |
+
+The store also supports `register` / `unregister` / `batch` / `transaction` (atomic multi-entry change with a trace id) through `createRegistryStore`; most code never calls them directly (`usePage` and `useModuleRegistration` do).
+
+## 6. Modules
+
+### 6.1 `defineModule`
+
+```ts
+export const myModule = defineModule({
+  id: "announcement",                 // camelCase: /^[a-z][a-zA-Z0-9]*$/ ("contextMenu", not "context-menu")
+  context: MyContext,                 // React context carrying { actions, store } (ModuleRuntime)
+  Provider: MyProvider,               // wraps the app (nested after the modules it `uses`)
+  Backdrop: MyBackdrop,               // rendered BEFORE children (behind the page)
+  Overlay: MyOverlay,                 // rendered AFTER children (above the page)
+  uses: ["background"],               // optional peers (ordering + dev warning if missing)
+  registry: { keyPolicy: "singleton", singletonKey: "current", lifecycle: "route" },
+  page: {
+    select: (config) => config.announcement,           // default: config[id]
+    entries: (slice, { pathname }) => [{ key: "current", value: slice }],
+    use: (slice, { set }) => ({ show: () => set({ announcement: {...} }) }),   // page.modules.announcement
+  },
+});
+
+declare module "@omerdlw/base-framework/kernel" {
+  interface CoreModules { announcement: typeof myModule }
+  interface PageConfig { announcement?: AnnouncementConfig }
+}
+```
+
+`defineModule` freezes and returns the definition. `ModuleHost` throws on **invalid ids**, **duplicate ids**, and **dependency cycles**; in development it warns when a `uses` peer is not installed. Every field except `id` is optional: a module can be only an overlay, only a registry type, only a provider.
+
+### 6.2 Talking to other modules
+
+| API                                                | Use                                                                                                                                                                                                            |
+| :------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `useModule(id)`                                    | The module's runtime `{ actions, store }`, or `null` when not installed.                                                                                                                                       |
+| `useModuleState(id, selector, fallback, isEqual?)` | A slice of another module's state; returns `fallback` when it is not installed. Only re-renders when the slice changes.                                                                                        |
+| `definePeer(id, inert)`                            | A typed reader `{ useRuntime, useActions, useState }` that falls back to the `inert` stand-in when the module is missing. **List the id in `uses`.** This is the pattern the dock, background and ambient use. |
+| `useIsModuleInstalled(id)`                         | Boolean.                                                                                                                                                                                                       |
+| `ModuleBoundary`                                   | Wrap module UI in the host's error boundary (`name` is shown in the error UI).                                                                                                                                 |
+
+Pass the module id to `useModule`, `useModuleState` and `definePeer` as a **string literal** (`definePeer("media", …)`) and list it in the module's `uses`: `npm run check:architecture` greps for both.
+
+### 6.3 Install order and rendering
+
+`sortModules` orders modules so that every module comes **after** the modules it `uses`; `ModuleHost` nests providers in that order (a later module's provider is _inside_ earlier ones, so it can read them). All **Backdrops** render first, then `children`, then all **Overlays**, each wrapped in the boundary passed to the host (`ModuleError` from `@omerdlw/base-framework/error` in `CoreProvider`).
+
+### 6.4 Registering without `usePage`
+
+`useModuleRegistration(id, value, { enabled?, ...metadata })` registers one module's slice (each module re-exports a named wrapper: `useDockRegistration`, `useBackgroundRegistration`, `useLoadingRegistration`, …). `enabled: false` or a `null` value removes it.
+
+## 7. Public API
+
+| Export                                                                                                                            | Kind                       | Description                                                                                                                                                                                                                                    |
+| :-------------------------------------------------------------------------------------------------------------------------------- | :------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `defineModule(definition)`                                                                                                        | factory                    | Declare a module (§6.1).                                                                                                                                                                                                                       |
+| `ModuleHost`, `ModuleBoundary`                                                                                                    | components                 | Install modules; wrap UI in the module error boundary.                                                                                                                                                                                         |
+| `useModule`, `useModuleState`, `useIsModuleInstalled`, `definePeer`                                                               | hooks / factory            | Module-to-module access (§6.2).                                                                                                                                                                                                                |
+| `useModuleRegistration`                                                                                                           | hook                       | Register one slice outside `usePage`.                                                                                                                                                                                                          |
+| `usePage`, `usePageController`, `PageControllerProvider`                                                                          | hooks / provider           | Page registration and read access (§4).                                                                                                                                                                                                        |
+| `RegistryProvider`, `useRegistryValue`, `useRegistryEntries`, `createRegistryStore`                                               | provider / hooks / factory | Registry access (§5).                                                                                                                                                                                                                          |
+| `createRegistryOperations`, `createModuleRegistryDefinitions`, `sortModules`, `applyRegistryConfig`, `createRegistryApplyContext` | functions                  | Lower-level pieces (used by the host and by tests).                                                                                                                                                                                            |
+| `Compose`, `ProviderEntry`                                                                                                        | component / type           | Nest providers from a list (`[Component, props]` tuples allowed).                                                                                                                                                                              |
+| `REGISTRY_SOURCES`, `hasOwnProperty`                                                                                              | constants / util           |                                                                                                                                                                                                                                                |
+| Types (`export * from "./types"`)                                                                                                 |                            | `CoreModule`, `CoreModules`, `ModuleId`, `ModuleRuntime`, `ModuleStateOf`, `PageConfig`, `PageController`, `PageModules`, `PageOptions`, `RegistryDefinition`, `RegistryMetadata`, `RegistrySchema`, `AppRegistryEntry`, `ValidationResult`, … |
+
+## 8. Recipes and gotchas
+
+| I want to…                                     | Do this                                                                                                                      |
+| :--------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------- |
+| Static page metadata for every route           | Add to `APP_REGISTRY_ENTRIES` in `src/app/registry.tsx`.                                                                     |
+| Let a layout set a default that pages override | Register in the layout with `{ source: "static" }` (or a lower `priority`); pages use the default `dynamic`.                 |
+| Install only some modules                      | `<CoreProvider modules={[dockModule, notificationModule]}>`. Modules that `use` a missing peer fall back to inert stand-ins. |
+| Add my own module                              | Follow §6.1; export it, append it to `modules`, augment the kernel types. No edits to `src/core`.                            |
+| Read a module's state without coupling         | `useModuleState("dock", s => s.expanded, false)`.                                                                            |
+
+- `page.modules.x` is `undefined` for modules that are not installed or have no `page.use`: use `?.`.
+- `ModuleHost` reads the `modules` list **once** (at mount). Changing the array later has no effect; decide the module set before rendering `CoreProvider`.
+- A `useRegistryValue` read happens **after** the registering effect: the first render of the registering component sees `undefined`.
+- `usePage` registrations are page-scoped: they disappear (per lifecycle) when the component unmounts, so call it in the component that owns the page.
+- A module id is an identifier everywhere (registry type, `page.modules[id]`, `uses`): keep it camelCase and stable.
+
+## 9. File map
+
+| File                  | Responsibility                                                                                                       |
+| :-------------------- | :------------------------------------------------------------------------------------------------------------------- |
+| `index.ts`            | Public barrel.                                                                                                       |
+| `types.ts`            | Registry, module, page-config and controller contracts.                                                              |
+| `constants.ts`        | Registry sources, source priority/rank, lifecycles, metadata keys, default scope.                                    |
+| `utils.ts`            | Input and scope resolution, config merging (`mergeModuleConfigs`), small guards.                                     |
+| `schema.ts`           | Key/value/metadata validation, metadata normalization (lifecycle → cleanup delay).                                   |
+| `operations.ts`       | Pure registry state machine (`createRegistryOperations`): records, ordering, merge, resolution cache.                |
+| `store.ts`            | `createRegistryStore`: subscriptions, snapshots, handles, `batch`, `transaction`.                                    |
+| `runtime.ts`          | Transactions.                                                                                                        |
+| `provider.tsx`        | `RegistryProvider`, `useRegistryValue`, `useRegistryEntries`, `useRegistryActions`.                                  |
+| `handlers.ts`         | `applyRegistryConfig`: slices → entries in one batch, cleanup per lifecycle.                                         |
+| `hooks.ts`            | `useRegistry` (select → stabilize → apply), `createRegistryApplyContext`, `useShallowStable`, config stabilization.  |
+| `adapters.tsx`        | `useModuleRegistration`.                                                                                             |
+| `installed.ts`        | Host context, `sortModules`, payload creation, registry definitions from modules.                                    |
+| `module.tsx`          | `defineModule`, `ModuleHost`, `useModule`, `useModuleState`, `definePeer`, `ModuleBoundary`, `useIsModuleInstalled`. |
+| `page-controller.tsx` | `usePage` (producer), `usePageController` (consumer), controller stack and scopes.                                   |
+| `compose.ts`          | `Compose` and provider-entry helpers.                                                                                |
+
+## 10. Dependencies
+
+- **Uses:** `@omerdlw/base-framework/utils`, `@omerdlw/base-framework/hooks` only. It names no module and imports no upper layer.
+- **Used by:** every module (`defineModule`, registry hooks, peers), `src/core/provider.tsx` (mounts `ModuleHost`), `src/app/registry.tsx` (initial entries), pages and features (`usePage`, `useModuleState`).

package/docs/modules/loading.md

@@ -0,0 +1,157 @@
+# Loading — `@omerdlw/base-framework/modules/loading`
+
+> **Read this first if you need to:** show a full-screen loading state for a page or an async action, keep a spinner up long enough not to flicker, supply your own skeleton, or read "is the app busy" from another module.
+
+## 1. At a glance
+
+|                    |                                                                                                           |
+| :----------------- | :-------------------------------------------------------------------------------------------------------- |
+| **Import**         | `import { useLoadingActions, useLoading, defineLoading, … } from "@omerdlw/base-framework/modules/loading"`                     |
+| **Module id**      | `loading` (`loadingModule`, in `defaultModules`)                                                          |
+| **Renders**        | `LoadingOverlay`: a fixed full-screen `<div role="status" aria-busy>` with a `Spinner` (or your skeleton) |
+| **Registry type**  | `loading` — singleton key `page-loading`, lifecycle `graceful`, cleanup delay 600 ms                      |
+| **Page slice**     | `usePage({ loading })` → `page.modules.loading` (all actions + `set`)                                     |
+| **Peers (`uses`)** | none (the dock reads _this_ module through `definePeer("loading")`)                                       |
+| **Theme**          | `loadingTheme` slot `overlay` in `src/config/loading.module.theme.ts`                                     |
+| **z-index**        | `Z_INDEX.LOADING` (set in the theme `styles`)                                                             |
+| **Tests**          | `tests/modules/loading.test.ts`                                                                           |
+
+## 2. Mental model
+
+There are two independent sources of "loading", merged into one state:
+
+```
+page-registered  (usePage({ loading }), useLoading(config))   ← declarative, tied to the route
+manual           (startLoading / stopLoading / withLoading)   ← imperative, tied to a task
+        └────────────── LoadingStateWithPage ──────────────┘
+```
+
+- **Page-registered wins.** If the registered config has `isLoading: true`, its `message`, `skeleton`, `showOverlay` (and the fact that it is loading) are used and the manual state is ignored until it turns `false`.
+- Otherwise the **manual** state is used.
+- The overlay appears when `isLoading && showOverlay` **and** no `FullscreenState` primitive is active (a full-screen empty/error state always takes precedence).
+- Separately from the overlay, the **dock** reacts to `isLoading` (it shows its loading card; see [dock.md §7](./dock.md#7-attention-who-owns-the-top-card)). `showOverlay: false` suppresses only the full-screen overlay, not the dock's loading card.
+
+## 3. Quick start
+
+```tsx
+// Declarative: loading while a route-level query resolves
+usePage({ loading: isFetching ? "Loading profile…" : false }); // string = message (and loading)
+
+// Imperative: the overlay stays up at least `minDuration`
+const { withLoading } = useLoadingActions();
+await withLoading(saveSettings(), { message: "Saving…", minDuration: 400 });
+await withLoading(() => refresh(), "Refreshing…"); // a string is the message
+
+// From the page controller
+const page = usePage({ loading: false });
+page.modules.loading?.set("Refreshing…");
+```
+
+```tsx
+// Reusable preset
+const CheckoutLoading = defineLoading({
+  message: "Processing payment",
+  showOverlay: true,
+});
+CheckoutLoading.use(isSubmitting); // boolean | message string | LoadingOptions
+```
+
+## 4. Public API
+
+| Export                                                          | Kind      | Description                                                                                                                               |
+| :-------------------------------------------------------------- | :-------- | :---------------------------------------------------------------------------------------------------------------------------------------- |
+| `loadingModule`                                                 | module    | `defineModule` definition.                                                                                                                |
+| `LoadingProvider`                                               | component | Holds manual state, timers, merges the page-registered value, publishes the store. Mounted by the host.                                   |
+| `LoadingOverlay`                                                | component | The overlay. Mounted by the host.                                                                                                         |
+| `useLoading(config?, options?)`                                 | hook      | Registers `config` as the page's loading config **and** returns `{ ...state, ...actions }`. `options`: `RegistryMetadata & { enabled? }`. |
+| `useLoadingState()`                                             | hook      | `LoadingStateWithPage` (re-renders on change). Throws outside the provider.                                                               |
+| `useLoadingActions()`                                           | hook      | Stable actions.                                                                                                                           |
+| `useLoadingRegistration(config, options?)`                      | hook      | Register only (what `usePage` does).                                                                                                      |
+| `defineLoading(def)`                                            | builder   | `defineLoading(options \| message).use(overrides?, options?)` → `LoadingStateWithPage & LoadingActions`.                                  |
+| `LoadingContext`                                                | context   | For tests and the dock's peer reader.                                                                                                     |
+| `DEFAULT_LOADING_STATE`, `LOADING_REGISTRY_KEY`, `loadingTheme` | constants |                                                                                                                                           |
+| `normalizeLoadingOptions(options)`, `selectPageLoading(input)`  | utils     | Coerce loose input; map `boolean` / `string` / object page input to `LoadingOptions`.                                                     |
+| Types                                                           |           | `LoadingState`, `LoadingStateWithPage`, `LoadingOptions`, `LoadingActions`, `LoadingPageConfig`, `DefinedLoading`, …                      |
+
+### 4.1 `LoadingOptions`
+
+| Option        | Default | Meaning                                                                  |
+| :------------ | :------ | :----------------------------------------------------------------------- |
+| `isLoading`   | —       | Only meaningful for page-registered configs.                             |
+| `message`     | `null`  | Text (non-strings are dropped). Available in state for custom skeletons. |
+| `skeleton`    | `null`  | A node shown instead of the spinner.                                     |
+| `minDuration` | `0`     | Minimum ms the **manual** loading stays up. Non-positive / invalid → 0.  |
+| `showOverlay` | `true`  | `false` keeps state without the full-screen overlay.                     |
+
+### 4.2 `LoadingStateWithPage`
+
+`{ isLoading, isPageLoading, message, skeleton, minDuration, showOverlay }`. `isPageLoading` is `true` whenever loading is on (page-registered or manual).
+
+### 4.3 Actions
+
+| Action                                  | Behaviour                                                                                                                                |
+| :-------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |
+| `startLoading(options?)`                | Turn manual loading on (cancels a pending delayed stop) and record the start time.                                                       |
+| `stopLoading()`                         | Turn it off. If `minDuration` has not elapsed yet, the stop is **delayed** by the remaining time. With no `minDuration` it is immediate. |
+| `setLoading(boolean)`                   | Shorthand for the two above (no options).                                                                                                |
+| `setSkeleton(nodeOrUpdater)`            | Replace the manual skeleton; accepts `(current) => next`. No re-render when unchanged.                                                   |
+| `withLoading(task, options \| message)` | `startLoading`, await the promise (or call the function and await its result), `stopLoading` in `finally`. Rejections propagate.         |
+
+`page.modules.loading` = these actions plus `set(loading)` (`page.set({ loading })`).
+
+### 4.4 Page input forms
+
+| `usePage({ loading })` | Becomes                                      |
+| :--------------------- | :------------------------------------------- |
+| `true` / `false`       | `{ isLoading }`                              |
+| `"Loading…"`           | `{ isLoading: true, message: "Loading…" }`   |
+| object                 | used as is (needs `isLoading: true` to show) |
+| `null` / `undefined`   | nothing registered                           |
+
+The same value also feeds the dock's `isLoading` card flag (`usePage({ dock })` derives it from `loading`).
+
+## 5. Behaviour details
+
+- **Graceful cleanup.** The registry entry survives 600 ms after the page unmounts, so a route change does not flash the overlay off and on between pages.
+- **`minDuration` is manual-only.** Page-registered loading ends as soon as the page stops declaring it.
+- **Navigation.** The dock calls `stopLoading()` after a navigation completes or times out (15 s), so a `startLoading()` made before navigating does not stick.
+- **No counter.** Manual loading is a single flag. Two overlapping `withLoading` calls share it: the **first** to finish stops it. Use a page-level `loading` flag derived from your own pending count if you need reference counting.
+- **Fullscreen suppression.** While `useIsFullscreenStateActive()` is true (a full-screen view is active) the overlay is hidden.
+- **Accessibility.** The overlay has `role="status"`, `aria-busy="true"` and `aria-label="Loading"`.
+- **Next.js `loading.tsx`.** `src/app/loading.tsx` (a bare `Spinner`) is the route-segment fallback and is independent of this module.
+
+## 6. Theming
+
+No classes or inline styles in the module. The `loadingTheme` slot `overlay` (starter: `center fixed inset-0 h-screen w-screen`) and its `styles` (`zIndex: Z_INDEX.LOADING`) come from `src/config/loading.module.theme.ts`. The default content is `<Spinner size={30} />`; pass a `skeleton` to replace it. The overlay has no animation (it mounts and unmounts instantly; [README](./README.md#42-why-some-optional-slots-are-absent)).
+
+## 7. Recipes and gotchas
+
+| I want to…                                  | Do this                                                                                      |
+| :------------------------------------------ | :------------------------------------------------------------------------------------------- |
+| Block the UI during a mutation              | `await withLoading(mutate(), "Saving…")`                                                     |
+| Avoid a flash for fast tasks                | `minDuration: 300` (only delays the _stop_; it does not delay showing).                      |
+| Loading state without the overlay           | `showOverlay: false` and read `useLoadingState().isLoading` yourself.                        |
+| Know if the app is busy from another module | `definePeer("loading", inert)` and `useState((s) => s.isLoading)`; list `loading` in `uses`. |
+| A custom loader                             | `skeleton: <MyLoader />` in the options.                                                     |
+
+- `useLoading(config)` registers the config for the **page**, not for the component; two components registering different configs fight over the singleton key (higher registry priority wins).
+- `defineLoading(...).use(false)` registers `{ isLoading: false }`, which is a no-op loading state (useful to switch it off).
+- A `message` is stored in state but the default overlay does not print it; render it in your `skeleton`.
+
+## 8. File map
+
+| File           | Responsibility                                                                                    |
+| :------------- | :------------------------------------------------------------------------------------------------ |
+| `index.ts`     | Public barrel.                                                                                    |
+| `types.ts`     | State, options, actions, definition, page-config and theme contracts.                             |
+| `constants.ts` | `DEFAULT_LOADING_STATE`, registry key, `loadingTheme`.                                            |
+| `utils.ts`     | `normalizeLoadingOptions`, `selectPageLoading`.                                                   |
+| `context.tsx`  | `LoadingProvider` (manual state, min-duration timer, registry merge, store), `useLoading*` hooks. |
+| `hooks.ts`     | `useLoadingOverlayModel` (visibility incl. fullscreen check, theme).                              |
+| `overlay.tsx`  | `LoadingOverlay`.                                                                                 |
+| `module.tsx`   | `loadingModule`, page API, `defineLoading`, kernel type augmentation.                             |
+
+## 9. Dependencies
+
+- **Uses:** `@omerdlw/base-framework/kernel` (`defineModule`, `useModuleRegistration`, `useRegistryValue`), `@omerdlw/base-framework/atoms` (`Spinner`), `@omerdlw/base-framework/hooks` (`useIsFullscreenStateActive`), `@omerdlw/base-framework/utils` (`createStore`), `@omerdlw/base-framework/theme`.
+- **Used by:** `src/core/provider.tsx` (installs it); the **dock**, which reads `isLoading` and calls `stopLoading` through `definePeer("loading")` (inert when not installed); pages and features through `useLoading*` / `page.modules.loading`.