@visns-studio/visns-components 6.6.4 → 6.15.0

package/README.md

@@ -9,6 +9,1034 @@ A comprehensive React component library used by the VISNS Studio team for CRM an
 
 VISNS Components is a React-based UI component library that provides a set of reusable, consistent, and customizable components for building web applications. It includes components for authentication, data grids, forms, navigation, and more, designed to work seamlessly together.
 
+## Recent Updates (v6.15.0)
+
+### The detail page joins the dashboard system
+
+`GenericDetail`'s overview was a grid of tinted boxes — every single field in
+its own bordered, filled container, so a summary of six facts arrived as six
+competing panels and the card around them counted for nothing. The card is the
+container now; the fields inside it are label-above-value pairs on the card's
+own surface, on a real two-column grid (`--detail-overview-columns`) so the
+right column's labels line up with the left's instead of drifting with whatever
+the row above happened to need. Section headings take the page's ink at
+0.9rem/600, the eyebrow treatment they used to wear having moved down to the
+field labels, and a field with nothing in it says so with a muted dash rather
+than trailing off after its label.
+
+A section can carry `meta` — the same item shape as `content` — rendered as
+quiet facts at the far end of its heading, for the one or two things that
+describe the whole card (a count, a last-updated stamp) rather than sitting
+among the fields.
+
+```json
+{
+  "title": "Template",
+  "meta": [{ "id": "checkpoint_count", "label": "Checkpoints" }],
+  "content": [ ... ]
+}
+```
+
+### Tabs as a strip, for pages that want one
+
+`page.tabLayout: "underline"` lays a detail page's tabs across the top with an
+accent edge under the selected one, instead of down a rail on the left. The
+rail costs a fifth of the page width, which is worth paying at seven tabs and
+is not at two. It is the same treatment narrow viewports already gave any flat
+rail, promoted out of the phone media query into a shared mixin and exposed as
+`<TableFilter variant="underline">`. Every existing page keeps the rail.
+
+### Counts look like counts
+
+An `arrayCount` column renders its number in a small neutral pill instead of as
+a bare digit in a text column, and an empty list shows a muted dash instead of
+an empty cell — an empty cell is what a column shows when it has no answer, and
+here there is one. `arrayCountFrom` in `src/components/utils/displayValue.js`
+also fixed what the count was: the old `value.length` returned the character
+count for a JSON string that was never decoded, and nothing at all for a keyed
+object. `sortable: false` now turns the header control off, for the JSON-backed
+counts where server-side ordering is lexicographic nonsense.
+
+### Buttons on a detail page line up
+
+The floating action bar's own `display: block; float: left` was overriding the
+shared button mixin, so an icon and its label sat off-centre and the bar's
+buttons were visibly shorter than every other button in the app. It is a flex
+row of shared controls now, and Cancel — the way back out of editing, not a
+destructive act — is a neutral secondary rather than error red beside the Save
+it competes with. An overview form can name its own button with
+`form.editLabel`.
+
+## Recent Updates (v6.14.0)
+
+### The vault list fits the window
+
+`VaultManager` no longer asks for a fixed 25 entries. It measures the room
+between the top of the list and the bottom of the window, subtracts the pager,
+divides by the height of a row it has actually rendered, and asks the server
+for exactly that many — so the page never scrolls and the pager is always in
+view. Resizing refits after 150ms of quiet and keeps the reader on the page
+that still holds the entry they were looking at.
+
+The arithmetic is pure and tested: `fitRowsToHeight({available, pagerHeight,
+rowHeight, chrome, min, max})` in `src/components/vault/vaultFit.js`, with
+`pageForIndex` / `firstIndexOfPage` beside it. It clamps to `[5, 100]` — 100 is
+`VaultController::MAX_PER_PAGE`, which silently clamps anything larger — and
+returns `null` when it has nothing to measure, which is what stops the list
+flashing a five-row page on first paint.
+
+```jsx
+<VaultManager perPage={25} />   // opt out: a fixed size turns the fitting off
+```
+
+### One place for each vault action
+
+Every row now ends in the same cluster: **copy username**, **copy password**,
+**copy 2FA code** as icon buttons, a hairline, then Edit / Log / Delete with
+their words intact. The copy-username glyph that used to sit inside the
+username cell is gone — each action exists once. A copy that lands shows a tick
+on the button for a second and a half rather than relying on a toast alone, and
+the 2FA copy reports the server's own countdown ("2FA code copied · valid for
+14s"), so a code with three seconds left is visibly worth re-copying. The
+ticking `OtpChip` stays in the 2FA column for anyone who wants to read the code
+rather than paste it.
+
+The fetch behind both is `fetchOtp(request, routes, entryId)` in
+`src/components/vault/vaultOtp.js` — the request function is a parameter, so
+the module carries no React and `node --test` drives it with a fake.
+
+### Checkboxes and radios the host cannot stretch
+
+The vault's visibility radios rendered as 34×22 ovals inside the CRM, whose
+untyped `input` rules set a width and a text-field height. Asking for the
+native widget back was not enough, so `Vault.module.scss` now draws the control
+itself: `appearance: none`, every axis pinned (`width`/`height`/`min`/`max` and
+the flex basis), the radio's dot painted with an inset ring and the checkbox's
+tick with a background image. The selector is element-qualified
+(`input.checkControl`) so it outweighs a host rule of the form `.form input`.
+
+## Recent Updates (v6.13.0)
+
+### Desktop alerts
+
+Native browser notifications while a tab of the app is open — a new task
+assigned to you, or a text arriving on one of your lines — so the bell badge is
+not the only thing that has to be watched.
+
+No service worker and no push subscription. This is the plain `Notification`
+API, which means the honest scope is *while a tab is open*: close the CRM and
+the alerts stop. It also needs a secure context — `https://` or `localhost`;
+over plain http the API is absent and every entry point below quietly no-ops.
+
+**The module** — `src/components/notify/desktopNotifications.js`, exported as
+`desktopNotifications` (and as the individual `desktopNotify`,
+`desktopAlertsEnabled`, `desktopAlertsSupported`, `getDesktopPermission`,
+`requestDesktopPermission`, `setDesktopAlertsEnabled`,
+`DESKTOP_ALERTS_STORAGE_KEY`, `DESKTOP_ALERT_AUTO_CLOSE_MS`):
+
+```js
+import { desktopNotifications } from '@visns-studio/visns-components';
+
+desktopNotifications.notify({
+    title: 'New text from Margaret Chen',
+    body: 'Are we still on for Thursday?',
+    tag: 'sms-14',              // one toast per subject; a burst replaces itself
+    url: '/sms?thread=14',      // where a click lands
+    navigate,                   // react-router's navigate, when there is one
+    force: false,               // show even if the tab is focused
+});
+```
+
+Four gates, all of which must open: the API exists, permission is `granted`,
+the user's own switch is on, and **the tab is not already visible and focused**
+— the in-app UI is showing the same thing, and an OS toast on top of it is
+noise. A toast closes itself after 8 seconds; a click focuses the window,
+closes the toast and then calls `onClick`, or `navigate(url)`, or
+`location.assign(url)` in that order.
+
+The switch lives in `localStorage` under **`visns.desktopAlerts`** (`'on'` /
+`'off'`). Unset means *on once permission has been granted* — someone who has
+just been through the browser prompt should not have to say yes twice.
+
+**The bell** — `Notification` takes two new optional props:
+
+| Prop | Type | Notes |
+| --- | --- | --- |
+| `echo` | Echo instance or `() => echo` | A factory is called inside the effect, so nothing connects for a consumer that passes none. |
+| `channel` | `string \| null` | The user's private channel. `null` (the default) leaves the bell on polling. |
+
+Laravel broadcasts these as `BroadcastNotificationCreated`, which is what
+Echo's `.notification()` helper binds to; the payload is prepended to the list
+in the same shape the poller returns, so a live item and a polled one are
+interchangeable. Polling stays as the fallback — every 60s normally, dropping
+to 5 minutes once a channel reports `pusher:subscription_succeeded`. A compact
+**Desktop alerts** row at the foot of the dropdown owns the switch, asks for
+permission on first enable, and reads *Blocked in browser settings* when the
+browser has already refused.
+
+The channel name is the consumer's to build, and should carry the environment
+when one Pusher app serves several deployments — the same convention as
+`sms-line.{id}.{env}`:
+
+```jsx
+<Notification
+    setSystemAuth={setSystemAuth}
+    echo={getEcho}
+    channel={`user.${userProfile.id}.${import.meta.env.VITE_APP_ENV}`}
+/>
+```
+
+Server-side that is `User::receivesBroadcastNotificationsOn()` plus a
+`Broadcast::channel('user.{id}.' . config('app.env'), ...)` authorising the
+owner. Pass `null` rather than guessing the suffix: the wrong one puts a
+development browser on the production channel.
+
+**Messages** — `SmsInboxBadge` raises the same alert on `sms.received` (never
+on `sms.updated`), titled with the conversation's display name and carrying the
+first 120 characters of the message.
+
+## Recent Updates (v6.12.0)
+
+### The application header, refined
+
+`Navigation`'s `layout="full"` bar, restyled in `Navigation.module.scss` and
+`GenericMain.module.scss`. No new markup, no new props, no behaviour change
+beyond the two fixes noted at the end.
+
+- **The bar** now ends somewhere: a 1px `rgba(255,255,255,.08)` hairline and a
+  soft two-stop shadow, instead of navy running straight into the page. Its
+  height is `--nav-logo-height` — the logo is capped to that figure and the bar
+  takes it as a minimum, so swapping a logo no longer resizes the shell.
+- **Nav items** are 0.9rem/500 in a `--nav-item-radius` pill: `rgba(255,255,255,.08)`
+  on hover, `rgba(255,255,255,.14)` when current, plus a 2px
+  `--nav-active-bar-color` rule sitting on the bar's bottom edge (the items
+  stretch the full height of the bar so it can). The brand-red block the
+  current page used to wear is gone. Items with a sub-menu draw a caret, and
+  the sub-menu itself is a padded panel with rows that respond to the pointer —
+  its hover state was previously identical to its resting state, under an
+  `!important` that made it unreachable.
+- **Action chips** sit in a quieter `rgba(255,255,255,.08)` tray as borderless
+  34px circles, filling to `.14` on hover and taking the highlight colour on
+  the icon when active or open. A hairline sets the last chip (sign out) apart.
+  The second, contradictory copy of the chip rule — 32px, a 1px border in the
+  bar's own colour, a 1.05 hover scale — has been deleted; that invisible
+  border is what made the group read as a row of outlined squares.
+- **Focus-visible rings** on nav links, sub-menu rows and chips: 2px in the
+  highlight colour, offset 2px. The bar suppressed outlines everywhere and put
+  nothing back.
+- `.hactions-alternate` / `.nav-item-alternate` get the same treatment against
+  a light surface, so the alternate theme is the same design and not a second
+  one.
+- Several declarations referenced `--radius-pill`, `--radius-sm`, `--speed`,
+  `--ease` and `--shadow-sm` with **no fallback**. An undefined custom property
+  with no fallback is invalid at computed-value time and the whole declaration
+  is discarded — which is why, in a project that had not declared those names,
+  the "pill" was a square and the bar had no shadow. Every one of them now
+  carries its default.
+
+**New hooks** (all optional, all no-ops when unset — the documented block at the
+top of `Navigation.module.scss` carries the full set):
+
+| Hook | Default | What it moves |
+| --- | --- | --- |
+| `--nav-item-radius` | `var(--radius, 6px)` | The nav item's hover/active pill, and the sub-menu rows. |
+| `--nav-active-bar-color` | `var(--highlight-color, #fff)` | The rule under the current page, and every focus ring. |
+| `--nav-chip-radius` | `var(--radius-pill, 999px)` | One action chip. |
+
+Changed defaults: `--nav-item-font-size` is `0.9rem` (was `var(--font-size-sm)`,
+undefined in most projects and therefore nothing at all), `--nav-item-padding`
+is `0.5rem 0.8rem`, `--nav-action-size` is `34px`.
+
+**Two fixes that came with it**
+
+- Active-item detection moved to `src/components/navActive.js` (`isNavActive`,
+  covered by `tests/navActive.test.mjs`). It used to branch on how many
+  segments the URL had, consult an item's children in only one of those
+  branches, and compare paths with `String.includes` — so `/tasks` matched
+  `/tasks-archive`, and on `/reports`, which the Admin item owns as a child,
+  nothing in the bar was marked at all. Now: a path matches when it is the
+  item's path or sits under it as a whole segment, and an item is active when
+  it matches itself or any child.
+- Nav labels and sub-menu rows no longer set a native `title`, which drew the
+  browser's own tooltip on top of the menu it was describing. Every built-in
+  chip now carries both `data-tooltip-content` and `aria-label`, falling back
+  to a humanised id (`callRecordings` → "Call Recordings") when a config entry
+  brings no label.
+
+## Recent Updates (v6.11.0)
+
+### Messaging (SMS) — a virtual inbox on Zoom Phone lines
+
+A new module under `src/components/sms`, plus two icons in `Navigation`'s
+`SETTING_ICONS`. Nothing existing changes behaviour.
+
+Zoom is **not connected yet**, and the UI is built around that rather than
+around the day it is. `GET {base}/status` reports a transport of `zoom`, `log`
+or `null`, and every surface here says in words which one it is looking at:
+a message you send on `null` is saved, queued, and shown as *Held — not
+connected* rather than as an error, because it is not one.
+
+**Components**
+
+| Export | What it is |
+| --- | --- |
+| `SmsInboxBadge` | The header popover. Mounts as an account action through Navigation's `renderers` slot. |
+| `SmsInbox` | The page: line selector, search, filters, thread list, conversation, composer. |
+| `SmsThreadPanel` | One conversation on its own — header, timeline, composer — for embedding on a client page. |
+| `SmsComposeModal` | New message: line, a number or a client typeahead, templates, send. |
+| `SmsLineSettings` | Settings → Messaging: status card, lines table, templates. |
+| `useSmsLive` | Echo subscription per line, with a 30-second polling fallback when there is no Echo. |
+| `makeSmsEndpoints`, `DEFAULT_SMS_ENDPOINTS`, `resolveSmsEndpoints` | The URL table. |
+| `segmentCount`, `normaliseNumberForDisplay`, `looksLikeNumber`, `toE164`, `relativeTime`, `groupMessagesByDay`, `initialsFor`, `threadDisplayName`, `describeTransport`, `isHeldTransport`, `SMS_LIMITS`, `SMS_MAX_SEGMENTS`, `SMS_STATUS_LABELS` | Pure helpers, all covered by `tests/sms.test.mjs`. |
+
+#### `SmsInboxBadge`
+
+| Prop | Default | Notes |
+| --- | --- | --- |
+| `setting` | — | The navigation entry. Only `label` is read, for the tooltip and aria-label. |
+| `userProfile` | — | Accepted so the component matches what Navigation's renderers hand over; unread. |
+| `setSystemAuth` | — | Same. |
+| `endpoints` | `DEFAULT_SMS_ENDPOINTS` | Partial objects are merged over the defaults. |
+| `echo` | `null` | An Echo instance **or** a factory (`() => getEcho()`). A factory is called inside the effect, so a user without messaging never opens a Pusher connection. |
+| `channelFor` | `` (id) => `sms-line.${id}` `` | Return the environment-suffixed name if the deployment shares a Pusher app. |
+| `inboxUrl` | `'/sms'` | A row navigates to `` `${inboxUrl}?thread=<id>` ``. |
+| `limit` | `8` | Sent as `per_page`. |
+
+The trigger is the same 40px chip as `Notification` and `VaultQuickSearch`,
+with the same badge, so three unread counts in the header read as one row.
+↑↓ move the highlight, Enter opens the conversation, Esc closes. The popover
+carries `data-nav-overlay="open"` so `.hactions` stops clipping it.
+
+Each row is a four-column grid — `3px | 32px | minmax(0, 1fr) | auto` — and
+the unread marker lives in that fixed 3px track rather than in a
+`border-left`, so an unread row and a read one are measured identically and
+the avatars line up. The left pane of `SmsInbox` uses the same contract.
+`initialsFor` understands the CRM's own name format: brackets and honorifics
+are dropped and a comma is read as "Surname, First", so "Perera, Darshini
+(Mrs)" is `DP` rather than `P(`. An unnamed number is `#` — two of its digits
+in a circle read as data.
+
+Both list modules (`Sms` and `Vault`) also reset `> li` explicitly and restate
+their row geometry at `.rows > .row`. See "Navigation: the chip rules no
+longer reach into overlays" below — the host's `li` rules are 0,1,2 and no
+single module class can outrank them.
+
+#### Layout tokens
+
+| Token | Default | What it sizes |
+| --- | --- | --- |
+| `--s-inbox-offset` | `230px` | Subtracted from `100vh` for the host's own chrome, so the two panes scroll inside their card instead of the page scrolling under them. Set it on any ancestor if the CRM header is a different height. |
+| `--s-control` | `34px` | One height for the search field, the line selector, Templates and Send, so a row of controls lines up on both edges. |
+| `--s-select` | `primary @ 8%` | The selected thread row. |
+
+#### `SmsInbox`
+
+| Prop | Default | Notes |
+| --- | --- | --- |
+| `endpoints` | `DEFAULT_SMS_ENDPOINTS` | Merged over the defaults. |
+| `userProfile` | `null` | Accepted for consistency; unread. |
+| `canManage` | `false` | Shows the settings link and the "Simulate reply" tool. |
+| `echo` | `null` | Instance or factory. **The page owns the subscription** and feeds the conversation pane, so the pane is mounted with `subscribe={false}`. |
+| `channelFor` | `` (id) => `sms-line.${id}` `` | |
+| `settingsUrl` | `'/settings/sms'` | |
+| `clientUrl` | `` (id) => `/clients/${id}` `` | The "Open client" chip in the conversation header. |
+| `pageTitle` | `'Messages'` | |
+
+Deep links work: `?thread=<id>` opens that conversation, and selecting one
+rewrites the query with `history.replaceState` rather than pushing a history
+entry per click. Two panes above 900px; below it, one at a time with a back
+button. Filters are All / Unread / Archived; the list pages with **Load more**.
+
+#### `SmsThreadPanel`
+
+| Prop | Default | Notes |
+| --- | --- | --- |
+| `threadId` | — | `null` renders the "pick a conversation" state. |
+| `endpoints` | `DEFAULT_SMS_ENDPOINTS` | |
+| `echo`, `channelFor` | `null` | Only used when `subscribe` is true. |
+| `subscribe` | `true` | `false` when a parent already holds the subscription. |
+| `liveEvent` | `null` | `{seq, payload}` from that parent. `seq` must change per event. |
+| `refreshToken` | `0` | Changing it re-reads the conversation — how the inbox's poller reaches the pane. |
+| `status` | `null` | The `/status` payload. Fetched here when not supplied. |
+| `templates` | `null` | Fetched lazily on first opening the Templates menu when not supplied. |
+| `lines` | `null` | `[{id, label}]`, only so a template's `{line}` has a label to fill with. `SmsInbox` passes its own list. |
+| `canManage` | `false` | Gates "Simulate reply", which is also hidden once the transport is `zoom`. |
+| `clientUrl` | `` (id) => `/clients/${id}` `` | |
+| `onThreadChange`, `onMessage` | — | The inbox keeps its list in step through these. |
+| `onBack` | `null` | Renders the back button (visible only below 900px). |
+| `showTransportBanner` | `true` | The inbox sets `false` — it draws its own. |
+| `compact` | `false` | A shorter composer, no transport banner sizing for a page. |
+
+**Templates fill themselves in.** A body reading `Hi {first_name}, a reminder
+of your review on {date} at {time}` is completed from the open conversation the
+moment it is inserted — `{first_name}`, `{last_name}`, `{name}`/`{full_name}`,
+`{date}`, `{time}`, `{number}` and `{line}`, case-insensitively, and `{{...}}`
+and `{ ... }` as well. The names come from `thread.client` (which the backend's
+`messaging.client_details` hook enriches with `first_name`, `last_name` and
+`next_event`), falling back to the contact label and then to parsing the CRM's
+filed `Surname, First (Title)` form; `{name}` is always the spoken order, never
+the filed one. `{date}` and `{time}` come from `client.next_event.date` as
+`Mon 24 Aug` and `2:30 pm`.
+
+A token that cannot be filled is **left exactly as written**, and the composer
+selects the first one after inserting: `your review on {date}` is visibly a
+blank to type over, where dropping it would leave `your review on ` and be sent
+that way. `fillTemplate(body, context)` and `nextPlaceholder(text, from)` are
+exported from `smsHelpers` for anything else that wants the same rules.
+
+Sending appends an optimistic bubble, then reconciles it against the 201
+payload — matched on the temporary key it carries, so an `.sms.updated`
+broadcast arriving first cannot produce a duplicate. Enter sends by default
+(Shift+Enter for a newline); the toggle beside the counter persists in
+`localStorage`. The counter is character count, segment count and encoding,
+because "70" with no explanation looks like a bug: one curly quote or emoji
+drops the message from GSM-7 to UCS-2 and the limit with it.
+
+#### `SmsLineSettings`
+
+| Prop | Default | Notes |
+| --- | --- | --- |
+| `endpoints` | `DEFAULT_SMS_ENDPOINTS` | |
+| `userProfile` | `null` | Accepted for consistency; unread. |
+| `staffOptions` | `[]` | **Required in practice** — `[{id, name}]`. `GET {base}/settings/lines` returns the staff already on each line but no route lists everyone who could be, and inventing one here would be a second contract. With nothing supplied the picker falls back to the union of staff already on lines. |
+| `pageTitle` | `'Messaging'` | |
+
+#### Endpoints
+
+`makeSmsEndpoints(base = '/ajax/sms')` builds the table; every component takes
+a partial `endpoints` object merged over it. Session + CSRF come from
+`CustomFetch`, and GET is never cached.
+
+```
+GET    {base}/status                         -> {transport, connected, lines_count, unread_total}
+GET    {base}/lines                          -> {data: [{id, label, phone_number, display_number, active, unread_count}]}
+GET    {base}/unread                         -> {total, by_line, by_thread}
+GET    {base}/threads?line_id&search&unread_only&archived&page&per_page
+POST   {base}/threads                        {line_id, to, body?}   -> 201 {thread, message|null}
+GET    {base}/threads/{id}?before&limit      -> {thread, messages, has_more}   (marks read)
+PUT    {base}/threads/{id}                   {client_id, client_name, contact_name}
+POST   {base}/threads/{id}/messages          {body}  -> 201 {message}
+POST   {base}/threads/{id}/read | /archive | /unarchive      -> 204
+POST   {base}/threads/{id}/simulate-inbound  {body}  -> 201 {message}   (manage, non-zoom only)
+GET    {base}/clients/search?q=
+GET/POST/PUT/DELETE {base}/templates[/{id}]
+GET/POST/PUT/DELETE {base}/settings/lines[/{id}]
+```
+
+Broadcasts arrive on the private channel `sms-line.{lineId}` as `.sms.received`
+and `.sms.updated`, both carrying `{thread, message}`.
+
+#### Wiring it into a CRM
+
+```jsx
+<Navigation
+    renderers={{
+        messages: (p) => (
+            <SmsInboxBadge
+                {...p}
+                echo={getEcho}
+                channelFor={(id) => `sms-line.${id}.${import.meta.env.VITE_PUSHER_ENV}`}
+            />
+        ),
+    }}
+/>
+```
+
+```json
+{
+    "id": "messages",
+    "icon": "message",
+    "label": "Messages",
+    "permission": false,
+    "permissionKey": "Messaging Access"
+}
+```
+
+`message` (MessageSquare) and `messages` (MessagesSquare) were added to
+`SETTING_ICONS`.
+
+#### The fixture
+
+`yarn dev:sms` serves `dev/sms-fixture.html` on port 5181 against an in-memory
+backend (`dev/smsMockServer.js`): three lines, twelve conversations, mixed
+statuses, one thread deep enough to page. The transport switch in the fixture
+header is the point of it — on `null` a sent message stays *Held*, on `log` it
+reaches *Sent*, on `zoom` it reaches *Delivered*. The mock also exports a fake
+Echo, so "Simulate an inbound" pushes a real broadcast and the badge, the list
+and the open conversation all move at once.
+
+## Recent Updates (v6.10.0)
+
+### Vault — a staff password manager
+
+A new module under `src/components/vault`, plus the two small openings in
+shared code it needed. Nothing existing changes behaviour.
+
+**Components**
+
+| Export | What it is |
+| --- | --- |
+| `VaultQuickSearch` | The header popover. Mounts as an account action through Navigation's new `renderers` slot. |
+| `VaultManager` | The page: search, filter, create, edit, delete/restore, access log. |
+| `VaultEntryForm` | The create/edit modal, usable on its own. |
+| `PasswordGenerator` | The generator popover behind the form's "Generate" button. |
+| `QrScanner` | The camera panel behind the form's "Scan QR" button. |
+| `decodeImageData`, `decodeFromSource`, `decodeFromBlob` | The QR readers. `jsqr` stays behind a dynamic import inside them. |
+| `OtpChip` | One entry's 2FA code, on demand, with a countdown ring. |
+| `VaultAccessLog` | Per-entry and global access log. |
+| `VaultConfirmPanel` | The "confirm your CRM password" form, driven by `useVaultReveal`. |
+| `useVaultReveal` | The reveal + confirm + retry flow, shared by both surfaces. |
+| `makeVaultEndpoints`, `DEFAULT_VAULT_ENDPOINTS`, `resolveVaultEndpoints` | The URL table. |
+| `parseOtpAuthUri`, `generatePassword`, `scorePassword`, `formatOtp`, `secondsUntilBoundary`, `matchesShortcut`, `shortcutLabel`, `isValidBase32`, `cleanBase32`, `describeOtpConfig`, `hostFromUrl`, `openableUrl`, `parseTags`, `OTP_DEFAULTS` | Pure helpers, all covered by `tests/vault.test.mjs`. |
+
+#### `VaultQuickSearch`
+
+| Prop | Default | Notes |
+| --- | --- | --- |
+| `setting` | — | The navigation entry. Only `label` is read, for the tooltip and aria-label. |
+| `userProfile` | — | Accepted so the component matches what Navigation's renderers hand over; unread. |
+| `setSystemAuth` | — | Same. |
+| `endpoints` | `DEFAULT_ENDPOINTS` | Partial objects are merged over the defaults. |
+| `manageUrl` | `'/settings/vault'` | Where "Manage vault" and "Add a password" go. |
+| `shortcut` | `['mod+k', 'mod+shift+k']` | A string or a list; any one of them opens the popover. `mod` is ⌘ on a Mac, Ctrl elsewhere. The first is what the footer and the trigger tooltip print. |
+| `limit` | `8` | Sent as `per_page`. |
+
+**⌘K** (Ctrl+K off a Mac) opens it from anywhere; ⌘⇧K still does too. The
+listener is on `window` in the capture phase, because the CRM is full of
+controls that stop keydown from propagating — the data grid, the rich text
+editors, react-select — and a bubbling listener behind any of them never hears
+the key. It stands down while a modal dialog is open and while the caret is in
+rich text (a TinyMCE body is `contenteditable` in an iframe, and an editor's
+own ⌘K has the better claim).
+
+↑↓ move the highlight, Enter reveals and copies the highlighted row's
+password, Esc closes. Hovering a row highlights it. With a row highlighted,
+`Alt+U` copies its username and `Alt+O` opens its 2FA code — Alt-modified
+because focus never leaves the search box, so a bare letter is a character
+being typed into the query. The footer lists both.
+
+The popover is a 560px opaque panel with its own border and shadow, headed by
+a permanent primary **Open password manager** button — the manager is the only
+place entries can be added, edited or deleted, so it is never more than one
+click away.
+
+Each result is **one line**: a title, then `· username · host` in muted text,
+truncated with an ellipsis (the whole `title — username — url` is in the row's
+`title` attribute), and on the right a cluster of 29px icon buttons that never
+wraps — copy username, copy password, the 2FA chip, open site. Each carries a
+tooltip and an aria-label. They were labelled pills, and with a real title
+beside a real email username they spilled onto two and three rows per entry.
+The 2FA chip is the one that grows: idle it is the same square button, and once
+a code is fetched it expands in place to the digits and countdown ring.
+
+There is no "show the password" here. A revealed password goes to the
+clipboard and nowhere else — this popover hangs off the header of a screen
+other people walk past, and a password printed into a list is one anyone behind
+the desk can read. Nothing in a row ever adds a second line. (The only time a
+password is put on screen is when the browser refuses the clipboard outright,
+and then it goes in the panel's own fallback field, labelled and dismissable.)
+`VaultManager` keeps its own reveal, which is a deliberate page-level action.
+
+#### `VaultManager`
+
+| Prop | Default | Notes |
+| --- | --- | --- |
+| `endpoints` | `DEFAULT_ENDPOINTS` | As above. |
+| `userProfile` | — | Accepted for symmetry with the library's other pages; the server decides what a user may see, so nothing here reads it. |
+| `canManage` | `false` | Gates "Show deleted", the global access log, the per-entry log button, and whether an entry may be shared with the team. |
+| `pageTitle` | `'Password manager'` | |
+
+It reads `?create=1&title=…` from the URL on mount and opens the form
+prefilled — that is the link the quick search's empty state produces.
+
+A heading and a primary "New entry" button, then one toolbar holding search,
+the visibility filter, "Show deleted" and the global access log, then the
+table: title (with the host beneath it), username with a copy button, URL,
+visibility pill, 2FA, updated, and labelled row actions — Copy password, Edit,
+Log, Delete, or Restore on a deleted row. Below 1200px the URL column folds
+away and the host under the title carries it instead, so an iPad at 1024px
+never scrolls sideways.
+
+#### The endpoints object
+
+```js
+import { makeVaultEndpoints } from '@visns-studio/visns-components';
+
+const endpoints = makeVaultEndpoints('/ajax/vault'); // the default
+```
+
+```js
+{
+  list: base,                          // GET  ?search=&page=&per_page=&sort=&direction=&include_deleted=1
+  show: id => `${base}/${id}`,         // GET
+  create: base,                        // POST
+  update: id => `${base}/${id}`,       // PUT
+  destroy: id => `${base}/${id}`,      // DELETE -> 204
+  restore: id => `${base}/${id}/restore`,
+  confirm: `${base}/confirm-password`, // POST {password} -> 204 | 422 | 429
+  reveal: id => `${base}/${id}/reveal`,// POST -> {password} | 423
+  otp: id => `${base}/${id}/otp`,      // GET  -> {code, expires_in, period}
+  logCopy: id => `${base}/${id}/log`,  // POST {action}
+  entryLog: id => `${base}/${id}/log`, // GET
+  globalLog: `${base}/log`,            // GET  ?user_id=&action=
+}
+```
+
+Pass a partial `endpoints` prop to move one route; the rest keep their
+defaults.
+
+##### The password confirmation is the server's decision, not the UI's
+
+`reveal` may answer `423` — "confirm your CRM password first" — and
+`useVaultReveal` treats that as a step rather than a failure: it parks the
+caller's promise, both surfaces draw `VaultConfirmPanel`, and a successful
+confirmation retries the original reveal and settles the promise the caller is
+already awaiting.
+
+Whether that happens at all is the backend's call —
+`vault.require_password_confirmation` in `visns-packages`, which the CRM
+currently has **off**, so a reveal answers `200` and no panel is ever drawn.
+Nothing in the UI assumes otherwise: every confirm-related element is behind an
+actual `423`, and no copy anywhere promises an unlock window. Leave the
+handshake wired up regardless — it is the contract the moment a consumer turns
+the flag on.
+
+On `PUT`, **omit** `password` / `totp_secret` to leave them unchanged, send
+`""` to clear, send a value to replace. The form does this by tracking intent
+rather than value — neither the list nor the show payload carries a secret, so
+both fields necessarily start blank even when editing an entry that has them.
+
+`totp_secret` accepts a bare base32 secret or a full `otpauth://totp/…` URI.
+The field says what it understood — `6 digits · 30 s · SHA1` — before you save.
+
+##### Getting the secret in: four ways, one field
+
+The QR code is the one thing every provider shows; the link underneath it is
+not. So the 2FA field takes the code itself as well:
+
+| Way | How |
+| --- | --- |
+| Type or paste | The `otpauth://` link, or the bare base32 key. |
+| **Scan QR** | Opens the device camera in a panel inside the form. Hidden entirely where `navigator.mediaDevices.getUserMedia` does not exist. |
+| **Upload QR image** | A file picker (`accept="image/*"`) — a screenshot, or the PNG a provider offers. |
+| Paste or drop an image | Paste a screenshot straight into the field (⌘/Ctrl+V with an image on the clipboard), or drag the image file onto it. |
+
+All four end as decoded text in the same input, so the same feedback line
+vouches for it and the API sees no difference. A QR that is not an
+authenticator code says so and quotes what it did contain; an image with no
+code in it says *"No QR code found in that image — try a sharper screenshot, or
+paste the setup link instead."*
+
+**The decoder is lazy.** `jsqr` (~131 KB raw, ~47 KB gzipped) is behind
+`await import('jsqr')` inside `qrDecode.js` and is fetched only when a scan,
+upload, paste or drop actually starts — a consumer that never opens the vault
+form never downloads it. Where the browser has the platform's own
+`BarcodeDetector` (Chrome and Edge, desktop and Android) that is tried first
+and jsQR may never load at all. Images are downscaled to 1280px on the long
+edge before decoding, and a second pass tries the inverted reading for
+dark-mode screenshots.
+
+**The camera needs https.** `getUserMedia` is unavailable on an insecure
+origin — `localhost` excepted — and the panel says so rather than failing
+silently. It also names the difference between a blocked permission, no camera
+at all, and a camera that would not start, because each needs the user to do
+something different. Every exit from the panel stops the stream.
+
+**On an iPad:** the camera works in Safari on an https page, and the rear
+camera is requested (`facingMode: environment`); "Switch camera" appears when
+more than one video input is listed. Safari has no `BarcodeDetector`, so iPad
+always uses jsQR — decoding is a little slower there but still well inside the
+250ms frame budget the scanner polls on. Safari also requires the video be
+muted and inline, which the panel sets; and it will not grant a camera inside
+an iframe without `allow="camera"` on that iframe.
+
+#### Checkboxes and radios keep their own box
+
+The host CRM styles bare `input` — padding, a min-width, a text-field height
+and a pill radius — and none of that is typed, so it lands on
+`input[type=radio]` too: the form's Visibility choice rendered as two wide
+ovals with a dot adrift inside one of them, and the manager's "Show deleted"
+was the same shape. The module's `vault-reset` cannot help, because it unsets
+`appearance` and for these two that is what draws the control at all.
+
+Every checkbox and radio the vault renders now carries `styles.checkControl`,
+which restates the native box — 16px square, no padding, no border, no radius
+(50% for a radio), `appearance: auto`, `accent-color: var(--v-primary)` — and
+keeps the focus ring. Their labels are `align-items: center` flex rows with a
+`0.5rem` gap. `tests/vault.test.mjs` fails if a new one is added without the
+class.
+
+#### Wiring it into an app
+
+```jsx
+import { Navigation, VaultQuickSearch } from '@visns-studio/visns-components';
+
+<Navigation
+    {...props}
+    renderers={{
+        vault: (p) => <VaultQuickSearch {...p} manageUrl="/settings/vault" />,
+    }}
+/>
+```
+
+```json
+{
+    "id": "vault",
+    "icon": "key",
+    "label": "Vault",
+    "permission": false,
+    "permissionKey": "Vault Access"
+}
+```
+
+Through `GenericMain` the same object is passed as `navRenderers`:
+
+```jsx
+<GenericMain
+    {...props}
+    navRenderers={{ vault: (p) => <VaultQuickSearch {...p} /> }}
+/>
+```
+
+And the page itself, on a route:
+
+```jsx
+<VaultManager canManage={userProfile.permissions.includes('Vault Manage')} />
+```
+
+#### The fixture
+
+```bash
+yarn dev:vault   # http://localhost:5180/vault-fixture.html
+```
+
+The page carries a **QR demo**: a real setup QR for `ACME Co /
+jane@example.com`, and a button that hands it to an open entry form the way the
+clipboard would. It is how the decode path gets reviewed on a desktop with no
+camera attached — dragging the same image onto the field, or saving it and
+using "Upload QR image", takes the identical path.
+
+`dev/vaultMockServer.js` answers every route from memory and a real ticking
+TOTP. The header carries two switches: `canManage`, and **require password
+confirmation** — off by default, as the CRM now runs it, so a reveal answers
+straight away; ticked, it puts the `423 → confirm → retry` handshake back (the
+demo password is `password`, and the window it buys is 90 seconds so the 423
+path comes back). It is never imported by the library and is not published — `files` ships
+`src` and `README.md` only.
+
+The fixture's fake header reproduces the one thing about the CRM's chrome that
+matters here: `.hactions` is a horizontal scroll container, so it clips on both
+axes, and a popover anchored inside it is cut off unless the host is told to
+let it out. That is what `data-nav-overlay="open"` on the popover wrapper does
+— the same contract `Notification` uses.
+
+### Navigation: `renderers`
+
+`Navigation` gained an optional `renderers` prop — `{ [setting.id]: ({ setting,
+userProfile, setSystemAuth }) => node }`. A matching id renders the supplied
+node inside the same row wrapper the built-in branches use, on both the header
+chips and the sidebar rail, and is checked before the hard-coded chain so a
+project can also override a shipped action. Empty by default. `GenericMain`
+passes it through as `navRenderers`. `key` and `lock` were added to
+`SETTING_ICONS`.
+
+### Navigation: the chip rules no longer reach into overlays (extended in 6.11.0)
+
+**6.11.0** found the same shape again in the rules the first pass did not
+cover. `.hactions > ul li` and `.hactions > ul li > span` were descendant
+selectors at 0,1,2, so a popover that mounts a **list** — the vault's results,
+the messaging inbox's threads — had every row inheriting `display: flex`,
+`justify-content: center`, a 32px minimum box and 2px side margins. A grid row
+was quietly flattened into a centred flex line and the whole list sat indented;
+the `li > span` rule turned the text cell into a flex box, which is what
+stopped the ellipsis engaging on a long preview.
+
+| Was | Now |
+| --- | --- |
+| `.hactions > ul li` | `.hactions > ul > li:not([data-nav-overlay] *)` |
+| `.hactions > ul li > div, li > span` | `.hactions > ul > li > div:not(…), > li > span:not(…)` |
+| `.hactions > ul li button:not(…)` | `.hactions > ul > li button:not(…)` |
+| `.hactions-alternate > ul li` | `.hactions-alternate > ul > li:not([data-nav-overlay] *)` |
+
+The chips are always direct children of that `ul`, so `> li` loses nothing and
+cannot reach into anything a chip opens; the `:not()` is belt and braces for a
+project that nests one. `tests/vault.test.mjs` guards every element name the
+sheet can use — `a`, `button`, `li`, `ul`, `span`, `svg`, `img`, `div`, `p`,
+`input` — not just the two that were caught the first time.
+
+
+
+`.hactions > ul` styles the header's account chips, and it did so with bare
+`a` / `button` descendant selectors. Anything mounted inside that cluster
+inherited white text, a fixed 36px box and a pill radius, at a specificity no
+popover's own module class could beat — `Notification` only survived it by
+carrying `!important` overrides. The vault's popover rendered as blank white
+boxes on a white panel.
+
+Five selectors now exclude `[data-nav-overlay] *`, the same flag the `:has()`
+overflow rule beside them already relies on:
+
+| File line | Was | Now |
+| --- | --- | --- |
+| `.hactions > ul` | `a, button` | `a:not([data-nav-overlay] *), button:not([data-nav-overlay] *)` |
+| `.hactions > ul` | `li button` | `li button:not([data-nav-overlay] *)` |
+| `.hactions > ul` | `button` | `button:not([data-nav-overlay] *)` |
+| `.hactions-alternate > ul` | `a` | `a:not([data-nav-overlay] *)` |
+| `.hactions-alternate > ul` | `button` | `button:not([data-nav-overlay] *)` |
+
+It is a pure exclusion — everything that matched before still matches unless it
+sits inside an open overlay — so the chips are pixel-identical and the
+notification bell and account switcher are untouched (their triggers are
+siblings of their overlays, never inside them). `tests/vault.test.mjs` compiles
+the sheet and fails if any `.hactions` rule reaches a descendant control again.
+
+### CustomFetch: `options.silentStatuses`
+
+```js
+CustomFetch(url, 'POST', body, onSuccess, null, { silentStatuses: [423] })
+    .catch((error) => {
+        if (error.status === 423) { /* error.data is the parsed body */ }
+    });
+```
+
+A listed status skips both the toast and the `errorCallback`, and rejects with
+`status` and the parsed `data` hung directly off the error. Previously an
+`errorCallback` only ever saw a flattened message string, so there was no way
+to branch on a status that is part of a flow rather than a failure — which is
+exactly what the vault's 423 is. Opt-in, so every existing caller is unchanged.
+
+## Recent Updates (v6.9.0)
+
+### React 19 support
+
+`peerDependencies` now accept `^17 || ^18 || ^19` for `react` and `react-dom`.
+Widened only after an audit and a real render against React 19.2.8.
+
+**Fixed** (genuine React 19 removals):
+
+- **12 `defaultProps` on function components**, across `GroupedReportRenderer`
+  and the nine `reportSemanticSteps/*` files. React 19 removed `defaultProps`
+  for function components, so each of those props would silently have become
+  `undefined`. Converted to default parameters — same values, and the change is
+  invisible under React 17/18.
+- **Two callback refs with expression bodies** in `SketchField`
+  (`ref={c => (this._x = c)}`). React 19 treats a callback ref's return value
+  as a cleanup function, so those handed React an element where it expects a
+  function. Converted to block bodies.
+- **`prop-types` was undeclared.** 183 lines import it and it resolved only
+  because a transitive dependency hoisted it — a latent packaging bug that
+  would bite any consumer on pnpm or Yarn PnP, React version notwithstanding.
+  Now a real dependency.
+
+**Warns but works under 19:** `propTypes` on function components is ignored
+rather than removed, so the ~180 declarations still present are dead weight and
+nothing more — no warning, no error. They are kept because they still document
+intent, and still run under 17/18.
+
+**Verified:** the existing suite stays green under React 18 (152 tests), and
+every auth screen, both `ClientAuth` layouts, `CallQueuePop`, `CallQueueSettings`,
+`GroupedReportRenderer` and `SemanticValueInput` server-render against React
+19.2.8 with **no `console.error` or `console.warn` from any component**.
+
+#### Known limits under React 19
+
+Seven of this library's own dependencies declare peer ranges that exclude
+React 19: `@nivo/{bar,core,line,pie}`, `react-quill`, `react-sortable-hoc` and
+`react-toggle`. Installing the package root against React 19 will therefore
+produce peer warnings (and an install error under strict npm).
+
+**None of them is reachable from the auth or call-pop entry points.** Verified
+by tracing the import graph: `ClientAuth`, `ImpersonateGate`, `LogoutScreen`,
+`Login`, `TwoFactorAuth` and `CallQueuePop` pull in none of the seven. A React
+19 consumer should import those by path —
+
+```js
+import ClientAuth from '@visns-studio/visns-components/src/components/auth/ClientAuth';
+```
+
+— which is what the Next.js portal already does for `ImpersonateGate`. Importing
+the package root pulls in every component and therefore all seven.
+
+`CallQueueSettings` is the one auth-adjacent component that does reach a
+blocked dependency (`react-toggle`), and `DataGrid` depends on the vendored
+`@visns-studio/visns-datagrid-*` fork, which has its own React 19 work
+outstanding. Neither is a blocker for the portal, which uses neither.
+
+## Recent Updates (v6.8.3)
+
+### A two-pane layout for the client sign-in
+
+The client screens rendered a small card floating in whatever vertical space
+the host page gave them, which on the portal meant a login box marooned in a
+tall empty band. `layout="split"` brings across the staff sign-in's design
+language — the brand on one side, the task on the other — as an **opt-in**:
+`layout="card"` is the default and is byte-identical to what every consumer
+rendered before.
+
+- **The brand panel is now written once.** `_authBrandPanel.scss` and
+  `AuthBrandPanel.jsx` are shared by the staff `Login`, `AuthShell` (behind
+  TwoFactorAuth/Reset/Verify) and the new split layout. It had been copied
+  twice, which is the arrangement where one copy quietly stops matching the
+  others. The extraction is verified byte-for-byte: every CSS rule in
+  `Login.module.scss`, `TwoFactorAuth.module.scss`, `Reset.module.scss` and
+  `Verify.module.scss` is unchanged.
+- **It is a section, not a screen.** The staff `.auth` is `position: fixed;
+  inset: 0` because it owns the viewport. The split has no `100vh` anywhere: it
+  fills its parent (`height: 100%`, with `flex: 1` and `align-self: stretch` so
+  it works in a flex column too), because the consumer keeps its own header and
+  footer and hands this the space between.
+- **Under 900px the brand becomes a header band**, not nothing. The staff
+  screens hide the photograph on a phone — the form is the whole job there. A
+  public-facing portal still has to say whose front door it is, so the panel
+  collapses to a compact strip carrying the image and the name, with the
+  eyebrow and tagline dropped.
+
+Same tokens as the staff panel throughout (`--primary-color-darker`,
+`--accent-color`, `--auth-font-family`, …) with the library's existing
+fallbacks, so one token layer themes the whole product.
+
+## Recent Updates (v6.8.2)
+
+### CSRF resync on a no-reload hand-off
+
+Paired with a `visns-packages` change. Every sign-in used to end in a full page
+load, which fetched a new document and with it a new
+`<meta name="csrf-token">`. The 6.8.1 curtain hand-off keeps the document — so
+when the backend rotated the token on a successful 2FA challenge, the SPA held
+a token the server had just invalidated and every subsequent POST came back
+419, as a toast storm.
+
+The package is removing that rotation and adding a `csrf_token` field to its
+auth success responses. The screens now consume it: **whenever an auth response
+carries a non-empty `csrf_token`, the meta tag is updated before any callback,
+state change or navigation** — `CustomFetch` re-reads the tag on every request,
+so that is the whole of the fix.
+
+Applied at every point where an auth response is consumed and the app then
+continues without a reload: `Login` (both the plain success and the
+`requires_two_factor` branch), `TwoFactorAuth` (challenge completion),
+`ClientOTPVerify` and `ImpersonateGate`.
+
+Fully back-compatible: `syncCsrfToken` is inert when the field is absent, when
+the meta tag is missing, and when there is no `document` at all — so a backend
+that never sends the field sees no change. Exported, along with
+`syncCsrfFromResponse`, for consumers with their own auth flows.
+
+## Recent Updates (v6.8.1)
+
+### Pending states across the auth flow
+
+Live review: pressing **Verify** on the 2FA screen showed nothing — the label
+snapped back to "Verify", the screen sat there looking idle, and half a second
+later the browser reloaded out from under it.
+
+- **The 2FA success transition is no longer a hard reload.** It sets the auth
+  state and lets `GenericAuth` do the navigation, exactly as `Login`'s non-2FA
+  branch does, so the please-wait curtain covers the whole hand-off. The old
+  `window.location.href` bypassed that curtain entirely — the known 6.5.5 gap.
+  A `previousUrl` (or a consumer-set `successPath`) still gets a real
+  navigation, now under a full-screen curtain held from the click until the
+  browser unloads.
+- **`GenericAuth` recognises `/2fa`** as a hand-off screen alongside `/login`,
+  which is what lets it perform that navigation. Previously it only ever moved
+  the user off `/login`, because the 2FA screen reloaded instead of asking.
+- **Every control in the flow now has a pending state and is disabled while
+  pending**, so a double-submit is impossible: both 2FA buttons, the resend
+  link (which said "Resend Code" *while sending* — the in-flight moment itself
+  was silent), the Microsoft SSO button (which gave no sign at all that it had
+  been pressed), and both password-reset submits.
+- **`AuthLoading` is exported.** It moved out of `GenericAuth` so the screens
+  raise the identical curtain — when a screen's own curtain and `GenericAuth`'s
+  are both up, there is nothing to see between them.
+
+Visible to existing consumers only as a spinner and a disabled button where
+there were neither. Two things change beyond that, both deliberate: the 2FA
+success path no longer reloads the document, and `Login` gained a `copy` prop
+whose defaults are the strings it already rendered.
+
+## Recent Updates (v6.8.0)
+
+### Portal adoption: wire protocols, injected navigation, bundler portability
+
+6.7.0 presented `ClientLogin` / `ClientOTPVerify` as portal parity, but the
+Next.js portal could not adopt them: they spoke a different wire protocol from
+the one behind `/api/auth/*` and nothing bridged the gap. Four blockers, any
+one of them fatal, all fixed here:
+
+- **The wire protocol is a prop.** `protocol="contact"` switches the request
+  bodies, the success test and the challenge-id requirement to ThroughLife's
+  contract. `'uuid'` remains the default and is bit-identical to 6.7.0. See
+  [The `protocol` prop](#the-protocol-prop).
+- **The token reaches the consumer.** `onAuthenticated(user, token,
+  rawResponse)` on the verify step — `login-otp`'s `access_token` used to be
+  read and discarded, so there was nothing to write into a `portal_token`
+  cookie. When it is present the component defers all state and navigation to
+  the consumer.
+- **react-router is optional.** Navigation is injectable (`onNavigate`,
+  `onChallengeIssued`, `onBack`, `challenge`) and the router hooks are consulted
+  only when nothing else was supplied and only when a Router exists. All three
+  client screens now mount cleanly with no router at all.
+- **`ClientAuth`** puts both steps on one page, which is the shape a Next.js
+  App Router page can actually host — and makes the whole integration props and
+  config, with no adapter code.
+- **Bundler portability.** `import.meta.env` reads moved behind `readBuildEnv`;
+  see below.
+
+## Recent Updates (v6.7.0)
+
+### Auth journey, client portal parity, and the call queue
+
+Everything in this release is **opt-in**. Every new prop's default reproduces
+6.6.3's rendering and network behaviour exactly, because other applications
+consume these components.
+
+- **Configurable auth endpoints** — every URL the auth screens talked to was a
+  string literal inside the component that used it. They are now one `endpoints`
+  object, threaded from `GenericAuth` into each screen, whose defaults are the
+  old literals. See [the endpoints table](#the-endpoints-object).
+- **One design language for the whole sign-in journey** — `TwoFactorAuth`,
+  `Reset` and `Verify` were still the pre-6.1 centred card, so signing in with
+  2FA on crossed a visible design seam halfway through. All three now render the
+  two-pane frame the login screen was redesigned onto, via the new `AuthShell`
+  component and the shared `_authShell.scss` mixin.
+- **Barlow is actually loaded** — `Login.module.scss` had asked for it since the
+  redesign, but nothing in the library imported `@fontsource/barlow`, so every
+  consumer silently fell through to `system-ui`. The family is also read from
+  `--auth-font-family` first, so an app can put its own face on the journey.
+- **SMS-code 2FA** — `TwoFactorAuth` gains `mode="code"`: the masked
+  destination, expiry messaging, and a working Resend button.
+- **`mainComponent` on `GenericAuth`** — keep your own app shell while still
+  getting this file's route table, `ProtectedRoute` and please-wait curtain.
+- **Client portal parity** — `ClientLogin` and `ClientOTPVerify` gain the
+  behaviour of the Next.js portal's own login page: the live contact-type hint,
+  masked contacts, the dev-OTP panel, a back link that keeps what you typed, a
+  configurable resend cooldown, and configurable labels throughout. Route paths
+  are props, so the same screens serve `/client/*` and `/portal/*`.
+- **`ImpersonateGate` and `LogoutScreen`** — the portal's impersonation
+  hand-off and its logout confirmation, both framework-agnostic and
+  callback-driven (no `next/router`, no cookie writing, no URL reading).
+- **`CallQueuePop` and `CallQueueSettings`** — the ThroughLife CRM's Zoom call
+  queue pop and its admin page, ported with every host-specific decision turned
+  into a prop. See [Call Queue Components](#call-queue-components).
+- **Bundler-agnostic env reads** — `Fetch.jsx` and `DataGrid.jsx` read
+  `import.meta.env.VITE_*` directly, which is Vite's interface. Under webpack
+  `import.meta` compiles to a bare `{}`, so the property read threw a
+  TypeError on the Next.js portal's first request and it needed a DefinePlugin
+  shim. Both now go through `readBuildEnv`, which falls back to `process.env`
+  (including the `NEXT_PUBLIC_` prefix Next.js requires). Vite behaviour is
+  unchanged — its value is still found first and still wins.
+- **`{error}` bodies surface again** — `CustomFetch`'s error path looked at
+  `errors` and `message` and never at `error`, so on a non-200 an
+  `{"error": "…"}` body was dropped entirely and the caller got an empty toast.
+  A last-resort fallback was added *after* the existing checks, so nothing that
+  already surfaced changes.
+- **Documentation corrected** — the 2FA API section documented `requires_2fa`
+  and a `{user_id, verification_code}` challenge body. Neither was ever what the
+  code sent; the real contract (`requires_two_factor`, `{code, previous_url,
+  remember}`) is now what is written down.
+- **Debug logging removed** from `TwoFactorAuth`, which shipped a dozen
+  `console.log` calls including the full challenge response.
+
 ## Recent Updates (v5.15.10)
 
 ### Latest Enhancements
@@ -431,6 +1459,31 @@ All existing DropZone implementations continue to work without modification. The
 
 ### Authentication Components
 
+> **6.7.0 — everything below is configurable, and every default is what 6.6.3
+> already did.** The auth screens used to hardcode their endpoints, their route
+> paths and their copy. All three are now props. Passing none of them leaves
+> the rendering and the network calls exactly as they were, so upgrading is a
+> no-op until you opt in.
+
+##### The `endpoints` object
+
+One object, threaded from `GenericAuth` into every screen. Partial overrides
+are merged over the defaults, and nullish/empty entries are ignored (so a key
+missing from your config cannot blank a URL and leave a screen posting to `''`).
+
+| Key | Default | Used by |
+| --- | --- | --- |
+| `authenticate` | `/login/authenticate` | `Login` |
+| `twoFactorChallenge` | `/login/two-factor-challenge` | `TwoFactorAuth` |
+| `twoFactorResend` | `/login/two-factor-resend` | `TwoFactorAuth` (`mode="code"`) |
+| `azureSso` | `/auth/azure` | `Login` (the Microsoft button) |
+| `profile` | `/ajax/user/profile` | `GenericAuth` (the session check) |
+| `passwordForgot` | `/password/forgot` | `Reset` |
+| `passwordReset` | `/password/reset` | `Verify` |
+
+`resolveAuthEndpoints`, `DEFAULT_AUTH_ENDPOINTS`, `resolveClientPaths` and
+`DEFAULT_CLIENT_PATHS` are exported if you want to build on them.
+
 #### GenericAuth
 
 The main component that handles authentication and routing.
@@ -446,6 +1499,8 @@ The main component that handles authentication and routing.
     routeConfig={routeConfig} // Route configuration
     themeType="primary" // Theme type: 'primary', 'secondary', etc.
     enforce2FA={false} // Whether to enforce 2FA (default: false)
+    endpoints={{ profile: '/api/me' }} // 6.7.0 — merged over the defaults
+    mainComponent={MyAppShell} // 6.7.0 — defaults to GenericMain
     clientPortalConfig={{
         component: <ClientPortalComponent />, // Main component for client portal
         urls: {
@@ -454,6 +1509,9 @@ The main component that handles authentication and routing.
             logout: '/clientPortal/logout',
             profile: '/clientPortal/profile',
         },
+        paths: { base: 'client' }, // 6.7.0 — route paths, see below
+        login: { showContactHint: true }, // 6.7.0 — props for ClientLogin
+        verify: { showDevOtp: true }, // 6.7.0 — props for ClientOTPVerify
         keys: {
             name: ['firstname', 'surname'], // Fields to use for client name display
         },
@@ -461,6 +1519,16 @@ The main component that handles authentication and routing.
 />
 ```
 
+| Prop | Default | Notes |
+| --- | --- | --- |
+| `endpoints` | `{}` → the table above | Threaded into `Login`, `TwoFactorAuth`, `Reset`, `Verify` and the session check. |
+| `mainComponent` | `GenericMain` | The authenticated shell. Pass your own component (or an already-created element, which is cloned) to keep your chrome while still getting this file's route table, `ProtectedRoute` and please-wait curtain. It receives exactly the props `GenericMain` does. |
+| `mainComponentProps` | `{}` | Extra props for a custom shell that needs something `GenericMain` does not take. |
+| `config.twoFactorMode` | *(unset)* | `'code'` puts `TwoFactorAuth` into SMS-code mode. Unset leaves it on `'totp'`. |
+| `clientPortalConfig.paths` | `{base: 'client'}` | Client route paths. `{base: 'portal'}` derives the whole `/portal/*` family; individual keys (`login`, `verify`, `portal`) can be set explicitly and win over the derived ones. |
+| `clientPortalConfig.login` | `{}` | Spread onto `ClientLogin` — see its prop table. |
+| `clientPortalConfig.verify` | `{}` | Spread onto `ClientOTPVerify` — see its prop table. |
+
 #### Login
 
 Handles user login with email and password.
@@ -468,40 +1536,438 @@ Handles user login with email and password.
 ```jsx
 <Login
     logo="/path/to/logo.png"
+    loginBg="/path/to/background.jpg"
     providers={['azure']} // Optional SSO providers
     setSystemAuth={setAuthFunction}
     setUserProfile={setUserProfileFunction}
+    config={{ branding: { name: 'Acme', tagline: '…' }, passwordReset: true }}
 />
 ```
 
+| Prop | Default | Notes |
+| --- | --- | --- |
+| `logo`, `loginBg` | — | Panel logo and the brand-side photograph. |
+| `providers` | `undefined` | `['azure']` renders the Microsoft button and collapses the email form behind a disclosure. |
+| `setSystemAuth`, `setUserProfile` | — | Required callbacks. |
+| `config.branding` | `{}` | `{eyebrow, name, tagline, signInHint, footer}`. Absent entries simply do not render. |
+| `config.passwordReset` | `true` | `false` hides the "Forgot password?" link. |
+| `endpoints` | *(defaults)* | Uses `authenticate` and `azureSso`. |
+| `twoFactorPath` | `'/2fa'` | Where a `requires_two_factor` response navigates. |
+| `resetPath` | `'/reset'` | Target of the "Forgot password?" link. |
+
 #### TwoFactorAuth
 
-Handles 2FA verification.
+Handles 2FA verification. **Redesigned in 6.7.0** onto the same two-pane frame
+as `Login` — the pre-6.1 centred card it used to render is gone, so the whole
+sign-in journey now looks like one journey.
 
 ```jsx
+{/* Authenticator-app code — the default, unchanged from 6.6.3 */}
 <TwoFactorAuth
     logo="/path/to/logo.png"
     setSystemAuth={setAuthFunction}
     setUserProfile={setUserProfileFunction}
 />
+
+{/* Texted code, with a working Resend and expiry messaging */}
+<TwoFactorAuth
+    logo="/path/to/logo.png"
+    mode="code"
+    expiryMinutes={10}
+    resendCooldown={30}
+    setSystemAuth={setAuthFunction}
+    setUserProfile={setUserProfileFunction}
+/>
 ```
 
+| Prop | Default | Notes |
+| --- | --- | --- |
+| `mode` | `'totp'` | `'totp'` reads the code from an authenticator app: no expiry line, no Resend. `'code'` is for a texted code: it shows the masked destination, the expiry, and a Resend button. |
+| `endpoints` | *(defaults)* | Uses `twoFactorChallenge` and, in `code` mode, `twoFactorResend`. |
+| `expiryMinutes` | `10` | Substituted into `copy.expiry`. `code` mode only. |
+| *(router state)* | — | `Login` hands over `{challenge, userData, maskedContact, previousUrl, remember}`. `userData` is **null on a code-driver challenge**; nothing on this screen may assume otherwise. |
+| `resendCooldown` | `0` | Seconds to keep Resend disabled *after* a successful send. `0` disables it only while the request is in flight. `code` mode only. |
+| `loginPath` | `'/login'` | "Back to Login", and the bounce when a challenge session has expired. |
+| `successPath` | `'/'` | `'/'` means **hand off to `GenericAuth`**: the screen sets the auth state, raises no navigation of its own, and the curtain plus profile check carry the user in. Any other value is a consumer asking to land somewhere specific, which `GenericAuth` cannot do, so it gets a real navigation under a full-screen curtain. A `previousUrl` from before sign-in always outranks this and always gets a real navigation. |
+| `copy` | *(see below)* | Merged over the defaults; override only the lines you want to change. |
+| `config.branding` | `{}` | Same shape as `Login`'s. |
+
+`copy` keys: `title`, `totpSubtitle`, `codeSubtitle`, `sentTo`, `fieldLabel`,
+`submit`, `submitting`, `expiry` (`{minutes}`), `resend`, `resending`,
+`resendIn` (`{seconds}`), `resent`, `help`, `back`, `remembered`, `leaving`,
+`invalidLength`, `failed`, `expired`, `resendFailed`.
+
+`submitting` is shown for the whole request **and** the transition that follows
+it; `resending` is the resend link's label while its own request is in flight;
+`leaving` captions the full-screen curtain during the hand-off.
+
+The masked destination shown in `code` mode comes from the router state the
+login step hands over (`maskedContact`), falling back to
+`userData?.masked_contact`. The packages' `AuthController` sends neither today,
+so the chip is normally not rendered — see the API section below.
+
 #### Reset
 
-Password reset request form.
+Password reset request form. **Redesigned in 6.7.0** onto the two-pane frame.
 
 ```jsx
-<Reset logo="/path/to/logo.png" setSystemAuth={setAuthFunction} />
+<Reset logo="/path/to/logo.png" loginPath="/login" />
 ```
 
+| Prop | Default | Notes |
+| --- | --- | --- |
+| `endpoints` | *(defaults)* | Uses `passwordForgot`. |
+| `loginPath` | `'/login'` | The "Back to Login" link. |
+| `copy` | *(see below)* | Merged over the defaults. |
+| `config.branding` | `{}` | Same shape as `Login`'s. |
+
+`copy` keys: `title`, `subtitle`, `fieldLabel`, `submit`, `submitting`, `sent`,
+`back`, `required`, `failed`.
+
+Once the request is in, the form is replaced by a confirmation rather than
+re-offered — submitting twice only invalidates the first link.
+
 #### Verify
 
-Password reset verification form.
+Password reset verification form (`/verify/:code`). **Redesigned in 6.7.0**
+onto the two-pane frame.
+
+```jsx
+<Verify logo="/path/to/logo.png" showRules />
+```
+
+| Prop | Default | Notes |
+| --- | --- | --- |
+| `endpoints` | *(defaults)* | Uses `passwordReset`. |
+| `showRules` | `true` | The live password-rules checklist, which ticks itself off as the user types. The pre-6.7.0 behaviour was a five-line `<br />`-separated toast *after* a rejected submit. |
+| `rules` | `PASSWORD_RULES` | `[{label, test}]`. Display only — the submit is still gated by `validator.isStrongPassword`, so the two cannot disagree. |
+| `loginPath` | `'/login'` | Where a successful reset lands, and the "Back to Login" link. |
+| `copy` | *(see below)* | Merged over the defaults. |
+| `config.branding` | `{}` | Same shape as `Login`'s. |
+
+`copy` keys: `title`, `subtitle`, `passwordLabel`, `repeatLabel`, `submit`,
+`submitting`, `back`, `success`, `required`, `mismatch`, `weak`, `failed`.
+
+#### AuthShell
+
+The two-pane frame `TwoFactorAuth`, `Reset` and `Verify` render inside. Exported
+so an app can build a fourth screen that matches the other three.
+
+```jsx
+import styles from './MyScreen.module.scss'; // must @include auth-shell
+
+<AuthShell
+    styles={styles}
+    logo={logo}
+    loginBg={loginBg}
+    branding={{ eyebrow, name, tagline }}
+    title="…"
+    subtitle="…"
+    footer="…"
+>
+    {/* your form */}
+</AuthShell>;
+```
+
+`AuthBrandPanel` is the brand side on its own, exported for the same reason:
+the staff `Login`, `AuthShell` and the client split layout all render exactly
+it, against the shared `auth-brand-panel` mixin in `_authBrandPanel.scss`.
+
+The `styles` module is supplied by the caller — each screen owns its own CSS
+module so module scoping stays intact. Share the look by putting
+`@use './authShell' as *; @include auth-shell;` at the top of it, then add only
+what is particular to your screen. Set `--auth-font-family` to use a face other
+than Barlow across the whole journey.
+
+### Client Portal Sign-In
+
+Two steps — identify yourself, then enter the code — available three ways:
+`ClientAuth` (both on one page, no router needed), or `ClientLogin` and
+`ClientOTPVerify` mounted on separate routes.
+
+#### The `protocol` prop
+
+There are two OTP wire protocols in the wild and they disagree about nearly
+everything. Before 6.8.0 only one of them was expressible, which is what
+blocked the Next.js portal from adopting these screens at all.
+
+| | `uuid` *(default)* | `contact` |
+| --- | --- | --- |
+| Request body | `{email, location}` | `{contact}` |
+| Verify body | `{email, uuid, otp, previous_url}` | `{contact, otp_code, minimal_response}` |
+| Challenge id | required — step two redirects without one | **none in the contract** |
+| Success | `body.success === true` | `body.error === ''` |
+| Failure | `{message}` / `{errors}` | non-200 `{error: '…'}` |
+| Session | cookie, set server-side | `access_token` in the body |
+| Resend | `{email, resend: true}` | just another request |
+
+`protocol="contact"` is the configuration for ThroughLife's `/api/auth/*`
+routes (visns-packages' `OtpController`). `protocol` also accepts an object of
+overrides, optionally naming what it starts from:
+`{extends: 'contact', contactField: 'identifier'}`. An unknown name falls back
+to the default rather than throwing — a typo in a prop should not white-screen
+a login page.
+
+`CLIENT_AUTH_PROTOCOLS`, `resolveClientProtocol` and `verifyContactFor` are
+exported for anything more exotic.
+
+#### ClientAuth
+
+Both steps on one page, with the challenge held in state instead of in router
+state. It needs no router, so it mounts cleanly in a Next.js App Router page,
+and it is the whole of the "no adapter code" story — supply endpoints, a
+protocol name and an `onAuthenticated`, and write nothing that knows a request
+body from a response field.
+
+```jsx
+'use client';
+import { useRouter } from 'next/navigation';
+import { ClientAuth } from '@visns-studio/visns-components';
+
+export default function PortalLoginPage() {
+    const router = useRouter();
+
+    return (
+        <ClientAuth
+            protocol="contact"
+            urls={{
+                login: '/api/auth/request-otp',
+                verify: '/api/auth/login-otp',
+            }}
+            usernameDomain="virtualportal.com.au"
+            showContactHint
+            showMaskedContact
+            showContactField
+            showDevOtp
+            resendCooldown={0}
+            loginLabels={{ submit: 'Send Code', submitting: 'Please wait...' }}
+            verifyLabels={{ submit: 'Login', submitting: 'Please wait...' }}
+            onAuthenticated={(user, token) => {
+                setCookie('portal_token', token, { maxAge: 28800 });
+                setUserData(user);
+                router.push('/portal/dashboard');
+            }}
+        />
+    );
+}
+```
+
+| Prop | Default | Notes |
+| --- | --- | --- |
+| `protocol`, `urls`, `paths`, `contactField`, `logo`, `showDevOtp`, `onError` | — | Passed to both steps. |
+| `showContactHint`, `contactHints`, `usernameDomain`, `loginCopy`, `loginLabels` | — | Step one. |
+| `resendCooldown`, `showMaskedContact`, `showContactField`, `minimalResponse`, `verifyCopy`, `verifyLabels` | — | Step two. |
+| `onAuthenticated` | — | `(user, token, rawResponse)`. |
+| `onCodeSent` | `undefined` | Notified with the challenge each time a code is sent. |
+| `loginProps`, `verifyProps` | `{}` | Merged last onto either step, for anything that has to differ. |
+| `layout` | `'card'` | `'card'` is the original box centred in the host page's space — byte-identical to pre-6.8.3. `'split'` is the two-pane brand layout described above. Anything unrecognised falls back to `'card'`. |
+| `loginBg` | `undefined` | Split only: the brand panel's photograph. Ignored by `'card'`. |
+| `branding` | `undefined` | Split only: `{eyebrow, name, tagline, footer}`, rendered in the same type hierarchy as the staff `Login`'s brand panel — eyebrow with its accent rule, name at display size, tagline beneath, footer at the foot of the form column. Ignored by `'card'`. |
+
+`layout`, `loginBg` and `branding` are also accepted directly by `ClientLogin`
+and `ClientOTPVerify`, for a consumer mounting the two steps on separate
+routes.
+
+##### Sizing the split
+
+The split fills its parent, so give it somewhere to fill. In a page that keeps
+its own header and footer:
+
+```jsx
+<div style={{ display: 'flex', flexDirection: 'column', minHeight: '100vh' }}>
+    <Header />
+    <ClientAuth layout="split" /* … */ />
+    <Footer />
+</div>
+```
+
+The section carries `flex: 1 1 auto` and `align-self: stretch`, so a flex
+column like this needs nothing further. A parent with an explicit height works
+too (`height: 100%`); a parent with no height at all falls back to the
+section's `min-height: 24rem`.
+
+##### Throughlife portal configuration
+
+The whole integration, for the record — the split layout, the contact protocol,
+and the consumer owning its own session:
+
+```jsx
+'use client';
+import { useRouter } from 'next/navigation';
+import { ClientAuth } from '@visns-studio/visns-components';
+
+export default function PortalLoginPage() {
+    const router = useRouter();
+
+    return (
+        <ClientAuth
+            layout="split"
+            loginBg="/images/portal-hero.jpg"
+            branding={{
+                eyebrow: 'Client portal',
+                name: 'Throughlife',
+                tagline: 'Your plan, your documents, in one place.',
+                footer: '© Throughlife Financial Planning',
+            }}
+            protocol="contact"
+            urls={{
+                login: '/api/auth/request-otp',
+                verify: '/api/auth/login-otp',
+            }}
+            usernameDomain="virtualportal.com.au"
+            showContactHint
+            showMaskedContact
+            showContactField
+            showDevOtp
+            resendCooldown={0}
+            loginLabels={{ submit: 'Send Code', submitting: 'Please wait...' }}
+            verifyLabels={{ submit: 'Login', submitting: 'Please wait...' }}
+            onAuthenticated={(user, token) => {
+                setCookie('portal_token', token, { maxAge: 28800 });
+                setUserData(user);
+                router.push('/portal/dashboard');
+            }}
+        />
+    );
+}
+```
+
+The back link clears the challenge and returns to step one with what was typed
+still in the field.
+
+#### ClientLogin
+
+Step one on its own. Every 6.7.0/6.8.0 addition is opt-in — with no new props
+this renders exactly what 6.6.3 rendered.
+
+| Prop | Default | Notes |
+| --- | --- | --- |
+| `urls.login` | — | The POST this screen makes. |
+| `protocol` | `'uuid'` | See the table above. |
+| `paths` | `{base: 'client'}` | Route paths — `resolveClientPaths` shape. |
+| `onChallengeIssued` | `undefined` | `(challenge) => void`, called once a code is sent. **When present the screen does not navigate** — the consumer owns what happens next. The challenge is `{contact, rawContact, challengeId, maskedContact, contactMethod, devOtp, message, previousUrl}`, which is exactly `ClientOTPVerify`'s `challenge` prop. |
+| `onNavigate` | `undefined` | `(path, options) => void`. Used before react-router's `navigate`, which is used before a plain page load. |
+| `initialContact` | `undefined` | Prefills the field. |
+| `layout`, `loginBg`, `branding` | `'card'`, — , — | As on `ClientAuth`; pass them here when mounting the steps on separate routes. |
+| `showContactHint` | `false` | The live "Email address detected" / "Mobile number detected" / "Username detected" line under the field. |
+| `contactHints` | *(defaults)* | Merged over `DEFAULT_CONTACT_HINTS`. |
+| `usernameDomain` | `null` | Completes a bare username to `name@domain`. Emails and phone numbers are untouched. |
+| `contactField` | *(the protocol's)* | Overrides the request-body key: `email` under `uuid`, `contact` under `contact`. |
+| `showDevOtp` | `false` | Carry the response's dev OTP through to step two. Never honoured in production. |
+| `onError` | `undefined` | Notified with the normalised message. |
+| `labels` | `{submit: 'Continue', submitting: 'Sending...'}` | **The 6.6.3 strings, not the portal's.** For portal parity pass `{submit: 'Send Code', submitting: 'Please wait...'}`. |
+| `copy` | *(see below)* | Merged over the defaults. |
+
+`copy` keys: `title`, `subtitle`, `fieldLabel`, `placeholder`, `required`,
+`notFound`, `sending`, `sent`.
+
+#### ClientOTPVerify
+
+Step two on its own.
+
+| Prop | Default | Notes |
+| --- | --- | --- |
+| `urls.verify`, `urls.login` | — | The verify POST, and the resend. |
+| `protocol` | `'uuid'` | See the table above. **This is what decides whether a challenge id is required** — under `contact` there is none, and demanding one bounced every user straight back to step one. |
+| `challenge` | `undefined` | The object `ClientLogin`'s `onChallengeIssued` hands over. Supplying it is what lets this screen render outside a router; without it, router state is read (the 6.6.3 hand-off, both old and new key spellings). |
+| `onAuthenticated` | `undefined` | `(user, token, rawResponse)` on a successful verification. **When present the component does nothing else** — no `setUserProfile`, no `setSystemAuth`, no navigation. That is the only way an app can write its own cookie from the bearer token. `token` is `null` under `uuid`, whose backend sets a cookie server-side. |
+| `onBack` | `undefined` | Replaces the back navigation; receives the challenge. A single-page consumer clears its challenge state here. Passing it also stops this screen redirecting when it decides it has nothing to answer. |
+| `onNavigate` | `undefined` | As on `ClientLogin`. |
+| `minimalResponse` | `true` | `contact` protocol: ask for the cookie-sized user payload. `false` returns the full model. |
+| `resendCooldown` | `60` | Seconds Resend stays disabled after a send. **60 is what 6.6.3 hardcoded**; the portal has none, so pass `0` for parity. |
+| `showMaskedContact` | `false` | Show the server's `masked_contact` in the sub-line (falling back to a locally-computed mask). |
+| `showContactField` | `false` | Render a disabled contact field above the code field, echoing the raw contact, with `Code sent to: {masked}` captioned beneath it — the layout the portal's OTP step used before it adopted this component. The destination moves out of the sub-line when this is on, so it is never said twice. The field is `readOnly`, `tabIndex={-1}` and never submitted: the verify body is built by the protocol from the challenge, not read off the form. |
+| `showDevOtp` | `false` | The development-only OTP panel with an "Auto-fill OTP" button. Gated on `NODE_ENV !== 'production'` as well as this prop, so a build that leaves it on cannot print a live code. |
+| `backKeepsContact` | `false` | The back navigation carries the identifier so step one is not blank. |
+| `contactField` | *(the protocol's)* | |
+| `layout`, `loginBg`, `branding` | `'card'`, — , — | As on `ClientAuth`. Every field, hint and panel — including `showContactField` and the dev-OTP panel — renders identically in both layouts. |
+| `onError` | `undefined` | Notified with the normalised message. |
+| `labels` | `{submit: 'Verify', submitting: 'Verifying...'}` | **The 6.6.3 strings.** For portal parity pass `{submit: 'Login', submitting: 'Please wait...'}`. |
+| `copy` | *(see below)* | Merged over the defaults. |
+
+`copy` keys: `title`, `subtitle`, `fieldLabel`, `placeholder`,
+`contactFieldLabel`, `sentTo` (`{contact}`), `resendPrompt`, `resend`,
+`resendIn` (`{seconds}`), `back`, `devOtpLabel`, `devOtpAction`,
+`invalidLength`, `invalidCode`, `resendFailed`, `verifying`, `resending`,
+`resent`, `success`.
+
+`contactFieldLabel` and `sentTo` are only rendered under `showContactField`.
+
+Not opt-in, because it cannot change the outcome for input that already worked:
+the code field **strips** non-digits and clamps to 6 instead of ignoring any
+value containing one, so a code pasted out of a text message as `123 456` lands
+rather than being dropped.
+
+#### ImpersonateGate
+
+"Open the client's portal as them" — a staff member follows a one-use link, this
+exchanges its token for a session and the browser lands in the portal. A
+curtain, not a screen: a spinner, or one error card.
+
+Framework-agnostic on purpose. It does not read the URL, write cookies, or know
+what a router is, so the same component serves a Next.js app and a React Router
+SPA.
 
 ```jsx
-<Verify logo="/path/to/logo.png" setSystemAuth={setAuthFunction} />
+<ImpersonateGate
+    token={searchParams.get('token')}
+    validateUrl="/api/validateImpersonationToken"
+    onAuthenticated={(user, token) => {
+        setCookie('portal_token', token, { maxAge: 3600 });
+        setUserData(user);
+    }}
+    redirectPath="/portal/dashboard"
+    loginPath="/portal"
+    onNavigate={(path) => router.push(path)}
+/>
 ```
 
+| Prop | Default | Notes |
+| --- | --- | --- |
+| `token` | — | Extracted from the URL **by the consumer**. |
+| `validateUrl` | `/api/validateImpersonationToken` | POST target. |
+| `buildBody` | `(t) => ({token: t, minimal_response: true})` | Request body builder. |
+| `onAuthenticated` | — | `(user, token)`. Where you persist your own session. May return a promise; it is awaited before the settle delay starts. |
+| `settleDelay` | `500` | Milliseconds between `onAuthenticated` and the redirect, so a `Set-Cookie` written in the callback is visible to the next request. |
+| `redirectPath` | `/portal/dashboard` | Where a successful hand-off lands. |
+| `loginPath` | `/portal` | The error card's "Go to Login" button. |
+| `onNavigate` | `undefined` | `(path) => void`. Absent, a full page load is used — usually what a session hand-off wants. |
+| `onError` | `undefined` | Notified with the normalised message when validation fails. |
+| `spinner` | *(built-in)* | Any node. |
+| `copy` | `{loading, errorTitle, loginAction, missingToken, failed}` | Merged over the defaults. |
+
+**Security:** neither the token nor the URL is logged, at any level, in any
+branch. The token is a bearer credential for someone else's account.
+
+#### LogoutScreen
+
+The 1.5s animated confirmation shown while a session is torn down. Signing out
+is the one action where "did that work?" matters and where an instant redirect
+leaves no evidence that it did.
+
+Callback-driven: this component clears nothing itself, because a library has no
+business deciding which of your cookies and storage keys constitute a session.
+
+```jsx
+<LogoutScreen
+    onLogout={() => {
+        removeCookie('portal_token');
+        clearUserData();
+    }}
+    redirectPath="/portal"
+/>
+```
+
+| Prop | Default | Notes |
+| --- | --- | --- |
+| `onLogout` | `undefined` | Runs once on mount (guarded against StrictMode's double invocation). |
+| `onComplete` | `undefined` | Runs after `delay`. Takes precedence over `redirectPath`. |
+| `redirectPath` | `undefined` | Hard navigation performed after `delay` when `onComplete` is absent. |
+| `delay` | `1500` | How long the confirmation is held. |
+| `icon` | Lucide `LogOut` | Any node. |
+| `showSpinner` | `true` | |
+| `copy` | `{title: 'Logging out...', message: 'Please wait while we log you out.'}` | Merged over the defaults. |
+
 #### Profile
 
 User profile management.
@@ -513,6 +1979,87 @@ User profile management.
 />
 ```
 
+### Call Queue Components
+
+Ported from the ThroughLife CRM in 6.7.0. Two ends of one feature: the pop that
+tells staff a call is ringing, and the settings page where the codes it dials
+are configured.
+
+#### CallQueuePop
+
+A permission-gated, root-level stack of "call is ringing" cards for every Zoom
+Phone call queue, so monitoring staff can see an incoming call without watching
+the Zoom client. Render it once, inside the authenticated shell.
+
+Everything that talks to the server is optional and fails silently, so the
+component is safe to ship ahead of its backend: with neither the snapshot
+endpoint nor an Echo instance present it renders nothing and logs nothing.
+
+```jsx
+<CallQueuePop
+    userProfile={userProfile}
+    echo={() => getEcho()} // lazily created — only a gated-in user connects
+    pickupEnabled={false}
+    trialBadge={false}
+/>
+```
+
+| Prop | Default | Notes |
+| --- | --- | --- |
+| `userProfile` | `undefined` | Gates the pop. Read for the Spatie shape `roles[].permissions[].name`, and for direct permissions. |
+| `echo` | `null` | The Laravel Echo instance, **or a factory function** returning one. A function is called lazily inside the subscription effect, so only a permission-gated user ever opens a connection. |
+| `channel` | `'call-queue-monitor'` | Fallback Echo channel. The live snapshot's own `channel` field wins once it lands — which is how the CRM scopes the channel per environment. Pass `null` to subscribe only once the server has named a channel. |
+| `pickupEnabled` | `false` | Replaces the CRM's hardcoded `PICKUP_ENABLED`. `false` renders Pick up visibly inert with a "coming soon" title; `true` makes it a live `zoomphonecall://` dial. |
+| `trialBadge` | `true` | `true` renders "Trial run — the call pop is being tested". A string replaces the copy; `false` hides the banner. |
+| `monitorPermission` | `'Call Queue Monitor'` | The Spatie permission name. |
+| `endpoints` | `{live: '/ajax/call-queue/live', clientTasks: (id) => '/ajax/call-queue/client/{id}/tasks'}` | Merged over the defaults. |
+| `onOpenTask` | `null` | `(task) => void`. Absent, a task row opens `taskUrl(task)` in a 1440×1024 popup window — the CRM's current behaviour. |
+| `taskUrl` | `(task) => '/tasks/detail/{id}'` | Builder, or a string template containing `{id}`. |
+| `clientUrl` | `(client) => '/clients/{id}'` | Ditto. |
+| `clientTasksUrl` | `(clientId) => '/tasks/0/{id}'` | The "View all tasks" link. |
+| `onOpenCalendar` | `null` | `(event) => void`. Absent, the "Next: …" line is a `<Link>` to `calendarPath`. |
+| `calendarPath` | `'/calendar'` | |
+| `callWorkspacePath` | `'/call/{number}'` | Template, or `(workspaceId, call) => path`. `{number}` is the `61…` form the workspace route expects. |
+| `syncChannelName` | `'throughlife-call-queue-pop'` | The `BroadcastChannel` that keeps every open tab's stack in step. Falsy switches cross-tab sync off. |
+| `demoEnabled` | `true` | Registers `window.callPopDemo()` / `window.callPopClear()` for reviewing the UI without a backend. |
+
+**Payload contract.** Snake_case and camelCase are both accepted, so a Laravel
+resource passes through untouched: `call_id`/`callId`, `queue_id`/`queueId`,
+`queue_name`/`queueName`, `caller_number`/`callerNumber`, `caller_name`,
+`started_at`, plus `client` (already resolved server-side) and, for demo cards,
+`tasks`. A call with no id is dropped; a queue with no name gets `Call Queue`.
+The snapshot's `pickup_codes` map is keyed by Zoom call queue id — a queue
+absent from it still pops, its card simply has no Pick up button.
+
+Named exports for testing: `toLocalDigits`, `formatAuPhone`, `formatEventDate`,
+`formatDueDate`, `toCallWorkspaceId`, `normaliseCall`, `normalisePickupCodes`,
+`formatElapsed`, `hasMonitorPermission`, `clientDetails`.
+
+#### CallQueueSettings
+
+The admin table behind the pop: one row per Zoom call queue, carrying the
+pickup code the pop tells staff to dial and whether the queue may pop at all.
+
+```jsx
+<CallQueueSettings
+    endpoints={{ list: '/ajax/call-queue/settings' }}
+    onSaved={(queue) => console.log('saved', queue.queue_id)}
+/>
+```
+
+| Prop | Default | Notes |
+| --- | --- | --- |
+| `endpoints` | `{list: '/ajax/call-queue/settings', save: (id) => '/ajax/call-queue/settings/{id}'}` | `save` also accepts an `{id}` template. |
+| `title` | `'Call Queues'` | |
+| `breadcrumb` | *(unset)* | Unset renders the CRM's `Settings > Call Queues` header. `null` renders no header. Any React node replaces it. |
+| `intro` | *(the CRM copy)* | The muted line above the table. |
+| `infoNote` | *(the CRM copy)* | The callout explaining that Zoom will not accept the digits over its API. |
+| `codePrefix` | `'*99'` | The dial prefix shown as an adornment on the code input. |
+| `onSaved` | `null` | `(queue) => void`, fired after a successful save. |
+
+Named exports for testing: `validateCode`, `cleanCode`, `formatAuNumber`,
+`titleCase`.
+
 ### DataGrid Component
 
 A powerful data table component with sorting, filtering, and pagination. The DataGrid features a modular column renderer architecture with support for 28 different column types.
@@ -3219,11 +4766,16 @@ This grouping is handled internally by the GenericAuth component, so you don't n
 ### How 2FA Works
 
 1. User enters email and password on the login screen
-2. If credentials are valid and 2FA is required, the backend returns `requires_2fa: true`
-3. The user is redirected to the 2FA verification screen
+2. If credentials are valid and 2FA is required, the backend returns `requires_two_factor: true`
+3. The user is redirected to the 2FA verification screen (`/2fa` by default; `twoFactorPath` on `Login` moves it)
 4. User enters the verification code
 5. If the code is valid, the user is authenticated and redirected to the main application
 
+> **Note (6.7.0):** this section previously documented `requires_2fa` and a
+> `{user_id, verification_code}` challenge body. Neither was ever what the code
+> sent — the field names below are the real contract, taken from
+> `Login.jsx` and `TwoFactorAuth.jsx`.
+
 ### Setting Up 2FA
 
 Users can set up 2FA through their profile page. The setup process includes:
@@ -3268,12 +4820,28 @@ The login form includes a "Remember Me" checkbox that persists through the 2FA v
 
 ### API Integration for 2FA
 
+`POST /login/authenticate` (configurable — `endpoints.authenticate`)
+
+Request:
+
+```json
+{
+    "email": "user@example.com",
+    "password": "…",
+    "remember": true,
+    "location": "/optional-previous-url"
+}
+```
+
 #### Login Endpoint Response (when 2FA is required)
 
+TOTP echoes the user, because its challenge screen renders the account it is
+challenging:
+
 ```json
 {
     "error": "",
-    "requires_2fa": true,
+    "requires_two_factor": true,
     "user": {
         "id": "user_id",
         "email": "user@example.com",
@@ -3282,14 +4850,44 @@ The login form includes a "Remember Me" checkbox that persists through the 2FA v
 }
 ```
 
+**The code (SMS) driver returns `user: null`, deliberately** — there the account
+is identified by a code sent out of band, so echoing the record would hand an
+unauthenticated caller a user lookup:
+
+```json
+{
+    "error": "",
+    "previous": "",
+    "user": null,
+    "requires_two_factor": true
+}
+```
+
+`Login` therefore marks the hand-over with `challenge: true` rather than
+relying on the user payload, and `TwoFactorAuth` bounces only when the router
+state is absent entirely (a direct URL hit or a reload). Anything that keys
+"is a challenge in progress?" off `userData` breaks every SMS sign-in: the code
+arrives and the screen to type it into never appears. `hasChallengeState` is
+exported if you need the same decision elsewhere.
+
+Neither driver sends a masked contact on the challenge response, and the resend
+answers a bare `{"error": ""}`, so `TwoFactorAuth`'s destination chip is not
+rendered against the current backend. `Login` reads `masked_contact` and threads
+it through anyway, so a backend that grows the field needs no change here.
+
+An `error` of `""` means success. A non-empty `error` is shown to the user and
+the credentials fields are marked invalid. `previous` (when present and
+non-empty) is followed instead of the default landing page.
+
 #### 2FA Verification Endpoint
 
+`POST /login/two-factor-challenge` (configurable — `endpoints.twoFactorChallenge`)
+
 Request:
 
 ```json
 {
-    "user_id": "user_id",
-    "verification_code": "123456",
+    "code": "123456",
     "previous_url": "/optional-redirect-url",
     "remember": true
 }
@@ -3297,19 +4895,26 @@ Request:
 
 Response:
 
+A successful challenge answers with the user object itself (no envelope). A
+rejected code answers **200** with `{"error": "…"}` — a 401 is reserved for a
+challenge whose session has expired, which bounces the user back to the login
+screen:
+
 ```json
 {
-    "error": "",
-    "user": {
-        "id": "user_id",
-        "email": "user@example.com",
-        "name": "User Name",
-        "roles": ["admin"]
-    },
-    "previous": "/optional-redirect-url"
+    "id": "user_id",
+    "email": "user@example.com",
+    "name": "User Name",
+    "roles": ["admin"]
 }
 ```
 
+#### 2FA Resend Endpoint (`mode="code"` only)
+
+`POST /login/two-factor-resend` (configurable — `endpoints.twoFactorResend`),
+with an empty body. Answers `{"error": ""}` on success, `{"error": "…"}`
+otherwise. Only ever called when `TwoFactorAuth` is in `mode="code"`.
+
 #### 2FA Setup Endpoint Response
 
 ```json