@omerdlw/base-framework 1.0.6 → 2.0.1

package/docs/modules/ambient.md

@@ -1,30 +1,41 @@
 # 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.
+> **Read this first if you need to:** tint a page from an image (cover, avatar, album art), compute a palette on the server and hand it to the client, use more than one colour from an image (roles, tonal ramps, region glows, text colours), 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`                                                |
+|                    |                                                                                                   |
+| :----------------- | :------------------------------------------------------------------------------------------------ |
+| **Import**         | `import { useAmbientTheme, configureAmbient, … } from "@omerdlw/base-framework/modules/ambient"`  |
+| **Server entry**   | `import { extractAmbientPalette } from "@omerdlw/base-framework/ambient/server"` (Node; no React)  |
+| **Worker entry**   | `import { serveAmbientWorker } from "@omerdlw/base-framework/ambient/worker"`                     |
+| **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`                                                           |
+| **HTTP route**     | optional proxy, `/api/ambient/proxy?url=…` by default (`configureAmbient({ proxy })`)             |
+| **Tests**          | `tests/modules/ambient.test.ts`, `tests/modules/ambient-palette.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
+server (RSC)  image URL ─fetch─▶ sharp ─▶ 128px sample ─┐
+client        image URL ─fetch─▶ createImageBitmap ─────┤   (worker or main thread)
+                                                        ▼
+                    letterbox cut ─▶ OKLab k-means (coloured + grey apart) ─▶ clusters
+                                                        ▼
+        roles: dominant · vibrant · muted · accent   (each: colour, `on`, 11-tone ramp)
+        regions: top · bottom · left · right · center
+        shadow: the deep tone of the image's shadows
+                                                        ▼
+                         CSS variables on the target element ─▶ everything 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.
+Ambient is a **colour pipeline**, not a component: pick an image (or pass colors directly), and the `--ambient-*` variables change. The app maps its own tokens onto them, e.g. `:root { --primary: var(--ambient-vibrant, #101010); --black: var(--ambient-shadow, #0b0b0b) }`; Tailwind classes such as `bg-primary` and anything using `var(--black)` then follow automatically, and the fallbacks apply whenever no palette is set.
+
+A palette is plain JSON (~2.7 KB), so it can be computed once on the server, cached, and passed down as `initialPalette`. When its `source` is the same image URL, the client does not extract again. Client extraction is the fallback.
 
 ## 3. Quick start
 
@@ -42,24 +53,73 @@ useAmbientTheme({ image: backdropUrl || account?.avatarUrl || null });
 // 4. Explicit colors, scoped to one element
 const cardRef = useRef<HTMLDivElement>(null);
 useAmbientTheme({
-  colors: { primary: "#e5d3ff", black: "#140d1f" },
+  colors: { "--ambient-vibrant": "#e5d3ff", "--ambient-shadow": "#140d1f" },
   scope: cardRef,
 });
 ```
 
+### 3.1 Server palette → client (recommended)
+
+```tsx
+// app/movie/[id]/page.tsx (server component; `"use cache"` needs `cacheComponents: true`,
+// otherwise wrap the call in `unstable_cache`)
+import { cacheLife } from "next/cache";
+import { extractAmbientPalette } from "@omerdlw/base-framework/ambient/server";
+
+async function paletteOf(url: string) {
+  "use cache";
+  cacheLife("max");
+  return extractAmbientPalette(url, {
+    allow: (target) => target.hostname === "image.tmdb.org",
+  });
+}
+
+export default async function Page({ params }) {
+  const movie = await getMovie((await params).id);
+  const backdrop = `https://image.tmdb.org/t/p/w780${movie.backdrop_path}`;
+  const palette = await paletteOf(backdrop);
+  return <MovieChrome backdrop={backdrop} palette={palette} />;
+}
+
+// movie-chrome.tsx ("use client")
+useAmbientTheme({ image: backdrop, initialPalette: palette ?? undefined });
+// palette.source === backdrop → applied at once, no fetch, no flash.
+```
+
+Use the **same URL** on both sides (the palette is keyed by `source`). A palette for a different size of the same image works as `initialPalette` too, but the client then extracts its own.
+
+### 3.2 Worker (optional)
+
+```ts
+// app/ambient.worker.ts
+import { serveAmbientWorker } from "@omerdlw/base-framework/ambient/worker";
+serveAmbientWorker();
+
+// once, in a client module that runs at start-up
+configureAmbient({
+  worker: () =>
+    new Worker(new URL("./ambient.worker.ts", import.meta.url), { type: "module" }),
+});
+```
+
+The app builds the `Worker` itself because only its bundler can turn `new URL("./x.ts", import.meta.url)` into a worker chunk. Without a worker, decoding still happens off the main thread (`createImageBitmap`); only drawing a 128 px bitmap and the analysis (a few ms) run on it.
+
 ## 4. What gets written
 
-| Variable                       | Set when                                     | Value                                                        |
-| :----------------------------- | :------------------------------------------- | :----------------------------------------------------------- |
-| `--primary`                    | an `image` is given and extracted            | bright OKLCH colour; lightness 0.60–0.86 and chroma 0–0.24 follow the image (neutral images give a neutral, chroma 0)       |
-| `--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 OKLCH (lightness ≈ 0.15, chroma ≤ 0.055, tint scales with the image; 0 for neutral images) |
-| any variable named in `colors` | `colors` is set                              | the literal value                                            |
+Default names; see §5.2 to rename them or turn groups off. Nothing is written until a palette exists.
 
-`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.
+| Variable                                   | Value                                                                  |
+| :----------------------------------------- | :--------------------------------------------------------------------- |
+| `--ambient-shadow`                         | deep tone (L ≈ 0.16) of the shadows' hue, at the chroma sRGB allows there: navy, burgundy, forest… (chroma 0 for grey images) |
+| `--ambient-{role}`                         | the role's colour; roles: `dominant`, `vibrant`, `muted`, `accent`     |
+| `--ambient-on-{role}`                      | text colour on that role, ≥ 4.5:1 (WCAG 2) by default                  |
+| `--ambient-{role}-{tone}`                  | ramp tones `10 15 20 30 40 50 60 70 80 90 95` (= OKLCH L × 100)        |
+| `--ambient-{region}`                       | regions: `top`, `bottom`, `left`, `right`, `center`                     |
+| any variable named in `colors`             | the literal value                                                      |
 
-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).
+`colors` keys are custom property names: 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 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
 
@@ -68,14 +128,19 @@ On cleanup the previous inline values (and priorities) are restored exactly. If
 | `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.                                                                                                                                        |
+| `useAmbientColor(image, options?)`                                                               | hook      | Extract a palette **without** applying it. Uses `options.initialPalette` as is when its `source` is this image.                                                                   |
 | `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.                                                                                                                                                        |
+| `configureAmbient(settings)`                                                                     | config    | Proxy, CSS variable names, strategy, worker, analysis defaults (§5.2). Returns a function that restores the previous settings. `getAmbientSettings()` reads them.                 |
+| `extractPaletteFromImage(src, options?)`                                                         | util      | Async client extraction with cache and in-flight de-duplication; resolves `null` on any failure.                                                                                 |
+| `primeAmbientPalette(src, palette)`, `getCachedAmbientPalette(src)`                              | utils     | Seed / read the client cache (e.g. with server palettes).                                                                                                                         |
+| `analyzeAmbientPixels(pixels, options?)`                                                         | util      | The pure analysis on RGBA pixels (`{ data, width, height }`). Same function on server, worker and client.                                                                     |
+| `findContentBounds(pixels)`                                                                      | util      | The letterbox / pillarbox cut used by the analysis.                                                                                                                               |
+| `maxChroma(l, h)`, `toneOf(h, l, rel, cap?)`, `onColorFor(bg, min?)`, `contrastRatio(a, b)`, `formatOklch(lch)`, `srgbToOklab(r, g, b)` | utils | Gamut-aware OKLCH helpers. |
+| `paletteVarMap(palette, names?)`, `resolveAmbientVarMap(…)`, `resolveCssVarNames(overrides?)`    | utils     | The variable maps the hooks write.                                                                                                                                                |
 | `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`, …                                                             |
+| `AMBIENT_TONES`, `AMBIENT_ROLES`, `AMBIENT_REGIONS`, `DEFAULT_ANALYSIS`, `DEFAULT_CSS_VAR_NAMES`, `ambientTheme`, `AmbientContext` | constants | |
+| Types                                                                                            |           | `AmbientPalette`, `AmbientSwatch`, `AmbientRegionColor`, `AmbientConfig`, `AmbientSettings`, `AmbientAnalysisOptions`, `AmbientCssVarNames`, `AmbientStrategy`, …               |
 
 ### 5.1 `AmbientConfig`
 
@@ -83,72 +148,121 @@ On cleanup the previous inline values (and priorities) are restored exactly. If
 | :--------------- | :---------------------------------- | :---------------------------------------------------------------------------------------------- |
 | `image`          | `null`                              | URL string or `{ src }`.                                                                        |
 | `colors`         | `null`                              | Explicit variables (see §4). A config with only `colors` is active without extraction.          |
+| `cssVars`        | `null`                              | Per-theme override of the variable names (same shape as `configureAmbient({ cssVars })`).       |
 | `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.
+| `initialPalette` | `null`                              | Palette shown before extraction finishes (and if it fails); used as is (no extraction) when `source` equals `image`. |
+| `options`        | `null`                              | `{ initialPalette, strategy, proxy, analysis }` for this theme.                                 |
+
+Until a palette exists the shared state's `palette` is `null` and no variable is written, so the app's own CSS fallbacks apply.
+
+### 5.2 `configureAmbient(settings)`
+
+Settings live on `globalThis`, so every bundled copy of the module (one per package entry) shares them. Call it once at start-up, in a client module (and on the server too if you change `analysis`).
+
+| Setting      | Default                                   | Meaning |
+| :----------- | :---------------------------------------- | :------ |
+| `proxy`      | `"/api/ambient/proxy?url="`               | Tried last, only for cross-origin images whose direct request (and its one cache-bypassing retry) failed. A string is a prefix the encoded URL is appended to, or a template with `{url}`; a function returns the URL; `null` turns it off. |
+| `strategy`   | `"auto"`                                  | `"auto"`: the worker if one is configured, else the main thread. `"worker"`: worker only (no main-thread extraction). `"main"`: main thread only. `"none"`: never extract on the client (server palettes only). |
+| `worker`     | `null`                                    | `() => Worker` running `serveAmbientWorker()` (§3.2). If it fails to start or errors, extraction falls back to the main thread (except under `"worker"`). |
+| `cssVars`    | `--ambient-shadow`, `--ambient-{role}`, `--ambient-on-{role}`, `--ambient-{role}-{tone}`, `--ambient-{region}`, all 11 tones | Rename any variable; `null` turns that variable or group off; `tones: [10, 20, 90]` or `false` limits the ramp variables. |
+| `analysis`   | `DEFAULT_ANALYSIS`                        | `sampleSize` 128, `clusters` 7, `centerWeight` 0.5, `letterbox` true, `minHueDistance` 40, `minContrast` 4.5, `shadowLightness` 0.16. |
+| `cacheLimit` | `100`                                     | Client palettes kept (oldest evicted). |
+
+### 5.3 `AmbientPalette`
+
+```ts
+{
+  source?: string | null;                   // the image URL it was made from
+  neutral: boolean;                         // the image has (almost) no colour
+  shadow: string;                           // deep tone of the shadows (oklch())
+  roles: Record<"dominant" | "vibrant" | "muted" | "accent", {
+    color: string; on: string;              // oklch() strings
+    l: number; c: number; h: number;
+    population: number;                     // share of the image (centre-weighted)
+    fromImage: boolean;                     // false: derived (e.g. no second hue → accent = vibrant)
+    ramp: Record<10 | 15 | … | 95, string>;
+  }>;
+  regions: Record<"top" | "bottom" | "left" | "right" | "center", {
+    color: string; l: number; c: number; h: number;
+    strength: number;                       // 0 grey … 1 fully coloured
+  }>;
+}
+```
 
-### 5.2 `usePage({ ambient })` resolution
+### 5.4 Server entry: `@omerdlw/base-framework/ambient/server`
 
-`resolvePageAmbientTheme` runs with the page's `ambient`, the dock **banner**, and the background's `posterUrl`:
+| Export | Description |
+| :----- | :---------- |
+| `extractAmbientPalette(url, options?)` | Fetches and analyzes; returns the palette (with `source = url`) or `null`. In-process cache (500) and in-flight sharing; wrap it in `"use cache"` / `unstable_cache` to keep palettes across requests. |
+| `extractAmbientPaletteFromBytes(bytes, options?)` | Same, from bytes you already have. |
+| `sharpDecoder` | The default decoder: `sharp` (optional peer dependency, `^0.35.0`), loaded on first use with a bundler-ignored dynamic import; Next.js already installs it. |
+| `isPublicImageUrl(url)` | The default `allow`: http(s), no credentials, no localhost / `.local` / `.internal` / single-label names, no private, loopback, link-local, CGNAT or reserved IP literals in any spelling (`127.1`, `0x7f000001`, `[::ffff:127.0.0.1]`, …). `isPrivateAddress(ip)` and `isPrivateHostname(name)` are exported too. |
+| `AmbientDecoderMissingError` | Thrown (not swallowed) when `sharp` is missing and no `decode` was passed. |
+| `analyzeAmbientPixels`, `configureAmbient`, colour helpers, types | Re-exported. |
 
-| `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. |
+Options: `allow(url)` (checked on every redirect hop), `resolve` (see below), `decode(bytes, size)`, `fetch`, `init` (e.g. `{ next: { revalidate } }`), `maxBytes` (12 MB), `timeoutMs` (8 s), `cache` (true), `analysis`.
 
-`page.modules.ambient` is just `{ set(ambient) }`.
+Before every request, redirects included, the host is resolved (`resolve`, default `node:dns` lookup of all addresses) and the request is refused if **any** address is loopback, private, link-local, CGNAT, multicast or reserved, even when a custom `allow` let the URL through. `resolve: false` turns this off; only do that behind an `allow` list. The fetch itself resolves the name again, so a host that changes its answer in between (DNS rebinding) is only ruled out by an `allow` list of hosts you trust, e.g. `allow: (url) => url.hostname === "image.tmdb.org"`. Use one in production.
 
 ## 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 64×64 canvas. Pixels with alpha < 128 are skipped; near-black and near-white pixels (unreliable hue) are ignored, and pixels with chroma < 0.03 count as neutral. Remaining pixels vote into 36 hue bins with weight `chroma² × lightness-usability`, so vivid mid-tone pixels beat muddy or very dark/light ones. The best bin plus half-weighted neighbours gives hue, chroma and lightness (weighted). If coloured pixels are under 4% of the colourable ones, or there are none, the result is a **neutral** (`c 0`, lightness = image average); a small accent on a mostly neutral image is kept but subdued.
-- **Derivation.** A source chroma < `0.012` is treated as neutral (no hue is invented). Otherwise chroma is clamped to `≤ 0.28`. `primary` chroma is `0.24 × (1 − e^(−chroma × 9.4))` and lightness is `0.74 + (L − 0.6) × 0.5` clamped to `0.60–0.86`; `black` chroma is `min(0.055, chroma × 0.35)` and lightness is `0.15 + (L − 0.6) × 0.06` clamped to `0.12–0.18`.
-- **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.
+- **Loading (client).** The image URL is fetched as is with `mode: "cors"`: no `?cors=1`, so the request the page already made is answered from the HTTP cache. If that is blocked and the image is cross-origin, it is fetched once more with `cache: "reload"`: some CDNs (TMDB's among them) send CORS headers only to requests that carry an `Origin` and do not `Vary: Origin`, so the copy a plain `<img>` cached has none. Only then is the proxy tried. Give such images `crossOrigin="anonymous"` (`next/image` takes it too) and the one download serves both the `<img>` and the palette, with no blocked request in the console. Decoding uses `createImageBitmap` (asking for a 128 px wide bitmap where supported) and an `OffscreenCanvas` (or a `<canvas>`), so a full-size image is never drawn on the main thread; browsers without `createImageBitmap` fall back to an `<img>`.
+- **Sampling.** The image is scaled to 128 px on its long side, keeping its aspect ratio. Pixels with alpha < 128 are skipped. Uniformly near-black rows/columns at the edges (letterbox / pillarbox; mean L < 0.12, max L < 0.2, at most 22% per side) are cut. Each pixel's weight falls from 1.5 at the centre to 0.5 at the corners (`centerWeight` 0.5).
+- **Clustering.** Pixels are binned by 15-bit RGB (OKLab averaged per bin). Coloured bins (chroma ≥ 0.022) and grey bins are clustered **apart** with weighted, deterministically seeded k-means in OKLab (ΔL counts 0.45×, so hue beats lightness; vivid bins pull up to ~2.5× harder), 5 + 2 clusters by default. Splitting them keeps the greys of a dark poster from using up every cluster and swallowing its one coloured detail.
+- **Roles.** A hue's share is that of its family (clusters within 20°). `dominant` = max share × chroma; `vibrant` = max chroma² × share^0.3; `accent` = the best hue at least `minHueDistance` (40°) from `dominant`, or `vibrant` marked `fromImage: false` when the image has one hue; `muted` = the largest low-chroma (≤ 0.09) colour, or a quiet tone of the dominant hue. Hue trust fades below L 0.28 and above L 0.9.
+- **Tones.** Every role colour and ramp tone is `toneOf(h, L, rel)`: `rel` (the source colour's share of the available chroma, lifted per role) × the most chroma sRGB allows at that L and hue (`maxChroma`, a binary search on the gamut edge, × 0.96). So a dark tone of blue stays blue, and nothing is ever out of gamut.
+- **`shadow`.** The hue of the shadows (clusters at L ≤ 0.5, scored by share × relative chroma) or, without coloured shadows, of `dominant`; at L `shadowLightness` ± 0.02 and up to 0.1 chroma.
+- **`on`.** A near-white or near-black carrying a hint of the role's hue, pushed toward pure white / black until it reaches `minContrast`.
+- **Regions.** Each region (thirds of the content box; `center` is the middle half) takes its most chromatic-and-present cluster at L 0.42–0.72; `strength` is how coloured the region is.
+- **Neutral images.** If coloured pixels make up under 3% (weighted), the palette is grey: `neutral: true`, `dominant`, `vibrant`, `muted`, `shadow` and regions have chroma 0. A vivid detail (≥ 0.6% of the image, chroma ≥ 0.06) still becomes `accent`, e.g. the red coat in *Schindler's List*.
+- **Cost.** About 3–8 ms per image for the analysis (Node, warm); in Chromium, ~13 ms for a cached image end to end on the main thread, ~20 ms through the worker (off the main thread). ~2.7 KB of JSON per palette.
+- **Cache.** Client: `cacheLimit` palettes (oldest evicted), keyed by URL (+ analysis overrides); concurrent requests share one promise. Server: 500 per process.
+- **Stability.** `colors`, `cssVars`, `options` and `initialPalette` are stabilized with `shallowEqual`, so fresh object literals each render do **not** re-apply the theme (keep `cssVars.tones` a constant array). The same pixels always give the same palette.
+- **Failure.** Client: `extractPaletteFromImage` resolves `null` and the hooks keep `initialPalette` (or nothing); it never throws. Server: `null`, except a missing decoder.
 
 ## 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.
+| I want to…                           | Do this                                                                 |
+| :----------------------------------- | :---------------------------------------------------------------------- |
+| Tint a page from its hero image      | `usePage({ ambient: heroUrl })`                                         |
+| No flash, no client work             | Compute on the server (§3.1); add `configureAmbient({ strategy: "none" })` if every image has one |
+| Glows that follow the picture        | `radial-gradient(at 20% 0%, color-mix(in oklab, var(--ambient-top) 30%, transparent), transparent)` … |
+| Text on a role colour                | `background: var(--ambient-accent); color: var(--ambient-on-accent)`     |
+| A surface a few steps above the shadow | `var(--ambient-dominant-20)` / `-30`                                  |
+| Tint only one section                | `useAmbientTheme({ image, scope: "#section" })`                         |
+| Rename the variables                 | `configureAmbient({ cssVars: { shadow: "--bg", role: "--tint-{role}" } })` |
+| Fewer variables on `<html>`          | `configureAmbient({ cssVars: { tones: [20, 80], region: null } })`       |
+| Own proxy / no proxy                 | `configureAmbient({ proxy: "/img?u={url}" })` / `{ proxy: null }`        |
+| Disable tint on one page             | `usePage({ ambient: false })`                                           |
+
+- The theme is global by default: two components calling `useAmbientTheme` without `scope` fight over the `--ambient-*` variables; the last effect wins.
+- Cross-origin images that block CORS **and** the proxy cannot be sampled on the client; `initialPalette` (or the app's CSS fallbacks) stays. The server has no CORS limits.
 - `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.
+- Components should read the variables rather than the palette object, so they follow transitions for free.
 
 ## 8. File map
 
-| File           | Responsibility                                                                                      |
-| :------------- | :-------------------------------------------------------------------------------------------------- |
-| `index.ts`     | Public barrel export.                                                                               |
-| `types.ts`     | Palette, config, descriptor, target/source, page contracts.                                         |
-| `constants.ts` | Default palette constants and `ambientTheme` spec.                                                  |
-| `color.ts`     | Pure OKLCH color math, linear sRGB conversions, string formatting, and palette derivation.          |
-| `extractor.ts` | Canvas 2D pixel histogram sampling, CORS/proxy image fetch, and LRU palette cache.                   |
-| `dom.ts`       | Target element resolution, CSS variable mapping (`AMBIENT_CSS_VARS`), and scoped style restoration. |
-| `hooks.ts`     | React hooks: `useAmbientColor`, `useAmbientTheme`, `useAmbient`, `useStableObject`.                 |
-| `builder.ts`   | Reusable theme factory builder (`defineAmbient`).                                                   |
-| `context.tsx`  | Microkernel global `AmbientContext` and `AmbientProvider` store.                                    |
-| `module.tsx`   | `ambientModule` definition, `resolvePageAmbientTheme`, and 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)).
+| File                 | Responsibility                                                                                 |
+| :------------------- | :--------------------------------------------------------------------------------------------- |
+| `index.ts`           | Public barrel export (client entry).                                                           |
+| `types.ts`           | Palette, swatch, region, settings, config, descriptor, page contracts.                         |
+| `settings.ts`        | Defaults, `configureAmbient` (on `globalThis`), proxy resolution. Pure.                        |
+| `oklab.ts`           | OKLab/OKLCH math, gamut room (`maxChroma`), tones, WCAG contrast, `on` colours. Pure.          |
+| `quantize.ts`        | Deterministic weighted k-means. Pure.                                                          |
+| `analyze.ts`         | Letterbox cut, binning, clustering, roles, ramps, regions, `shadow`. Pure.                     |
+| `pipeline.ts`        | fetch → `createImageBitmap` → canvas pixels → analysis; runs in a window or a worker.          |
+| `extractor.ts`       | Client cache, strategy, worker dispatch with main-thread fallback.                             |
+| `worker/index.ts`    | `serveAmbientWorker` (the `ambient/worker` entry).                                             |
+| `server/index.ts`    | `extractAmbientPalette`, sharp decoder, URL guard, server cache (the `ambient/server` entry).   |
+| `dom.ts`             | Target resolution, CSS variable maps, scoped style restoration.                                |
+| `hooks.ts`           | `useAmbientColor`, `useAmbientTheme`, `useAmbient`, `useStableObject`.                         |
+| `context.tsx`        | `AmbientContext` and `AmbientProvider` store.                                                  |
+| `module.tsx`         | `ambientModule`, `resolvePageAmbientTheme`, `defineAmbient`, kernel type augmentation.         |
 
 ## 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).
+- **Uses:** `@omerdlw/base-framework/kernel` (`defineModule`, `useModuleState`), `@omerdlw/base-framework/hooks` (`useRequiredContext`, `useStore`), `@omerdlw/base-framework/utils` (`createStore`, `shallowEqual`), `@omerdlw/base-framework/theme`.
+- **Server entry:** `sharp` `^0.35.0`, an **optional peer dependency** (Next.js already installs it), loaded on first use with a bundler-ignored dynamic import. Apps that never call the server entry, or pass their own `decode`, do not need it.
 - **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`).
+- **Used by:** `usePage({ ambient })`, and features such as the account layout (`useAmbientTheme`).

package/docs/modules/background.md

@@ -71,7 +71,7 @@ usePage({
 | Edge fades                     | `fadeEdges` (`number`, `"20"`, `{ left, right }`, `false`), `leftGradient` / `rightGradient` (strength 1–n). A custom `width` implies a 20 % fade unless `fadeEdges: false`.                                                                  |
 | Film grain                     | `noiseStyle: { opacity, mixBlendMode }`.                                                                                                                                                                                                      |
 | Layout                         | `width` (number px or CSS length) places a video frame left/right/center via `position`; `fit` / `videoOptions.fit` (`cover contain fill none scale-down`); `bg-*` class tokens in `className`/`videoClassName` map to object-position slots. |
-| Custom transition              | `animation: { initial, animate, exit, transition, exitDurationFactor }` (defaults: opacity fade with `DURATION_TOKENS.SLOW`; exit factor 0.6).                                                                                                |
+| Custom transition              | `animation: { initial, animate, exit, transition, exitDurationFactor }`, field by field over the app's background motion (`motion: BackgroundMotion` in the theme; the starter fades opacity over 0.58 s, exit factor 0.6). It follows the app's tempo.|
 | Programmatic control           | `useBackgroundActions()` / `page.modules.background`.                                                                                                                                                                                         |
 | Dock media controls            | Automatic through the `media` module ([§8](#8-media-integration)).                                                                                                                                                                            |
 
@@ -155,7 +155,7 @@ return <MediaSource src="/audio/city.mp3" follow={BACKGROUND_MEDIA_ID} />;
 
 ## 9. Theming
 
-All classes come from `backgroundTheme` (`src/config/background.module.theme.ts`): layer slots (`root`, `image`, `solid`, `gradient`, `edge`, `noise`), direct video slots (`video`, `videoFrame`) and YouTube player slots (`youtube*`). Variants are `data-*` modifiers on the slot (`data-side`, `data-position`, `data-width`, `data-visible`). `fit` and `bg-*` tokens are translated to inline `object-fit` / `object-position` by the module, not by theme slots. Stays in code: compositor hints (`will-change`), mask/gradient math (`generateBaseGradient`, `generateEdgeGradient`, `getEdgeFadeMask`), and motion (defaults derive from `DURATION_TOKENS` / `EASING_CURVES`, [Rule 4](../architecture-and-rules.md)). The module deliberately has **no presets** (a test bans `BACKGROUND_PRESETS`): pass a URL or a state object, or build your own with `defineBackground`.
+All classes come from `backgroundTheme` (`src/config/background.module.theme.ts`): layer slots (`root`, `image`, `solid`, `gradient`, `edge`, `noise`), direct video slots (`video`, `videoFrame`) and YouTube player slots (`youtube*`). Variants are `data-*` modifiers on the slot (`data-side`, `data-position`, `data-width`, `data-visible`). `fit` and `bg-*` tokens are translated to inline `object-fit` / `object-position` by the module, not by theme slots. Motion is the app's: `motion: BackgroundMotion` in the theme ([theming §5](../theming.md#5-motion-your-app-owns-every-animation), starter in `templates/motion/background.ts`) gives the default `initial`, `animate`, `exit` and `transition`, plus `exitDurationFactor` for a page exit without its own transition. Stays in code: compositor hints (`will-change`) and mask/gradient math (`generateBaseGradient`, `generateEdgeGradient`, `getEdgeFadeMask`). The module deliberately has **no presets** (a test bans `BACKGROUND_PRESETS`): pass a URL or a state object, or build your own with `defineBackground`.
 
 ## 10. Recipes and gotchas
 
@@ -183,7 +183,7 @@ All classes come from `backgroundTheme` (`src/config/background.module.theme.ts`
 | `visual.ts`          | Gradient generation, smoothstep edge-fade masks, and video styling/fit options.                           |
 | `playback.ts`        | Direct HTML video DOM controls: play/pause, volume/mute, loop, and playbackRate sync.                     |
 | `overlay.tsx`        | `BackgroundOverlay`, `NativeVideo`, and backdrop overlay layers (solid, noise, gradients).                |
-| `motion.ts`          | Motion animations, transition presets, and CSS duration/easing helpers.                                  |
+| `motion.ts`          | `useBackgroundMotion`, how a page's `animation` merges over the app's motion, the exit fallback, and CSS duration/easing helpers.|
 | `context.tsx`        | `BackgroundProvider`: store, actions, `media` module bridge, and `useBackground*` hooks.                  |
 | `module.tsx`         | `backgroundModule` definition, `selectPageBackground`, `defineBackground`, and kernel type augmentation.  |
 | `youtube/parse.ts`   | YouTube URL/ID parsing, time params, stream/thumbnail URLs, and video element proxy.                      |

package/docs/modules/context-menu.md

@@ -208,7 +208,7 @@ Important: the global capture listener runs **before** React's element handler.
 
 ## 6. Theming
 
-No classes or colors in the module, except the pointer-following `left/top/position: fixed`. Slots in `contextMenuTheme`: `backdrop`, `menu`, `header`, `headerIcon`, `headerText`, `headerEyebrow`, `headerTitle`, `headerDescription`, `separator`, `item`, `itemIcon`, `itemLabel`, `itemShortcut`, plus optional per-slot `styles` (the starter theme sets the backdrop/menu z-index there). A config's `classNames` (and an item's `className`) are appended on top of the theme. Active items get `data-active="true"`, handy for theme selectors. Motion (`menuPopVariants`, `menuContentVariants`, `menuItemVariants`, tap/spring) lives in `motion.ts`.
+No classes or colors in the module, except the pointer-following `left/top/position: fixed`. Slots in `contextMenuTheme`: `backdrop`, `menu`, `header`, `headerIcon`, `headerText`, `headerEyebrow`, `headerTitle`, `headerDescription`, `separator`, `item`, `itemIcon`, `itemLabel`, `itemShortcut`, plus optional per-slot `styles` (the starter theme sets the backdrop/menu z-index there). A config's `classNames` (and an item's `className`) are appended on top of the theme. Active items get `data-active="true"`, handy for theme selectors. Motion comes from the theme too (`motion: ContextMenuMotion`, [theming §5](../theming.md#5-motion-your-app-owns-every-animation)): `pop` (the surface), `content` (the header), `item` (rows; `visible` may take the row index for a stagger), `itemTap` and `itemTransition`. Start from `templates/motion/context-menu.ts`.
 
 ## 7. Recipes and gotchas
 
@@ -238,7 +238,7 @@ No classes or colors in the module, except the pointer-following `left/top/posit
 | `resolver.ts`  | Candidate normalization, path/target/route scoring, context building, `resolveContextMenu`, `prepareMenu`.                 |
 | `context.tsx`  | `ContextMenuProvider` (store, `openMenu`, `closeMenu`, `bind`), `useContextMenu*` consumer hooks.                          |
 | `overlay.tsx`  | `ContextMenuGlobal`, portalled renderer, content host, header, item components, and interaction listeners.                |
-| `motion.ts`    | Pop, content and item animation variants; tap and spring presets.                                                          |
+| `motion.ts`    | `useContextMenuMotion`. The values come from the app's context-menu theme.                                                 |
 | `module.tsx`   | `contextMenuModule`, page API adapter, `defineContextMenu`, kernel type augmentation.                                     |
 
 ## 9. Dependencies

package/docs/modules/dock.md

@@ -220,7 +220,7 @@ Everything below is exported from `@omerdlw/base-framework/modules/dock`. Anythi
 | `DockCardHeader`, `DockCardBanner`, `DockIcon`, `DockTitle`, `DockDescription`              | The same pieces the route card uses.                                                                                                                                                                                                                                                                                      |
 | `useDockActionClass()`                                                                      | Returns `(options?) ⇒ className` for buttons that must look like dock actions (`variant`, `className`, `tone`). Needs the theme.                                                                                                                                                                                          |
 | `isValidBannerUrl(value)`                                                                   | Banner URL guard (rejects unsafe/empty values).                                                                                                                                                                                                                                                                           |
-| `DOCK_FADE_TRANSITION`, `dockFadeVariants`, `dockListItemVariants`, `textCrossfadeVariants` | The only motion presets surface content should use ([Rule 4](../architecture-and-rules.md)).                                                                                                                                                                                                                              |
+| `useDockMotion()`                                                                           | The app's dock motion (retimed by its tempo, or reduced), for surface content that should move like the dock: `useDockMotion().variants.fade`, `.transitions.text`, …                                                                                                                                                     |
 | `dockTheme`                                                                                 | The theme spec (for `defineTheme`).                                                                                                                                                                                                                                                                                       |
 | Types                                                                                       | `DockItem`, `DockPageConfig`, `DockPageApi`, `DockActions`, `DockState`, `DockActionDescriptor`, `SurfaceDescriptor` / `SurfaceEntry`, `SurfaceStep`, `SurfaceResult`, `SurfaceFlowDefinitionInput`, `DockHudDescriptor`, `DockOperation`, `DockGuardDefinition`, `BreadcrumbConfig`, … (`export type * from "./types"`). |
 
@@ -339,7 +339,7 @@ The dock itself closes surfaces with these reasons: `"dock"` (route change, prog
 
 Focus returns to the element that opened the surface after the last surface closes, except for `browser-back`, `dock`, `unmount`.
 
-Lifecycle phases (`DOCK_SURFACE_PHASE`): `idle → dismissing_action → expanding_body → open → closing_anticipation → collapsing_body → restoring_header → idle`. They drive animation and height locking and are exposed as `surfacePhase` in `DockState`.
+Lifecycle phases (`DOCK_SURFACE_PHASE`): `idle → dismissing_action → expanding_body → open → closing_anticipation → collapsing_body → restoring_header → idle`. They drive animation and are exposed as `surfacePhase` in `DockState`. In `dismissing_action`, `collapsing_body` and `restoring_header` the card faces the page: it shows the page's header and action (the surface item carries the page's action as `restingAction`) and keeps the page's measured height, so the card resizes once, straight between the page's size and the surface's. Set `timings.restoreHeader` to `0` to go from `collapsing_body` straight to `idle`.
 
 ### 8.5 Steps (wizards)
 
@@ -409,12 +409,13 @@ Imperative equivalents on `DockActions`: `openSurfaceFlow(def, input)`, `restore
 
 ```tsx
 function InviteForm({ close }) {
+  const dockMotion = useDockMotion();
   return (
     <>
       <DockSurfaceHeaderButton icon="solar:question-circle-bold" onClick={openHelp} />
       <DockSurfaceExtension id="invite-tabs" align="center"><Tabs … /></DockSurfaceExtension>
       <DockSurfaceAction><Button onClick={() => close({ success: true })}>Send</Button></DockSurfaceAction>
-      <motion.ul variants={dockFadeVariants} initial="hidden" animate="visible">…</motion.ul>
+      <motion.ul variants={dockMotion.variants.fade} initial="hidden" animate="visible">…</motion.ul>
     </>
   );
 }
@@ -663,7 +664,9 @@ Reserve space with `useDockHeight().padding` or `padding-bottom: var(--dock-h)`.
 
 The module contains **no design classes**. Every slot comes from `dockTheme` (`src/config/dock.module.theme.ts`, 101 slots, named after the component that renders them): `stack`, `backdrop`, `card*`, `banner*`, `header*`, `title*`, `description*`, `icon*` (incl. `iconBadge`, `iconOverlay*`), `command*`, `status*`, `surface*`, `control*` (incl. `controlHeaderButton`), `extension*`, `scrubber*`, `media*`, `breadcrumbs*`, `loading*`, `action*`. State variants are `data-*` modifiers on the slot itself (`data-placement`, `data-blur`, `data-shelf`, `data-anchored`, `data-ghost`, `data-fill`, `data-active`, `data-banner`, `data-multiline`, `data-interactive`, `data-text`); the header of `src/config/dock.module.theme.ts` lists them. `styles` can add inline CSS per slot (z-index, banner masks, stack size/radius).
 
-Stays in code: stack motion (offsets, scale, opacity), measured geometry, per-position z-index (`Z_INDEX.DOCK_CARD_STACK_BASE − position`), compositor hints, the skeleton pulse class. All motion presets derive from `@omerdlw/base-framework/tokens` ([Rule 4](../architecture-and-rules.md)). The theme is **required**: a missing theme throws `Theme "dock" is missing…`.
+The theme also carries the dock's **motion** (`motion: DockMotion`, [theming §5](../theming.md#5-motion-your-app-owns-every-animation)): every transition and variant, the deck's elevation, compression, peek and card exit, the swipe-to-dismiss feel, the skeleton class, and `timings`, which hold how long each surface phase lasts (`dismissAction`, `anticipation`, `expandBody`, `collapseBody`, `restoreHeader`) plus the card staggers, in seconds. The surface state machine schedules its phases from those timings, so they follow the app's tempo with everything else. Start from `templates/motion/dock.ts`, the dock's original motion.
+
+Stays in code: measured geometry and stack layout (card offsets and scales per position, the breadcrumb lift), per-position z-index (`Z_INDEX.DOCK_CARD_STACK_BASE − position`), compositor hints, swipe thresholds, and which of the app's transitions each state uses. The theme and its motion are **required**: a missing theme throws `Theme "dock" is missing…` and a theme without motion throws `Motion for theme "dock" is missing…`. `DockProvider` on its own (no dock theme) still runs; its surface phases advance immediately.
 
 Per-card overrides use `style` on the card (see [§6.1](#61-dockpageconfig-the-dock-key-of-usepage)). Custom buttons inside surfaces should use `useDockActionClass()` so they match.
 
@@ -687,7 +690,7 @@ Gotchas:
 - A flow `snapshot` must be a plain object; anything else becomes `null`.
 - Status events are global: remember to emit `DOCK_STATUS_CLEAR` for sticky (`duration: 0`) statuses.
 - Guards registered by an unmounted page disappear with it; `clearDockGuards()` drops every guard, including other pages'.
-- No arbitrary durations or `z-*` classes in surface content: use the exported motion presets and `Z_INDEX` ([Rules 4 and 5](../architecture-and-rules.md)).
+- No arbitrary durations or `z-*` classes in surface content: use your app's motion (`useDockMotion()`, or your own tokens) and `Z_INDEX` ([Rules 4 and 5](../architecture-and-rules.md)).
 
 ## 19. File map
 
@@ -711,7 +714,7 @@ Gotchas:
 | `overlay.tsx`             | `Dock` and every rendered piece: cards, header, banner, command bar, surface shell/controls/extensions, HUD view, media controls and scrubber, breadcrumbs card, `ErrorActions`, `GuardActions`.                          |
 | `cards.tsx`               | View models for the card components (banner, header, command bar, item, media controls/scrubber), `applyMediaAction`, action-slot resolution.                                                                             |
 | `hud.ts`                  | HUD descriptors, registry hook, `defineHud`, `useHud`, `useDockHud`, HUD lifecycle and view model, operation HUD.                                                                                                         |
-| `motion.ts`               | Dock durations, springs, transitions, variants and factories, all derived from `@omerdlw/base-framework/tokens`.                                                                                                                           |
+| `motion.ts`               | `useDockMotion`, `useDockSurfaceTimings`, and helpers that pick from the app's dock motion by state (stack, cards, media, backdrop). No motion values.                                                                                     |
 | `runtime/dock.tsx`        | `useDock` (view controller), `useDockModel`, layout ordering, expansion, operation state, route bridge.                                                                                                                   |
 | `runtime/display.ts`      | Item pipeline: registry entries → filtered items → active item (applies surface / status / media).                                                                                                                        |
 | `runtime/pipeline.ts`     | Item identity, active item detection, ancestor deduplication, loading item cleanup, and stacking reorder.                                                                                                                |

package/docs/modules/modal.md

@@ -191,7 +191,7 @@ No classes or colors in the module except the two z-indexes. Slots in `modalThem
 
 `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)).
+Motion comes from the theme too (`motion: ModalMotion`, [theming §5](../theming.md#5-motion-your-app-owns-every-animation)): the `backdrop`, and the `content`, `header` and `footer` rows of a `ModalContainer`, plus `positions`, the dialog's variants per position (`center`, `top`, `right`, `bottom`, `left`) with an optional own `transition` (the starter gives `center` a spring). A theme without motion throws `Motion for theme "modal" is missing…`. Start from `templates/motion/modal.ts`. Use `Z_INDEX` for anything layered above or below a modal ([Rule 5](../architecture-and-rules.md)).
 
 ## 8. Recipes and gotchas
 
@@ -223,7 +223,7 @@ Motion (`motion.ts`: backdrop, per-position panel variants/transitions, header/b
 | `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.                                                                                   |
+| `motion.ts`    | `useModalMotion`, `getModalPositionMotion`, compositor hints. The values come from the app's modal theme.                             |
 | `module.tsx`   | `modalModule`, lazy renderer, page API, `defineModal`, kernel type augmentation.                                                      |
 
 ## 10. Dependencies

package/docs/modules/notification.md

@@ -116,7 +116,7 @@ String messages are trimmed and **trailing periods/whitespace are removed** (`"S
 
 ## 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`.
+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. The toast's motion comes from the theme as well (`motion: NotificationMotion`, [theming §5](../theming.md#5-motion-your-app-owns-every-animation)): `toast` variants (`hidden` → `visible` → `exit`) and its `transition`. Start from `templates/motion/notification.ts`.
 
 ## 8. Writing toast copy
 
@@ -150,7 +150,7 @@ No classes or inline styles in the module. `notificationTheme` slots: `layer`, `
 | `context.tsx`  | `NotificationProvider` (store, timers, show/dismiss actions), `NotificationContext`.         |
 | `hooks.ts`     | Public hooks (`useToast`, `useNotification*`), `NotificationListener`, container view model. |
 | `overlay.tsx`  | `Toast`, `NotificationContainer` (dock/floating portal), `NotificationLayer`.               |
-| `motion.ts`    | Toast variants and transition.                                                              |
+| `motion.ts`    | `useNotificationMotion`, compositor hints. The values come from the app's notification theme.|
 | `module.tsx`   | `notificationModule` and the page API.                                                      |
 
 `builder.ts` is absent: toasts are imperative ([README](./README.md#42-why-some-optional-slots-are-absent)).