@omerdlw/base-framework 1.0.0 → 1.0.2

package/docs/architecture-and-rules.md

@@ -0,0 +1,129 @@
+# Architecture, Boundaries & The 10 Inviolable Rules
+
+> **Read this first if you are about to:** contribute to `@omerdlw/base-framework`, author or modify a module, structure downstream application code that consumes the package, or understand how the microkernel enforces layer boundaries.
+
+---
+
+## 1. The Package Architecture Hierarchy
+
+`@omerdlw/base-framework` is built as an ultra-lean microkernel orchestrating self-contained declarative UI modules:
+
+```
+@omerdlw/base-framework/modules/*    (3. Declarative UI Modules: dock, modal, notification, ambient, background, controls, loading, media, context-menu)
+   ↓ imports
+@omerdlw/base-framework/{kernel, provider, theme, error} (2. Orchestration Engine: ModuleHost, RegistryStore, PageController, Error Boundaries)
+   ↓ imports
+@omerdlw/base-framework/{atoms, hooks} (1. React Layer: Accessible atoms & universal React hooks)
+   ↓ imports
+@omerdlw/base-framework/{utils, tokens, result, events} (0. Pure Foundation: Zero React dependencies, server & edge safe)
+```
+
+### 1.1 Layer Invariants
+
+1. **Downwards Only:** Higher layers may import from lower layers; a lower layer **never** imports from a higher layer.
+2. **Server-Safe Foundation:** `@omerdlw/base-framework/utils`, `tokens`, `result`, and `events` have **zero dependencies on React or Next.js DOM**. They can be imported safely in Server Components, Route Handlers, Server Actions, and Edge functions.
+3. **Module Isolation:** Modules are strict siblings. A module (`dock`, `modal`, etc.) **must never import from another module**. Cross-module communication occurs strictly via declared peers (`uses: ["peerId"]`), `useModuleState()`, or `globalEvents`.
+4. **No Deep Imports:** Public consumers import only from official subpath exports (`@omerdlw/base-framework/kernel`, `@omerdlw/base-framework/modules/dock`). Direct file-path imports (e.g., `@omerdlw/base-framework/dist/kernel/page.js`) are forbidden.
+5. **Zero Cycles:** All package internal code maintains 0 cyclical dependencies, verified statically by `npm run check:architecture`.
+
+---
+
+## 2. Canonical Module File Pattern
+
+Every first-party module inside `src/modules/<name>/` strictly adheres to a canonical slot pattern:
+
+| File | Responsibility | Required? |
+| :--- | :--- | :---: |
+| `index.ts` | Clean barrel export (public API types, hooks, module definition). | ✅ |
+| `types.ts` | Complete TypeScript type contracts and state interfaces (no runtime code). | ✅ |
+| `constants.ts` | Module identifier, theme spec definition (`defineThemeSpec`), constants. | ✅ |
+| `utils.ts` | Pure deterministic helper functions (zero React state). | ✅ |
+| `module.tsx` | Module definition via `defineModule()`, `declare module` type augmentations. | ✅ |
+| `context.tsx` | React Context, Provider, and `useX()` hooks (**at most one context per module**). | Optional |
+| `state.ts` | Initial state factory, pure reducers, state transition functions. | Optional |
+| `hooks.ts` | Component view-models (e.g. `useDockOverlayModel`). | Optional |
+| `overlay.tsx` | Pure visual JSX presentation (consumes view-models; defines no state or refs). | Optional |
+| `motion.ts` | Module-specific animation presets derived from `@omerdlw/base-framework/tokens`. | Optional |
+
+---
+
+## 3. The 10 Inviolable Rules
+
+### Rule 1: Zero Cross-Module Imports
+Modules must remain completely decoupled. Never import from another module directly.
+- ❌ `import { useDock } from "@omerdlw/base-framework/modules/dock"` inside `src/modules/modal/overlay.tsx`
+- ✅ Declare the peer dependency in `module.tsx` (`uses: ["dock"]`) and access state via `useModuleState("dock")` or `definePeer("dock", inert)`.
+
+### Rule 2: Public Subpath Import Contract
+All code imported by consumer applications must resolve through defined subpaths. Deep internal paths are strictly prohibited.
+- ❌ `import { RegistryStore } from "@omerdlw/base-framework/kernel/registry-store"`
+- ✅ `import { usePage, defineModule } from "@omerdlw/base-framework/kernel"`
+
+### Rule 3: Server-Safe Foundation Purity
+The foundation entries (`@omerdlw/base-framework/utils`, `tokens`, `result`, `events`) must never import React, hooks, or browser-specific window globals at module scope.
+- ❌ `import { useState } from "react"` inside `src/utils/`
+- ✅ Keep utility functions pure, deterministic, and testable without a DOM.
+
+### Rule 4: Motion Token Singularity
+Never hardcode inline animation durations (`duration: 0.3`) or custom bezier curves inside UI components. Use universal tokens from `@omerdlw/base-framework/tokens`.
+- ❌ `<motion.div transition={{ duration: 0.35, ease: "easeInOut" }} />`
+- ✅ `<motion.div transition={SPRING_PRESETS.GENTLE} />` or `transition={{ duration: DURATION_TOKENS.FAST, ease: EASING_CURVES.OUT_QUART }}`
+
+### Rule 5: Z-Index Token Contract
+Never use arbitrary stacking classes like `z-50`, `z-[99]`, or `z-[9999]`.
+- ❌ `<div className="fixed inset-0 z-50 bg-black/80">`
+- ✅ `<div className="fixed inset-0 bg-black/80" style={{ zIndex: Z_INDEX.MODAL_BACKDROP }}>`
+
+### Rule 6: Result Pattern for Operations
+Asynchronous workflows, Server Actions, and data mutations must never throw unhandled errors across execution boundaries. Always return `Result<T, E>` using `ok(data)` and `err(message)` from `@omerdlw/base-framework/result`.
+- ❌ `if (!id) throw new Error("Invalid ID");`
+- ✅ `if (!id) return err("Invalid ID"); return ok({ success: true });`
+
+### Rule 7: Declarative Chrome (`usePage`)
+Consumer applications must never handcraft ad-hoc fixed headers, floating toolbars, or sticky navigation bars in individual page views. All route chrome is declared through `usePage()`:
+- ❌ Building custom `<header className="fixed top-0...">` inside every page.
+- ✅ `const page = usePage({ title: "Settings", dock: { description: "User settings", icon: "solar:settings-bold" } });`
+
+### Rule 8: Event Bus Decoupling
+Cross-cutting state notifications, external data updates, or global triggers must pass through `@omerdlw/base-framework/events` (`globalEvents`). Components must not couple directly to external transport implementations.
+- ❌ Hardcoding direct listeners across isolated feature boundaries.
+- ✅ `globalEvents.publish(EVENT_TYPES.STATE_CHANGE, { key, value });` and listen via `useGlobalEvent()`.
+
+### Rule 9: Theme Decoupling
+First-party modules must contain zero locked-in visual styling classes or hardcoded Tailwind colors. All visual design is expressed through theme slots (`defineThemeSpec`) and supplied by the consumer application via `ThemeProvider`.
+- ❌ Hardcoding `bg-neutral-900 border-neutral-800` directly in module overlay markup.
+- ✅ `className={theme.slots.card}` where `theme = useTheme(dockTheme)`.
+
+### Rule 10: Pre-Flight Verification
+Never consider any modification to the package or consumer code complete without running the full verification pipeline:
+```bash
+npm run type-check && npm run lint && npm run check:architecture && npm test && npm run build
+```
+All checks must exit with code `0`.
+
+---
+
+## 4. Enforcement Mechanisms
+
+| Tool | Command | Scope Enforced |
+| :--- | :--- | :--- |
+| **TypeScript** | `npm run type-check` | Strict compiler type verification across all source files and test suites. |
+| **ESLint** | `npm run lint` | Subpath boundary checks, no deep imports, no `any` without comment, motion rules. |
+| **Architecture Script** | `npm run check:architecture` | Validates 0 import cycles across all files, validates module `uses` declarations. |
+| **Node Test Runner** | `npm test` | 520+ tests asserting kernel lifecycles, module state machines, token correctness, and atom accessibility. |
+| **tsup Bundler** | `npm run build` | Validates tree-shakable ESM packaging and `.d.ts` declaration generation. |
+
+---
+
+## 5. Decision Tree: Where Does Code Go?
+
+```
+What are you adding?
+├─ Reusable unstyled UI atom (Button, Icon, Spinner, Tooltip) -> src/atoms/
+├─ First-party UI module (Dock, Modal, Ambient, Toast)   -> src/modules/<module>/
+├─ Universal React hook (useStore, useClickOutside)       -> src/hooks/
+├─ Design token (motion preset, z-index layer)           -> src/tokens/
+├─ Orchestration logic (registry, provider nesting)      -> src/kernel/
+├─ Pure utility or data store (scheduler, store, clamp)   -> src/utils/
+└─ Error handling & reporting (reporter, boundary)       -> src/error/
+```

package/docs/core-engine.md

@@ -0,0 +1,196 @@
+# Core Engine — `src/core`
+
+> **Read this first if you need to:** know what lives in `src/core`, wire `CoreProvider`, restyle things through themes, use the event bus, motion tokens or z-index layers, or find a utility/hook before writing your own.
+>
+> **Location:** `src/core/` · **Key principle:** frozen upstream, zero imports from higher layers, zero coupling between sibling modules, pure composability. Module and feature specifics live in [modules/](./modules/README.md).
+
+## 1. What is in the core
+
+| Entry               | Path           | Server-safe? | What it is                                                                                                                                 |
+| :------------------ | :------------- | :----------: | :----------------------------------------------------------------------------------------------------------------------------------------- |
+| `@omerdlw/base-framework/utils`      | `utils/`       |      ✅      | `cn`, scheduling, stores, string/number/object helpers, `report`, `toUserMessage`. Bottom of the stack: imports nothing from other layers. |
+| `@omerdlw/base-framework/tokens`     | `tokens/`      |      ✅      | Motion tokens, `Z_INDEX`, shared surface class constants.                                                                                  |
+| `@omerdlw/base-framework/result`     | `result.ts`    |      ✅      | `Result<T, E>`, `createSafeAction`. → [result.md](./modules/result.md)                                                                     |
+| `@omerdlw/base-framework/events`     | `events.ts`    |      ✅      | `globalEvents` bus, `EVENT_TYPES`, `FrameworkEventMap`.                                                                                    |
+| `@omerdlw/base-framework/hooks`      | `hooks/`       |    client    | Universal React hooks.                                                                                                                     |
+| `@omerdlw/base-framework/theme`      | `theme.tsx`    |    client    | Theme specs and provider (shared by core and modules).                                                                                     |
+| `@omerdlw/base-framework/atoms`      | `atoms/`       |    client    | Accessible UI atoms (`Button`, `Icon`, `Spinner`, `Tooltip`).                                                               |
+| `@omerdlw/base-framework/kernel`     | `kernel/`      |    client    | Module host, registry, `usePage`. → [kernel.md](./modules/kernel.md)                                                                       |
+| `@omerdlw/base-framework/error`      | `error/`       |    client    | Boundaries, reporter. → [error-boundary.md](./modules/error-boundary.md)                                                                   |
+| `@omerdlw/base-framework/provider`   | `provider.tsx` |    client    | `CoreProvider`: the one component that assembles everything.                                                                               |
+
+Server-safe entries (`utils`, `tokens`, `result`, `events`) must not import React or `next/*`, so route handlers, server actions and the Edge can use them.
+
+## 2. `CoreProvider`
+
+```tsx
+// src/app/providers.tsx (simplified)
+<Compose
+  providers={[
+    AuthProvider,
+    AccountProvider,
+    [ThemeProvider, { themes }], // from src/config/index.ts
+    [
+      CoreProvider,
+      { modules: defaultModules, registryEntries: APP_REGISTRY_ENTRIES },
+    ],
+  ]}
+>
+  {children}
+</Compose>
+```
+
+| Prop              | Type                                                | Meaning                                                                                                                                                                             |
+| :---------------- | :-------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `modules`         | `readonly AnyCoreModule[]`                          | **Required.** Which modules to install (order does not matter; `uses` sorts them). Listing only some (`[dockModule, notificationModule]`) ships only those. Read **once** at mount. |
+| `registryEntries` | `readonly AppRegistryEntry[]`                       | Initial (static) registry entries: dock cards, global context menus… `{ type, items: { key: value } }`.                                                                             |
+| `providers`       | `readonly ProviderEntry[]`                          | Extra providers nested **inside** the module host (so they can use modules). A provider is a component or `[Component, props]`.                                                     |
+| `overlays`        | `ReactNode`                                         | Rendered after `children`, inside the pipeline.                                                                                                                                     |
+| `slots`           | `{ beforeContent?, afterContent?, overlays? }`      | Positional content around `children`.                                                                                                                                               |
+| `tooltip`         | `boolean \| { delayDuration?, skipDelayDuration? }` | Radix `TooltipProvider` (default on: 300 / 150 ms). `false` removes it (then `Tooltip` components need their own provider).                                                          |
+
+Resulting tree: `GlobalError` → `TooltipProvider` → `ModuleHost` (registry, page controller stack, module providers, backdrops, **children**, overlays; each module UI inside `ModuleError`) → your `providers` → `beforeContent`, `children`, `afterContent`, `overlays`, `slots.overlays`, `GlobalErrorListener`.
+
+`Compose` (from `@omerdlw/base-framework/kernel`) is the helper that nests provider lists; use it for your own pipelines.
+
+## 3. Theme system (`@omerdlw/base-framework/theme`)
+
+All visual design of modules is data, not code.
+
+```ts
+// 1. The module declares the contract (slot names)
+export const dockTheme = defineThemeSpec<DockThemeSlot>("dock");
+
+// 2. The project supplies the design (src/config/dock.module.theme.ts)
+export const dockThemeConfig = defineTheme(dockTheme, {
+  slots:  { card: "rounded-[30px] bg-black/60 …", header: "…" },   // Tailwind classes — all slots required
+  styles: { card: { zIndex: Z_INDEX.DOCK } },                       // optional inline CSS per slot
+});
+
+// 3. src/config/index.ts lists it in `themes`; src/app/providers.tsx passes it to <ThemeProvider themes={themes}>
+
+// 4. Components read it
+const theme = useTheme(dockTheme);   // → { slots, styles }
+<div className={theme.slots.card} style={theme.styles.card} />
+```
+
+| API                                     | Notes                                                                                                                                                                          |
+| :-------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `defineThemeSpec<Slots>(id)`            | Creates the spec object `{ id }`; the generic carries the slot-name union.                                                                                                     |
+| `defineTheme(spec, { slots, styles? })` | Type-checked: every slot must be present in `slots`; `styles` is optional and partial.                                                                                         |
+| `ThemeProvider({ themes })`             | Builds an `id → config` map.                                                                                                                                                   |
+| `useTheme(spec)`                        | Returns `{ slots, styles }` (empty `styles` default). **Throws** `Theme "<id>" is missing. Add its theme file to src/config/ and list it in src/config/index.ts.` when absent. |
+| `@omerdlw/base-framework/theme`                       | Re-exports `ThemeProvider`, `defineTheme`, `defineThemeSpec` and `useTheme` (named `useModuleTheme`) for module authors.                                                       |
+
+Theme files in this repo: `ambient`, `background`, `context-menu`, `controls`, `dock`, `loading`, `modal`, `notification` (module themes), and `error` (core theme). See [theming.md](./theming.md) for full customization details.
+
+## 4. Event bus (`@omerdlw/base-framework/events`)
+
+```ts
+import { globalEvents, EVENT_TYPES } from "@omerdlw/base-framework/events";
+
+const off = globalEvents.subscribe(EVENT_TYPES.STATE_CHANGE, (payload) => { … });  // returns unsubscribe
+globalEvents.emit(EVENT_TYPES.STATE_CHANGE, { message: "Saved", notify: true });
+```
+
+| Member                                                                       | Notes                                                                                                                |
+| :--------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------- |
+| `subscribe(event, cb)`                                                       | Returns an unsubscribe function. Typed by `FrameworkEventMap`, or `subscribe<T>(name: string, cb)` for ad-hoc names. |
+| `emit(event, payload)`                                                       | Calls a **snapshot** of the listeners; a throwing listener is reported (`report`) and does not stop the others.      |
+| `emitDebounced(event, payload, waitMs = 100)` / `cancelDebounced(event?)`    | Trailing-edge emit per event name.                                                                                   |
+| `unsubscribeAll(event?)`, `hasListeners`, `getListenerCount`, `getAllEvents` | Management.                                                                                                          |
+| `EventEmitter<TEvents>`                                                      | The class, for isolated buses (tests).                                                                               |
+
+`globalEvents` is a **process-wide singleton** stored on `globalThis` under `Symbol.for("__base_framework_global_events__")`, so duplicated bundles still share one bus.
+
+Core events (`EVENT_TYPES`): `API_UNAUTHORIZED { error?, status?, source? }`, `API_ERROR { error, isCritical?, message?, retry?, status? }`, `APP_ERROR { error?, message?, resetError?, source? }`, `STATE_CHANGE { message?, status? }`. Module- and feature-owned events (`DOCK_EVENTS.*`, `AUTH_EVENTS.*`) live with their owner and **augment** `FrameworkEventMap`:
+
+```ts
+declare module "@omerdlw/base-framework/events" {
+  interface FrameworkEventMap {
+    MY_EVENT: { id: string };
+  }
+}
+```
+
+React side: `useGlobalEvent(event | event[] | null, callback, { debounceMs?, throttleMs? })` subscribes for the component's lifetime (callback always fresh; `null` disables); `useEventState(event, initial, reducer)` turns events into state.
+
+Who listens to what: the dock turns `APP_ERROR` / critical `API_ERROR` into status cards; the notification module toasts `API_UNAUTHORIZED`, and `APP_ERROR` / `STATE_CHANGE` with `notify: true`.
+
+## 5. Hooks (`@omerdlw/base-framework/hooks`)
+
+| Hook                                                                                                  | Signature / behaviour                                                                                                                                                                                                                                          |
+| :---------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `useRequiredContext(ctx, hookName, providerName)`                                                     | `use(ctx)` or throw `"<hook> must be used within <Provider>"`.                                                                                                                                                                                                 |
+| `useStore(store, selector?, isEqual?)`                                                                | Subscribe to an `ExternalStore` slice with `useSyncExternalStore`; re-renders only when `isEqual(prev, next)` is false (default `Object.is`). Pass `shallowEqual` for object slices.                                                                           |
+| `useClickOutside(ref, cb)`                                                                            | `pointerdown` outside `ref.current` → `cb(event)`.                                                                                                                                                                                                             |
+| `useIsomorphicLayoutEffect`                                                                           | `useLayoutEffect` in the browser, `useEffect` on the server.                                                                                                                                                                                                   |
+| `useGlobalEvent(event \| event[] \| null, cb, { debounceMs?, throttleMs? })`                         | Subscribes to one or multiple global events for the component lifetime with optional debounce or throttle timing. Fresh callback reference maintained without effect restarts.                                                                                 |
+| `useIsFullscreenStateActive()`                                                                        | Reactively subscribes to global fullscreen state presence (used by `dock` and `loading` to yield when active).                                                                                                                                                 |
+
+## 6. Utilities (`@omerdlw/base-framework/utils`)
+
+| Group         | Exports                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| :------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Classes       | `cn(...)` — `clsx` + `tailwind-merge` (later classes win).                                                                                                                                                                                                                                                                                                                                                                     |
+| DOM / env     | `isBrowser`, `acquireGlobalScrollLock()` (ref-counted; returns a release function that restores previous body and html overflow styles).                                                                                                                                                                                                                                                                                      |
+| Strings       | `trimToNull`, `stripTrailingSlash`, `normalizePath` (`""` for empty, `"/"` kept), `isImageIconSource` (http(s) / `/` / `data:image/`).                                                                                                                                                                                                                                                                                        |
+| Numbers       | `clamp(val, min, max)`, `toFiniteNumber(value, fallback = 0)`.                                                                                                                                                                                                                                                                                                                                                                |
+| Objects       | `isObject`, `isPlainObject`, `shallowEqual`, `toArray`.                                                                                                                                                                                                                                                                                                                                                                        |
+| Timing        | `debounce`, `throttle` (both return a function with `.cancel()`).                                                                                                                                                                                                                                                                                                                                                              |
+| Reporting     | `report(scope, error, level?)`, `setReportSink(fn)` — replaces `console.*` ([error-boundary.md](./modules/error-boundary.md#7-user-facing-messages-and-report)).                                                                                                                                                                                                                                                               |
+| User messages | `USER_MESSAGES`, `UserError`, `toUserMessage(error, { fallback?, codes? })`.                                                                                                                                                                                                                                                                                                                                                   |
+| Stores        | `createStore(initial, { freezeSnapshots = true })` → `{ getSnapshot, subscribe, publish(next \| updater), setState(partial \| updater) }`. `publish` returns `false` when the value is identical (`Object.is`) and **notifies only on change**; subscriber errors are reported, not thrown. In development, snapshots are deep-frozen (disable with `freezeSnapshots: false` for stores holding DOM nodes or class instances). |
+| Scheduling    | `createScheduler(options?)` → `{ schedule(cb, delayMs, { label }), scheduleFrame(cb, { label }), cancel(id), cancelAll(), getSnapshot(), subscribe, now }`. Timers and frames are tracked (`pendingCount`, labels), and **inject-able** (`now`, `requestFrame`, `scheduleTimer`, …) so tests run deterministically. The dock uses it instead of ad-hoc `setTimeout`/intervals.                                                 |
+| Types         | `ExternalStore`, `CreateStoreOptions`, `CoreSchedulerOptions`, `ScheduleHandle`, `ScheduledTaskSnapshot`, `SchedulerSnapshot`, `ReportLevel`, `ReportSink`, `UserMessageOptions`.                                                                                                                                                                                                                                              |
+
+## 7. Motion & design tokens (`@omerdlw/base-framework/tokens`)
+
+Rule 4 in practice: **never** write a literal duration/ease in a component.
+
+- **GPU compositor only.** Animate `transform` (`translate3d`, `scale`) and `opacity`. Animating layout properties (`height`, `top`, `left`) is forbidden. `gpuTransform(y, scale, x)` builds the canonical `translate3d(...) scale(...)` string; `COMPOSITOR_GPU_STYLE` supplies `backface-visibility`/`will-change` hints.
+- **Durations (`DURATION_TOKENS`, seconds):** `INSTANT` 0.08 · `MICRO` 0.18 · `FAST` 0.28 · `BASE` 0.36 · `MODERATE` 0.44 · `SLOW` 0.58 · `CINEMATIC` 0.86. The same steps exist as `duration-*` utility classes in `globals.css` (`duration-micro` is the default transition duration).
+- **Easings (`EASING_CURVES`):** `OUT_EXPO`, `OUT_QUART` (default CSS easing), `OUT_QUINT`, `IN_OUT_CUBIC`, `IN_CUBIC`, `OUT_BACK` (also `ease-out-expo`, … classes). `MOTION_EASINGS`: `ENTER` (= OUT_QUART), `ENTER_EMPHASIZED` (= OUT_EXPO), `EXIT` (= IN_CUBIC).
+- **Springs (`SPRING_PRESETS`):** `MICRO`, `SNAPPY`, `GENTLE`, `BOUNCY` (`{ type: "spring", stiffness, damping, mass }`).
+- **Tiers (`MOTION_TIERS`):** `MICRO` (4 px), `FAST` (9 px), `STANDARD` (18 px), `SURFACE` (28 px): distance, duration, ease and scale delta per step; dock and modal both use them.
+- **Reduced motion:** `REDUCED_MOTION_TRANSITION` (`INSTANT`, linear). The dock wraps its tree in `MotionConfig reducedMotion="user"` so Framer Motion honours the OS setting; CSS-driven motion uses `motion-safe:` / `motion-reduce:` variants.
+- **Variant builders** (return frozen Framer Motion variants): `contentSwap`, `overlaySurface`, `staggerItem` / `staggerDelay`, `chip`, `press` (`TAP_SCALE_SUBTLE` = 0.97), `dragDismiss`, `contentSwapTransitions`, `surfaceResizeTransition(distancePx)` / `durationForDistance` (longer moves take a bit longer, clamped).
+- **Module motion files** (`modules/*/motion.ts`) compose these into named presets; they are the only place besides `tokens/` where timing literals are tolerated by lint.
+
+### Z-index layers (`Z_INDEX`)
+
+Global layers, bottom to top: `BACKGROUND` 0 · `DOCK_BACKDROP` 100 · `DOCK` 110 · `NOTIFICATION` 120 · `MODAL_BACKDROP` 130 · `MODAL` 140 · `SELECT` 150 · `LOADING` 160 · `ERROR_OVERLAY` 170 · `CONTEXT_MENU_BACKDROP` 180 · `CONTEXT_MENU` 190 · `TOOLTIP` 200.
+
+Local layers (inside their own stacking context, ≤ 30): `UI_ELEMENT` 10, `DOCK_CARD_BACKGROUND` 0, `DOCK_CARD_CONTENT` 10, `DOCK_CARD_STACK_BASE` 10 (card `i` uses `BASE − i`), `DOCK_CARD_BADGE` 20, `DOCK_CARD_MEDIA` 30, `DOCK_BREADCRUMBS` 10, `DOCK_SURFACE_CONTROL` 10, `DOCK_SURFACE_POPOVER` 30, `DOCK_SURFACE_CENTER` 0, `MODAL_FRAME` 1, `MODAL_STICKY_HEADER` 10.
+
+Only the **order** of global layers matters, but each must stay above the local range (and above Tailwind's allowed `z-0/10/20`), otherwise page content covers it. Stacked modals share `Z_INDEX.MODAL` and stack by DOM order. A test asserts `SELECT` and `CONTEXT_MENU` exist and `DROPDOWN` / `DEBUG_OVERLAY` do not.
+
+### Shared class constants
+
+`SURFACE_CLASSES` (`surface`, `title`, `description`, `icon`) and `ACTION_TONE_CLASS` give feature surfaces the same glass look as the dock without importing it.
+
+### Global CSS (`src/app/globals.css`)
+
+Defines the color variables (`--white`, `--black`, `--primary`) that [ambient](./modules/ambient.md) rewrites, Tailwind v4 `@theme` color bindings (`bg-black`, `text-primary`), the motion token classes (`duration-*`, `ease-*`), and utilities `center` (flex-center) and `skeleton-block` (pulse).
+
+## 8. Module overview
+
+| Module                         | Does                                                                                                                                                   | Doc                                          |
+| :----------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------- |
+| `dock`                         | The framework's only chrome: route card stack, surfaces (sheets/wizards/flows), HUD, operations, status overlays, guards, breadcrumbs, media controls. | [dock.md](./modules/dock.md)                 |
+| `modal`                        | Promise-based stacked dialogs and sheets.                                                                                                              | [modal.md](./modules/modal.md)               |
+| `notification`                 | Single-slot toasts docked to the dock, event-driven feedback.                                                                                          | [notification.md](./modules/notification.md) |
+| `loading`                      | Full-screen loading overlay and busy flag.                                                                                                             | [loading.md](./modules/loading.md)           |
+| `background`                   | Image / video / YouTube layer behind the page.                                                                                                         | [background.md](./modules/background.md)     |
+| `media`                        | The active media session the dock controls operate on.                                                                                                 | [media.md](./modules/media.md)               |
+| `ambient`                      | Palette extraction → CSS color variables.                                                                                                              | [ambient.md](./modules/ambient.md)           |
+| `controls`                     | Paired control rails beside the dock.                                                                                                                  | [controls.md](./modules/controls.md)         |
+| `context-menu` (`contextMenu`) | Declarative right-click menus.                                                                                                                         | [context-menu.md](./modules/context-menu.md) |
+
+## 9. Gotchas
+
+- Importing `@omerdlw/base-framework/hooks` or `@omerdlw/base-framework/atoms` from a server-safe entry breaks the lint boundary and the Edge bundle.
+- `createStore` snapshots are frozen in development: mutate through `publish`/`setState`, never in place.
+- `useStore` without a selector re-renders on every change; select a slice.
+- A theme file that is not listed in `src/config/index.ts` crashes the first component that uses it (by design, with a clear message).
+- `globalEvents` handlers run synchronously inside `emit`; keep them cheap or schedule work.

package/docs/custom-modules.md

@@ -0,0 +1,267 @@
+# Custom Module Authoring Guide — `@omerdlw/base-framework/kernel`
+
+> **Read this first if you need to:** create a new declarative module for your application (e.g. an Audio Player, Command Palette, or Interactive Onboarding Tour), hook into `usePage()`, or register custom items in the microkernel's transactional registry.
+
+---
+
+## 1. Overview: The Microkernel Extensibility Model
+
+The core strength of `@omerdlw/base-framework` is its **inversion-of-control microkernel**. The kernel knows *no module by name*. All 9 built-in modules (`dock`, `modal`, `notification`, etc.) are authored using the exact same public API available to you: `defineModule()`.
+
+When you register a module in `<CoreProvider modules={[myModule, ...]}>`:
+1. The kernel validates uniqueness of the module's `id`.
+2. The kernel topologically sorts dependencies declared in `uses: ["peerModule"]` so that providers are nested in guaranteed dependency order.
+3. The kernel mounts the module's `<Provider>`, renders its `<Backdrop>` behind `{children}`, and renders its `<Overlay>` in an isolated error boundary above `{children}`.
+4. The kernel wires your module into `usePage()`, allowing any route in your application to declare configuration for your module.
+
+---
+
+## 2. Anatomy of a CoreModule
+
+```ts
+import { defineModule } from "@omerdlw/base-framework/kernel";
+
+export const myModule = defineModule({
+  id: "myModule",                    // Unique string identifier
+  uses: ["dock"],                    // Peer dependencies (determines mounting order)
+  Provider: MyContextProvider,       // Optional: Context provider wrapping application children
+  Backdrop: MyBackdropLayer,         // Optional: Rendered behind children (e.g. canvas, ambient lighting)
+  Overlay: MyOverlayLayer,           // Optional: Rendered above children in an error boundary (e.g. sheets, dialogs)
+  registry: {                        // Optional: Registry definition for transactional data
+    keyPolicy: "named",              // "singleton" | "named" | "path" | "route"
+    lifecycle: "route",              // "immediate" | "graceful" | "persistent" | "route"
+  },
+  page: {                            // Optional: usePage() integration
+    select: (config) => config.myModule,
+    entries: (slice, context) => [...],
+    use: (slice, { set }) => ({ ... }),
+  },
+});
+```
+
+---
+
+## 3. Step-by-Step Tutorial: Building a "Tour Guide" Module
+
+Let's create a custom **Onboarding Tour Module** that allows any page to declare step-by-step tooltips via `usePage({ tour: [...] })`.
+
+### Step 1: Define Types & Theme Spec
+
+Create `src/modules/tour/types.ts`:
+
+```ts
+export interface TourStep {
+  target: string;      // CSS selector or data attribute
+  title: string;
+  description: string;
+}
+
+export interface TourConfig {
+  steps: TourStep[];
+  autoStart?: boolean;
+}
+
+export interface TourPageApi {
+  start: () => void;
+  next: () => void;
+  stop: () => void;
+}
+```
+
+Create `src/modules/tour/constants.ts`:
+
+```ts
+import { defineThemeSpec } from "@omerdlw/base-framework/theme";
+
+export type TourThemeSlot = "card" | "title" | "description" | "nextButton" | "skipButton";
+export const tourTheme = defineThemeSpec<TourThemeSlot>("tour");
+```
+
+---
+
+### Step 2: Create the State & Context
+
+Create `src/modules/tour/context.tsx`:
+
+```tsx
+"use client";
+
+import React, { createContext, useContext, useState, useMemo } from "react";
+import type { TourStep } from "./types";
+
+interface TourContextValue {
+  currentStepIndex: number;
+  currentStep: TourStep | null;
+  isActive: boolean;
+  start: () => void;
+  next: () => void;
+  stop: () => void;
+}
+
+const TourContext = createContext<TourContextValue | null>(null);
+
+export function TourProvider({ children }: { children?: React.ReactNode }) {
+  const [steps, setSteps] = useState<TourStep[]>([]);
+  const [index, setIndex] = useState(0);
+  const [isActive, setIsActive] = useState(false);
+
+  const value = useMemo<TourContextValue>(() => ({
+    currentStepIndex: index,
+    currentStep: isActive ? steps[index] ?? null : null,
+    isActive,
+    start: () => { setIndex(0); setIsActive(true); },
+    next: () => {
+      if (index + 1 < steps.length) setIndex(index + 1);
+      else setIsActive(false);
+    },
+    stop: () => setIsActive(false),
+  }), [index, isActive, steps]);
+
+  return <TourContext.Provider value={value}>{children}</TourContext.Provider>;
+}
+
+export function useTour() {
+  const ctx = useContext(TourContext);
+  if (!ctx) throw new Error("useTour must be used within TourProvider");
+  return ctx;
+}
+```
+
+---
+
+### Step 3: Create the Visual Overlay
+
+Create `src/modules/tour/overlay.tsx`:
+
+```tsx
+"use client";
+
+import React from "react";
+import { useTheme } from "@omerdlw/base-framework/theme";
+import { Button } from "@omerdlw/base-framework/atoms";
+import { useTour } from "./context";
+import { tourTheme } from "./constants";
+
+export function TourOverlay() {
+  const { currentStep, isActive, next, stop } = useTour();
+  const theme = useTheme(tourTheme);
+
+  if (!isActive || !currentStep) return null;
+
+  return (
+    <div className="fixed inset-0 pointer-events-none z-50 flex items-center justify-center">
+      <div className={`${theme.slots.card} pointer-events-auto`}>
+        <h3 className={theme.slots.title}>{currentStep.title}</h3>
+        <p className={theme.slots.description}>{currentStep.description}</p>
+        <div className="mt-4 flex gap-2">
+          <Button onClick={stop} className={theme.slots.skipButton}>Skip</Button>
+          <Button onClick={next} className={theme.slots.nextButton}>Next</Button>
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+---
+
+### Step 4: Define the Module & Wire into `usePage`
+
+Create `src/modules/tour/module.tsx`:
+
+```tsx
+"use client";
+
+import { defineModule } from "@omerdlw/base-framework/kernel";
+import { TourProvider, useTour } from "./context";
+import { TourOverlay } from "./overlay";
+import type { TourConfig, TourPageApi } from "./types";
+
+export const tourModule = defineModule<
+  "tour",
+  null,
+  TourConfig,
+  TourPageApi
+>({
+  id: "tour",
+  Provider: TourProvider,
+  Overlay: TourOverlay,
+  page: {
+    select: (config) => config.tour,
+    use: (slice, { set }) => {
+      const { start, next, stop } = useTour();
+      return { start, next, stop };
+    },
+  },
+});
+
+// TypeScript type augmentation for auto-complete in usePage()
+declare module "@omerdlw/base-framework/kernel" {
+  interface PageConfig {
+    tour?: TourConfig;
+  }
+}
+```
+
+Create `src/modules/tour/index.ts`:
+
+```ts
+export * from "./types";
+export * from "./constants";
+export * from "./context";
+export * from "./module";
+```
+
+---
+
+## 4. Consuming Your Custom Module
+
+### 1. Mount in `<CoreProvider>`:
+
+In `src/app/providers.tsx`:
+
+```tsx
+import { CoreProvider } from "@omerdlw/base-framework/provider";
+import { dockModule } from "@omerdlw/base-framework/modules/dock";
+import { tourModule } from "@/modules/tour";
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <CoreProvider modules={[dockModule, tourModule]}>
+      {children}
+    </CoreProvider>
+  );
+}
+```
+
+### 2. Declare in Any Page Route:
+
+In `src/app/dashboard/page.tsx`:
+
+```tsx
+"use client";
+
+import { usePage } from "@omerdlw/base-framework/kernel";
+
+export default function DashboardPage() {
+  const page = usePage({
+    title: "Dashboard",
+    tour: {
+      steps: [
+        { target: "#metrics", title: "Key Metrics", description: "Monitor your KPIs here in real time." },
+        { target: "#export", title: "Export Data", description: "Download CSV reports with one click." },
+      ],
+    },
+  });
+
+  return (
+    <div>
+      <button onClick={() => page.modules.tour?.start()}>
+        Take a Tour
+      </button>
+    </div>
+  );
+}
+```
+
+Notice that `page.modules.tour` is **fully type-safe** and auto-completed by TypeScript!