@owlmeans/web-panel 0.1.18-rc.78 → 0.1.18-rc.79

package/agent-meta/skills/web-panel/SKILL.md

@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/web-panel
 
 **Layer:** Web (React)
-**Install:** `"@owlmeans/web-panel": "^0.1.18-rc.78"` in `dependencies`
+**Install:** `"@owlmeans/web-panel": "^0.1.18-rc.79"` in `dependencies`
 
 ## Choosing a component
 
@@ -17,9 +17,9 @@ root unless the import column names a subpath.
 
 | Job | Use | Import | Correct one-liner |
 |---|---|---|---|
-| The app's context | `makeContext` | root | `const context = makeContext<C, T>(cfg)` in `context.ts`, then `append*(context)` mixins |
+| The app's context — the base web context factory (shadcn/Radix + default OwlMeans router) | `makeContext` | root | `const context = makeContext<C, T>(cfg)` in `context.ts`, then `append*(context)` mixins |
 | Mount the app | `render` (or `PanelApp` for a host that mounts itself) | root | `render(context)` |
-| The application shell | `NavLayout` | root | `<NavLayout nav={navConfig} title="App" mobileMenu themeToggle>{children}</NavLayout>` |
+| The application shell — header, section menu, screen menu, content, footer | `NavLayout` | root | `<NavLayout nav={navConfig} title="App" mobileMenu themeToggle>{children}</NavLayout>` |
 | One piece of the shell | `TopNav` / `SideNav` / `MobileNav` / `Footer` / `ShellCredit` | root | `<Footer links={footerLinks} />` |
 | Toasts | `Toaster` + `toast` from `sonner` | root | `<Toaster />` once, in the layout; `toast.success('Saved')` where the action ends |
 | Light / dark switch | `ThemeToggle` / `useColorScheme`; head script from `./scheme` | root, `./scheme` | `<NavLayout themeToggle … />` |
@@ -59,23 +59,18 @@ root unless the import column names a subpath.
 
 ## Key Exports
 
+Rows the chooser above already covers (`makeContext`, the shell pieces, `Toaster`, `Link`) are not
+repeated here, and the rows of `ThemeToggle`, `SocketReloadDialog`, `LoginScreen` and the
+`Form` family live in their parts.
+
 | Export | Description |
 |--------|-------------|
-| `makeContext<C, T>(cfg)` | Base web context factory (shadcn/Radix + default OwlMeans router) |
-| `NavLayout` | The application shell — header, section menu, screen menu, content, footer |
-| `TopNav` / `SideNav` / `MobileNav` / `Footer` | The shell's pieces, mountable on their own |
-| `Toaster` | The application's toast surface — mounted once, in the layout |
-| `ThemeToggle` / `useColorScheme` | The light/dark switcher (`ThemeToggleProps`, `ThemeToggleLabels`) and the hook behind it (`ColorSchemeModel`) — see *Light and dark* below |
-| `SocketReloadDialog` | The global "connection lost — try again / reload" prompt (opt in via `cfg.socket.reloadDialog`) `PanelApp` mounts automatically — see below. The hooks it reads, `useSocketStatus` and `useSocketRetry`, are imported from `@owlmeans/client-socket`, not from this package |
-| `Link` | An `<a>` addressing an entrypoint alias (or a literal `src`), with the label taken from i18n |
-| `LoginProviderNote` | The provider disclosure (`LoginProviderNoteProps`) — see *The provider disclosure* below |
-| `LoginScreen` / `LocalizedLoginScreen` / `appendLoginScreen` | The identity-provider choice screen — see `login-methods`. `LoginScreen` is pure w.r.t. `locale` too, exactly like `translate`: it is a prop, defaulting to nothing, never an implicit `useLanguage()` read, because a component that reaches for i18n context directly crashes an app mounted without one. `LocalizedLoginScreen` supplies `useLanguage()`'s value when the caller does not pass its own |
+| `LoginProviderNote` | The provider disclosure (`LoginProviderNoteProps`) — see [parts/sign-in.md](parts/sign-in.md) |
 | `render(context, opts?)` | Mounts the tree inside `PanelApp`, with the browser language detector installed on the i18n instance. `opts` is `RenderOptions` plus `rootClassName` |
 | `PanelApp` | That wrapper on its own — the themed root `div` plus the i18n provider — for a host that mounts the tree itself |
 | `useContext<C, T>()` | The current context, from React. `AppContext` adds `context.flow()` over `@owlmeans/web-client`'s |
 | `entrypoints` | The base declaration list — `@owlmeans/web-client`'s plus `@owlmeans/api-config-client`'s. Compose the app's own over it |
 | `Block` / `Text` / `Status` | The shadcn `Card` panel with an optional `Actions` footer, a heading/paragraph whose copy comes from the panel namespace, and the shadcn `Alert` resolving a `ResilientError` to a translated message |
-| `Form` / `TextInput` / `Button` / `SubmitButton` / `ButtonSelector` | The web form family. `Form` builds its own `useForm` + `ajvResolver` and borrows only `FormContext` and `schemaToFormDefault` from `@owlmeans/client-panel`; `TextInput` drives `react-hook-form`'s `Controller` directly, and the buttons call `handleSubmit` directly — none of them wraps `ClientForm`, `InputCtrl` or `ActionCtrl` |
 | `ImageUploader` / `Layout` | The uploader in a drop target with a preview, and a plain content wrapper (the shell is `NavLayout`) |
 | `scalingToStyles(h, v)` | `BlockScaling` → the width/height utility classes the panels share |
 | `useBreakPoint()` | The current Tailwind breakpoint name, tracked on `resize` (`lg` when there is no `window`) |
@@ -90,19 +85,12 @@ root unless the import column names a subpath.
 - `./auth/entrypoints` — auth panel entrypoint declarations
 - `./consent` — the cookie consent dialog and policy, bound to this app's i18n, plus a menu-row
   widget and a presence service so a host's own collapsed menu can take over the floating button's
-  job
-- `./scheme` — the React-free colour-scheme half: `COLOR_SCHEME_KEY`, `COLOR_SCHEME_EVENT`,
-  `ColorSchemeChoice`, `colorSchemeHelper` (`readColorScheme`, `applyColorScheme`, `colorSchemeBootstrapScript`) — safe
-  to import from a Node build script
-- `./picker` — the standard icon + colour picker and its parts (`IconColorPicker`, `ColorPicker`,
-  `IconPicker`, `ColorSwatches`, `IconGrid`, `IconTile`, `ColorDot`, `usePickerTranslate`), the icon
-  components (`PICKER_ICONS`, `pickerIconHelper`) and everything of `./picker/vocabulary` — see
-  *Subpath: `./picker`* below. Not re-exported by the root, so only a bundle importing it carries
-  the icon catalogue
-- `./picker/vocabulary` — the React-free half: the 24-colour palette (`PICKER_COLORS`,
-  `PICKER_COLOR_KEYS`), the icon catalogue's names, categories and search words
-  (`PICKER_ICON_ENTRIES`, `PICKER_ICON_NAMES`, `PICKER_ICON_CATEGORIES`), the fallbacks and
-  `pickerColorHelper` — safe on a server, in a seed or a Node build script
+  job — see [parts/consent.md](parts/consent.md)
+- `./scheme` — the React-free colour-scheme half, safe to import from a Node build script — see
+  [parts/theme.md](parts/theme.md)
+- `./picker` — the standard icon + colour picker and its parts, not re-exported by the root; and
+  `./picker/vocabulary`, its React-free half (palette, icon names, `pickerColorHelper`), safe on a
+  server, in a seed or a Node build script — see [parts/picker.md](parts/picker.md)
 
 ## Usage
 
@@ -125,305 +113,6 @@ layer below it, applies idempotent `append*(context)` mixins, and returns that s
 whole shape of the file above. Nothing is stored for re-creation, and every service, resource and
 entrypoint binds to exactly the one context it was appended to.
 
-### Navigation — `NavLayout`
-
-`NavLayout` is the application shell. A layout entrypoint binds a component that renders it and
-nothing else; the matched screen arrives as `children`. Keep the navigation as data in its own
-module (`src/nav.ts`) so screens, entrypoints and the shell all read the same aliases.
-
-```tsx
-import { NavLayout, HOME } from '@owlmeans/web-panel'
-import type { PanelNavConfig, PanelNavLink } from '@owlmeans/web-panel'
-
-export const navConfig: PanelNavConfig = {
-  sections: [
-    { name: 'home', label: 'Home', items: [{ alias: HOME, label: 'Overview' }] },
-    {
-      name: 'demo', label: 'Demo', items: [
-        { alias: web.session, label: 'Session' },
-        { alias: web.about, label: 'About' },
-      ]
-    },
-  ],
-}
-
-export const footerLinks: PanelNavLink[] = [
-  { alias: HOME, label: 'My App' },
-  { href: 'https://owlmeans.com', label: 'OwlMeans', open: true },
-]
-
-export const MainLayout: FC<PropsWithChildren> = ({ children }) =>
-  <NavLayout nav={navConfig} title="My App" footer={footerLinks}>{children}</NavLayout>
-```
-
-**Navigation is two-layer.** The top menu lists **sections** — the first level; the side menu lists
-the **active section's screens** — the second. A section holding a single screen renders **no side
-menu at all**: the model owns that rule (`showSide`), so a section that later grows a second screen
-gains its menu with no layout change. `NavLayout` mounts `SideNav` twice — `variant="side"` as the
-`hidden md:block` column beside the content, `variant="bar"` as the `md:hidden` strip under the
-header. Both render the same items; only one is visible at a time.
-
-| Component | Props |
-|---|---|
-| `NavLayout` | `nav: PanelNavConfig`, `translate?`, `title?: ReactNode`, `home?: string` (brand target — defaults to the first section's first item), `actions?: ReactNode`, `mobileMenu?: boolean`, `skipLinkLabel?: string \| false`, `themeToggle?: boolean \| { labels? }`, `footer?: PanelNavLink[] \| ReactNode`, `headerClassName?`, `contentClassName?`, `containerClassName?`, `className?`, `style?` |
-| `TopNav` | `config: PanelNavConfig`, `translate?`, `ariaLabel?`, `className?`, `style?` |
-| `SideNav` | the same, plus `variant?: 'side' \| 'bar'` |
-| `MobileNav` | the same as `TopNav`; `ariaLabel` names the landmark inside the sheet, `className`/`style` land on the trigger button |
-| `Footer` | `links?: PanelNavLink[]`, `content?: ReactNode` (a full-width block — see below), `translate?`, `containerClassName?` (the shell's rhythm, so the footer row lines up with the header and content), `children?` (joins the centred link row), `themeToggle?: boolean \| { labels? }` (the switcher beside the credit), `className?`, `style?` |
-| `ShellCredit` / `useShellCredit` | `className?`; the platform/owner credit line `Footer` always renders — see below |
-
-**The narrow-viewport menu is opt-in: `mobileMenu`.** Off (the default) the shell is exactly the
-two-layer layout above at every width. On, below `md` (768px) the section menu is hidden
-(`hidden md:flex`) and `MobileNav` puts a menu button — accessible name "Menu", a 44px target, a
-solid focus ring — at the end of the actions row, so `actions` ("Get started", sign-in) stay in
-the header at every width. The button opens a shadcn `Sheet` from the right listing every section:
-a multi-screen section as its name over links to its screens, a single-screen section as one link
-carrying the section's own label, so no destination appears twice. Labels, keys and `translate`
-are the menus' own (`nav.<section>`, `modules.<alias>`); the button's name, the sheet title and
-its close button resolve `shell.menu` / `shell.close` — outside the `nav.` family, because an
-app may have a section called `menu`. Rules the component owns:
-
-- **The screen strip is not mounted when `mobileMenu` is on.** The sheet already lists the active
-  section's screens; a strip under the header would be a second menu for the same level. The side
-  column (`hidden md:block`) is untouched — wide viewports are the same shell either way.
-- **An entry navigates AND closes from its own click handler.** It is an `<a href>` (focusable,
-  openable in a new tab) whose `onClick` calls `preventDefault()` for in-app navigation — which a
-  dialog never notices, so a sheet left to close itself stays open over the screen it just
-  navigated to.
-- **The sheet states both halves of its surface** (`bg-background text-foreground`): it is
-  portalled to the document body and inherits nothing from the shell.
-- Pinned by `nav.spec.ts` → "the narrow-viewport menu", at 375px and 1280px, with and without
-  the prop (`?mobileMenu=1` in the harness).
-
-**The skip link comes first, and `main` is its target.** `NavLayout` renders
-`<a href="#main" data-skip-link>` as the FIRST child of its root — before `<header>`, never inside
-it, because `header > div` (first) is the shared-rhythm row the layout pins locate. It is `sr-only`
-until focused, then a pill fixed in the top-left corner (`bg-foreground text-background`,
-`rounded-full`, `z-50`, the 3px `--ring` focus ring); its padding is `focus:`-only, since a plain
-`px-*` sorts after `sr-only` and leaves a padded box behind the clip. Activating it focuses
-`<main id="main" tabIndex={-1}>` by hand (`preventDefault` + `focus()`), because a fragment
-navigation changes the location and the router reads that as navigation. The label is
-`skipLinkLabel`, defaulting to `translate('shell.skip', 'Skip to content')`. `skipLinkLabel={false}`
-renders no link AND leaves `main` without the id: an application rendering its own skip link owns
-its own `#main`, and no two elements may share it. A screen never renders a second `<main>`.
-Pinned by `nav.spec.ts` → "the skip link" (Tab from the page start, Enter lands on `main#main`,
-`?skip=off`).
-
-**A node `footer` is a full-width block, never a replacement.** An array renders the centred link
-row. A node — an application's own footer layout: a brand, a description, link columns — goes to
-`Footer`'s `content` and renders as a `w-full self-stretch text-start` block (`data-footer-content`)
-inside the footer's container, above the credit. The container keeps `items-center` for the link
-row and the credit; only the block stretches. It used to land INSIDE the centred link row, where
-it shrink-wrapped to its content in the middle of the page. `ShellCredit` stays the last thing the
-footer renders in every case — the container's own last child, or, with `themeToggle`, first in the
-bottom row `[data-footer-bottom]` with the switcher after it. Pinned by `nav.spec.ts` → "a node footer" (`?footer=node`).
-
-**The style slots are REGIONS, and each region is its own SURFACE.** `className` is the root —
-the full-height page *behind* the header, side menu and footer. `headerClassName` is the sticky
-top bar. `contentClassName` is the content area. `containerClassName` is width and padding for
-all three at once, never colour.
-
-The header paints an opaque background of its own, because it is sticky and content scrolls
-beneath it. That makes it a **different surface from the root**, so it states `text-foreground`
-alongside its `bg-background` — not as decoration, and not redundantly. A root carrying a
-contrasting pair (`className="bg-primary text-primary-foreground"`, an ordinary dark shell)
-otherwise inherits its near-white foreground into a near-white bar, and every header child that
-states no colour of its own — the brand, a ghost-variant action button — is painted in the
-foreground of a surface it is not on. It type-checks, it builds, it renders, and the menu is
-invisible. Pinned by `tests/nav.spec.ts` → "the header is its own surface", which measures
-rendered lightness rather than class names; the harness root carries a dark shell permanently so
-every navigation test runs against that case.
-
-**The header is opaque even when `headerClassName` fails to be.** Behind the header's own visible
-content sits a `[data-nav-backdrop]` layer that always paints `bg-background`, at negative
-z-index inside the header's own `isolate` stacking context — so it never covers a caller's actual
-header content, only whatever the header's own background would have been. It exists because
-`headerClassName` is free text a design or restyle pass writes, and three shapes of it leave
-tailwind-merge with no background utility at all on the header: a bare `bg-transparent`, an alpha
-surface (`bg-<x>/50`), or Tailwind v3's dead syntax for referencing a CSS variable
-(`bg-[--my-var]` — square brackets; v4's real shorthand is `bg-(--my-var)`, parentheses). Any of
-those used to leave the sticky header fully see-through, with page content visibly scrolling
-through the menu. A caller that genuinely wants a coloured bar still gets it: `headerClassName`'s
-own background renders on top of the backdrop. Pinned by `nav.spec.ts` → "a broken headerClassName
-still leaves the backdrop layer opaque".
-
-**`Footer` always renders the platform/owner credit line, and there is no prop that hides it.**
-Below the content block and the links (or on its own, when a layout passes no `footer` at all — `NavLayout` renders
-`<Footer>` unconditionally now), `ShellCredit` shows "Powered by OwlMeans" and the owner's own
-copyright notice, resolved from `security.auth.login.credit` via `resolveCredit`
-(`@owlmeans/client-auth/login`) — the SAME resolver and the SAME config the sign-in screen's
-`LoginCredit` reads, so an owner who pays to drop the platform credit (`poweredBy: false`) drops
-it everywhere, not only on a screen a signed-in visitor may never see again. Order is the opposite
-of the sign-in screen's: the owner's own notice leads, the platform credit follows — a footer is
-read as "whose page is this, and who built it". The links row and the credit are both centred
-(`justify-center`), not left-aligned. `useShellCredit()` is exported separately so a caller that
-needs to know whether there is anything to show (without rendering it) can ask, exactly how
-`Footer` itself decides whether to render `null`. Pinned by `nav.spec.ts` → "the shell footer
-credit".
-
-**Every style slot is MERGED over its default — none of them substitutes.** `className`,
-`headerClassName`, `contentClassName` and `containerClassName` all go through `cn`, so a caller
-names only the utility it wants to move and tailwind-merge drops just the one it conflicts with.
-This matters most for `containerClassName`, whose default is a four-part rhythm
-(`mx-auto w-full max-w-6xl px-4`): a design asking for a wider page writes `max-w-[1280px]` and
-means *wider*, not *unpadded and uncentred*. Substituting there took `px-4` and `mx-auto` down
-with the width and left the header, content and footer all flush to the window edge. Pinned by
-`nav.spec.ts` → "a width-only rhythm override keeps the side padding"; the harness passes a
-width-only override permanently.
-
-**A dark top bar is asked for with `headerClassName`**, giving it both halves
-(`bg-secondary text-secondary-foreground`) — never by colouring the root and expecting the bar
-to follow.
-
-**The shell reads exactly these colour variables**: `--background` (page and top bar),
-`--foreground` (active section link), `--muted-foreground` (resting section links),
-`--accent`/`--accent-foreground` (active side-menu item), `--border` (the header, side-menu and
-footer rules) and `--primary` — the footer renders its entries through `Link`, which paints
-`text-primary`; `mobileMenu` adds `--ring` (the menu button's and the sheet entries' focus rings)
-and a `bg-black/50` overlay. It reads **no `--sidebar*` variable at all**. So `--muted-foreground` is not merely
-the text colour of the `--muted` surface — it is secondary text sitting directly on `--background`,
-and a theme that lightens it to suit a dark muted panel loses its top menu.
-
-Rules that make the shell behave:
-
-- **Labels never reach for i18n implicitly.** `translate` is a **prop** (`NavTranslate`), defaulting
-  to `defaultNavTranslate`, which returns the fallback. An app mounted with `renderApp` from
-  `@owlmeans/web-client` has no i18n provider, and the panel i18n hook dereferences `i18n.options`
-  on the empty object `react-i18next` returns without an instance — a throw inside render that
-  blanks the whole app. An app that does have i18n passes its own
-  `(key, defaultValue) => string` resolver. Order: literal `label` → `translate(key, humanized)` →
-  humanized alias. Default keys are
-  `nav.<section>` for sections and `modules.<alias>` for items and footer links — the same family
-  `Link` uses.
-- **Menu entries are real links.** `TopNav` puts the resolved path on `href` and calls
-  `preventDefault()` in `onClick`, navigating in-app through `nav.press`. Never drop the `href`: an
-  `<a>` without one is not focusable, does not answer the keyboard, cannot be opened in a new tab,
-  and does not even carry the `link` role.
-- **A parent route needs a `default: true` child.** A frontend entrypoint that has children but no
-  child declared `default: true` renders blank at its own path — give a grouping screen an index
-  child at `'/'`.
-- **Vendor `navigation-menu` and `sheet`.** `SideNav` builds on the package-local `Button`; `TopNav`
-  uses the package-local shadcn `navigation-menu` primitive and `MobileNav` the package-local
-  `sheet` (over `@radix-ui/react-dialog`, a peer) — see the package-boundary rule below.
-
-### Light and dark — `ThemeToggle`, `useColorScheme`, `./scheme`
-
-The standard switcher, with no theme library behind it. `NavLayout themeToggle` (or `Footer
-themeToggle`) puts it in the footer's bottom row beside the credit, whatever `footer` is; absent or
-`false`, the footer's DOM is what it is without one. It is also mountable on its own.
-
-**The contract is two classes on `<html>`.** `dark` = the visitor chose dark, `light` = chose light,
-neither = follow the operating system. The choice is stored under `COLOR_SCHEME_KEY`
-(`owlmeans:color-scheme`, `localStorage`, every access in `try`). `light` exists as a class of its
-own because a visitor choosing light on a dark system has no other way to say so to a stylesheet
-that paints dark under `prefers-color-scheme: dark`. So a consumer's CSS must read BOTH:
-
-```css
-:root { color-scheme: light; /* light tokens */ }
-.dark { color-scheme: dark; /* dark tokens */ }
-@media (prefers-color-scheme: dark) {
-  :root:not(.light) { color-scheme: dark; /* the same dark tokens */ }
-}
-/* Tailwind v4: a `dark:` variant that follows the same rule */
-@custom-variant dark {
-  &:where(.dark, .dark *) { @slot; }
-  @media (prefers-color-scheme: dark) { &:where(:root:not(.light), :root:not(.light) *) { @slot; } }
-}
-```
-
-A theme with dark tokens under `.dark` alone never follows the OS; one with them under the media
-query alone ignores an explicit light choice.
-
-**The head bootstrap goes before any stylesheet paints.** `colorSchemeHelper.colorSchemeBootstrapScript()` returns a
-self-contained inline script that puts the stored choice's class on `<html>` before first paint —
-the only moment it can; a component doing it after mount shows a visitor who chose dark one frame
-of the light page. A build step inlines it into `index.html` (import it from
-`@owlmeans/web-panel/scheme` — that module imports nothing, React included) and a CSP that hashes
-inline scripts must hash it. Without the bootstrap, `useColorScheme` re-applies the stored class on
-mount: correct, one frame late.
-
-Rules the pieces own:
-
-- **The toggle flips the RESOLVED scheme** (`choice ?? system`), never the stored choice alone: on
-  a dark system with nothing stored the first press means light. The icon is the scheme the page
-  is in (sun while light, moon while dark), chosen in script, not by a `dark:` variant.
-- **The accessible name says what pressing does** — `labels.toLight` / `labels.toDark`, English
-  defaults; `NavLayout` resolves them through `translate` (`shell.toLight`, `shell.toDark`).
-- **One choice per document.** `colorSchemeHelper.applyColorScheme(choice | null)` sets the class, stores or clears
-  the key and dispatches `COLOR_SCHEME_EVENT`, so every mounted `useColorScheme` agrees at once;
-  another tab's change arrives through `storage`, and an OS switch through `matchMedia` while
-  nothing is stored. `setChoice(null)` hands the page back to the OS.
-- **Look:** a 44px round target, `text-muted-foreground` → `hover:text-foreground`, the 3px
-  `--ring` focus ring, no fill, border, gradient or shadow.
-
-Pinned by `tests/scheme.spec.ts` (`?themeToggle=1`): the module's imports, the bootstrap string,
-the class flip and persistence, the resolved flip under an emulated dark system, a node footer,
-and the absent case.
-
-### Toasts — `Toaster`
-
-An action that succeeded or failed says so in a toast. The surface is `Toaster`; the messages are
-`toast.success(...)` / `toast.error(...)` imported from **`sonner`** by whatever raised them.
-
-```tsx
-import { NavLayout, Toaster } from '@owlmeans/web-panel'
-
-export const MainLayout: FC<PropsWithChildren> = ({ children }) => <>
-  <NavLayout nav={navConfig} title="My App">{children}</NavLayout>
-  <Toaster />
-</>
-```
-
-- **Mount it exactly once, in the layout.** `toast()` writes to a module-global store, so two
-  mounted `Toaster`s render every message twice and none renders any of them — both failures are
-  silent, which is why `tests/toaster.spec.ts` asserts the count rather than the presence.
-- **Colours come from the app's own tokens** — `--popover`, `--popover-foreground`, `--border` —
-  so a toast matches every other floating surface. A caller's `style` merges over them.
-- **The theme follows the `.dark` class on the document element**, not a theme provider: the
-  package reads the class an app's `next-themes`, the owl theme provider, or a hand-written
-  toggle all set, and depends on none of them. Pass `theme` explicitly to override.
-- Defaults are `richColors`, `closeButton`, `duration={5000}`, `position="top-right"`; every one
-  of them, and every other `ToasterProps` field, is overridable per app.
-- `sonner` is a dependency of this package, so nothing is required of the consumer — but an app
-  raising its own toasts should declare `sonner` too, at a range that resolves to the same copy.
-
-`appendPermissionDeniedToast(context)` plugs into the client entrypoint failure service and
-shows a localized access-denied toast for errors carrying the server IAM marker. Mount `Toaster`
-once as usual. The toast exposes the technical message and incident id in a separate details
-section. The app supplies its locale through its i18n context.
-
-### Reload prompt — `SocketReloadDialog`
-
-`makeContext` calls `appendSocketStatus` from `@owlmeans/client-socket` unconditionally, and
-`PanelApp` mounts `SocketReloadDialog` as a sibling of the Router — exactly where
-`PanelCookieConsent` lives, and for the same reason: a dialog mounted inside a route is torn down
-on every navigation. Neither does anything unless an app opts in:
-
-```typescript
-cfg.socket = { reloadDialog: true }
-```
-
-Once any `socketClientHelper.ws()`/`useWs()` connection in the app has exhausted its own retry budget
-(`useSocketStatus() === 'lost'`), a global, blocking `AlertDialog` covers the screen — no Escape,
-no outside click, two actions:
-
-- **"Try again"** (`data-socket-retry-action`) — `useSocketRetry().retry()` revives every lost
-  connection (see the `client-socket` skill). The dialog stays up with the button disabled and
-  reading "Reconnecting…" while they retry, closes once the aggregate is `'online'`, and offers
-  both buttons again if it falls back to `'lost'`.
-- **"Reload page"** (`data-socket-reload-action`) — `window.location.reload()`, the fallback that
-  always works.
-
-The status service also retries by itself when the tab becomes visible, the window gains focus or
-the browser comes back online, so a socket that died in a background tab is usually back before
-anyone presses anything — an open dialog shows "Reconnecting…" through that too. Strings are
-lib-tier (`useI18nLib('socket', 'reload')`: `title`, `description`, `action`, `retry`,
-`retrying`), 8 languages, under `src/components/socket/i18n/`.
-
-Leave `cfg.socket.reloadDialog` unset (or `false`) for an app that would rather show its own
-inline "reconnecting…" state — `useSocketStatus()` from `@owlmeans/client-socket` serves that,
-independent of the dialog.
-
 ### Links — `Link`
 
 `Link` renders an `<a>` whose `href` is the entrypoint's own answer: it asks
@@ -444,342 +133,6 @@ known — so never key a test or a layout on the anchor having an `href` synchro
 falls back to `modules.<alias>` when neither `name` nor `children` is given, `open` adds
 `target="_blank"` with `rel="noopener noreferrer"`, and `center` centres the text.
 
-### Forms — `Form`, `TextInput`, the buttons
-
-`WebFormProps` is `@owlmeans/client-panel`'s `FormProps` plus `className` and `style`. `Form` holds
-the whole model itself — `useForm` with `mode: 'all'`, `delayError: 300`, an `ajvResolver` over
-`validation` with `coerceTypes` and the `ajv-formats` formats — and publishes it through
-`FormProvider` plus `FormContext`, so every control below reads one form.
-
-```tsx
-import { Form, TextInput, SubmitButton, Button } from '@owlmeans/web-panel'
-
-<Form decorate validation={schema} onSubmit={async (data, update) => { await save(data); update(data) }}>
-  <TextInput name="email" label placeholder hint />
-  <TextInput name="password" type="password" label="Password" />
-</Form>
-```
-
-- **`decorate` switches the whole rendering.** With `decorate={true}` the fields go inside a shadcn
-  `Card`, the root error surfaces through `Status`, and a `SubmitButton` is rendered in the
-  `CardFooter` **whenever `onSubmit` is given** — the caller writes no action. Without it (the
-  default) `Form` is a bare flex column: no card, no root-error surface, no submit button, so the
-  caller renders its own action. `horizontal`/`vertical` scaling, `className` and `style` land on
-  the `Card` when decorated and on that column otherwise.
-- **`formRef`** — a `useFormRef()` ref filled with `{ form, update, loader, error }`, which is how a
-  caller drives the form, flips the loader, or plants a field/root error from outside.
-- **`TextInput` takes `label`, `placeholder` and `hint` as `string | boolean`.** `true` resolves
-  `<name>.label` / `<name>.placeholder` / `<name>.hint` from the form namespace; a string is used
-  verbatim; anything else renders nothing. It also takes `name`, `def`, `type` (any HTML input type,
-  default `text`) and `disableAutocomplete`. A field error replaces the hint line.
-- **`Button`** takes a required `label`, `onClick`, `loader` (a `Toggleable` — open disables the
-  button and shows the spinner), `size` (`small`/`medium`/`large`), `fullWidth`, and `variant`,
-  which maps the MUI vocabulary onto shadcn (`contained` → `default`, `outlined` → `outline`,
-  `text` → `ghost`) and forwards a shadcn variant name unchanged.
-- **`SubmitButton`** is that button bound to `handleSubmit`, taking `onSubmit` (or `onClick`) and a
-  `label` defaulting to `submit`. It resolves the label with the form `t` itself and passes it down
-  with `i18n.suppress` set, so the label is translated once.
-- **`ButtonSelector`** renders one `Button` per entry of `options`, the one equal to `current`
-  `contained` and the rest `outlined`, calling `onSelect(option)`. `name` prefixes each option's
-  label key as `<name>.<option>`.
-
-### The terms confirmation — `LoginTerms`, `LoginPrivacyNotice`
-
-`components/login/terms.tsx` renders `LoginTermsModel` (`@owlmeans/client-panel/auth`) via
-`loginTermsHelper.termsSentence` + `.termsLabelResolver` (`@owlmeans/client-auth/login`) rather than re-deriving
-link/label pairs itself. **`[data-login-terms]` marks exactly one checkbox — or NONE, once
-`model.terms.deferred` is true** (`LoginScreen` renders `LoginTerms` when not deferred,
-`LoginPrivacyNotice` when it is): an e2e suite elsewhere in the platform treats the checkbox as a
-strict, at-most-one-match locator, so a change here must never add a second one, whatever
-billing/product/custom documents a configuration adds. `[data-login-privacy]` is a SIBLING
-paragraph of the checkbox's `<label>`, never nested inside it — a privacy disclosure is not
-something the checkbox consents to — and it is exported ON ITS OWN as `LoginPrivacyNotice`: it
-still renders while deferred, since the disclosure was never the checkbox's to remove. A linked
-document/notice fragment carries `data-login-document="<key>"`. `[data-login-revised]` renders only
-when NOT deferred and the resolved terms carry a `revisedAt` (i.e. the configuration set
-`showRevision: true` and at least one document has its own revision date) — deferred, that date
-belongs to the document the checkbox agreed to, and there is no checkbox on this screen to attach it
-to. `LoginTerms`/`LoginPrivacyNotice` take `locale?: string` — from `LoginScreen`'s own `locale`
-prop, never read from context directly — for `Intl.ListFormat` and a custom document's locale-keyed
-`labelMap`. Method buttons carry `aria-disabled={model.blocked || undefined}`, never a literal
-`"false"` — a deferred screen (which never sets `blocked`) then renders identically to an unblocked
-ordinary one, with no special case. Pinned by `tests/login.spec.ts` → the "with billing, product and
-custom documents configured" and "the Terms confirmation deferred to a step" blocks.
-
-### The provider disclosure — `LoginProviderNote`
-
-`LoginScreen` renders `useLoginMethods().provider` (`@owlmeans/client-panel/auth`, resolution rules
-there) through `components/login/provider.tsx`:
-`<div role="note" data-login-provider data-placement="top|inline">` — a `ShieldCheck` icon, the
-sentence, and, when `info` resolved, `<a data-login-provider-info target="_blank"
-rel="noopener noreferrer">More information</a>`. Never a `header`/`nav`: it is a disclosure, not a
-landmark.
-
-- **No provider → the DOM is exactly the pre-provider screen** (no note, no stage, title
-  `login.title`).
-- **`top`** (the platform's own hosts) — the strip is the FIRST child of `[data-login-screen]`,
-  full width, at the screen's top edge; the card sits in `<div data-login-stage>`, which takes the
-  remaining height and centres it. The screen's column layout, its zero padding, the stage's flex
-  centring/padding and the strip's width are INLINE styles (same reason as the screen height —
-  `login-methods` → Layout); classes there are cosmetic only.
-- **`inline`** (an owner's own domain) — the note is one line inside `CardContent`, directly under
-  the methods and above the terms; the screen keeps its ordinary shape.
-- The card title becomes `login.provider.title` ("Sign in to {{product}}") whenever a provider
-  resolves; `props.title` still wins.
-- Copy: `login.provider.{title,top,inline,more}` in all eight languages
-  (`components/login/i18n/*.json`), registered by `components/login/i18n.ts` into the SAME `auth`
-  library resource as `client-auth`'s login copy (deep-merged; this package owns only the
-  `login.provider` subtree). Names are filled after translation by `loginProviderHelper.fill`.
-- Still exactly one `[data-login-terms]` in either placement. Pinned by `tests/login.spec.ts` →
-  "the provider disclosure" (`?provider=top|inline` in the harness) and
-  `tests/login-provider.spec.ts` (resolver, `fill`, eight-language key/placeholder parity).
-
-## Subpath: `./consent`
-
-`PanelCookieConsent` and `PanelCookiePolicy` — `@owlmeans/web-consent`'s components bound to this
-app's language and translations, falling through to the package's own eight-language bundle for
-every key the app has not overridden — and to the app's cookie-consent configuration. See the
-`consent` and `web-consent` skills.
-
-**The configuration lives in `cfg.cookieConsent`** (`PanelCookieConsentConfig`, on `AppConfig`),
-set where the rest of the app's configuration is, before anything renders:
-
-```typescript
-cfg.cookieConsent = { geo: { cloudflare: true } }   // ask only in consent countries; mode: 'bar' default
-```
-
-- `mode` (`'bar'` | `'window'`) and `geo` (`ConsentGeoOptions`) feed both components; a prop of the
-  same name always wins. Not `cfg.consent` — "consent" also names the marketing-consent and sign-in
-  terms options.
-- A file restored into apps of every age (a generated target's `config.ts`) writes it as
-  `Object.assign(cfg, { cookieConsent: … })`, so a tree whose framework predates the key still
-  type-checks; an older package ignores it.
-- **A locator of the app's own** is code, not configuration: `appendConsentGeoPlugin(context,
-  plugin)` in `context.ts` registers a `ConsentGeoPlugin` (`{ alias, locate }` — resolve the country
-  or throw) ahead of Cloudflare's and installs `context.consentGeo()`. Appending one IS asking for
-  the gate: `PanelCookieConsent` turns it on (`geo: {}`) even where `cfg.cookieConsent.geo` says
-  nothing. `PanelCookiePolicy` reads the same, so the policy states the regional rule exactly when
-  the dialog applies it.
-
-A re-export does not move Tailwind class strings, so a consumer adds a second `@source` for
-`@owlmeans/web-consent` alongside this package's — pointing at **`src`**, for the reason spelled out
-under *Consumer setup* below. Without it the dialog renders half-styled.
-
-**A service wrapping a state resource is what lets a host's own menu take over the floating
-button's job.** `appendConsentWidgetService(context, alias?)` registers a ref-counted presence
-service (`@owlmeans/state`'s `appendStateResource` behind `@owlmeans/context`'s `createService`) —
-call it once, from the app's own `context.ts`, the same as any other `append*` mixin:
-
-```ts
-import { appendConsentWidgetService } from '@owlmeans/web-panel/consent'
-
-appendConsentWidgetService<C, T>(context)
-```
-
-Then call `useConsentMenuPresence()` from the host menu's own **always-mounted** shell component,
-never from inside the row. A dropdown's content (Radix `DropdownMenuContent` and most headless
-menu content primitives) mounts its children only while the menu is OPEN, so presence announced
-from inside the row hid the floating button only while the dropdown happened to be open, and
-showed it again the instant it closed. The row is also not a `DropdownMenuItem`: an item takes the
-inner button's focus and closes the menu on the click before the button's own handler runs.
-
-```tsx
-import { PanelConsentMenuWidget, useConsentMenuPresence } from '@owlmeans/web-panel/consent'
-
-const MyMenu: FC = () => {
-  useConsentMenuPresence()   // declares the row reachable for as long as THIS component is mounted
-  return <DropdownMenu>
-    <DropdownMenuTrigger>…</DropdownMenuTrigger>
-    <DropdownMenuContent>
-      <div className="px-2 py-1.5"><PanelConsentMenuWidget /></div>   {/* a plain row, not an item */}
-    </DropdownMenuContent>
-  </DropdownMenu>
-}
-```
-
-`PanelCookieConsent` reads the same service (`useConsentWidgetPresent()`, internally) and computes
-`noReopenButton` from it whenever the caller has not passed one explicitly — an app that both
-mounts `PanelCookieConsent` at its root and calls `useConsentMenuPresence()` from its collapsed
-menu gets the floating button exactly while the menu is not, with no further wiring. Ref-counted
-rather than a boolean latch, because more than one menu shell can be mounted for one commit during
-a layout transition (a stale header still showing its own collapsed menu while a new screen's own
-menu has already mounted) and because React 18 StrictMode double-invokes mount/cleanup in dev.
-
-**The pair a consumer imports** — the dialog and the control that takes over its floating button:
-
-| Job | Import from `@owlmeans/web-panel/consent` | Where it goes |
-|---|---|---|
-| The consent UI — bar, window, spinner (and its floating re-open button) | `PanelCookieConsent` | Beside the router — a `PanelApp` child — once |
-| Asking only in consent countries | `cfg.cookieConsent.geo`, or `appendConsentGeoPlugin(context, plugin)` | The app's `config.ts` / `context.ts` |
-| The "Cookie settings" control in a footer or menu | `PanelConsentMenuWidget` (`label`, `className`, `onSelect?` — defaults to `consentStore.open('reopen')`) | Inside the host's own footer/menu |
-| Hiding the floating button while that control is reachable | `useConsentMenuPresence()` | Called by the always-mounted component that renders the control — mounted ONLY while the control can actually be reached: a component that is merely hidden by CSS (`xl:hidden`) is still mounted and still claims presence, so the floating button vanishes with nothing else to open the dialog; render it conditionally instead (viable's header mounts its hamburger menu only below the full-row breakpoint) |
-| Registering the presence service | `appendConsentWidgetService(context)` | The app's `context.ts` |
-
-A footer is the simplest host, because it is always mounted — the control and the presence call
-live in one component:
-
-```tsx
-const CookieSettings: FC = () => {
-  useConsentMenuPresence()
-  return <PanelConsentMenuWidget label={t('footer.cookies')} className="w-auto text-muted-foreground" />
-}
-```
-
-The widget renders a `<button data-consent-menu-widget>` styled as a menu row (`w-full`,
-`text-popover-foreground`, `hover:bg-accent`); a footer passes `className` to restyle it (merged
-through `cn`) and its own `label` — the packaged default reads "Cookie preferences".
-
-**The presence service is optional, and nothing throws without it.** `PanelCookieConsent` checks
-the context for `consentWidget` and, when `appendConsentWidgetService` never ran, renders the plain
-bound dialog with its floating button; `useConsentMenuPresence()` then has nothing to claim and
-does nothing. The presence read itself (`useConsentWidgetPresent`) still needs the service — its
-state resource is registered by it — so any other caller checks first. A dialog that read an
-unregistered state resource threw inside render ("Resource consent-widget-presence not found") and
-blanked the whole application. Pinned by `tests/consent.spec.ts` (`?consent=bare` / `?consent=menu`;
-the configuration by `?consentCfg=window|bar`, `?modeProp=` and `?consentGeo=<CC>|fail`).
-
-## Subpath: `./picker`
-
-The standard editor and renderer of an icon and a colour **a person chooses** — a workcard type's
-or a status flow's mark, a label, a category. One component family, so every application offers
-the same 24 colours, the same curated icons and the same behaviour on a desktop and a phone.
-
-```ts
-import {
-  IconColorPicker, ColorPicker, IconPicker, ColorSwatches, IconGrid, IconTile, ColorDot, usePickerTranslate,
-  pickerColorHelper, pickerIconHelper, PICKER_COLORS, PICKER_COLOR_KEYS,
-} from '@owlmeans/web-panel/picker'
-// Server, seed, build script — the data and the colour helper without React or icons:
-// import { pickerColorHelper, PICKER_COLOR_KEYS } from '@owlmeans/web-panel/picker/vocabulary'
-```
-
-### Which part
-
-| Part | When |
-|---|---|
-| `IconColorPicker` | Both halves of a mark. One trigger (the tile, "Rocket · Indigo", a chevron — or `trigger="tile"` for the tile alone) opens swatches above a searchable, categorized icon grid tinted in the chosen colour. Stays open for the other half; Esc, a click outside or (sheet) Done closes it |
-| `ColorPicker` | A colour alone (`trigger="button"` or `"dot"`). Closes on a swatch. `colors` takes an application palette — e.g. status tones |
-| `IconPicker` | An icon alone, tinted in `color`. Closes on a pick |
-| `ColorSwatches`, `IconGrid` | Inline, for a dialog or sheet the application already owns — no trigger, no surface of their own |
-| `IconTile` | A stored mark shown: the icon in the colour's ink on its ground (`variant="tile"`), or the ink alone (`"plain"`); `size` `xs`/`sm`/`md`/`lg`; `label` makes it an image, else decorative |
-| `ColorDot` | A stored colour as a dot in its ink (`size` `xs`/`sm`/`md`) |
-| `usePickerTranslate()` | The `translate` for an app rendered by `PanelApp` / `render()` — the packaged bundle in the current language |
-
-### Values
-
-- **Colour**: a palette key — `red orange amber yellow lime green emerald teal cyan sky blue indigo
-  violet purple fuchsia pink rose maroon brown olive navy slate stone graphite` (`PICKER_COLOR_KEYS`,
-  hue order) — or, only with `customColors`, a lowercase `#rrggbb`. Never a label ("Indigo").
-- **Icon**: a kebab-case lucide name from the catalogue (`PICKER_ICON_NAMES`, ~250 in ten categories,
-  a superset of the planning kits' icons). Never a component, never a label.
-- `IconColorPicker` emits `onChange({ icon, color })` — both halves as they now stand; a half
-  never chosen stays `undefined`, never `null`. `value` tolerates `null`s and absent halves.
-- An unknown stored value renders the fallback (`slate`, `circle`) and never throws, so a value
-  from an older palette or a typo never breaks a page.
-- `customColors` (default `false`) adds a colour wheel (react-colorful) and a hex field: a full
-  `#rrggbb` commits while typing, `#rgb` / `abc` on Enter or blur, always normalized to lowercase six
-  digits; anything else marks the field `aria-invalid` and changes nothing. A custom colour's ink
-  and grounds are derived to keep 4.5:1 in both modes.
-
-### Surfaces
-
-`surface="auto"` (default) opens a popover from 768px up and a bottom sheet below — decided when
-it OPENS, kept until it closes. `surface="popover" | "sheet"` forces one. The popover is modal, so
-inside an application's own Dialog or Sheet the wheel scrolls it and focus stays in it; it keeps
-12px off the edges and scrolls inside rather than growing past the viewport. The sheet has a grab
-handle, a sticky header with the preview and a 44px Done button, `88dvh` at most and safe-area
-padding. Below 768px and on coarse pointers every cell, chip, field and button is at least 44px;
-the search field takes focus on open only for a fine pointer (no keyboard pops up on a phone).
-Keyboard: arrows move in two dimensions through swatches and icons (one tab stop each), Home/End,
-ArrowDown from the search into the grid and ArrowUp back, Enter/Space picks, Esc closes and focus
-returns to the trigger. Every control is a `<button type="button">` with an `aria-label`, so a
-pick never submits an enclosing form.
-
-### Strings
-
-The parts never read i18n implicitly — rendered without an i18n instance they show English. Pass
-`translate={usePickerTranslate()}` in an app rendered by `PanelApp` / `render()`: chrome, colour
-names and category names come from the lib-tier `picker` bundle in eight languages (en, pl, ru, be,
-uk, es, de, fr); icon names stay English. An app overrides a string at the App tier in the `lib`
-namespace (`i18nHelper.addI18nApp('de', 'picker', { colors: { teal: 'Türkis' } }, { ns: LIB_NAMESPACE })`).
-Keys: `label`, `icon`, `color`, `placeholder.{both,icon,color}`, `nothing`, `done`, `search`,
-`searchPlaceholder`, `categoriesLabel`, `all`, `results` (`{count}`), `empty` (`{query}`), `clear`,
-`custom`, `hex`, `invalidHex`, `colors.<key>`, `categories.<category>`. `label` and `placeholder`
-props override per instance. Only the 24 palette names translate: an application palette passed as
-`colors` shows its `label`s as given, so translate them before passing them in.
-
-### RIGHT and WRONG
-
-```tsx
-import type { IconColorChange } from '@owlmeans/web-panel/picker'
-
-// RIGHT — local state
-const translate = usePickerTranslate()
-const [mark, setMark] = useState<IconColorChange>({ icon: type.icon, color: type.tone })
-<IconColorPicker label="Mark" value={mark} onChange={setMark} translate={translate} />
-
-// RIGHT — react-hook-form: the field holds { icon, color }; the picker is the whole control
-<Controller
-  name="mark" control={form.control}
-  render={({ field }) => <IconColorPicker
-    id="mark" label="Mark" value={field.value} onChange={field.onChange} disabled={field.disabled} translate={translate}
-  />}
-/>
-// …and on save: { tone: values.mark.color, icon: values.mark.icon }
-
-// WRONG — a Select of colour names, a hand-made swatch row, or a label stored instead of the key
-<Select value={tone} onValueChange={setTone}>{PICKER_COLOR_KEYS.map(k => <SelectItem value={k}>{k}</SelectItem>)}</Select>
-{['red', 'blue'].map(c => <button className={`bg-${c}-500`} onClick={() => setTone(c)} />)}
-onChange={next => save({ tone: 'Indigo' })}
-// WRONG — the picker hands over a value, not an event
-<ColorPicker value={field.value} onChange={event => field.onChange(event.target.value)} />
-```
-
-### Rendering a stored mark
-
-```tsx
-<IconTile icon={type.icon} color={type.tone} size="sm" />                 // list row, chip, header
-<IconTile icon={flow.icon} color={flow.tone} variant="plain" />           // the ink alone, inline with text
-<ColorDot color={label.color} />                                          // a dot
-<span style={pickerColorHelper.styleOf(card.color)} className="text-(--pick-ink)">…</span>   // custom markup
-```
-
-`pickerColorHelper.styleOf(value, colors?)` returns the custom properties `--pick-swatch`,
-`--pick-ink`, `--pick-soft`, `--pick-ink-dark`, `--pick-soft-dark` (a plain string record — it goes
-straight into `style`). The parts switch to the dark values themselves, through explicit
-arbitrary variants on web-panel's scheme contract (`.dark` on `<html>`, or the system's dark
-unless `.light`) — never through the app's `dark:` variant. A hand-written element using
-`styleOf` reads `--pick-ink` / `--pick-ink-dark` itself. `pickerColorHelper.resolve(value)` gives
-every field (and `custom: true` for a hex); `hashKey(seed)` gives a stable palette key for a record
-that has none. Code-chosen tones (a status's meaning) stay the app's own classes; a colour a PERSON
-chose always renders through these parts.
-
-**DOM hooks** (stable, used by end-to-end suites): the trigger `data-picker-trigger`, the open
-surface `data-picker-surface="popover|sheet"`, a swatch `data-picker-color="<key>"` (the custom
-row `"custom"`, `data-selected` while a custom value is chosen), an icon cell
-`data-picker-icon="<name>"`, a chip `data-picker-category`, the search field `data-picker-search`,
-the hex field `data-picker-hex`, the sheet's Done `data-picker-done`; `IconTile` carries
-`data-icon-tile`, `data-icon`, `data-color`, `ColorDot` `data-color-dot`. Picker parts never carry
-`data-tone` or `data-slot="button"` — an application's own rules on those never reach them.
-
-### Consumer setup
-
-- `@radix-ui/react-popover` is a peer, like the other Radix primitives: keep it on the SAME Radix
-  generation as `@radix-ui/react-dialog` (update them together). The two share the dismissable-layer
-  and focus-scope stacks; a popover from another generation inside a Dialog is treated as an outside
-  click and loses focus to the dialog. `react-colorful` is a dependency of this package.
-- The `@source` line for this package's `src` (see *Consumer setup* below) is what brings the
-  picker's classes — including its `[.dark_&]:` and `pointer-coarse:` variants — into the stylesheet.
-- Tokens read: `--popover`, `--popover-foreground`, `--border`, `--input`, `--ring`, `--accent`,
-  `--accent-foreground`, `--primary`, `--primary-foreground`, `--muted-foreground`, `--foreground`,
-  `--destructive`.
-
-Pinned by `tests/picker.spec.ts` (harness `/picker`: `?custom=1`, `?inSheet=1`, `?bare=1`,
-`?surface=…`, `?compact=1`, `?empty=1`, `?inline=1`, `?dark=1`) and
-`tests/picker-vocabulary.spec.ts` (palette contrast and OKLab distance, hex handling, catalogue ↔
-components). `PICKER_SHOTS_DIR=<dir> bun test tests/picker-shots.spec.ts` writes every scenario's
-screenshot at 1280 and 375, light and dark.
-
 ## Consumer setup — package boundary and Tailwind
 
 `web-panel` ships its shadcn primitives and `cn` helper as private implementation files under its
@@ -819,3 +172,17 @@ in a linked workspace, so it is the reliable scan target in both modes.
 - `ajv-formats` is imported at module scope by the form model but is declared in no dependency
   section of the manifest, which lists `ajv` alone. An install that does not otherwise pull it in
   fails at import time, so declare `ajv-formats` next to `ajv` in the consuming application.
+
+## Parts
+
+Load a part on top of this core when its job is in play.
+
+| Part | Load it when |
+|---|---|
+| [navigation](parts/navigation.md) | Building or restyling the application shell — `NavLayout`, `TopNav`/`SideNav`/`MobileNav`/`Footer`, the nav config, `mobileMenu`, the skip link, the footer credit, the header surface |
+| [forms](parts/forms.md) | Writing a form (`Form`, `TextInput`, the buttons) or raising a toast (`Toaster`, `sonner`, the permission-denied toast) |
+| [theme](parts/theme.md) | Adding the light/dark switch (`ThemeToggle`, `useColorScheme`), the head bootstrap from `./scheme`, or CSS that follows the scheme |
+| [reload](parts/reload.md) | Opting into the "connection lost" prompt (`cfg.socket.reloadDialog`, `SocketReloadDialog`) |
+| [sign-in](parts/sign-in.md) | Changing the sign-in screen's terms confirmation, privacy notice or provider disclosure |
+| [consent](parts/consent.md) | Mounting cookie consent through `./consent`, its geo gate, or a host menu's cookie-settings row |
+| [picker](parts/picker.md) | Letting a person choose an icon or a colour, or rendering a stored mark (`./picker`) |