@owlmeans/web-panel 0.1.18-rc.9 → 0.1.18

package/agent-meta/skills/web-panel/parts/editor.md

@@ -0,0 +1,47 @@
+---
+name: editor
+description: Controlled JSON editing and previews with the optional web-panel/editor entrypoint, CodeMirror 6, syntax diagnostics, formatting, copying and read-only state.
+metadata:
+  purposes: form, view
+  mentions: JsonEditor, JsonEditorProps, JsonEditorLabels
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# JSON editor
+
+Import `JsonEditor` and its `JsonEditorProps` / `JsonEditorLabels` from
+`@owlmeans/web-panel/editor`. The root entrypoint does not import the editor, keeping CodeMirror
+out of consumers that do not use it. JSON support, linting and highlighting are package dependencies.
+
+```tsx
+<JsonEditor
+  key={record.id}
+  value={draft}
+  onChange={setDraft}
+  onValidityChange={setValid}
+  ariaLabel="Record JSON"
+  testId="record-json"
+/>
+```
+
+- `value` is always raw text. Preserve incomplete drafts; parse at the host's save boundary.
+  `onValidityChange` reports syntax validity so a host can disable its save action.
+- A change of document identity keys/remounts the component; an update within the same document
+  preserves undo history. External controlled values update the view without echoing `onChange`.
+- `readOnly` disables editing and removes Format; Copy remains available. Use it for previews and
+  inspectors. Formatting pretty-prints valid JSON without changing its values.
+- `id`, `testId` and `ariaLabel` address the editable content, including `aria-readonly`,
+  `aria-invalid` and its diagnostic description. The wrapper exposes `data-json-editor` and
+  `data-valid`. Pass `minHeight` / `maxHeight` in pixels when the host needs another viewport size.
+- `labels` overrides format/copy/copied/copyFailed/readOnly/valid/invalid copy. Components do not
+  read an implicit i18n provider; defaults are English.
+- Colours use host shadcn variables, falling back to Tailwind's `--color-*` variables. Brand-specific
+  primary/chart colours have standard-token fallbacks. The host still scans web-panel's `src`.
+
+Acceptance: `@owlmeans/web-panel`'s `editor.spec.ts` (`bun test tests/editor.spec.ts` in the package); the real Chromium harness checks
+highlighting, formatting, undo, incomplete drafts, validity, external values and read-only controls.
+
+## External docs
+
+- https://github.com/codemirror/lang-json — `json()` language support and `jsonParseLinter()` diagnostics for CodeMirror 6.
+- https://codemirror.net/docs/ref/ — editor state/view extensions, controlled transactions and read-only configuration.

package/agent-meta/skills/web-panel/parts/forms.md

@@ -0,0 +1,85 @@
+---
+name: forms
+description: The web form family (Form, TextInput, Button, SubmitButton, ButtonSelector) and the Toaster surface for sonner toasts.
+metadata:
+  purposes: form, feedback
+  mentions: TextInput, SubmitButton, ButtonSelector, useFormRef, WebFormProps, Toaster, sonner, appendPermissionDeniedToast
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/web-panel — Forms and toasts
+
+| Export | Description |
+|--------|-------------|
+| `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` |
+
+## 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>`.
+
+## 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.

package/agent-meta/skills/web-panel/parts/navigation.md

@@ -0,0 +1,203 @@
+---
+name: navigation
+description: The application shell — NavLayout, TopNav/SideNav/MobileNav/Footer, the two-layer nav config, the narrow-viewport menu, the skip link, the footer credit and the header's surface rules.
+metadata:
+  purposes: navigation, layout, screen
+  mentions: NavLayout, TopNav, SideNav, MobileNav, Footer, ShellCredit, useShellCredit, PanelNavConfig, PanelNavLink, NavTranslate, defaultNavTranslate, mobileMenu, skipLinkLabel, headerClassName, containerClassName
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/web-panel — Navigation shell
+
+## 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`, `navTestId?: string`, `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 *Consumer setup — package boundary and Tailwind* in [SKILL.md](../SKILL.md).
+
+## Stable selectors and detail screens
+
+`PanelNavSection.testId` and `PanelNavItem.testId` optionally name their rendered destinations;
+`NavLayout.navTestId` names the desktop navigation landmark. With `mobileMenu`, only the current
+viewport's section menu is mounted, keeping the same destination selector unique when the sheet
+opens. Side/bar item selectors are emitted only by the visible variant. Hosts keep their selectors
+in navigation data rather than querying translated text or styling classes.
+
+When an unlisted detail screen has no listed ancestor, the headless model selects the section of
+the longest listed pathname prefix. This covers sibling route declarations such as `/items` and
+`/items/:id` without changing their route hierarchy.

package/agent-meta/skills/web-panel/parts/picker.md

@@ -0,0 +1,164 @@
+---
+name: picker
+description: The ./picker subpath — the standard icon and colour picker parts, their values, surfaces and strings, rendering a stored mark, DOM hooks and consumer setup.
+metadata:
+  purposes: picker, form
+  mentions: IconColorPicker, ColorPicker, IconPicker, ColorSwatches, IconGrid, IconTile, ColorDot, usePickerTranslate, pickerColorHelper, pickerIconHelper, PICKER_COLORS, PICKER_COLOR_KEYS, PICKER_ICON_NAMES, @owlmeans/web-panel/picker
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/web-panel — Icon and colour picker
+
+## Subpath: `./picker`
+
+**Subpath exports**
+
+- `./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
+  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
+
+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 — package boundary and Tailwind* in [SKILL.md](../SKILL.md)) 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.

package/agent-meta/skills/web-panel/parts/reload.md

@@ -0,0 +1,46 @@
+---
+name: reload
+description: The global connection-lost prompt — SocketReloadDialog, the cfg.socket.reloadDialog opt-in, and its Try again and Reload page actions.
+metadata:
+  purposes: feedback, config
+  mentions: SocketReloadDialog, reloadDialog, useSocketStatus, useSocketRetry, appendSocketStatus
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/web-panel — Reload prompt
+
+| Export | Description |
+|--------|-------------|
+| `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 |
+
+## 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.

package/agent-meta/skills/web-panel/parts/sign-in.md

@@ -0,0 +1,65 @@
+---
+name: sign-in
+description: The sign-in screen's terms confirmation, privacy notice and provider disclosure — LoginTerms, LoginPrivacyNotice, LoginProviderNote and their DOM hooks.
+metadata:
+  purposes: auth
+  mentions: LoginTerms, LoginPrivacyNotice, LoginProviderNote, LoginScreen, LocalizedLoginScreen, appendLoginScreen, data-login-terms, data-login-provider
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/web-panel — Sign-in screen
+
+| Export | Description |
+|--------|-------------|
+| `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 |
+
+## 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).