@omerdlw/base-framework 1.0.0 → 1.0.2

package/docs/modules/media.md

@@ -0,0 +1,196 @@
+# Media — `@omerdlw/base-framework/modules/media`
+
+> **Read this first if you need to:** play an audio file for a page, make sure the dock's media controls work for audio or video, sync an audio track to the background video, or understand which source the controls operate on.
+
+## 1. At a glance
+
+|                   |                                                                                                                                                                                                                     |
+| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Import**        | `import { useMedia, MediaSource, … } from "@omerdlw/base-framework/modules/media"`                                                                                                                                                        |
+| **Module id**     | `media` (`mediaModule`, in `defaultModules`)                                                                                                                                                                        |
+| **Renders**       | Nothing. `MediaOverlay` is an overlay that returns `null`; it only plays the page's declared audio.                                                                                                                 |
+| **Registry type** | `media` — singleton key `page-media`, lifecycle `immediate` (entries are removed the moment the registering page unmounts; the declared 600 ms delay applies only if a registration opts into `graceful` / `route`) |
+| **Page slice**    | `usePage({ media })` → controller `page.modules.media`                                                                                                                                                              |
+| **Peers**         | none (it _is_ a peer: `background` and `dock` read it through `definePeer("media")`)                                                                                                                                |
+| **Theme**         | none (the controls are themed by the dock: `media*` and `scrubber*` slots)                                                                                                                                          |
+| **Tests**         | `tests/modules/media.test.ts` (session resolution, follower sync, displacement)                                                                                                                                     |
+
+## 2. Mental model
+
+The dock shows **one** set of media controls. The `media` module decides what those controls operate on. Any code can register a **source** (a playing element); the module resolves all registered sources into one **session**:
+
+```
+sources ──resolveMediaSession──▶ { transport, audible, followers }
+                                   │         │         └─ mirror the transport (play/pause/seek/speed)
+                                   │         └─ volume & mute controls
+                                   └─ play/pause, scrubber, ±10 s, speed, loop, PiP
+```
+
+| Group         | Controls                                                     | Bound to                                                                       |
+| :------------ | :----------------------------------------------------------- | :----------------------------------------------------------------------------- |
+| **Transport** | play/pause, scrubber, ±10 s, speed, loop, Picture-in-Picture | the newest **standalone** source                                               |
+| **Audible**   | volume, mute                                                 | the newest **audio follower** of the transport; otherwise the transport itself |
+
+A source is a **follower** only when it says so explicitly with `follow: "<id>"`. Followers never get their own controls.
+
+| Scenario                                                      | Transport  | Audible    |
+| :------------------------------------------------------------ | :--------- | :--------- |
+| Background video only                                         | video      | video      |
+| Audio only                                                    | audio      | audio      |
+| Muted background video + `useMedia({ follow: "background" })` | video      | audio      |
+| Video + audio with no `follow`                                | newest one | newest one |
+
+Picture-in-Picture is offered only when the transport is a video.
+
+## 3. Quick start
+
+```tsx
+// Page level: a URL, or the same options as useMedia (minus id/enabled).
+// The audio belongs to the route and stops when the user leaves it.
+usePage({ media: "/audio/rain.mp3" });
+usePage({ media: { src: "/audio/rain.mp3", loop: true, volume: 0.6 } });
+```
+
+```tsx
+// Component level: the source lives as long as the component is mounted
+function Ambience() {
+  const { toggle } = useMedia({ src: "/audio/rain.mp3", loop: true });
+  return <button onClick={toggle}>Play / pause</button>;
+}
+
+// Declarative form
+<MediaSource src="/audio/rain.mp3" loop />;
+```
+
+```tsx
+// Muted background video + a parallel audio track.
+// The video drives the timeline; volume and mute control the audio.
+usePage({
+  background: { video: "/video/city.mp4", videoOptions: { muted: true } },
+});
+return <MediaSource src="/audio/city.mp3" follow={BACKGROUND_MEDIA_ID} />; // "background"
+```
+
+## 4. Behaviour
+
+- **Registration.** `useMedia` creates an `HTMLAudioElement` (`preload="auto"`) when `src` is truthy and `enabled` is not `false`, registers it, and mirrors its `play` / `playing` / `pause` / `ended` events into `isPlaying`. On cleanup it pauses, clears `src`, and unregisters.
+- **Autoplay.** Standalone sources try to play immediately unless `autoplay: false`. Followers never autoplay: they start when the transport starts. A blocked autoplay leaves the source paused and the dock shows a play button.
+- **Following.** `bindFollowers` mirrors `play`, `playing`, `pause`, `waiting`, `ended`, `seeking`, `seeked`, `ratechange` and `timeupdate`; sets follower playback rate to the transport's; and corrects drift only when it exceeds `MEDIA_SYNC_DRIFT_SECONDS` (0.3 s) during playback (hard-seeks on seeks). Followers' own `loop` is disabled while bound and restored on cleanup.
+- **Displacement.** When a **new standalone** source takes over the controls, other standalone audio that is still playing is **paused**, so two tracks never play over each other while the dock only controls one. Videos, followers and already-paused tracks are untouched, and a paused track does not resume on its own when the newer one goes away.
+- **Edge cases are resolved, never thrown.** A `follow` whose target is missing, is itself a follower, or points at itself makes the source standalone. Follow cycles never leave the dock without a transport. When a standalone source unmounts, control falls back to the previous one.
+- **State updates.** The published `MediaState` is shallow-compared; unrelated source updates do not re-render consumers.
+- **Page media.** `MediaOverlay` reads the registry value, and calls `useMedia({ ...page, id: "page", src })`. When the page unmounts the registry drops the value, which stops the audio.
+
+## 5. Public API
+
+| Export                                                                                   | Kind      | Description                                                                                                                                                     |
+| :--------------------------------------------------------------------------------------- | :-------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mediaModule`                                                                            | module    | `defineModule` definition (provider, overlay, `usePage({ media })`).                                                                                            |
+| `MediaProvider`                                                                          | component | Source registry, session resolution, follower sync, actions. Mounted by the host.                                                                               |
+| `useMedia(options)`                                                                      | hook      | Register an audio file for the lifetime of the component. Returns `{ id, play, pause, toggle }`.                                                                |
+| `MediaSource`                                                                            | component | Declarative form of `useMedia` (renders `null`).                                                                                                                |
+| `MediaOverlay`                                                                           | component | Plays the page-declared `media`. Mounted by the host.                                                                                                           |
+| `useMediaState()`                                                                        | hook      | Read-only `MediaState` (re-renders on change).                                                                                                                  |
+| `useMediaActions()`                                                                      | hook      | `MediaActions`. Both hooks throw outside `MediaProvider`.                                                                                                       |
+| `MediaContext`                                                                           | context   | For tests / custom providers.                                                                                                                                   |
+| `resolveMediaSession(sources)`                                                           | util      | Pure: sources → `{ transport, audible, followers }` or `null`.                                                                                                  |
+| `createMediaState(session)`                                                              | util      | Session → `MediaState` (`DEFAULT_MEDIA_STATE` for `null`).                                                                                                      |
+| `bindFollowers(transport, followers)`                                                    | util      | Wire followers to a transport element; returns a cleanup function.                                                                                              |
+| `selectPageMedia(media)`                                                                 | util      | Normalizes `usePage({ media })` input.                                                                                                                          |
+| `DEFAULT_MEDIA_STATE`, `MEDIA_REGISTRY_KEY`, `MEDIA_SYNC_DRIFT_SECONDS`, `PAGE_MEDIA_ID` | constants | `PAGE_MEDIA_ID` is `"page"`.                                                                                                                                    |
+| Types                                                                                    |           | `MediaOptions`, `MediaHandle`, `MediaState`, `MediaActions`, `MediaEntry`, `MediaEntryInput`, `MediaSession`, `MediaKind`, `MediaPageConfig`, `MediaPageApi`, … |
+
+### 5.1 `useMedia` / `<MediaSource>` options
+
+| Option            | Default                     | Meaning                                                                                           |
+| :---------------- | :-------------------------- | :------------------------------------------------------------------------------------------------ |
+| `src`             | —                           | Audio URL. A falsy value registers nothing.                                                       |
+| `id`              | generated (`media-<useId>`) | Stable id other sources can `follow`.                                                             |
+| `follow`          | `null`                      | Id of the source to mirror, e.g. `"background"`. Always explicit; nothing is followed implicitly. |
+| `autoplay`        | `true`                      | Start as soon as the file is ready. Ignored for followers.                                        |
+| `loop`            | `false`                     | Loop the file. Ignored while following (the transport decides).                                   |
+| `muted`, `volume` | —                           | Element state (`volume` is clamped to 0–1). Updated live when the option changes.                 |
+| `enabled`         | `true`                      | `false` unregisters without unmounting.                                                           |
+
+`usePage({ media })` accepts a URL string or `MediaPageOptions` (`MediaOptions` minus `id` and `enabled`, plus `registry`). An object without `src` registers nothing.
+
+### 5.2 `MediaState`
+
+| Field               | Meaning                                           |
+| :------------------ | :------------------------------------------------ |
+| `hasMedia`          | A session exists.                                 |
+| `element`           | The **transport** element (timeline, speed, PiP). |
+| `audibleElement`    | The element volume/mute act on.                   |
+| `isPlaying`, `loop` | Transport state.                                  |
+| `kind`              | `"audio"` or `"video"` (transport).               |
+| `sourceId`          | Id of the transport source.                       |
+
+### 5.3 `MediaActions`
+
+| Action                | Effect                                                                                                                                                   |
+| :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `toggle()`            | Play/pause the transport (through the source's own `controls.toggle` when it has one, e.g. the background video).                                        |
+| `toggleLoop()`        | Toggle loop on the transport.                                                                                                                            |
+| `setMuted(muted)`     | Mute/unmute the **audible** element.                                                                                                                     |
+| `upsertSource(input)` | Register or patch a source (`id` required). New sources get the next `order`; patches keep their order. Used by `useMedia` and by the background module. |
+| `removeSource(id)`    | Unregister.                                                                                                                                              |
+
+`page.modules.media` is these plus `set(media)` (`page.set({ media })`).
+
+### 5.4 Registering a custom source
+
+`useMedia` is for audio files. For anything else (a video element you own, a streaming player) register through the actions:
+
+```tsx
+const { upsertSource, removeSource } = useMediaActions();
+useEffect(() => {
+  upsertSource({
+    id: "my-player",
+    element: videoEl,
+    kind: "video",
+    isPlaying: false,
+    loop: false,
+    controls: {
+      toggle: () => player.toggle(),
+      toggleLoop: () => player.toggleLoop(),
+      setMuted: (m) => player.mute(m),
+    },
+  });
+  return () => removeSource("my-player");
+}, [videoEl]);
+```
+
+Keep `isPlaying` current with another `upsertSource({ id, isPlaying })` call. `controls` overrides the default element handling (the background module does exactly this).
+
+## 6. Recipes and gotchas
+
+| I want to…                             | Do this                                                                 |
+| :------------------------------------- | :---------------------------------------------------------------------- |
+| Page ambience that stops on navigation | `usePage({ media: url })`.                                              |
+| Audio that survives navigation         | Mount `<MediaSource>` in a layout, not a page.                          |
+| Let the user mute only the audio track | Nothing: the dock's volume binds to the audible follower automatically. |
+| Disable autoplay                       | `autoplay: false`; the dock shows play.                                 |
+
+- Two **unrelated** standalone audios cannot play at once; the newer pauses the older. If you need layering, make one a follower of the other or of the background video.
+- `follow` ids must exist **at registration time or later**; a follower registered before its target is standalone until the target appears.
+- `useMedia` returns controls for **its own** element only; use `useMediaActions().toggle()` to control whatever the dock controls.
+
+## 7. File map
+
+| File           | Responsibility                                                                                                                                                         |
+| :------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `index.ts`     | Public barrel.                                                                                                                                                         |
+| `types.ts`     | Entries, sessions, state, actions, option and page-config contracts.                                                                                                   |
+| `constants.ts` | `DEFAULT_MEDIA_STATE`, registry key, drift threshold, page source id.                                                                                                  |
+| `utils.ts`     | `resolveMediaSession`, `createMediaState`, `mergeMediaSource`, `bindFollowers`, `toggleElement`, `findDisplacedAudio`, `selectPageMedia` (pure or DOM-only, no React). |
+| `context.tsx`  | `MediaProvider`: source registry, session publishing, follower binding, actions; `useMediaState`, `useMediaActions`.                                                   |
+| `hooks.ts`     | `useMedia`: owns the `HTMLAudioElement` lifecycle and registers it.                                                                                                    |
+| `overlay.tsx`  | `MediaSource` and `MediaOverlay` (components that render nothing).                                                                                                     |
+| `module.tsx`   | `mediaModule`, `usePage({ media })` page API, kernel type augmentation.                                                                                                |
+
+The module has no `view.tsx`, `motion.ts` or `provider.tsx` (the provider is `context.tsx`) because it renders no UI.
+
+## 8. Dependencies
+
+- **Uses:** `@omerdlw/base-framework/kernel` (`defineModule`, `useRegistryValue`), `@omerdlw/base-framework/hooks` (`useStore`, `useRequiredContext`), `@omerdlw/base-framework/utils` (`createStore`, `shallowEqual`).
+- **Used by:** `src/core/provider.tsx` (via `defaultModules`); the **background** module (registers its video as `background`, with its own controls); the **dock** (reads the session with `definePeer("media")`, inert when not installed). Both list `media` in `uses`.

package/docs/modules/modal.md

@@ -0,0 +1,229 @@
+# Modal — `@omerdlw/base-framework/modules/modal`
+
+> **Read this first if you need to:** open a dialog and `await` its answer (confirm, pick, form), show a bottom sheet or side panel, stack dialogs, or expose route-specific dialogs by key.
+>
+> For the dock-integrated sheet use a dock **surface** ([dock.md](./dock.md#8-surfaces)); `modal` is the classic centered/edge dialog with a backdrop.
+
+## 1. At a glance
+
+|                    |                                                                                                                                                                                                                                     |
+| :----------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Import**         | `import { defineModal, useModal, ModalContainer, … } from "@omerdlw/base-framework/modules/modal"`                                                                                                                                                        |
+| **Module id**      | `modal` (`modalModule`, in `defaultModules`)                                                                                                                                                                                        |
+| **Renders**        | `Modal` overlay, **lazy-loaded** (`next/dynamic`, `ssr: false`), portalled to `document.body`                                                                                                                                       |
+| **Registry type**  | `modal` — key policy `named`, value kind `component`, lifecycle `immediate` (entries are removed the moment the registering page unmounts; the declared 600 ms delay applies only if a registration opts into `graceful` / `route`) |
+| **Page slice**     | `usePage({ modal: { key: Component } })` → `page.modules.modal` (`open`, `set`, + actions)                                                                                                                                          |
+| **Peers (`uses`)** | none                                                                                                                                                                                                                                |
+| **Theme**          | `modalTheme` slots in `src/config/modal.module.theme.ts`                                                                                                                                                                            |
+| **z-index**        | layer `Z_INDEX.MODAL`, frame `Z_INDEX.MODAL_FRAME`                                                                                                                                                                                  |
+| **Tests**          | `tests/modules/modal.test.ts`                                                                                                                                                                                                       |
+
+## 2. Mental model
+
+- A modal is **a component + options**. `openModal(input, options)` pushes an entry on a **stack** and returns a **promise** that resolves with whatever the component passes to `close(result)` (or `null` when dismissed).
+- Only the **top** modal is interactive. Lower modals stay mounted, are dimmed (clicking the dim closes the top one) and the top gets a small _"Previous / Current"_ switcher to go back.
+- Modals are identified by a **type** string (`id`, `type`, the component's `displayName`/`name`, or the string you passed). The same type or component cannot be on top twice.
+- The component you render receives `close`, `data` and `header` props. `ModalContainer` consumes `header` to draw a consistent title bar.
+
+## 3. Quick start
+
+```tsx
+const ConfirmDelete = defineModal({
+  component: ConfirmDialog, // receives { close, data, header }
+  title: (data) => `Delete ${data.name}?`, // string, node, or function of data
+  position: { mobile: "bottom", desktop: "center" },
+});
+
+function DeleteButton({ post }) {
+  const [openConfirm] = useModal(ConfirmDelete); // [open, controls]
+  return (
+    <Button
+      onClick={async () => {
+        if (await openConfirm({ name: post.title })) await deletePost(post.id);
+      }}
+    >
+      Delete
+    </Button>
+  );
+}
+
+function ConfirmDialog({ data, close, header }) {
+  return (
+    <ModalContainer
+      close={close}
+      header={header}
+      footer={{
+        right: (
+          <>
+            <Button onClick={() => close(false)}>Cancel</Button>
+            <Button onClick={() => close(true)}>Delete</Button>
+          </>
+        ),
+      }}
+    >
+      This cannot be undone.
+    </ModalContainer>
+  );
+}
+```
+
+```tsx
+// Route-level modals, opened by key
+const page = usePage({ modal: { share: ShareModal } });
+await page.modules.modal?.open("share", { url });
+
+// Ad-hoc
+const { openModal } = useModalActions();
+const answer = await openModal(PickDate, {
+  data: { min: today },
+  position: "right",
+  title: "Pick a date",
+});
+```
+
+## 4. Capability matrix
+
+| Capability          | How                                                                                                                                                       |
+| :------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Awaitable result    | `await openModal(...)` → the value passed to `close(result)`; `null` when dismissed (Esc, backdrop, dim, switcher, `closeModal()`).                       |
+| Five positions      | `center`, `top`, `bottom`, `left`, `right`.                                                                                                               |
+| Responsive position | `position: { mobile?: ModalPosition; desktop?: ModalPosition }` (mobile = `max-width: 639px`). Updates live on resize.                                    |
+| Two chromes         | `"panel"` (default: surface, radius, header/close) or `"bare"` (your component owns the look).                                                            |
+| Stacking            | Open from within a modal; lower ones dim, top shows a back switcher.                                                                                      |
+| Header              | `title`, `actions` (header actions node), `showClose` (default `true`) via options; drawn by `ModalContainer`.                                            |
+| Header/footer slots | `ModalContainer` `header` / `footer` configs with `left` / `center` / `right`, `sticky`.                                                                  |
+| Focus management    | Initial focus on the first focusable element; Tab wraps inside the top modal; focus returns to the previous element on close.                             |
+| Scroll lock         | Body scroll is locked while any modal is visible (`acquireGlobalScrollLock`) and a `modal:smooth-scroll-lock` window event tells smooth-scroll libraries. |
+| By key              | `usePage({ modal })` / `useModalRegistration` register components by key; open with `open("key", data)`.                                                  |
+
+## 5. Public API
+
+| Export                                          | Kind      | Description                                                                                                                                                                                                                               |
+| :---------------------------------------------- | :-------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `modalModule`                                   | module    | `defineModule` definition.                                                                                                                                                                                                                |
+| `ModalProvider`                                 | component | Stack state, actions, pending promises. Prop `modalRenderer` renders a custom stack renderer inside the provider. Mounted by the host.                                                                                                    |
+| `Modal`                                         | component | The stack renderer (portal). Mounted lazily by the host.                                                                                                                                                                                  |
+| `ModalContainer`                                | component | Header / body / footer layout for modal content.                                                                                                                                                                                          |
+| `useModal()`                                    | hook      | `ModalState & ModalActions` (state + `openModal`, `closeModal`, `closeAllModals`).                                                                                                                                                        |
+| `useModal(input)`                               | hook      | Binding for one modal: `[open, controls]` that is also `{ open, close, closeAll, isOpen, state }`.                                                                                                                                        |
+| `useModalActions()`, `useModalState()`          | hooks     | Split access (stable actions / state). Throw outside `ModalProvider`.                                                                                                                                                                     |
+| `defineModal(def)`                              | builder   | Reusable modal definition (frozen) with `.use()`.                                                                                                                                                                                         |
+| `useModalRegistration(config, options?)`        | hook      | Register modal components by key outside `usePage`.                                                                                                                                                                                       |
+| `ModalContext`                                  | context   | For tests and custom providers.                                                                                                                                                                                                           |
+| `MODAL_POSITIONS`, `MODAL_CHROME`, `modalTheme` | constants |                                                                                                                                                                                                                                           |
+| Types                                           |           | `ModalPosition`, `ResponsiveModalPosition`, `ModalChrome`, `ModalInput`, `ModalOptions`, `ModalActions`, `ModalState`, `ModalEntry`, `ModalDefinition`, `DefineModalOptions`, `ModalContainerProps`, `ModalPageConfig`, `ModalPageApi`, … |
+
+### 5.1 `ModalInput`
+
+`openModal(input, options?)` accepts:
+
+| Input                                  | Resolved how                                                                                                   |
+| :------------------------------------- | :------------------------------------------------------------------------------------------------------------- |
+| `ModalDefinition` (from `defineModal`) | Its `component`, `type`/`id`, `defaultData`, and option defaults. Call options override definition options.    |
+| A component                            | Type = `displayName ?? name ?? "modal"`.                                                                       |
+| A string                               | Looked up in the `modal` registry (page/registry-registered components). An unknown key opens nothing visible. |
+| falsy                                  | Resolves `null`.                                                                                               |
+
+### 5.2 `ModalOptions`
+
+| Option            | Default   | Meaning                                                                                     |
+| :---------------- | :-------- | :------------------------------------------------------------------------------------------ |
+| `data`            | `{}`      | Props passed to the component as `data` (merged over `defaultData`).                        |
+| `title`           | `null`    | Node or `(data) => node`; shown by `ModalContainer`.                                        |
+| `actions`         | `null`    | Node shown in the header (`header.actions`).                                                |
+| `position`        | `center`  | `ModalPosition` or `{ mobile, desktop }`.                                                   |
+| `chrome`          | `"panel"` | `"panel"` or `"bare"`.                                                                      |
+| `showClose`       | `true`    | Close button in the header.                                                                 |
+| `onClose(result)` |           | Called once when the modal closes (errors, including async ones, are reported, not thrown). |
+
+### 5.3 What the component receives
+
+```ts
+{ close(result?), data, header: { actions, position, showClose, title, titleId } }
+```
+
+`close` is bound to **this** modal's id (closing a lower modal from the top one is safe). `header.titleId` is wired to `aria-labelledby` of the dialog.
+
+### 5.4 `ModalContainer` props
+
+| Prop                         | Meaning                                                                                                                                                                                                                                                                           |
+| :--------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `header`                     | `false` hides it; a config `{ title, left, center, right, actions, showClose, sticky, position, titleId }`; or a node (rendered in the center). The easiest is to pass the received `header` straight through. `showClose` must be `true` to draw a close button (needs `close`). |
+| `footer`                     | `false`/absent hides it; config `{ left, center, right, sticky }`.                                                                                                                                                                                                                |
+| `close`                      | The `close` prop of the modal.                                                                                                                                                                                                                                                    |
+| `position`                   | Override position (side positions switch to full-height layout).                                                                                                                                                                                                                  |
+| `className`, `bodyClassName` | A height class (`h-*`, `max-h-*`) in `className` disables the default max-height.                                                                                                                                                                                                 |
+| `children`                   | The body (scrollable; `data-lenis-prevent` is set).                                                                                                                                                                                                                               |
+
+### 5.5 Actions
+
+| Action                       | Description                                                                                                            |
+| :--------------------------- | :--------------------------------------------------------------------------------------------------------------------- |
+| `openModal(input, options?)` | Push a modal. **Duplicate guard:** if the top entry has the same type or component, resolves `null` and opens nothing. |
+| `closeModal(result?, id?)`   | Close the top modal (or the one with `id`); resolves its promise. Unknown ids are ignored.                             |
+| `closeAllModals(result?)`    | Close everything; every pending promise resolves with the same `result` (default `null`).                              |
+
+`page.modules.modal` = actions plus `open(modalOrKey, data?)` (looks the key up in **this page's** `modal` slice first, then falls back to the registry) and `set(modal)`.
+
+`ModalState`: `isOpen`, `modalStack`, `activeModalId`, `modalType`, `title`, `props`, `position`, `responsivePosition`, `chrome`, `showClose`, `headerActions` (the top entry's values).
+
+## 6. Behaviour details
+
+- **Dismissal.** `Esc` (top modal), backdrop click, and clicking the dim over a lower modal close the **top** modal with `null`. During a top-modal exit animation the backdrop ignores clicks so one click cannot close two modals.
+- **Lifecycle.** Entries are removed from the stack immediately; the exit animation is played by the renderer. Promises resolve at close time, not after the animation.
+- **Rendering.** Entries whose component cannot be resolved (string type not in the registry) are skipped; they remain in `modalStack` but not on screen.
+- **Error isolation.** Each modal body is wrapped in `ModuleBoundary`, so a crash shows the module error UI for that modal only.
+- **Accessibility.** `role="dialog"`, `aria-modal` on the top modal only, labelled by the title id; lower layers are covered by a dim that closes the top modal.
+- **SSR.** Nothing renders until mounted (`useSyncExternalStore` guard); the module is lazy and client-only.
+
+## 7. Theming
+
+No classes or colors in the module except the two z-indexes. Slots in `modalTheme`:
+
+| Group     | Slots                                                                           |
+| :-------- | :------------------------------------------------------------------------------ |
+| Backdrop  | `backdrop`, `dim`                                                               |
+| Placement | `layer` (`data-position`, `data-inset`), `frame` (`data-layout`, `data-active`) |
+| Panel     | `panel`, `panelChrome`, `panelBare` (`data-layout`)                             |
+| Container | `content` (`data-height`), `body`, `title`, `closeButton`                       |
+| Rows      | `row` (`data-columns`, `data-sticky`), `rowStart`, `rowCenter`, `rowEnd`        |
+| Switcher  | `switcher`, `switcherButton`, `switcherDivider`, `switcherCurrent`              |
+
+`data-layout` is one of `center`, `top`, `bottom`, `left`, `right`, `top-mobile`, `bottom-mobile`, `side-mobile` (`getModalLayout`), so each position/viewport combination is a single selector.
+
+Motion (`motion.ts`: backdrop, per-position panel variants/transitions, header/body/footer variants) is derived from `@omerdlw/base-framework/tokens` ([Rule 4](../architecture-and-rules.md)). Use `Z_INDEX` for anything layered above or below a modal ([Rule 5](../architecture-and-rules.md)).
+
+## 8. Recipes and gotchas
+
+| I want to…                                  | Do this                                                                                         |
+| :------------------------------------------ | :---------------------------------------------------------------------------------------------- |
+| A confirm dialog                            | `defineModal` + `close(true/false)`; `await open()`.                                            |
+| A bottom sheet on phones, dialog on desktop | `position: { mobile: "bottom", desktop: "center" }`.                                            |
+| Chain dialogs                               | Call `openModal` from inside the first one; the second gets the "back" switcher.                |
+| A fully custom look                         | `chrome: "bare"` and skip `ModalContainer`, or style via the theme.                             |
+| Open by key from anywhere                   | Register with `usePage({ modal })` / `useModalRegistration`, then `openModal("key", { data })`. |
+
+- Treat `null` as "dismissed"; only a result you pass to `close(...)` is meaningful.
+- Opening the same modal twice quickly returns `null` for the second call.
+- Registering components via the registry makes them available **only while the page that registered them is mounted** (lifecycle `immediate`).
+- `useModal()` re-renders on every stack change; use `useModalActions()` for fire-and-forget buttons.
+
+## 9. File map
+
+| File           | Responsibility                                                                                                                        |
+| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ |
+| `index.ts`     | Public barrel.                                                                                                                        |
+| `types.ts`     | Positions, chrome, entries, state, actions, definitions, container props, theme slots.                                                |
+| `constants.ts` | `MODAL_POSITIONS`, `MODAL_CHROME`, mobile breakpoint, scroll-lock event, focusable selector, height-constraint pattern, `modalTheme`. |
+| `state.ts`     | `createModalState` (stack → state) and the initial state.                                                                             |
+| `utils.ts`     | Identity resolution, position normalization (responsive), focus trap helpers, header-action resolution, labels.                       |
+| `context.tsx`  | `ModalProvider` (stack, pending promises, actions), `useModal*` hooks, registry lookup.                                               |
+| `hooks.ts`     | View models: `useModalModel` (visibility, viewport, scroll lock), `useModalLayerModel` (focus, Esc), `useModalContainerModel`.        |
+| `overlay.tsx`  | `Modal`, `ModalLayer`, `ModalContainer`, switcher, close button.                                                                      |
+| `motion.ts`    | Backdrop, panel, header, content and footer motion.                                                                                   |
+| `module.tsx`   | `modalModule`, lazy renderer, page API, `defineModal`, kernel type augmentation.                                                      |
+
+## 10. Dependencies
+
+- **Uses:** `@omerdlw/base-framework/kernel` (`defineModule`, `useModuleRegistration`, `useRegistryEntries`, `ModuleBoundary`), `@omerdlw/base-framework/tokens` (`Z_INDEX`, motion), `@omerdlw/base-framework/utils` (`acquireGlobalScrollLock`, `createStore`), `@omerdlw/base-framework/atoms` (`Button`, `Icon`), `@omerdlw/base-framework/theme`, `next/dynamic`, `motion/react`.
+- **Used by:** `src/core/provider.tsx` (installs it), pages and features through `useModal` / `page.modules.modal`.

package/docs/modules/notification.md

@@ -0,0 +1,161 @@
+# Notification — `@omerdlw/base-framework/modules/notification`
+
+> **Read this first if you need to:** show feedback ("Saved", "Link copied"), toast a promise or a server-action `Result`, raise feedback from code that does not import React, or understand where toasts appear.
+
+## 1. At a glance
+
+|                     |                                                                                                    |
+| :------------------ | :------------------------------------------------------------------------------------------------- |
+| **Import**          | `import { useToast } from "@omerdlw/base-framework/modules/notification"`                                                |
+| **Module id**       | `notification` (`notificationModule`, in `defaultModules`)                                         |
+| **Renders**         | `NotificationLayer` overlay: the toast + an event listener                                         |
+| **Registry type**   | none                                                                                               |
+| **Page slice**      | `usePage({ notification: 3000 })` or `{ duration }` → `page.modules.notification = { toast, set }` |
+| **Peers (`uses`)**  | none (the dock reads _this_ module as a peer)                                                      |
+| **Theme**           | `notificationTheme` slots in `src/config/notification.module.theme.ts`                             |
+| **Events listened** | `API_UNAUTHORIZED`, `APP_ERROR` (`notify: true`), `STATE_CHANGE` (`notify: true`)                  |
+| **DOM contract**    | Portals into `#dock-card-stack` (owned by the dock) when it exists                                 |
+| **Tests**           | `tests/modules/notification.test.ts`                                                               |
+
+## 2. Mental model
+
+- There is **one toast slot**. Showing a toast replaces the one on screen (and cancels its timer); the newest always wins. There is no queue and no stack.
+- A toast has an **id**. Showing a toast with an id that is already visible updates it **in place**; this is how `toast.promise` turns "Uploading…" into "Done".
+- The toast is rendered **against the dock**: it portals into the dock's card stack so feedback appears where the user's attention already is. Without a dock it falls back to a floating layer on `document.body`.
+- Feedback can also come from **events**, so features never import this module.
+
+## 3. Quick start
+
+```tsx
+const toast = useToast();
+
+toast("Profile saved");
+toast("Link copied", 1500); // duration in ms
+toast("Syncing…", { id: "sync", dedupeKey: "sync" }); // update in place
+toast("Stays until dismissed", { duration: null });
+
+await toast.promise(uploadAvatar(file), {
+  loading: "Uploading…",
+  success: "Avatar updated",
+  error: (e) => `Upload failed: ${toUserMessage(e)}`,
+});
+
+toast.fromResult(await updateProfileAction(form), { success: "Saved" }); // Result<T, E>
+```
+
+```ts
+// From anywhere, without importing the module
+globalEvents.emit(EVENT_TYPES.STATE_CHANGE, {
+  message: "Draft restored",
+  notify: true,
+});
+```
+
+## 4. Public API
+
+| Export                                               | Kind      | Description                                                                                                                                                                                                                                       |
+| :--------------------------------------------------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `useToast(defaultDuration?)`                         | hook      | Returns a `ToastController` (below). `defaultDuration` is the duration used when a call does not pass one (default 2000 ms).                                                                                                                      |
+| `notificationModule`                                 | module    | `defineModule` definition.                                                                                                                                                                                                                        |
+| `NotificationProvider`                               | component | Holds the notification store, timers and actions. Mounted by the host.                                                                                                                                                                            |
+| `useNotification()`                                  | hook      | `NotificationState & NotificationActions`.                                                                                                                                                                                                        |
+| `useNotificationActions()`, `useNotificationState()` | hooks     | Split access. Throw outside the provider.                                                                                                                                                                                                         |
+| `NotificationContext`                                | context   | For tests and the dock's peer reader.                                                                                                                                                                                                             |
+| `TOAST_DURATIONS`                                    | constant  | `{ DEFAULT: 2000, SHORT: 1500 }`.                                                                                                                                                                                                                 |
+| `notificationTheme`                                  | spec      | For `defineTheme`.                                                                                                                                                                                                                                |
+| Types                                                |           | `NotificationData`, `NotificationEntry`, `NotificationOptions` / `ToastOptions`, `ToastOptionsInput`, `NotificationActions`, `ToastController`, `ToastPromiseMessages`, `NotificationPageConfig`, `NotificationPageApi`, `NotificationThemeSlot`. |
+
+### 4.1 `ToastController`
+
+| Member                                           | Behaviour                                                                                                                                                                                                                                                                                                                                                                     |
+| :----------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `toast(message, options?)`                       | Show a toast. `options` is a number (duration) or `{ id?, dedupeKey?, duration? }`. Returns the toast id, or `null` when the message is empty.                                                                                                                                                                                                                                |
+| `toast.promise(promiseOrFn, messages, options?)` | Shows `messages.loading` (sticky, `duration: null`) under a stable id, awaits, then replaces it with `success` / `error` (same id). If the resolved value is a `Result`, `ok` → `success(data)`, `err` → `error(error)`. Errors are **re-thrown**. Without `loading`, only the outcome toast is shown; with `loading` but no outcome message, the loading toast is dismissed. |
+| `toast.fromResult(result, messages?, options?)`  | If `result` is a `Result`, shows `messages.success(data)` or `messages.error(error)` (falling back to `toUserMessage(error)`) and **returns the result unchanged**. Non-`Result` values are ignored.                                                                                                                                                                          |
+| `toast.dismiss(id?)`                             | Dismiss one toast, or all when no id.                                                                                                                                                                                                                                                                                                                                         |
+| `toast.dismissAll()`                             | Dismiss everything.                                                                                                                                                                                                                                                                                                                                                           |
+
+`messages` values may be a node or a function of the data / error.
+
+### 4.2 Options and durations
+
+| Option      | Meaning                                                                                                                           |
+| :---------- | :-------------------------------------------------------------------------------------------------------------------------------- |
+| `duration`  | Milliseconds. `undefined` → the hook default (2000). `null` → sticky. Any non-positive or non-numeric value is treated as sticky. |
+| `id`        | Identity for in-place updates.                                                                                                    |
+| `dedupeKey` | Same as `id` (wins over `id`). Equal keys replace each other.                                                                     |
+
+When neither is given the id is the first 64 characters of the message (string messages) or `notification-N`.
+
+### 4.3 Text normalization
+
+String messages are trimmed and **trailing periods/whitespace are removed** (`"Saved. "` → `"Saved"`). Empty / `null` / `undefined` messages are ignored (`toast` returns `null`).
+
+### 4.4 Page default
+
+`usePage({ notification: 3000 })` (or `{ duration: 3000 }`) sets the default duration for `page.modules.notification.toast` while the page is mounted; calls can still pass their own duration. `page.modules.notification.set(...)` changes it at runtime.
+
+## 5. Events
+
+`NotificationListener` (part of the overlay) turns framework events into toasts:
+
+| Event                          | Condition                      | Toast                                                                           |
+| :----------------------------- | :----------------------------- | :------------------------------------------------------------------------------ |
+| `EVENT_TYPES.API_UNAUTHORIZED` | `source` is missing or `"app"` | `USER_MESSAGES.unauthorized` ("Your session has expired. Please sign in again") |
+| `EVENT_TYPES.APP_ERROR`        | `notify: true` and a `message` | the message                                                                     |
+| `EVENT_TYPES.STATE_CHANGE`     | `notify: true` and a `message` | the message                                                                     |
+
+(The **dock** independently turns every `APP_ERROR` and every critical `API_ERROR` into its error status card, whether or not `notify` is set; `notify: true` only adds this module's toast.)
+
+## 6. Rendering
+
+- Docked: `createPortal(…, #dock-card-stack)` with `toastDocked`; announced with `aria-live="polite"`.
+- Floating (no dock in the DOM): a `layer` on `document.body` with `toast`.
+- The toast is `role="alert"`, focusable, and dismisses on **click** or **Escape**. Nothing renders before hydration.
+- While a toast is visible the dock hides its breadcrumbs companion card (the toast takes the companion slot).
+
+## 7. Theming
+
+No classes or inline styles in the module. `notificationTheme` slots: `layer`, `toast`, `toastDocked`, `toastMessage` (Tailwind classes, all required) plus optional inline `styles` per slot. A missing theme throws a descriptive error. Motion (`toastVariants`, `NOTIFICATION_TRANSITION`) stays in `motion.ts`.
+
+## 8. Writing toast copy
+
+- Speak to the user, never the developer: no codes, no vendor names, no stack wording.
+- Say what happened and what to do: "Couldn't rename this passkey", not "Failed to rename".
+- Sentence case, no trailing period, no exclamation marks. Success is short: "Profile updated".
+- Never pass `error.message` to `toast`. Use `toUserMessage(error, { fallback: "Couldn't …" })`; `fromResult` and `promise` already do.
+
+## 9. Recipes and gotchas
+
+| I want to…                       | Do this                                                                      |
+| :------------------------------- | :--------------------------------------------------------------------------- |
+| Toast after a server action      | `toast.fromResult(await action(), { success: "Saved" })`                     |
+| A toast that updates             | Give it an `id`; call `toast(…, { id })` again.                              |
+| A persistent toast               | `{ duration: null }`, then `toast.dismiss(id)`.                              |
+| Feedback from a non-React module | Emit `STATE_CHANGE` with `notify: true`.                                     |
+| Show several messages at once    | Not supported (single slot). Combine the messages, or use a dock status/HUD. |
+
+- Calling `toast` rapidly keeps only the last message; the earlier ones disappear immediately.
+- `useToast` is a hook; outside React use the `STATE_CHANGE` event.
+- `promise` shows the loading toast **only if** `messages.loading` is set.
+
+## 10. File map
+
+| File           | Responsibility                                                                              |
+| :------------- | :------------------------------------------------------------------------------------------ |
+| `index.ts`     | Public barrel.                                                                              |
+| `types.ts`     | Notification data, options, controller, page and theme-slot contracts.                      |
+| `constants.ts` | `TOAST_DURATIONS`, session-expired message, `DOCK_STACK_ELEMENT_ID`, `notificationTheme`.   |
+| `utils.ts`     | Option normalization, default duration, text normalization, active-toast selection, guards. |
+| `context.tsx`  | `NotificationProvider` (store, timers, show/dismiss), `useNotification*` hooks.             |
+| `hooks.ts`     | `useToast` (`promise`, `fromResult`), `NotificationListener`, container view model.         |
+| `overlay.tsx`  | `Toast`, `NotificationContainer` (dock/floating portal), `NotificationLayer`.               |
+| `motion.ts`    | Toast variants and transition.                                                              |
+| `module.ts`    | `notificationModule` and the page API (plain `.ts`: it has no JSX).                         |
+
+`builder.ts` is absent: toasts are imperative ([README](./README.md#42-why-some-optional-slots-are-absent)).
+
+## 11. Dependencies
+
+- **Uses:** `@omerdlw/base-framework/kernel` (`defineModule`), `@omerdlw/base-framework/events` (`EVENT_TYPES`), `@omerdlw/base-framework/hooks` (`useGlobalEvent`, `useRequiredContext`, `useStore`), `@omerdlw/base-framework/result` (`isResult`), `@omerdlw/base-framework/utils` (`toUserMessage`, `USER_MESSAGES`, `createStore`), `@omerdlw/base-framework/theme`, `motion/react`. It finds the dock through the DOM id `dock-card-stack`.
+- **Used by:** `src/core/provider.tsx`, `page.modules.notification`, features (for example the account social surface), and the **dock**, which reads "is a toast visible" from this module's store through `definePeer("notification")`.