@omerdlw/base-framework 1.0.0 → 1.0.2

package/docs/getting-started.md

@@ -0,0 +1,199 @@
+# Getting Started with `@omerdlw/base-framework`
+
+> **A complete step-by-step guide to installing, configuring, and building app-like Next.js 16 (App Router) & React 19 web applications with `@omerdlw/base-framework`.**
+
+---
+
+## 1. Prerequisites & Tech Stack
+
+Before installing `@omerdlw/base-framework`, verify your environment:
+- **Node.js:** `v20.0.0` or higher (Node 22 recommended)
+- **Framework:** Next.js `15.0.0` or `16.0.0+` (App Router)
+- **React:** React `19.0.0+` & React DOM `19.0.0+`
+- **Styling:** Tailwind CSS v4
+
+---
+
+## 2. Installation
+
+Install `@omerdlw/base-framework` alongside its required peer dependencies:
+
+```bash
+npm install @omerdlw/base-framework motion @iconify-icon/react @radix-ui/react-tooltip clsx tailwind-merge
+```
+
+### Peer Dependencies Breakdown
+
+| Package | Purpose in Base Framework |
+| :--- | :--- |
+| `motion` (`>=12.0.0`) | Hardware GPU-accelerated motion presets (`translate3d`, `scale`, spring physics). |
+| `@iconify-icon/react` | Unified SVG-free icon rendering via `<Icon icon="solar:..." />`. |
+| `@radix-ui/react-tooltip` | Accessible WAI-ARIA tooltip primitives. |
+| `clsx` & `tailwind-merge` | Backing utilities for `cn()` class merging. |
+
+---
+
+## 3. Tailwind CSS v4 Configuration
+
+To ensure Tailwind scans the components, overlays, and atoms bundled inside `@omerdlw/base-framework`, add the package source to your main CSS file (e.g. `src/app/globals.css`):
+
+```css
+@import "tailwindcss";
+
+/* 1. Instruct Tailwind to scan the Base Framework package files */
+@source "../node_modules/@omerdlw/base-framework";
+
+/* 2. Custom helper utility classes used by Base Framework */
+@utility center {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+@utility skeleton-block {
+  animation: pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+  background-color: rgb(255 255 255 / 0.08);
+}
+```
+
+---
+
+## 4. Setting Up Application Providers
+
+Create a client-side provider component (e.g., `src/app/providers.tsx`) to mount `CoreProvider` and install your desired UI modules:
+
+```tsx
+"use client";
+
+import React from "react";
+import { CoreProvider } from "@omerdlw/base-framework/provider";
+import { ThemeProvider } from "@omerdlw/base-framework/theme";
+
+// Import desired first-party modules
+import { dockModule } from "@omerdlw/base-framework/modules/dock";
+import { modalModule } from "@omerdlw/base-framework/modules/modal";
+import { notificationModule } from "@omerdlw/base-framework/modules/notification";
+import { ambientModule } from "@omerdlw/base-framework/modules/ambient";
+import { backgroundModule } from "@omerdlw/base-framework/modules/background";
+import { controlsModule } from "@omerdlw/base-framework/modules/controls";
+import { loadingModule } from "@omerdlw/base-framework/modules/loading";
+import { contextMenuModule } from "@omerdlw/base-framework/modules/context-menu";
+
+// Define the modules your application uses
+const modules = [
+  dockModule,
+  modalModule,
+  notificationModule,
+  ambientModule,
+  backgroundModule,
+  controlsModule,
+  loadingModule,
+  contextMenuModule,
+];
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <CoreProvider modules={modules}>
+      {children}
+    </CoreProvider>
+  );
+}
+```
+
+Then wrap your Root Layout in `src/app/layout.tsx`:
+
+```tsx
+import "./globals.css";
+import { Providers } from "./providers";
+
+export const metadata = {
+  title: "My Base Framework App",
+  description: "Next.js application built with Base Framework",
+};
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body className="min-h-screen bg-black text-white antialiased">
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  );
+}
+```
+
+---
+
+## 5. Building Your First Route with `usePage()`
+
+Downstream routes never manually render headers, docks, or modals. Instead, a route simply declares its desired visual state using `usePage()`:
+
+Create `src/app/page.tsx`:
+
+```tsx
+"use client";
+
+import { usePage } from "@omerdlw/base-framework/kernel";
+import { Button, Icon } from "@omerdlw/base-framework/atoms";
+
+export default function HomePage() {
+  const page = usePage({
+    title: "Dashboard",
+    dock: {
+      description: "Application Overview & Analytics",
+      icon: "solar:widget-bold",
+    },
+    background: {
+      image: "https://images.unsplash.com/photo-1618005182384-a83a8bd57fbe",
+      overlay: true,
+    },
+  });
+
+  return (
+    <main className="p-8">
+      <h1 className="text-3xl font-bold tracking-tight">Dashboard Overview</h1>
+      <p className="mt-2 text-white/60">
+        Notice how the dock, background, and title were automatically configured by the microkernel.
+      </p>
+
+      <div className="mt-6 flex gap-3">
+        <Button
+          onClick={() => page.modules.notification?.toast("Action triggered successfully!", { type: "success" })}
+          className="inline-flex h-9 items-center gap-2 rounded-xl bg-white px-4 text-xs font-semibold text-black hover:bg-white/90"
+        >
+          <Icon icon="solar:bell-bold" size={16} />
+          Show Notification
+        </Button>
+      </div>
+    </main>
+  );
+}
+```
+
+---
+
+## 6. Official Package Subpaths
+
+`@omerdlw/base-framework` exposes 11 tree-shakable subpaths. Always import from the dedicated subpath:
+
+| Subpath | Purpose | Key Exports |
+| :--- | :--- | :--- |
+| `@omerdlw/base-framework/kernel` | Microkernel engine | `usePage()`, `defineModule()`, `definePeer()`, `useModule()`, `useModuleState()` |
+| `@omerdlw/base-framework/provider` | Root host component | `CoreProvider` |
+| `@omerdlw/base-framework/modules/*` | 9 UI modules | `dockModule`, `modalModule`, `notificationModule`, `ambientModule`, etc. |
+| `@omerdlw/base-framework/result` | Functional error handling | `Result<T, E>`, `ok()`, `err()`, `isResult()`, `createSafeAction()` |
+| `@omerdlw/base-framework/events` | Cross-cutting event bus | `globalEvents`, `EVENT_TYPES`, `FrameworkEventMap` |
+| `@omerdlw/base-framework/theme` | Declarative theme engine | `defineThemeSpec()`, `defineTheme()`, `ThemeProvider`, `useTheme()` |
+| `@omerdlw/base-framework/atoms` | Unstyled accessible UI atoms | `Button`, `Icon`, `Spinner`, `Tooltip` |
+| `@omerdlw/base-framework/hooks` | Universal React hooks | `useStore()`, `useClickOutside()`, `useGlobalEvent()`, `useRequiredContext()` |
+| `@omerdlw/base-framework/utils` | Pure runtime utilities | `cn()`, `clamp()`, `debounce()`, `throttle()`, `createStore()`, `createScheduler()`, `report()` |
+| `@omerdlw/base-framework/error` | Isolated error boundaries | `GlobalError`, `ModuleError`, `UserError`, `toUserMessage()` |
+| `@omerdlw/base-framework/tokens` | Design & motion tokens | `DURATION_TOKENS`, `EASING_CURVES`, `SPRING_PRESETS`, `Z_INDEX` |
+
+---
+
+## 7. Next Steps
+
+- Explore how visual design is configured via [Theming Guide (`theming.md`)](./theming.md).
+- Learn how to build custom modules via [Custom Module Authoring (`custom-modules.md`)](./custom-modules.md).
+- Read the [Architecture & 10 Rules (`architecture-and-rules.md`)](./architecture-and-rules.md) for strict architectural invariants.

package/docs/modules/README.md

@@ -0,0 +1,176 @@
+# Module Reference
+
+> **Read this first if you need to:** find which module does what, see how modules connect, add a new module, or learn the structure every module page follows.
+
+One page per module/core entry. Each page answers, from the big picture down to the details: **what it is → mental model → quick start → capabilities → full API → behaviour → theming → recipes/gotchas → file map → dependencies**.
+
+## 1. Index
+
+| Module         | Import                                      | Doc                                      | What it owns                                                                                       | Page key (`usePage`) | Registry type |
+| :------------- | :------------------------------------------ | :--------------------------------------- | :------------------------------------------------------------------------------------------------- | :------------------- | :------------ |
+| Kernel         | `@omerdlw/base-framework/kernel`                             | [kernel.md](./kernel.md)                 | Module host, registry, `usePage`, `defineModule`, peers                                            | `title`, `registry`  | —             |
+| Dock           | `@omerdlw/base-framework/modules/dock`                            | [dock.md](./dock.md)                     | The only chrome: card stack, surfaces/flows, HUD, operations, status overlays, guards, breadcrumbs | `dock`               | `dock`        |
+| Modal          | `@omerdlw/base-framework/modules/modal`                           | [modal.md](./modal.md)                   | Promise-based stacked dialogs                                                                      | `modal`              | `modal`       |
+| Notification   | `@omerdlw/base-framework/modules/notification`                    | [notification.md](./notification.md)     | Single-slot toasts docked to the dock; event-driven feedback                                       | `notification`       | —             |
+| Loading        | `@omerdlw/base-framework/modules/loading`                         | [loading.md](./loading.md)               | Loading overlay + busy flag                                                                        | `loading`            | `loading`     |
+| Background     | `@omerdlw/base-framework/modules/background`                      | [background.md](./background.md)         | Image / video / YouTube layer behind the page                                                      | `background`         | `background`  |
+| Media          | `@omerdlw/base-framework/modules/media`                           | [media.md](./media.md)                   | The active media session the dock controls operate on                                              | `media`              | `media`       |
+| Ambient        | `@omerdlw/base-framework/modules/ambient`                         | [ambient.md](./ambient.md)               | Image → palette → CSS color variables                                                              | `ambient`            | —             |
+| Controls       | `@omerdlw/base-framework/modules/controls`                        | [controls.md](./controls.md)             | Paired control rails beside the dock                                                               | `controls`           | `controls`    |
+| Context menu   | `@omerdlw/base-framework/modules/context-menu` (id `contextMenu`) | [context-menu.md](./context-menu.md)     | Declarative right-click menus                                                                      | `contextMenu`        | `contextMenu` |
+| Error boundary | `@omerdlw/base-framework/error`                              | [error-boundary.md](./error-boundary.md) | Boundaries, reporter, window error listener                                                        | —                    | —             |
+| Result         | `@omerdlw/base-framework/result`                             | [result.md](./result.md)                 | `Result<T, E>`, `createSafeAction`                                                                 | —                    | —             |
+
+General guides: [../getting-started.md](../getting-started.md) (installation & setup), [../architecture-and-rules.md](../architecture-and-rules.md) (rules and boundaries), [../theming.md](../theming.md) (custom themes), [../custom-modules.md](../custom-modules.md) (custom module authoring), [../core-engine.md](../core-engine.md) (provider, theme, events, hooks, utils, tokens), [../testing.md](../testing.md) (testing guide).
+
+## 2. How the modules connect
+
+Modules never import each other. They connect through three channels only:
+
+```
+ ┌────────────┐  usePage({ dock, background, loading, … })    ┌──────────┐
+ │ pages/     │ ───────────────────────────────────────────▶ │ registry │  (per module type)
+ │ features   │                                               └────┬─────┘
+ └─────┬──────┘                                                    │ useRegistryEntries / useRegistryValue
+       │ globalEvents (DOCK_STATUS_SET, AUTH_*, APP_ERROR …)        ▼
+       ▼                                                      each module's provider/overlay
+ ┌────────────┐  definePeer / useModuleState (declared in `uses`)
+ │  modules   │ ◀────────────────────────────────────────────▶ other modules' stores
+ └────────────┘  DOM contracts: #dock-card-stack, data-controls-hidden, data-controls-anchor
+```
+
+| Reader → source               | How                      | Used for                                                                     |
+| :---------------------------- | :----------------------- | :--------------------------------------------------------------------------- |
+| dock → `loading`              | `definePeer`             | Page-loading flag; `stopLoading()` after navigation.                         |
+| dock → `media`                | `definePeer`             | Play/pause icon, media controls.                                             |
+| dock → `notification`         | `definePeer`             | Is a toast visible (breadcrumbs yield).                                      |
+| background → `media`          | `definePeer`             | Registers the background video as source `background`.                       |
+| ambient → `background`        | `useModuleState`         | Poster URL as the default tint image.                                        |
+| context-menu → `dock`         | `useModuleState`         | Active card as the default menu header.                                      |
+| notification, controls → dock | DOM id `dock-card-stack` | Portal target / rail anchor.                                                 |
+| dock ← events                 | `globalEvents`           | `APP_ERROR`, `API_ERROR`, `DOCK_STATUS_SET`, `DOCK_GUARD`, `DOCK_NOT_FOUND`. |
+| notification ← events         | `globalEvents`           | `API_UNAUTHORIZED`, `APP_ERROR`/`STATE_CHANGE` with `notify: true`.          |
+
+Every `definePeer`/`useModuleState`/`useModule` call needs the **peer id as a string literal** and the id in the module's `uses` (`npm run check:architecture` verifies it). Each peer ships an inert stand-in, so any module can be left out of `CoreProvider modules` and the rest still works.
+
+## 3. Install-time facts
+
+- `src/modules/index.ts` exports every module and `defaultModules` (`background, ambient, dock, controls, contextMenu, loading, media, modal, notification`); it is the only place that lists them all. `src/app/providers.tsx` passes the list to `CoreProvider`.
+- Install a subset to ship less: `modules={[dockModule, notificationModule, loadingModule]}`.
+- Module ids are **camelCase** (`contextMenu`); the folder and theme id may be kebab-case (`context-menu`).
+- A module is installable when it has a `module.tsx` (or `module.ts`) with `defineModule`; the order of the list does not matter (`uses` sorts it).
+
+## 4. Canonical module template
+
+Every folder in `src/modules/` uses the same **slots**. A slot that does not apply is omitted, never created empty. `tests/architecture.test.ts` fails when a required file or the module's doc page is missing, or when an unexpected file appears at the module root.
+
+| File           |      Required       | Responsibility                                                                                                                  |
+| :------------- | :-----------------: | :------------------------------------------------------------------------------------------------------------------------------ |
+| `index.ts`     |         ✅          | Public barrel: named exports only; nothing internal leaks through it.                                                           |
+| `types.ts`     |         ✅          | Public TypeScript contracts, **no runtime code** (a `types/` folder with an `index.ts` is also accepted).                       |
+| `constants.ts` |         ✅          | Frozen configuration, enums, event names, the theme spec (`defineThemeSpec`).                                                   |
+| `utils.ts`     |         ✅          | Pure helpers (no React state).                                                                                                  |
+| `module.tsx`   | installable modules | `defineModule` definition, `defineX` builder, `declare module "@omerdlw/base-framework/kernel"` augmentation (`module.ts` when there is no JSX). |
+| `context.tsx`  |    when stateful    | The context, the provider and the `useX` hooks (**one** context per module).                                                    |
+| `hooks.ts`     |      optional       | Extra hooks, notably the `use<Component>Model` logic behind each overlay component.                                             |
+| `state.ts`     |      optional       | State factory, initial state, pure reducers.                                                                                    |
+| `overlay.tsx`  |      optional       | **All** visual components: JSX only, calling `use*Model` hooks (no state, effects or refs).                                     |
+| `motion.ts`    |      optional       | Motion presets derived from `@omerdlw/base-framework/tokens`.                                                                                    |
+| `store.ts`     |      optional       | A store file when warranted.                                                                                                    |
+
+Rules of thumb:
+
+- A module may add a **topic file or folder** for a cohesive concern, declared in the file-pattern test (`background/youtube/`, `context-menu/resolver.ts`, the dock's `routing/ runtime/ status/ surface/ cards.tsx hud.ts provider.tsx`). Files past ~500 lines go into a sub-folder.
+- Relative imports may reach into the **same** module only. Cross-module needs go through peers or `globalEvents`.
+- Barrels use explicit named exports (`export { a, b } from "./x"`), never `export *` from implementation files; `export type * from "./types"` is fine.
+- **No design in code:** colors, sizes, radii and typography are theme slots (`src/config/<name>.module.theme.ts`); animation comes from `@omerdlw/base-framework/tokens` presets.
+
+### 4.1 File matrix (current)
+
+| Module       | `index types constants utils` |  `module`   |  `context`   | `hooks` | `state` | `overlay` | `motion` | Extras                                                                               |
+| :----------- | :---------------------------: | :---------: | :----------: | :-----: | :-----: | :-------: | :------: | :----------------------------------------------------------------------------------- |
+| ambient      |              ✅               |     ✅      |      ✅      |    —    |    —    |     —     |    —     |                                                                                      |
+| background   |              ✅               |     ✅      |      ✅      |   ✅    |    —    |    ✅     |    ✅    | `youtube/`                                                                           |
+| context-menu |              ✅               |     ✅      |      ✅      |   ✅    |   ✅    |    ✅     |    ✅    | `resolver.ts`                                                                        |
+| controls     |              ✅               |     ✅      |      —       |   ✅    |    —    |    ✅     |    —     |                                                                                      |
+| dock         |              ✅               |     ✅      | `context.ts` |   ✅    |   ✅    |    ✅     |    ✅    | `provider.tsx`, `cards.tsx`, `hud.ts`, `routing/`, `runtime/`, `status/`, `surface/` |
+| loading      |              ✅               |     ✅      |      ✅      |   ✅    |    —    |    ✅     |    —     |                                                                                      |
+| media        |              ✅               |     ✅      |      ✅      |   ✅    |    —    |    ✅     |    —     |                                                                                      |
+| modal        |              ✅               |     ✅      |      ✅      |   ✅    |   ✅    |    ✅     |    ✅    |                                                                                      |
+| notification |              ✅               | `module.ts` |      ✅      |   ✅    |    —    |    ✅     |    ✅    |                                                                                      |
+
+### 4.2 Why some optional slots are absent
+
+| Module         | Absent                  | Reason                                                                                                                                 |
+| :------------- | :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------- |
+| `ambient`      | `overlay`, `motion`     | Renders nothing: it writes CSS custom properties; transitions are CSS classes from the theme.                                          |
+| `controls`     | `context`, `motion`     | Stateless: entries live in the registry and layout is measured from the DOM. No animation.                                             |
+| `loading`      | `motion`, `state`       | The overlay renders `Spinner` (or a skeleton) and mounts/unmounts instantly; state is a small `useState` in the provider.              |
+| `media`        | `motion`                | Renders nothing; `overlay.tsx` holds only the components that return `null` (`MediaSource`, `MediaOverlay`).                           |
+| `notification` | builder                 | Toasts are imperative: `useToast` (in `hooks.ts`) plays the builder role.                                                              |
+| core `error`   | provider, builder, view | Boundaries are class components configured through props; `boundary.tsx` is the view, `listener.ts` and `reporter.ts` are topic files. |
+
+## 5. Adding a module
+
+1. **Create** `src/modules/<name>/` with `index.ts`, `types.ts`, `constants.ts`, `utils.ts`, and (as needed) `context.tsx`, `hooks.ts`, `overlay.tsx`, `motion.ts`, `module.tsx`.
+2. **Define it** in `module.tsx`:
+   ```ts
+   export const announcementModule = defineModule({
+     id: "announcement", // camelCase
+     context: AnnouncementContext,
+     Provider: AnnouncementProvider,
+     Overlay: AnnouncementBanner,
+     uses: ["dock"], // only peers you read via definePeer/useModuleState
+     registry: {
+       keyPolicy: "singleton",
+       singletonKey: "current",
+       lifecycle: "route",
+     },
+     page: {
+       entries: (slice) => [{ key: "current", value: slice }],
+       use: useAnnouncementPage,
+     },
+   });
+   declare module "@omerdlw/base-framework/kernel" {
+     interface CoreModules {
+       announcement: typeof announcementModule;
+     }
+     interface PageConfig {
+       announcement?: AnnouncementConfig;
+     }
+   }
+   ```
+3. **Theme it:** `defineThemeSpec<Slots>("announcement")` in `constants.ts`, `src/config/announcement.module.theme.ts` with `defineTheme`, and list it in `src/config/index.ts` (otherwise `useTheme` throws).
+4. **Export it** from `src/modules/index.ts` (and add it to `defaultModules` if it ships by default).
+5. **Document it** at `src/docs/modules/announcement.md` using the page structure in §6 and add a row to the index above.
+6. **Test it** in `tests/modules/announcement.test.ts` ([testing.md](../testing.md#41-adding-tests-for-a-new-module)); register its registry type in `tests/support/registry.ts` if it has one.
+7. **Run the pre-flight** (`type-check`, `lint`, `check:architecture`, `test`). The architecture test verifies the template, the doc page, overlay purity and one-context-per-module.
+
+In downstream projects `src/modules` is yours: add, change or delete modules there without touching `src/core`.
+
+## 6. Structure of a module page
+
+Every page follows this skeleton (omit sections that do not apply). Keep it **verified against the code**: names, defaults, numbers and file maps must match the source.
+
+1. **Title + "Read this first if you need to…"** one-liner.
+2. **At a glance** table: import, id, what it renders, registry type, page key, peers, theme, events/DOM contracts, tests.
+3. **Mental model** (diagram or short rules).
+4. **Quick start** with the 80 % usage.
+5. **Capabilities** (matrix with where to read more).
+6. **API reference**: every public export with signature, defaults and behaviour; option tables.
+7. **Behaviour details**: lifecycle, ordering, edge cases, accessibility.
+8. **Theming**: slots and what stays in code.
+9. **Recipes and gotchas**.
+10. **File map** (every file, one responsibility each).
+11. **Dependencies** (uses / peers / used by).
+
+## 7. Dependency direction
+
+```
+src/app ─┐
+src/features ─┼─▶ @omerdlw/base-framework/modules/* ──▶ @omerdlw/base-framework/kernel ──▶ @omerdlw/base-framework/{utils,hooks,tokens,events,result}
+src/core/provider.tsx ┘         │
+                               └──▶ @omerdlw/base-framework/atoms, @omerdlw/base-framework/theme
+```
+
+Modules are installed by `CoreProvider` from the list the app passes; orchestration drives modules through their `defineModule` definitions and never imports them.

package/docs/modules/ambient.md

@@ -0,0 +1,150 @@
+# Ambient — `@omerdlw/base-framework/modules/ambient`
+
+> **Read this first if you need to:** tint a page from an image (cover, avatar, album art), set theme colors from code, scope a tint to one element, or know which CSS variables change.
+
+## 1. At a glance
+
+|                    |                                                                                |
+| :----------------- | :----------------------------------------------------------------------------- |
+| **Import**         | `import { useAmbientTheme, defineAmbient, … } from "@omerdlw/base-framework/modules/ambient"`        |
+| **Module id**      | `ambient` (`ambientModule`, in `defaultModules`)                               |
+| **Renders**        | Nothing. It writes **CSS custom properties** on an element (default `<html>`). |
+| **Registry type**  | none (no `registry` definition; it only uses the page hook)                    |
+| **Page slice**     | `usePage({ ambient })` and the dock banner → `page.modules.ambient.set(...)`   |
+| **Peers (`uses`)** | `background` (reads `posterUrl` through `useModuleState`)                      |
+| **Theme**          | `ambientTheme` → one slot, `transition` (`src/config/ambient.module.theme.ts`) |
+| **HTTP route**     | `GET /api/ambient/proxy?url=…` (CORS-safe image proxy, used as a fallback)     |
+| **Tests**          | `tests/modules/ambient.test.ts`                                                |
+
+## 2. Mental model
+
+```
+image URL ──fetch (CORS) ─┬─▶ 32×32 canvas ─▶ OKLCH sampling ─▶ { primary, black } palette
+                          └─ fallback: /api/ambient/proxy
+palette ─▶ CSS variables on the target element ─▶ every rule that reads them re-tints
+```
+
+Ambient is a **colour pipeline**, not a component: pick an image (or pass colors directly), and the variables the design system already reads (`--primary`, `--black`, …) change. Because they are plain CSS variables, Tailwind classes such as `bg-primary` / `text-primary` and anything using `var(--black)` follow automatically, with a CSS color transition.
+
+## 3. Quick start
+
+```tsx
+"use client";
+// 1. Through usePage: a string is the image
+usePage({ ambient: "/images/album-cover.jpg" });
+
+// 2. `true` → use the dock banner, else the background video's poster; `false` → turn the automatic banner tint off
+usePage({ dock: { banner: coverUrl }, ambient: true });
+
+// 3. From any component
+useAmbientTheme({ image: backdropUrl || account?.avatarUrl || null });
+
+// 4. Explicit colors, scoped to one element
+const cardRef = useRef<HTMLDivElement>(null);
+useAmbientTheme({
+  colors: { primary: "#e5d3ff", black: "#140d1f" },
+  scope: cardRef,
+});
+```
+
+## 4. What gets written
+
+| Variable                       | Set when                                     | Value                                                        |
+| :----------------------------- | :------------------------------------------- | :----------------------------------------------------------- |
+| `--primary`                    | an `image` is given and extracted            | bright OKLCH colour (lightness 0.74, chroma 0.15–0.24)       |
+| `--color-ambient-glow`         | same                                         | same as `--primary`                                          |
+| `--color-primary`              | same **and** `tintGlobals` is true (default) | same as `--primary`                                          |
+| `--black`                      | an `image` is given and extracted            | deep, slightly tinted OKLCH (lightness 0.15, chroma ≤ 0.055) |
+| any variable named in `colors` | `colors` is set                              | the literal value                                            |
+
+`colors` keys are mapped as: `primary` → `--primary`, `black` → `--black`, `white` → `--white`, `ambientGlow` → `--color-ambient-glow`, `colorPrimary` → `--color-primary`; a key starting with `--` is used verbatim; anything else becomes `--color-<key>`. `colors` always wins over extracted values.
+
+On cleanup the previous inline values (and priorities) are restored exactly. If `transition` is true (default) the theme's `transition` classes (`transition-colors duration-moderate ease-out-quart`) are added to the target while the theme is active (and removed again only for scoped targets, so the global tint keeps animating between pages).
+
+## 5. Public API
+
+| Export                                                                                           | Kind      | Description                                                                                                                                                                       |
+| :----------------------------------------------------------------------------------------------- | :-------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ambientModule`                                                                                  | module    | `defineModule` definition (provider + `usePage({ ambient })`).                                                                                                                    |
+| `AmbientProvider`                                                                                | component | Holds the **current shared palette** and `isExtracting` in a store. Prop `initialPalette`.                                                                                        |
+| `useAmbientTheme(config)`                                                                        | hook      | **Main entry.** `config` is an image URL string or `AmbientConfig`. Extracts, applies CSS variables, updates the shared palette. Returns `{ palette, isExtracting }`.             |
+| `useAmbientColor(image, options?)`                                                               | hook      | Extract a palette **without** applying it.                                                                                                                                        |
+| `useAmbient(configOrImage?)`                                                                     | hook      | The shared state `{ palette, isExtracting, setPalette, setIsExtracting }`; with an argument it also applies that theme and returns its palette. Throws outside `AmbientProvider`. |
+| `defineAmbient(def)`                                                                             | builder   | Reusable theme; `image` / `colors` may be functions of props. Returns `{ id, config, create(props?, overrides?), use(props?, overrides?) }`.                                      |
+| `extractPaletteFromImage(src, options?)`                                                         | util      | Async extraction with cache and in-flight de-duplication; resolves the fallback palette on any failure.                                                                           |
+| `rgbToOklch(r, g, b)`, `oklchToString(l, c, h, alpha?)`                                          | utils     | Colour conversion helpers.                                                                                                                                                        |
+| `resolvePageAmbientTheme(slice, posterUrl)`                                                      | util      | Maps the page's `ambient` + dock banner to a theme config.                                                                                                                        |
+| `AMBIENT_CSS_VARS`, `AMBIENT_DEFAULTS`, `COLOR_EXTRACT_CONFIG`, `ambientTheme`, `AmbientContext` | constants |                                                                                                                                                                                   |
+| Types                                                                                            |           | `AmbientConfig`, `AmbientPalette`, `AmbientDescriptor`, `AmbientTarget`, `AmbientImageSource`, `AmbientPageConfig`, …                                                             |
+
+### 5.1 `AmbientConfig`
+
+| Field            | Default                             | Meaning                                                                                         |
+| :--------------- | :---------------------------------- | :---------------------------------------------------------------------------------------------- |
+| `image`          | `null`                              | URL string or `{ src }`.                                                                        |
+| `colors`         | `null`                              | Explicit variables (see §4). A config with only `colors` is active without extraction.          |
+| `scope`          | `null` → `document.documentElement` | CSS selector string, element, or `ref`. A selector that matches nothing applies nothing.        |
+| `tintGlobals`    | `true`                              | Also set `--color-primary`. Set `false` to tint only `--primary`/`--black`/glow inside a scope. |
+| `transition`     | `true`                              | Add the theme's transition classes to the target.                                               |
+| `initialPalette` | defaults                            | Palette shown before extraction finishes.                                                       |
+| `options`        | `null`                              | `{ initialPalette, fallbackPalette }` (the fallback is used when extraction fails).             |
+
+`AMBIENT_DEFAULTS` = `{ primary: "#101010", black: "#0b0b0b" }` is used until a palette exists.
+
+### 5.2 `usePage({ ambient })` resolution
+
+`resolvePageAmbientTheme` runs with the page's `ambient`, the dock **banner**, and the background's `posterUrl`:
+
+| `ambient` value | Result                                                                                               |
+| :-------------- | :--------------------------------------------------------------------------------------------------- |
+| `false`         | No theme (also disables the banner tint).                                                            |
+| `true`          | `image` = banner, else the background video poster.                                                  |
+| string          | That image (`tintGlobals: true`).                                                                    |
+| object          | `{ image: ambient.image ?? banner ?? poster, ...ambient }`.                                          |
+| not set         | If the dock has a banner and the background has no poster → tint with the banner; otherwise nothing. |
+
+`page.modules.ambient` is just `{ set(ambient) }`.
+
+## 6. Extraction details
+
+- **Source loading.** Remote (`http…`) images are first fetched with `cors=1` and `mode: "cors"`, then through `/api/ambient/proxy?url=…`; the blob is read from an object URL (revoked afterwards). Same-origin or non-http sources are loaded directly (with `crossOrigin="anonymous"` when no object URL was needed).
+- **The proxy** only serves `image/*` (415 otherwise), blocks unsafe/internal URLs with `isSafeUrl` (including on every redirect, up to 5), and caches responses for a day. Do not point it at anything but images.
+- **Sampling.** The image is drawn to a 32×32 canvas. Pixels with alpha < 128 are skipped; near-black, near-white and low-chroma pixels are counted as neutral. Remaining pixels go into 24 hue bins; the densest bin plus half-weighted neighbours gives the hue, chroma and lightness. An all-neutral image yields a muted blue (`h 252`).
+- **Derivation.** Chroma is clamped to `0.03–0.28`; `primary` uses lightness `0.74` with chroma `max(0.15, min(0.24, max(chroma × 1.15, 0.18)))`; `black` uses lightness `0.15` with chroma `min(0.055, max(0.025, chroma × 0.35))`.
+- **Cache.** Up to 100 palettes (`cacheLimit`, oldest evicted) and concurrent requests for the same URL share one promise.
+- **Stability.** `colors`, `options` and `initialPalette` are stabilized with `shallowEqual`, so passing fresh object literals each render does **not** re-apply the theme. (A test forbids `JSON.stringify` for this.)
+- **Failure.** Any failure resolves the fallback palette (`initialPalette` → `fallbackPalette` → defaults). It never throws.
+
+## 7. Recipes and gotchas
+
+| I want to…                      | Do this                                                                |
+| :------------------------------ | :--------------------------------------------------------------------- |
+| Tint a page from its hero image | `usePage({ ambient: heroUrl })`                                        |
+| Tint only one section           | `useAmbientTheme({ image, scope: "#section", tintGlobals: false })`    |
+| Read the palette in JS          | `const { palette } = useAmbientTheme(image)` or `useAmbient().palette` |
+| Disable tint on one page        | `usePage({ ambient: false })`                                          |
+| Brand colours without images    | `useAmbientTheme({ colors: { primary: "#…" } })`                       |
+
+- The theme is global by default: two components calling `useAmbientTheme` without `scope` fight over `--primary`; the last effect wins.
+- Cross-origin images that block CORS **and** the proxy cannot be sampled; the fallback palette is used.
+- `useAmbient()` without arguments only _reads_ the shared palette; it does not apply anything.
+- Components should read the variables (`bg-primary`, `var(--black)`) rather than the palette object, so they follow transitions for free.
+
+## 8. File map
+
+| File           | Responsibility                                                                                                                                                                        |
+| :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `index.ts`     | Public barrel.                                                                                                                                                                        |
+| `types.ts`     | Palette, config, descriptor, target/source, page contracts.                                                                                                                           |
+| `constants.ts` | CSS variable names, defaults, extraction tuning, `ambientTheme`.                                                                                                                      |
+| `utils.ts`     | OKLCH conversion, canvas sampling, palette derivation, fetch/cache/extraction, target resolution, scoped CSS-variable application, `resolveAmbientVarMap`, `resolvePageAmbientTheme`. |
+| `context.tsx`  | `AmbientProvider` (shared palette store), `useAmbientColor`, `useAmbientTheme`, `useAmbient`.                                                                                         |
+| `module.tsx`   | `ambientModule`, `useAmbientPage` (applies the page theme), `defineAmbient`, kernel type augmentation.                                                                                |
+
+No `view.tsx` or `motion.ts`: the module renders nothing, and transitions are CSS classes from the theme ([README](./README.md#42-why-some-optional-slots-are-absent)).
+
+## 9. Dependencies
+
+- **Uses:** `@omerdlw/base-framework/kernel` (`defineModule`, `useModuleState`), `@omerdlw/base-framework/hooks` (`useRequiredContext`, `useStore`), `@omerdlw/base-framework/utils` (`createStore`, `shallowEqual`), `@omerdlw/base-framework/theme`; `src/app/api/ambient/proxy` and `@/infrastructure/security/url-safety` (server side).
+- **Peer:** `background` (poster fallback), read through `useModuleState("background", …, null)`, so it works when background is not installed.
+- **Used by:** `src/core/provider.tsx`, `usePage({ ambient })`, and features such as the account layout (`useAmbientTheme`).