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

package/THIRD-PARTY-NOTICES.txt

@@ -0,0 +1,24 @@
+shadcn/ui — copied UI components
+Source: https://github.com/shadcn-ui/ui
+
+MIT License
+
+Copyright (c) 2023 shadcn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
-  "schemaVersion": 2,
+  "schemaVersion": 3,
   "package": "@owlmeans/web-panel",
-  "version": "0.1.18-rc.9",
-  "generatedAt": "2026-08-24T21:14:00.140Z",
+  "version": "0.1.18",
+  "generatedAt": "2026-10-28T00:31:34.768Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {
@@ -10,7 +10,166 @@
       "name": "web-panel",
       "category": "package-specific",
       "file": "skills/web-panel/SKILL.md",
-      "canonicalPath": ".agents/skills/web-panel/SKILL.md"
+      "canonicalPath": ".agents/skills/web-panel/SKILL.md",
+      "parts": [
+        {
+          "name": "consent",
+          "file": "skills/web-panel/parts/consent.md",
+          "description": "The ./consent subpath — PanelCookieConsent and PanelCookiePolicy bound to the app's i18n, cfg.cookieConsent, a geo plugin, and the host-menu presence service.",
+          "purposes": [
+            "consent"
+          ],
+          "mentions": [
+            "PanelCookieConsent",
+            "PanelCookiePolicy",
+            "PanelConsentMenuWidget",
+            "useConsentMenuPresence",
+            "appendConsentWidgetService",
+            "appendConsentGeoPlugin",
+            "cookieConsent",
+            "@owlmeans/web-panel/consent"
+          ]
+        },
+        {
+          "name": "editor",
+          "file": "skills/web-panel/parts/editor.md",
+          "description": "Controlled JSON editing and previews with the optional web-panel/editor entrypoint, CodeMirror 6, syntax diagnostics, formatting, copying and read-only state.",
+          "purposes": [
+            "form",
+            "view"
+          ],
+          "mentions": [
+            "JsonEditor",
+            "JsonEditorProps",
+            "JsonEditorLabels"
+          ]
+        },
+        {
+          "name": "forms",
+          "file": "skills/web-panel/parts/forms.md",
+          "description": "The web form family (Form, TextInput, Button, SubmitButton, ButtonSelector) and the Toaster surface for sonner toasts.",
+          "purposes": [
+            "form",
+            "feedback"
+          ],
+          "mentions": [
+            "TextInput",
+            "SubmitButton",
+            "ButtonSelector",
+            "useFormRef",
+            "WebFormProps",
+            "Toaster",
+            "sonner",
+            "appendPermissionDeniedToast"
+          ]
+        },
+        {
+          "name": "navigation",
+          "file": "skills/web-panel/parts/navigation.md",
+          "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.",
+          "purposes": [
+            "navigation",
+            "layout",
+            "screen"
+          ],
+          "mentions": [
+            "NavLayout",
+            "TopNav",
+            "SideNav",
+            "MobileNav",
+            "Footer",
+            "ShellCredit",
+            "useShellCredit",
+            "PanelNavConfig",
+            "PanelNavLink",
+            "NavTranslate",
+            "defaultNavTranslate",
+            "mobileMenu",
+            "skipLinkLabel",
+            "headerClassName",
+            "containerClassName"
+          ]
+        },
+        {
+          "name": "picker",
+          "file": "skills/web-panel/parts/picker.md",
+          "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.",
+          "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"
+          ]
+        },
+        {
+          "name": "reload",
+          "file": "skills/web-panel/parts/reload.md",
+          "description": "The global connection-lost prompt — SocketReloadDialog, the cfg.socket.reloadDialog opt-in, and its Try again and Reload page actions.",
+          "purposes": [
+            "feedback",
+            "config"
+          ],
+          "mentions": [
+            "SocketReloadDialog",
+            "reloadDialog",
+            "useSocketStatus",
+            "useSocketRetry",
+            "appendSocketStatus"
+          ]
+        },
+        {
+          "name": "sign-in",
+          "file": "skills/web-panel/parts/sign-in.md",
+          "description": "The sign-in screen's terms confirmation, privacy notice and provider disclosure — LoginTerms, LoginPrivacyNotice, LoginProviderNote and their DOM hooks.",
+          "purposes": [
+            "auth"
+          ],
+          "mentions": [
+            "LoginTerms",
+            "LoginPrivacyNotice",
+            "LoginProviderNote",
+            "LoginScreen",
+            "LocalizedLoginScreen",
+            "appendLoginScreen",
+            "data-login-terms",
+            "data-login-provider"
+          ]
+        },
+        {
+          "name": "theme",
+          "file": "skills/web-panel/parts/theme.md",
+          "description": "The light/dark switch — ThemeToggle, useColorScheme, the two-class html contract and the CSS a theme must read, and the head bootstrap script from ./scheme.",
+          "purposes": [
+            "theme"
+          ],
+          "mentions": [
+            "ThemeToggle",
+            "useColorScheme",
+            "colorSchemeHelper",
+            "colorSchemeBootstrapScript",
+            "applyColorScheme",
+            "COLOR_SCHEME_KEY",
+            "COLOR_SCHEME_EVENT",
+            "ColorSchemeChoice",
+            "themeToggle",
+            "@owlmeans/web-panel/scheme"
+          ]
+        }
+      ]
     }
   ]
 }

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

@@ -1,6 +1,6 @@
 ---
 name: web-panel
-description: How to use @owlmeans/web-panel — base browser context factory (makeContext) with shadcn/Radix + Tailwind and the default OwlMeans router wired in, plus the two-layer navigation shell (NavLayout/TopNav/SideNav/Footer) and form/panel components. Auto-invoked when building a web app's makeContext, wiring its navigation or layout, or importing web panel components.
+description: How to use @owlmeans/web-panel — base browser context factory (makeContext) with shadcn/Radix + Tailwind and the default OwlMeans router wired in, the two-layer navigation shell (NavLayout/TopNav/SideNav/Footer), form/panel components, and the controlled JSON editor (`./editor`: JsonEditor), the standard icon + colour picker (`./picker`: IconColorPicker, ColorPicker, IconPicker, IconTile, ColorDot). Auto-invoked when building a web app's makeContext, wiring its navigation or layout, importing web panel components, or letting a person choose (or showing) an icon or a colour.
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,23 +8,90 @@ user-invocable: false
 # @owlmeans/web-panel
 
 **Layer:** Web (React)
-**Install:** `"@owlmeans/web-panel": "^0.1.18-rc.9"` in `dependencies`
+**Install:** `"@owlmeans/web-panel": "^0.1.18"` in `dependencies`
+
+## Choosing a component
+
+Pick the row for the job; the one-liner is the correct shape. Everything comes from the package
+root unless the import column names a subpath.
+
+| Job | Use | Import | Correct one-liner |
+|---|---|---|---|
+| 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 — 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 … />` |
+| A link to a screen | `Link` | root | `<Link module={web.about} />` |
+| A form | `Form`, `TextInput`, `SubmitButton`, `Button`, `ButtonSelector` | root | `<Form decorate validation={schema} onSubmit={save}><TextInput name="email" label /></Form>` |
+| A panel, a heading, an error | `Block`, `Text`, `Status` | root | `<Status error={error} />` |
+| An image upload | `ImageUploader` (react-dropzone options) | root | `<ImageUploader accept={{ 'image/*': [] }} onDrop={files => upload(files[0])} previewUrl={url} />` |
+| "Connection lost" prompt | `SocketReloadDialog` (mounted by `PanelApp`) | root | `cfg.socket = { reloadDialog: true }` |
+| The sign-in screen | `LoginScreen` / `LocalizedLoginScreen` / `appendLoginScreen` | root | `appendLoginScreen(context, { Logo })` |
+| Cookie consent | `PanelCookieConsent`, `PanelConsentMenuWidget` | `./consent` | `<PanelCookieConsent />` as a `PanelApp` child |
+| A person picks an icon AND a colour (a type's, a flow's, a label's mark) | `IconColorPicker` | `./picker` | `<IconColorPicker label="Mark" value={{ icon, color }} onChange={next => …} translate={usePickerTranslate()} />` |
+| A person picks a colour only | `ColorPicker` | `./picker` | `<ColorPicker label="Colour" value={color} onChange={setColor} />` |
+| A person picks an icon only | `IconPicker` | `./picker` | `<IconPicker label="Icon" value={icon} onChange={setIcon} color={color} />` |
+| The same, inline in a dialog the app already owns | `ColorSwatches`, `IconGrid` | `./picker` | `<IconGrid value={icon} onChange={setIcon} color={color} />` |
+| Show a chosen mark or colour (list, chip, header) | `IconTile`, `ColorDot` | `./picker` | `<IconTile icon={type.icon} color={type.tone} size="sm" />` |
+| Palette, icon names, colour maths — no React | `PICKER_*`, `pickerColorHelper`, `pickerIconHelper` | `./picker/vocabulary` (`pickerIconHelper`, `PICKER_ICONS`: `./picker`) | `pickerColorHelper.styleOf(color)` |
+| Editable or read-only JSON | `JsonEditor` | `./editor` | `<JsonEditor key={record.id} value={draft} onChange={setDraft} onValidityChange={setValid} ariaLabel="Record JSON" />` |
+| The current breakpoint | `useBreakPoint` / `useMapBreakpoint` | root | `useMapBreakpoint({ xs: 1, md: 2 }, 3)` |
+
+**Common mistakes:**
+
+- **Importing the package's private primitives.** `src/@/components/ui/*` (button, sheet, popover …)
+  and its `cn` are not exports; an app keeps its own shadcn components and never imports
+  `@owlmeans/web-panel/build/@/…` or expects `@/components/ui` to resolve to this package's copy.
+- **A missing `@source`.** The app's Tailwind entry must scan this package's `src`
+  (`@source "../../../node_modules/@owlmeans/web-panel/src";`) or every class used only here — the
+  shell, the footer, the picker — silently never reaches the stylesheet.
+- **Two `Toaster`s.** Mount it once, in the layout: two render every toast twice.
+- **`Form decorate` plus an own submit button.** `decorate` already renders the `Card`, the root
+  error and a `SubmitButton` whenever `onSubmit` is given; without `decorate` there is no submit
+  button at all and the caller renders one.
+- **A `Select`, radio group or hand-made swatch row for a colour or an icon a person chooses, or
+  `` `text-${color}-600` `` / `` `text-tone-${…}` `` built from a stored value.** A person-chosen colour
+  or icon is always edited with the `./picker` parts and rendered with `IconTile` / `ColorDot` (or
+  `pickerColorHelper.styleOf`); code-chosen tones (a status's meaning) stay the app's own classes.
+- **`usePickerTranslate()` outside `PanelApp` / `render()`.** It needs the i18n instance and throws
+  without one; the picker parts themselves never read i18n (pass `translate`, or get English).
 
 ## 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` / `Footer` | The shell's pieces, mountable on their own |
-| `components` submodule | shadcn/Radix panel/form components |
+| `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 |
+| `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`) |
+| `useMapBreakpoint(map, def?, breakpoint?)` | The `map` entry for the current breakpoint (or for the `breakpoint` passed), falling back to `def`. It **throws a `SyntaxError`** when neither yields a value, so give it a `def` or cover every breakpoint |
 | Re-exports from `@owlmeans/client-panel` | Cross-platform panel primitives, incl. `usePanelNav` and the `PanelNav*` types |
-| `main`, `exports`, `context`, `modules`, `types` | Wiring helpers |
+| Re-exports from `@owlmeans/client` / `@owlmeans/client-entrypoint` / `@owlmeans/route` | `bind`, `bindAll`, `bindScreen`, `handler`, `lazyHandler` / `lazyComponent` (+ `LazyHandler` / `LazyComponent` / `LazyComponentOptions` types — see the `client` skill), `clientRequestHelper` (`provideRequest`), `stab`, `route`, `croute`, `frontend`, `useNavigate`, `useEntrypoint`, `useValue` |
+| Re-exports from the surrounding layers | `config`, `service`, `addWebService`, `AppType` / `HOME` / `ROOT` / `BASE` / `GUEST`, `DISPATCHER`, `CAUTHEN_FLOW_ENTER`, `DAUTH_GUARD`, `bindExternalAuthentication`, `Dispatcher`, `appendWebAuthService`, `flow` / `configureFlows` / `useFlow` / `FLOW_PARAM` / `SERVICE_PARAM`, `useI18n*` / `useLanguage` / `composePrefix`, `i18nHelper` (`addI18nApp` / `addI18nLib`) / `SUPPORTED_LNGS` |
 
 ## Subpath Exports
 
 - `./auth` — auth panel components for web
-- `./auth/modules` — auth panel module declarations
+- `./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 — 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
 
@@ -38,100 +105,86 @@ export const makeContext = <C extends Config, T extends Context<C>>(cfg: C): T =
   const context = makeBasicContext<C, T>(cfg)
   appendOidcGuard<C, T>(context)
   appendStateResource<C, T>(context, VIB_PROJECT_STATE)
-  context.makeContext = makeContext as typeof context.makeContext
   return context
 }
 ```
 
-### Navigation — `NavLayout`
+**A context is created once per process, by one factory.** An app factory calls the factory of the
+layer below it, applies idempotent `append*(context)` mixins, and returns that same context — the
+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.
 
-`NavLayout` is the application shell. A layout entrypoint elevates 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, modules and the shell all read the same aliases.
+### Links — `Link`
 
-```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' },
-      ]
-    },
-  ],
-}
+`Link` renders an `<a>` whose `href` is the entrypoint's own answer: it asks
+`entrypoint.url()` and puts the result on the anchor, so a link into another service comes out
+absolute and a link inside this one comes out as a path. Address a screen by **alias** (or hand it
+the entrypoint you already hold); `src` is the escape hatch for a literal URL.
 
-export const footerLinks: PanelNavLink[] = [
-  { alias: HOME, label: 'My App' },
-  { href: 'https://owlmeans.com', label: 'OwlMeans', open: true },
-]
+```tsx
+import { Link } from '@owlmeans/web-panel'
 
-export const MainLayout: FC<PropsWithChildren> = ({ children }) =>
-  <NavLayout nav={navConfig} title="My App" footer={footerLinks}>{children}</NavLayout>
+<Link module={web.about} />                                  // label from `modules.<alias>`
+<Link module={web.session} name="nav.session">Session</Link>  // explicit i18n key
+<Link src="https://owlmeans.com" open>OwlMeans</Link>         // literal target, new tab
 ```
 
-**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.
+Resolution is asynchronous — `href` is absent for the first paint and settles once the URL is
+known — so never key a test or a layout on the anchor having an `href` synchronously. The label
+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.
 
-| Component | Props |
-|---|---|
-| `NavLayout` | `nav: PanelNavConfig`, `translate?`, `title?: ReactNode`, `home?: string` (brand target — defaults to the first section's first item), `actions?: ReactNode`, `footer?: PanelNavLink[] \| ReactNode`, `contentClassName?`, `className?`, `style?` |
-| `TopNav` | `config: PanelNavConfig`, `translate?`, `ariaLabel?`, `className?`, `style?` |
-| `SideNav` | the same, plus `variant?: 'side' \| 'bar'` |
-| `Footer` | `links?: PanelNavLink[]`, `translate?`, `children?`, `className?`, `style?` |
-
-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`.** `SideNav` builds on the existing `Button`; `TopNav` uses the shadcn
-  `navigation-menu` primitive — see the `@` contract below.
-
-## Consumer setup — the `@` contract and Tailwind
-
-`web-panel` emits `@/components/ui/*` and `@/lib/utils` verbatim; the app's bundler resolves `@` to
-its own shadcn copy. Vendor every primitive the package imports: `alert`, `button`, `card`, `input`,
-`label`, `navigation-menu`, `progress` (plus `separator` if you use it), and add
-`@radix-ui/react-navigation-menu` alongside the other Radix peers.
-
-Then point Tailwind at the built package. Its oxide scanner reads the CSS root plus `@source`
-directives only, and excludes `node_modules` — so classes that exist **only** inside `web-panel`
-components (the whole navigation shell and footer) never reach the stylesheet, and the app renders
-an unstyled menu. In the app's Tailwind entry:
+## Consumer setup — package boundary and Tailwind
+
+`web-panel` ships its shadcn primitives and `cn` helper as private implementation files under its
+own `build/@/` tree. Package source imports them only through relative specifiers; it must never
+emit an absolute `@/…` import, because that alias belongs to the consuming application and makes a
+fresh installation depend on unrelated files. `cn` is not exported: a consumer keeps its own
+class-name helper and never vendors or imports this package's UI primitives.
+
+Consumers still supply the package's peer dependencies: the Radix primitives (`alert-dialog`,
+`dialog`, `label`, `navigation-menu`, `popover`, `progress`, `separator`, `slot` — `dialog` and
+`popover` on the same Radix generation) plus React, Tailwind and the usual utility libraries. A
+consumer may have its own shadcn `@` alias, but it is unrelated to this package.
+
+Then point Tailwind at the installed package's **`src`** directory. Its oxide scanner reads the CSS root
+plus `@source` directives only, and excludes `node_modules` — so classes that exist **only** inside
+`web-panel` components (the whole navigation shell and footer) never reach the stylesheet, and the
+app renders an unstyled menu. In the app's Tailwind entry:
 
 ```css
 @import "tailwindcss";
 
-@source "../../../node_modules/@owlmeans/web-panel/build";
+@source "../../../node_modules/@owlmeans/web-panel/src";
 ```
 
-Adjust the relative depth to your own layout; the target is the installed package's `build`.
+Adjust the relative depth to your own layout. Source ships in the published tarball and is tracked
+in a linked workspace, so it is the reliable scan target in both modes.
 
 ## Depends On
 
 - `@owlmeans/web-client`, `@owlmeans/client-panel`, `@owlmeans/client-i18n`, `@owlmeans/web-router`
+- `@owlmeans/client-socket` — `appendSocketStatus`, `useSocketStatus`, `useSocketRetry`, behind `SocketReloadDialog`
+- `react-colorful` — the custom-colour wheel of `./picker` (`customColors`); `sonner` — toasts
 - Peers (app-provided): `react`, `react-dom`, `react-hook-form`, `tailwindcss`, `tailwind-merge`,
-  `clsx`, `class-variance-authority`, `lucide-react`, `ajv`, and the `@radix-ui/react-*` primitives
-  (`label`, `navigation-menu`, `progress`, `separator`, `slot`). No MUI, no react-router.
+  `clsx`, `class-variance-authority`, `lucide-react` (`./picker` imports its ~250 catalogue icons
+  statically), `ajv`, and the `@radix-ui/react-*` primitives (`alert-dialog`, `dialog`, `label`,
+  `navigation-menu`, `popover`, `progress`, `separator`, `slot`). No MUI, no react-router.
+- `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 |
+|---|---|
+| [editor](parts/editor.md) | Editing or displaying JSON, syntax diagnostics, controlled text, read-only previews and document identity |
+| [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`) |

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

@@ -0,0 +1,114 @@
+---
+name: consent
+description: The ./consent subpath — PanelCookieConsent and PanelCookiePolicy bound to the app's i18n, cfg.cookieConsent, a geo plugin, and the host-menu presence service.
+metadata:
+  purposes: consent
+  mentions: PanelCookieConsent, PanelCookiePolicy, PanelConsentMenuWidget, useConsentMenuPresence, appendConsentWidgetService, appendConsentGeoPlugin, cookieConsent, @owlmeans/web-panel/consent
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/web-panel — Cookie consent
+
+## 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 — package boundary and Tailwind* in [SKILL.md](../SKILL.md). 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`).