@dloizides/auth-web 1.21.0 → 1.22.0

package/CHANGELOG.md

@@ -1,626 +1,635 @@
-# Changelog
-
-## 1.21.0
-
-**`<LoginForm emailUsername>`.** Opt-in; the default username field is unchanged. When on, the username input
-renders `type="email"` + `autocomplete="username"` on web (`inputMode="email"`), and `keyboardType="email-address"` +
-`textContentType="username"` on native, so the email keyboard shows and password managers pair it with the
-password field.
-
-## 1.20.0
-
-`mapRegisterErrorCode` reads the typed `status` + body `errorCode` that `@dloizides/auth-client` 4.5.0
-`BffRequestError` carries (duck-typed, so it needs no auth-client bump to compile). New codes:
-`TenantNameTaken` (409 `TENANT_NAME_TAKEN`), `RateLimited` (429) and `AutoLoginFailed` (account created, sign-in
-failed: tell the user to sign in, not to retry). `USER_EXISTS` maps to `EmailTaken`; 5xx to `Failed`. Consumers
-with an exhaustive `Record<RegisterErrorCode, string>` must add the three new keys.
-
-## 1.19.0
-
-**`<RegisterForm compact>` (AUTH-REG-1 "Compact register form").** Opt-in; the default seven-field form is unchanged.
-Shows only "Your name", Email, Password and the tenant name. The name is split into firstName/lastName (one word
-fills both, since Keycloak needs a last name), the username is derived from the whole email (lower-cased, chars
-outside `[a-z0-9._-]` become `_`), and there is no confirm-password field. New optional `labels.fullName`.
-`splitFullName` and `deriveUsernameFromEmail` are exported. `useRegisterForm({ compact })` for headless use.
-
-## 1.18.3
-
-- `useLoginSubmit` has an in-flight ref guard, like `useRegisterForm`. A focused field stays read-only (not
-  disabled) during a pending login and RN-web still fires `onSubmitEditing` there, so a second Enter sent a
-  second `/bff/login`. jsdom tests now cover a pending submit + a second non-repeat Enter for both forms,
-  a valid register submitted by Enter, and an IME-composition Enter not submitting.
-
-## 1.18.2
-
-**Enter in a text field submits `<RegisterForm>` and `<LoginForm>`.**
-
-- Every visible input now has `onSubmitEditing` wired to the same guarded submit as the button, plus
-  `returnKeyType="go"`. RN-web renders no `<form>`, so Enter in a field never submitted in any prior
-  version (no `onSubmitEditing` anywhere in auth-web history); only a focused button did.
-- An OS key-repeat of a held Enter in a field is ignored (`useSubmitOnEnter`), so a held Enter is still
-  one attempt / one login. jsdom tests cover Enter in each of the seven register fields and both login fields.
-
-## 1.18.1
-
-**Review fixes for the 1.18.0 registration extraction.**
-
-- `<RegisterForm>` and `<LoginForm>` submit through the `@dloizides/ui-buttons` `Button` (new peer
-  dependency, `>=1.9.0`). A held Enter is one press: previously each OS key-repeat re-ran submit,
-  so a rejected login was re-sent per repeat and a register validation failure alerted per repeat.
-- `useRegisterForm` takes `onSubmitAttempt` and calls it after the in-flight guard, so a press
-  ignored mid-submit no longer fires the app's "signup started" analytics event.
-- Email check restored to the pre-extraction rule (`a@b.c@d` is rejected), without the backtracking regex.
-- Honeypot input gets `accessibilityRole="none"` again.
-- Outcome routing moved to a tested `routeRegisterOutcome`.
-- `mapRegisterErrorCode` is no longer exported: the form decodes errors itself and no consumer imported it.
-## 1.18.0
-
-**Registration form, extracted from katalogos-web and erevna-web.** Additive.
-
-- `<RegisterForm>`: themeable sign-up form with seven fields plus the off-screen `website` honeypot.
-  Props: `onSubmit(values)` (the app builds the request and calls its BFF), `onSuccess(result)`,
-  `onError(code)`, `onSubmitAttempt`, `passwordPolicy`, `labels`, `theme`, `footer`, `testIdPrefix`.
-- `useRegisterForm({ onSubmit, passwordPolicy })` returns `{ state, setField, submit, isSubmitting, error }`.
-  A filled honeypot is refused with `Failed` and no network call; a second press mid-submit returns `InFlight`.
-- `RegisterErrorCode` (const enum) and `mapRegisterErrorCode(error)` decode `USERNAME_TAKEN`, `EMAIL_TAKEN`,
-  `REALM_REQUIRED`, `REALM_INVALID`. No error copy in the package; apps map the code to FM() keys.
-- `RegisterTestIds` keep the unprefixed `register-*` values the E2E suites select on.
-- Also exported: `isRegisterPasswordStrong`, `DEFAULT_REGISTER_LABELS`, the `Register*` types.
-
-## 1.17.0
-
-**Multi-account demo login — the `<DemoCredentialsHint>` now renders one labelled,
-one-tap-fillable row per published demo account.** Additive and
-backward-compatible: a single account renders byte-for-byte as before.
-
-- **`resolveDemoAccounts` / `resolveAccountList`** (new exports) — resolve either
-  the `publishedAccounts` list (from `@dloizides/auth-client` 4.4.0 / a BFF on
-  Bff.AspNetCore 1.17.0+) or a legacy single pair into an ordered, validated
-  `DemoAccount[]`. `resolveDemoCredentials` is unchanged and still exported.
-- **`useDemoCredentials().hintProps`** gains `accounts: DemoAccount[]` (the
-  resolved list). `credentials` is still passed through unchanged, so the field
-  is purely additive; `onUse` fills whichever account the hint reports.
-- **`<DemoCredentialsHint>`** gains an `accounts?` prop (preferred over
-  `credentials` when present). One account → no per-account heading, unsuffixed
-  testIDs (unchanged). Multiple accounts → each gets its label heading and
-  index-suffixed testIDs (`…-username-0`, `…-use-1`, `…-account-label-0`).
-- New testID `demoCredentialsAccountLabel`; new re-exported type `DemoAccount`.
-- Bumps `@dloizides/auth-client` to `^4.4.0` for the `publishedAccounts` type.
-
-## 1.16.0
-
-**New shared `AccountSettingsScreen` — one authenticated account surface for all
-seven portals, plus a first-class in-app change-password form.**
-
-Adds `AccountSettingsScreen`: a self-contained, theme-driven surface that stacks
-the account-management cards each portal was otherwise wiring by hand. Sections
-are config-driven — a card renders only when its config is passed:
-
-- **Change password (always):** a new `ChangePasswordCard` — a real in-app form
-  (current / new / confirm) with client-side validation (new === confirm + the
-  shared password policy) that submits `POST /bff/account/change-password`
-  (204 → success; 400 → "current password incorrect or fails the policy";
-  401 → session expired). The signed-in user changes their OWN password in the
-  app — no Keycloak-console detour. This package never stores, logs or inspects
-  the password values; it forwards them to the app's own BFF over the session
-  cookie and reads back only a status.
-- **Device PIN (optional):** the existing `DevicePinSettingsCard`.
-- **Passkeys (optional):** the existing `PasskeySettingsCard`.
-- **Preferred sign-in method (optional):** the existing `PreferredMethodSettingsCard`.
-
-New public API:
-
-- `AccountSettingsScreen` + `AccountSettingsScreenProps` and the per-section
-  config types (`AccountSettingsChangePasswordConfig`, `AccountSettingsDevicePinConfig`,
-  `AccountSettingsPasskeysConfig`, `AccountSettingsPreferredMethodConfig`).
-- `ChangePasswordCard` + `ChangePasswordCardProps`.
-- `useChangePassword` (react-query-free form state + validation + submit),
-  `ChangePasswordErrorKey`, `ChangePasswordResult`.
-- `createBffChangePasswordClient` (ready same-origin BFF client, CSRF marker
-  header attached) + `ChangePasswordCapableClient` / `ChangePasswordRequest` /
-  `CHANGE_PASSWORD_ENDPOINT` / `CreateBffChangePasswordClientOptions`.
-- `AccountSettingsLabels` + `DEFAULT_ACCOUNT_SETTINGS_LABELS`.
-
-Backend contract required by adopters: `POST /bff/account/change-password`,
-body `{ currentPassword, newPassword }` → `204` on success, `400` on
-wrong-current/policy-fail, `401` when unauthenticated.
-
-## 1.14.0 (2026-07-19)
-
-Three defects found by measuring the DEPLOYED portals rather than reading the
-source. All three had passing tests over them.
-
-### Fixed
-
-- **The auth card no longer vertically centres, so expanding anything stops
-  moving the inputs.** Measured on `app.zygos.dloizides.com/login` at 1.13.0:
-  expanding the demo disclosure grew the card 445.6 → 589.6px and pulled the
-  username input from `y=275.2` to `y=203.2` and the password from `y=368.8` to
-  `y=296.8` — **72px UP each**, mid-interaction. `<DemoCredentialsHint>` was
-  deliberately mounted BELOW the form to avoid exactly this; centring defeated
-  the placement, because a centred card re-centres as it grows and drags
-  everything above the growth upward.
-
-  `useAuthScreenStyles.screen` and `useAuthStyles.screen` are now top-anchored
-  (`justifyContent: 'flex-start'` + a 64dp `paddingTop`) instead of centred.
-  ⚠️ **This is a visible change on every portal**: the login card now sits below
-  a fixed gap rather than floating in the middle of tall viewports.
-
-  Chosen over the alternatives because the defect is not specific to the
-  disclosure — ANY growth shifted the fields (a validation error under an input,
-  a passkey button arriving after the config fetch, an OTP tab swap), and only
-  top-anchoring fixes the whole class. Reserving the disclosure's height would
-  have left ~144px of permanent dead space on every login; absolutely
-  positioning the expanded panel would have removed it from the scrollable area,
-  making the credentials unreachable on a short viewport. Top-anchoring is also
-  strictly safer at small viewports than what it replaces: overflow now runs
-  downward only, where centring pushed the top of the card past the top edge
-  where no scroll could reach it.
-
-- **Selection and expansion states are now announced on the web.** Three
-  components declared `accessibilityState` and announced nothing:
-  `<DemoCredentialsHint>` (`expanded`), `<DevicePinLengthPicker>` (`selected`)
-  and `<PreferredMethodSettingsCard>` (`selected`). Each now passes the ARIA
-  attribute **explicitly** (`aria-expanded` / `aria-checked`) alongside the RN
-  prop, which is kept for native.
-
-  Root cause is systemic, not a typo. Measured against react-native-web 0.21.2:
-  a `<TouchableOpacity>` given `accessibilityLabel`, `accessibilityRole`,
-  `accessibilityHint` and `accessibilityState={{ expanded: true, selected: true }}`
-  renders `<button role="button" aria-label="…">` — **no `aria-expanded`, no
-  `aria-selected`, and no trace of the hint at all**. `accessibilityState` is not
-  read by react-native-web; `accessibilityHint` produces zero DOM output.
-
-  For `<DevicePinLengthPicker>` the practical effect was WCAG 1.4.1: the chosen
-  PIN length was distinguishable only by the pill's fill colour. Its options also
-  move from `accessibilityRole="button"` to `"radio"` inside a `radiogroup`,
-  since `aria-checked` is only meaningful on a checkable role.
-
-- **Field labels now speak the shared contract's `field` voice — 13/600, not
-  14/600.** The forms contract (mirrored in `@dloizides/ui-forms`'
-  `labelVariants.ts`) defines exactly two label voices: `field` (13/600, sentence
-  case) and `control` (11/700, uppercase). `defaultAuthTheme.typography.label`
-  was 14, which is neither — drift, inherited uniformly by every portal, since
-  they all reuse `defaultAuthTheme.typography` verbatim. It read against the 13px
-  `Field` labels those same apps use on every non-auth form.
-
-### Tests
-
-- **New DOM-level guards** (`*.dom.test.tsx`), rendered through the real
-  `react-native-web` in a `jsdom` environment, asserting the rendered
-  **attribute** rather than the React prop. This is the point: the pre-existing
-  suite mocked `react-native` down to host strings and asserted
-  `props.accessibilityState` — so it passed, unchanged, against a button that
-  announced nothing in every browser. A prop assertion cannot catch this class of
-  bug, and did not.
-- `authVisualContract.test.ts` guards the two visual contracts by naming the
-  defect they forbid (`justifyContent` must NOT be `'center'`; labels must be
-  13/600 written as a literal, not read back from the token under test).
-
-`<DemoCredentialsHint>` gets a **discreet** presentation, and it is now the
-default. The demo stops competing with the sign-in form on login pages that real
-customers use every day.
-
-### Added
-
-- **`DemoCredentialsHintVariant`** (`Panel` | `Disclosure`), exported from the
-  package root.
-- **`Disclosure` variant** — one quiet, centred "Try the demo" line that expands
-  the credentials and the fill button on tap. Collapsed on mount.
-- **`toggle` / `toggleHint` labels** on `DemoCredentialsHintLabels`, so the
-  trigger copy is localised by the host like every other string in the package.
-- **`AuthTestIds.demoCredentialsToggle`** (`auth-demo-credentials-toggle`).
-
-### Changed
-
-- ⚠️ **`<DemoCredentialsHint>` now defaults to `Disclosure`.** A consumer that
-  wants the old always-open block must pass
-  `variant={DemoCredentialsHintVariant.Panel}`. No API broke — every existing
-  prop, `testID` and callback behaves identically — but the rendered output
-  changes, so this is called out as loudly as a breaking change.
-- The credential rows + fill button moved into an internal
-  `<DemoCredentialsBody>` shared by both variants, so the two presentations can
-  never drift apart.
-
-### Notes on the design
-
-Discretion is carried by **size, placement and the absence of chrome** — the
-trigger is caption-sized, centred, and has no fill, border or brand rail. It is
-NOT carried by lowering contrast: the trigger draws `colors.textSecondary`, the
-same AA-held token as the rest of the package's helper copy, so it inherits
-whatever contrast guarantee the consuming app's theme already makes.
-
-The trigger stays a real focusable `accessibilityRole="button"` carrying
-`accessibilityState.expanded`, so screen readers announce that it exists and
-whether it is open. Visually quiet is not the same as hidden.
-
-The expanded body renders **below** the trigger, and the component is intended to
-sit **below** `<LoginForm>`. Expanding therefore grows the card downward and never
-displaces the inputs the visitor is using — mounting it above the form is what
-would make every expansion shove the fields down the page.
-
-
-## 1.12.1 (2026-07-17)
-
-Internal refactor only — **no API change, no behaviour change**. The public
-export surface (`src/index.ts`) is byte-identical to 1.12.0; every consumer
-(zygos, katalogos, erevna, kefi, ichnos) keeps importing the same symbols with
-the same types from the same entry point.
-
-Two oversized source files from the demo-credential work were split to satisfy
-the repo size limits (files < 300 lines, components < 200):
-
-- **`src/components/labels.ts` (511 lines) → `src/components/labels/`.** The
-  single label bag is now one file per component family (`loginLabels.ts`,
-  `forgotPasswordLabels.ts`, `otpLabels.ts`, `pinLabels.ts`, `devicePinLabels.ts`,
-  `passkeyLabels.ts`, `preferredMethodLabels.ts`, `demoLabels.ts`,
-  `resetPasswordLabels.ts`) behind a `labels/index.ts` barrel that re-exports the
-  exact same names, so `./labels` remains a single import site.
-- **`src/components/LoginForm.tsx` (253 lines) → render body slimmed.** The
-  prop-doc-heavy `LoginFormProps` interface moved to a co-located
-  `LoginForm.types.ts` (re-exported from `LoginForm.tsx`), and the submit branch
-  logic moved into a unit-tested `useLoginSubmit` hook.
-
-### Changed
-
-- No runtime change. Splitting only; identical bundled output.
-
-Completes the demo-credential feature for **BFF-fronted apps**, whose demo pair
-arrives ASYNChronously from `GET /bff/config` rather than a module-level const (a
-const would bake the credentials into a bundle handed to a customer to
-self-deploy). Two gaps closed:
-
-1. `prefillOnMount` was inert for async credentials (1.11.0 bug).
-2. `useBffLoginConfig().config` dropped the `demo` field the BFF now serves.
-
-Requires `@dloizides/auth-client` **>= 4.2.0** (which surfaces `demo` on
-`BffLoginConfig`) — the peer floor is raised accordingly. Additive for existing
-consumers: the new `LoginForm` prop is optional and the synchronous /
-module-const path is byte-identical.
-
-### Fixed
-
-- **`prefillOnMount` now honours credentials that arrive AFTER mount.** `useState`
-  reads its initial argument on the first render only, so a demo pair landing a
-  render later (every BFF app) was silently dropped and the form stayed empty
-  beside a populated hint. `useDemoCredentials` now seeds when the resolved pair
-  transitions to non-null (or to a genuinely different pair), gated by VALUE so a
-  react-query refetch handing back a fresh-but-equal object does not re-seed on a
-  loop.
-
-### Added
-
-- **`config.demo` carries through `useBffLoginConfig`.** `BffLoginConfig` gains
-  `demo?: DemoCredentials | null`, so the intended wiring works end-to-end:
-  ```tsx
-  const { config } = useBffLoginConfig(bffAuthClient);
-  const demo = useDemoCredentials({ credentials: config.demo ?? undefined, prefillOnMount: true });
-  ```
-- **`PrefillIntent`** enum + **`LoginForm` gains `prefillIntent`** — the "don't
-  fight the user" control. An `Opportunistic` re-seed (a late config fetch) is
-  DROPPED unless both fields are still empty, so it never overwrites what a real
-  account holder is typing while `/bff/config` is in flight; an `Explicit` re-seed
-  (the user tapped "use these credentials") always applies. `useDemoCredentials`
-  sets the right intent automatically — most apps never touch this prop.
-- **`DemoCredentials` is now re-exported from `@dloizides/auth-client`** (its
-  canonical owner) rather than defined locally, so there is exactly ONE shape
-  across the two packages. Structurally identical to 1.11.0 — no consumer change.
-
-### "Don't fight the user" — what the hook can and cannot know
-
-`useDemoCredentials` does not own the input fields (`<LoginForm>` does), so it
-cannot observe keystrokes. The interaction test it CAN make is on the field
-values: an opportunistic seed applies only when both fields are still empty
-(pristine). This is intentionally conservative — a user who typed and then
-cleared a field keeps control for the rest of the session (a dropped
-opportunistic bump is not retried). An explicit user request is never subject to
-this test.
-
-## 1.11.0 (2026-07-17)
-
-Additive release adding **public demo-credential support** for products with an
-open, published demo account (Zygos is the first). Purely additive — every 1.10.0
-export is unchanged, and an app that imports none of the new exports renders
-byte-identically: the three new `<LoginForm>` props are all optional and inert
-when omitted.
-
-It fills form fields and nothing else. **No auth bypass**: the demo login travels
-the ordinary path (same BFF, same Keycloak, same session cookie, same roles), and
-no credential ships inside this package — the host supplies the pair.
-
-### Added
-
-- **`<DemoCredentialsHint>`** — a themed panel for the login card showing a
-  published demo username + password with a one-tap "use these credentials"
-  action. Takes the usual `AuthTheme` / `labels` / `testIdPrefix` props. Values
-  render as selectable monospace chips (an `l`/`1` in a published password must
-  not be a guess). Omit `onUse` for a read-only panel.
-
-  **Fails closed**: no credentials — or a half-configured pair (blank username,
-  blank password, or a field that is `undefined` at runtime because an env var
-  was never set) — renders `null`. Zero DOM. A misconfigured demo can never
-  publish an empty credentials panel.
-
-- **`useDemoCredentials({ credentials?, prefillOnMount? })`** — the hint↔form
-  wiring, so no app hand-rolls it. Returns two prop bags to spread:
-  `hintProps` (`{ credentials, onUse }`) and `loginFormProps`
-  (`{ initialUsername, initialPassword, prefillNonce }`).
-
-  `prefillOnMount` (default `false`) makes the form arrive already filled, so
-  signing in as the demo user is a single tap on "Sign in".
-
-- **`resolveDemoCredentials(credentials?)`** — the exported fail-closed gate the
-  above share: returns a trimmed pair, or `null` when there is no usable demo.
-
-- **`DemoCredentials`** type and `DEFAULT_DEMO_CREDENTIALS_HINT_LABELS` /
-  `DemoCredentialsHintLabels` (all copy stays app-supplied, as everywhere else).
-
-- **`<LoginForm>` gains `initialUsername` / `initialPassword` / `prefillNonce`.**
-  The `initial*` props **seed** the fields; they do not own them — every value
-  stays editable and clearable, so a real account holder can always wipe the demo
-  values and sign in with their own. `prefillNonce` is the re-seed signal:
-  changing it re-applies the seed over fields the user has edited or cleared.
-
-  The nonce is not ceremony. `useState` ignores its initial argument on
-  re-render, so a fill button wired to `initialUsername` alone would render a
-  form that stays stubbornly empty — the nonce is what makes "click the hint →
-  form fills" work at all. `useDemoCredentials` manages it for you.
-
-### Internal
-
-- `useLoginPrefill` — extracts `<LoginForm>`'s credential field state (the only
-  part of that component with real logic), so the seed/re-seed contract is unit
-  tested directly rather than through the JSX.
-
-## 1.10.0 (2026-07-17)
-
-Additive release adding the shared **logout sequencer**. Purely additive — every
-1.9.x export is unchanged, no component behaviour changes, and apps that do not
-import `performBffLogout` are byte-identical.
-
-### Added
-
-- **`performBffLogout({ client, onClearSession?, onRedirect?, onError?, navigateToIdp? })`**
-  — the shared logout sequence, extracted because all six consuming apps
-  hand-rolled it in their own `AuthProvider` and the orderings disagreed. Runs:
-  1. `onClearSession()` — local state first, so the UI reflects the sign-out
-     immediately.
-  2. `await client.logout({ redirect: false })` — lets the `POST /bff/logout`
-     SETTLE, and takes the IdP logout URL rather than letting the client navigate
-     mid-sequence.
-  3. Navigates exactly once, last: to the IdP logout URL when the BFF returned
-     one (ending the IdP browser session), otherwise `onRedirect()`. When it
-     navigates to the IdP it deliberately does NOT also call `onRedirect` — two
-     competing navigations would race, and the IdP round-trip already returns the
-     user to the app.
-
-  Never rejects; always navigates, even when the BFF logout fails (a down BFF
-  must not trap the user on a page they asked to leave).
-- **`BffLogoutClient`** / **`PerformBffLogoutOptions`** types.
-
-### Why
-
-`zygos-web` and `agora-web` navigated FIRST and called the BFF second:
-
-```ts
-redirectTo('/(auth)/login');   // → window.location.replace() → document unload
-await bffAuthClient.logout();  // races the unload — may never be sent
-```
-
-That is wrong twice over:
-
-1. **The BFF call can be cancelled.** A document navigation kills in-flight
-   fetches, so `POST /bff/logout` may never reach the server: the SPA looks
-   logged out while the httpOnly session cookie stays alive. The `catch` logged
-   it "non-fatal", so the defect was silent.
-2. **The IdP session survives.** `BffAuthClient.logout()` ends the identity
-   provider's browser session with a top-level navigation to its RP-initiated
-   logout URL (only a real navigation carries the IdP's own cookie — a
-   back-channel POST cannot clear it). An app that navigates to its own login
-   route first pre-empts that navigation, so the IdP still considers the user
-   signed in and the next authorize round-trip silently re-authenticates them —
-   the "sign-out that signs you back in" bug the client's own docs warn about.
-
-Synthetic tests that stub the client never reproduce either failure (there is no
-real navigation to cancel the request), which is why they survived. The helper
-owns the sequence so neither can be reintroduced per-app.
-
-## 1.8.0 (2026-07-09)
-
-Additive release for the Move 2b passkey in-app rebuild — the passkey ceremony
-now runs **in-page** (`navigator.credentials.*` against the BFF's same-origin
-`/bff/passkey/*` fetch endpoints) instead of a full-page redirect to Keycloak.
-**Inert by default / no behaviour change until the BFF's WebAuthn RP is
-configured:** when the RP is off the options endpoint returns 501 and the hook
-transparently falls back to the legacy redirect. No breaking changes; every
-1.7.x export is unchanged and the legacy `startPasskeyLogin` /
-`startPasskeyRegistration` navigation helpers stay exported (they ARE the
-fallback).
-
-### Added
-
-- **`usePasskeyCeremony({ mode, returnUrl, onSuccess })`** — the react-query-free
-  in-page ceremony hook: options fetch → `navigator.credentials.create/get` →
-  verify fetch. Returns `{ status, error, isSupported, start, reset }`. Falls
-  back to the legacy Keycloak redirect on a 501 (RP not configured), any non-2xx
-  options response, or an unsupported browser — so nothing regresses until the
-  owner flips `Bff:Passkey`. A cancelled/timed-out ceremony (`NotAllowedError` /
-  `AbortError`) surfaces as `'cancelled'`, anything else as `'failed'`.
-- **`PasskeyCeremonyMode`** (`Login` / `Register`) and **`PasskeyCeremonyStatus`**
-  (`Idle` / `Running` / `Success` / `Error`) `const enum`s.
-
-### Changed
-
-- **`<PasskeyLoginButton>`** and **`<PasskeySettingsCard>`** now drive
-  `usePasskeyCeremony` instead of `window.location.assign`. Same exported props,
-  same testIDs — a drop-in bump for consumers; the in-page path only activates
-  once the BFF RP is configured, otherwise they behave exactly as before.
-
-## 1.7.0 (2026-07-07)
-
-Additive release for the Kefi multi-role overhaul — the shared machinery for a
-cross-dashboard nav. No breaking changes; every 1.6.x export is unchanged.
-
-### Added
-
-- **`resolveAccessibleRoutes(user, table)`** — the multi-role companion to
-  `resolvePostLoginRoute`. Returns the full, ordered list of `RoleRoute` entries
-  the user's role-set unlocks (not just the top one), reusing the same
-  `collectUserRoles` reader and `RoleRouteTable`. Table (priority) order is
-  preserved; the table `fallback` is never included; a role-less user gets `[]`.
-  Pure and app-agnostic — an app renders the result as a cross-dashboard nav.
-- **`RoleRoute.labelKey?`** — optional translation key carried per route so a
-  consuming app can render a localized label per accessible dashboard. Ignored
-  by `resolvePostLoginRoute`; the package stays i18n-agnostic (carries the key,
-  the app resolves it).
-
-## 1.3.0 (2026-05-31)
-
-Additive release for the auth-UX reuse roll-out (feature-reuse-roadmap #1).
-Promotes the "Forgot password?" modal body the product apps each hand-rolled
-into a single shared, **react-query-free** export so katalogos / erevna / kefi
-stop duplicating it. No breaking changes; every 1.2.x export is unchanged.
-
-### Added
-
-- **`<ForgotPasswordFields>`** — the embedded, themeable "request a reset link"
-  body, sized to live inside an app-owned modal shell (no screen/card wrapper,
-  no title — the host modal owns those). Adds the two modal affordances a
-  screen-shaped form lacks: a `Cancel` button beside submit and a `Close` button
-  on the success state, each rendered only when its handler is supplied. Clears
-  itself when `visible` flips to `false` so reopening starts fresh.
-- **`useForgotPasswordSubmit`** — the headless, **react-query-free** forgot-
-  password logic: a plain `useState` + `client.forgotPassword(...)` promise
-  chain that runs on a provider-less login route (where the existing
-  `useBffForgotPassword` `useMutation` crashes with "No QueryClient set"). Email
-  validation gating via `canSubmit`, anti-enumeration success, `hasNetworkError`,
-  and `reset()`. Also exports the `isValidForgotPasswordEmail` helper.
-- **`ForgotPasswordFieldsLabels`** + **`DEFAULT_FORGOT_PASSWORD_FIELDS_LABELS`** —
-  the forgot-password label bag plus the modal `cancel` / `close` strings.
-- New `AuthTestIds` entries `forgotPasswordCancelButton` /
-  `forgotPasswordCloseButton`.
-
-### Notes
-
-- The existing screen-shaped `<ForgotPasswordForm>` (react-query-based) is
-  unchanged. A future cleanup may re-base it on `useForgotPasswordSubmit` to drop
-  its react-query coupling; deferred to keep this release additive.
-
-## 1.2.0 (2026-05-22)
-
-Additive release for Phase 3d of the unified-auth plan — the event-scoped PIN
-UI. Adds the native, branded event-PIN login surface so an app (Kefi) can offer
-"sign in with your event PIN" for operational staff (door / DJ / media) without
-the user ever bouncing to Keycloak's hosted UI. No breaking changes; every
-1.1.0 export is unchanged.
-
-### Added
-
-- **`<PinForm>`** — the ready-made, themeable single-step event-PIN login form,
-  built on `usePinLogin`. A PIN field + a "sign in" button; the
-  `eventExternalId` is a prop (the event context comes from the route/page, it
-  is never typed by the user). Styled by the same `AuthTheme` token bag as the
-  other forms; copy is supplied through the i18n-agnostic `PinFormLabels` bag
-  (English `DEFAULT_PIN_LABELS` fallback). `onSuccess` hands back the signed-in
-  `BffUser`.
-- **`usePinLogin`** — the headless PIN hook (the custom-layout escape hatch). A
-  single-step flow: `submit(pin)` → `POST /bff/pin/login` → `BffUser`, with
-  `reset()`. Mirrors `useOtpLogin` (mounted-guard, memoised result,
-  latest-`eventExternalId` ref).
-- **`PinFormLabels`** + **`DEFAULT_PIN_LABELS`** — the PIN label bag.
-- New `AuthTestIds` entries for every PIN interactive element.
-- Re-exports `BffPinLoginRequest` from `@dloizides/auth-client`.
-
-### Changed
-
-- Peer dependency `@dloizides/auth-client` raised to `>=3.2.0` — the version
-  that adds `BffAuthClient.pinLogin`.
-
-## 1.1.0 (2026-05-22)
-
-Additive release for Phase 2d of the unified-auth plan — the email-OTP UI. Adds
-the native, branded email-OTP login surface so an app can offer "sign in with a
-code" without the user ever bouncing to Keycloak's hosted UI. No breaking
-changes; every 1.0.0 export is unchanged.
-
-### Added
-
-- **`<OtpForm>`** — the ready-made, themeable two-step email-OTP login form,
-  built on `useOtpLogin`. Step 1 collects the email and sends a code; step 2
-  collects the code, verifies it, and offers "resend code" and "use a different
-  email". Styled by the same `AuthTheme` token bag as the other forms; copy is
-  supplied through the i18n-agnostic `OtpFormLabels` bag (English
-  `DEFAULT_OTP_LABELS` fallback). `onSuccess` hands back the signed-in `BffUser`.
-- **`useOtpLogin`** — the headless OTP hook (the custom-layout escape hatch). A
-  small forward state machine over `OtpLoginStep`: `requestCode(identifier)` →
-  `EnterCode`, then `verifyCode(otp)` → `BffUser`, with `resend()` and
-  `reset()`. Mirrors `useBffAuth` (mounted-guard, memoised result).
-- **`OtpLoginStep`** — the `RequestCode` / `EnterCode` step enum.
-- **`OtpFormLabels`** + **`DEFAULT_OTP_LABELS`** — the OTP label bag.
-- New `AuthTestIds` entries for every OTP interactive element.
-- Re-exports `BffOtpRequestRequest`, `BffOtpVerifyRequest` and
-  `BffOtpRequestResult` from `@dloizides/auth-client`.
-
-### Changed
-
-- Peer dependency `@dloizides/auth-client` raised to `>=3.1.0` — the version
-  that ships `BffAuthClient.requestOtp` / `.verifyOtp` (`POST /bff/otp/request`
-  and `POST /bff/otp/verify`).
-
-### Notes
-
-- Still strictly thin: UI + the same-origin `/bff/*` client. The OTP client
-  methods carry the `X-BFF-Csrf` header like every other state-changing call;
-  no token handling, no secrets in the browser.
-- This release adds the OTP surface to the package only. Wiring an app onto it
-  (the Kefi pilot) is Phase 3.
-
-## 1.0.0 (2026-05-22)
-
-Initial release — the frontend half of the unified-auth plan (Phase 1b).
-
-`@dloizides/auth-web` is the shared, themeable, branded auth UI for the
-dloizides.com portfolio. It is extracted and generalised from the per-app auth
-code that lived inside `apps/katalogos-web` so katalogos, erevna and kefi can
-share one implementation instead of copy-pasting auth adapters.
-
-### Added
-
-- **Themeable components**
-  - `<LoginForm>` — password login, built on `useBffAuth`.
-  - `<ForgotPasswordForm>` — request-a-reset-link, built on
-    `useBffForgotPassword`; no-enumeration confirmation state.
-  - `<ResetPasswordForm>` — choose-a-new-password, built on
-    `useResetPasswordForm`.
-  - All three are styled by an `AuthTheme` design-token bag so visually
-    distinct apps share one implementation.
-- **Theming** — `AuthThemeProvider`, `useAuthTheme`, `defaultAuthTheme`, and
-  the `AuthTheme` token contract (colors / radii / spacing / typography).
-  Precedence: explicit `theme` prop → `<AuthThemeProvider>` context → default.
-- **i18n-agnostic label bags** — `LoginFormLabels`, `ForgotPasswordFormLabels`,
-  `ResetPasswordFormLabels` plus English `DEFAULT_*` constants. The package
-  ships no `t()` / `FM()`; consuming apps pass already-localised strings.
-- **Headless hooks** (the custom-layout escape hatch)
-  - `useBffAuth` — login / logout / `/bff/me` session, lifecycle status.
-  - `useBffForgotPassword`, `useBffResetPassword` — React Query mutations.
-  - `useResetPasswordForm` — reset-password form-state + validation logic.
-- **`createBffAuthClient`** — one-line wiring of a same-origin `BffAuthClient`
-  with a lazily-resolved `fetch` (load-time side-effect-free).
-- **Role-based post-login router** — `resolvePostLoginRoute(user, table)` and
-  `collectUserRoles`. The consuming app supplies the role → route table.
-- **Password policy** — `validatePasswordPolicy`, `isPasswordValid`,
-  `PasswordPolicyError`; mirrors the TenantService backend rules.
-- **Test IDs** — `AuthTestIds` + `withTestIdPrefix` for E2E targeting.
-- Re-exports `BffAuthClient`, `createFetchHttpClient` and the BFF request /
-  response types from `@dloizides/auth-client` so consumers have a single
-  import surface.
-
-### Notes
-
-- Strictly thin: UI + a same-origin `/bff/*` fetch client + the router helper.
-  **No secrets, no token handling, no Keycloak calls** — the per-app BFF owns
-  all of that server-side.
-- Built on `@dloizides/auth-client` (peer dependency `>=3.0.0`), which ships
-  `BffAuthClient`.
-- This release creates the package only. Porting `apps/katalogos-web` onto it
-  is Phase 1c.
+# Changelog
+
+## 1.22.0
+
+**`<VerifyEmailScreen>` (AGORA-VERIFY-1 "agora-web has no verify-email route").** Extracted from the erevna-web /
+katalogos-web `app/(auth)/verify-email.tsx`. The app passes the `token` (read it with `readVerifyToken`), the
+`onContinue` route, a `labels` bag (`DEFAULT_VERIFY_EMAIL_LABELS`) and optional `onVerified` / `onFailed` funnel
+callbacks. Headless: `useVerifyEmail`, `useResendVerification`, `createBffVerifyEmailClient` (`POST
+/bff/verify-email`, `POST /bff/resend-verification`), `buildVerifyUrlTemplate`, `verifyEmailErrorText`,
+`VerifyEmailErrorCode`, `VerifyEmailPhase`.
+
+## 1.21.0
+
+**`<LoginForm emailUsername>`.** Opt-in; the default username field is unchanged. When on, the username input
+renders `type="email"` + `autocomplete="username"` on web (`inputMode="email"`), and `keyboardType="email-address"` +
+`textContentType="username"` on native, so the email keyboard shows and password managers pair it with the
+password field.
+
+## 1.20.0
+
+`mapRegisterErrorCode` reads the typed `status` + body `errorCode` that `@dloizides/auth-client` 4.5.0
+`BffRequestError` carries (duck-typed, so it needs no auth-client bump to compile). New codes:
+`TenantNameTaken` (409 `TENANT_NAME_TAKEN`), `RateLimited` (429) and `AutoLoginFailed` (account created, sign-in
+failed: tell the user to sign in, not to retry). `USER_EXISTS` maps to `EmailTaken`; 5xx to `Failed`. Consumers
+with an exhaustive `Record<RegisterErrorCode, string>` must add the three new keys.
+
+## 1.19.0
+
+**`<RegisterForm compact>` (AUTH-REG-1 "Compact register form").** Opt-in; the default seven-field form is unchanged.
+Shows only "Your name", Email, Password and the tenant name. The name is split into firstName/lastName (one word
+fills both, since Keycloak needs a last name), the username is derived from the whole email (lower-cased, chars
+outside `[a-z0-9._-]` become `_`), and there is no confirm-password field. New optional `labels.fullName`.
+`splitFullName` and `deriveUsernameFromEmail` are exported. `useRegisterForm({ compact })` for headless use.
+
+## 1.18.3
+
+- `useLoginSubmit` has an in-flight ref guard, like `useRegisterForm`. A focused field stays read-only (not
+  disabled) during a pending login and RN-web still fires `onSubmitEditing` there, so a second Enter sent a
+  second `/bff/login`. jsdom tests now cover a pending submit + a second non-repeat Enter for both forms,
+  a valid register submitted by Enter, and an IME-composition Enter not submitting.
+
+## 1.18.2
+
+**Enter in a text field submits `<RegisterForm>` and `<LoginForm>`.**
+
+- Every visible input now has `onSubmitEditing` wired to the same guarded submit as the button, plus
+  `returnKeyType="go"`. RN-web renders no `<form>`, so Enter in a field never submitted in any prior
+  version (no `onSubmitEditing` anywhere in auth-web history); only a focused button did.
+- An OS key-repeat of a held Enter in a field is ignored (`useSubmitOnEnter`), so a held Enter is still
+  one attempt / one login. jsdom tests cover Enter in each of the seven register fields and both login fields.
+
+## 1.18.1
+
+**Review fixes for the 1.18.0 registration extraction.**
+
+- `<RegisterForm>` and `<LoginForm>` submit through the `@dloizides/ui-buttons` `Button` (new peer
+  dependency, `>=1.9.0`). A held Enter is one press: previously each OS key-repeat re-ran submit,
+  so a rejected login was re-sent per repeat and a register validation failure alerted per repeat.
+- `useRegisterForm` takes `onSubmitAttempt` and calls it after the in-flight guard, so a press
+  ignored mid-submit no longer fires the app's "signup started" analytics event.
+- Email check restored to the pre-extraction rule (`a@b.c@d` is rejected), without the backtracking regex.
+- Honeypot input gets `accessibilityRole="none"` again.
+- Outcome routing moved to a tested `routeRegisterOutcome`.
+- `mapRegisterErrorCode` is no longer exported: the form decodes errors itself and no consumer imported it.
+## 1.18.0
+
+**Registration form, extracted from katalogos-web and erevna-web.** Additive.
+
+- `<RegisterForm>`: themeable sign-up form with seven fields plus the off-screen `website` honeypot.
+  Props: `onSubmit(values)` (the app builds the request and calls its BFF), `onSuccess(result)`,
+  `onError(code)`, `onSubmitAttempt`, `passwordPolicy`, `labels`, `theme`, `footer`, `testIdPrefix`.
+- `useRegisterForm({ onSubmit, passwordPolicy })` returns `{ state, setField, submit, isSubmitting, error }`.
+  A filled honeypot is refused with `Failed` and no network call; a second press mid-submit returns `InFlight`.
+- `RegisterErrorCode` (const enum) and `mapRegisterErrorCode(error)` decode `USERNAME_TAKEN`, `EMAIL_TAKEN`,
+  `REALM_REQUIRED`, `REALM_INVALID`. No error copy in the package; apps map the code to FM() keys.
+- `RegisterTestIds` keep the unprefixed `register-*` values the E2E suites select on.
+- Also exported: `isRegisterPasswordStrong`, `DEFAULT_REGISTER_LABELS`, the `Register*` types.
+
+## 1.17.0
+
+**Multi-account demo login — the `<DemoCredentialsHint>` now renders one labelled,
+one-tap-fillable row per published demo account.** Additive and
+backward-compatible: a single account renders byte-for-byte as before.
+
+- **`resolveDemoAccounts` / `resolveAccountList`** (new exports) — resolve either
+  the `publishedAccounts` list (from `@dloizides/auth-client` 4.4.0 / a BFF on
+  Bff.AspNetCore 1.17.0+) or a legacy single pair into an ordered, validated
+  `DemoAccount[]`. `resolveDemoCredentials` is unchanged and still exported.
+- **`useDemoCredentials().hintProps`** gains `accounts: DemoAccount[]` (the
+  resolved list). `credentials` is still passed through unchanged, so the field
+  is purely additive; `onUse` fills whichever account the hint reports.
+- **`<DemoCredentialsHint>`** gains an `accounts?` prop (preferred over
+  `credentials` when present). One account → no per-account heading, unsuffixed
+  testIDs (unchanged). Multiple accounts → each gets its label heading and
+  index-suffixed testIDs (`…-username-0`, `…-use-1`, `…-account-label-0`).
+- New testID `demoCredentialsAccountLabel`; new re-exported type `DemoAccount`.
+- Bumps `@dloizides/auth-client` to `^4.4.0` for the `publishedAccounts` type.
+
+## 1.16.0
+
+**New shared `AccountSettingsScreen` — one authenticated account surface for all
+seven portals, plus a first-class in-app change-password form.**
+
+Adds `AccountSettingsScreen`: a self-contained, theme-driven surface that stacks
+the account-management cards each portal was otherwise wiring by hand. Sections
+are config-driven — a card renders only when its config is passed:
+
+- **Change password (always):** a new `ChangePasswordCard` — a real in-app form
+  (current / new / confirm) with client-side validation (new === confirm + the
+  shared password policy) that submits `POST /bff/account/change-password`
+  (204 → success; 400 → "current password incorrect or fails the policy";
+  401 → session expired). The signed-in user changes their OWN password in the
+  app — no Keycloak-console detour. This package never stores, logs or inspects
+  the password values; it forwards them to the app's own BFF over the session
+  cookie and reads back only a status.
+- **Device PIN (optional):** the existing `DevicePinSettingsCard`.
+- **Passkeys (optional):** the existing `PasskeySettingsCard`.
+- **Preferred sign-in method (optional):** the existing `PreferredMethodSettingsCard`.
+
+New public API:
+
+- `AccountSettingsScreen` + `AccountSettingsScreenProps` and the per-section
+  config types (`AccountSettingsChangePasswordConfig`, `AccountSettingsDevicePinConfig`,
+  `AccountSettingsPasskeysConfig`, `AccountSettingsPreferredMethodConfig`).
+- `ChangePasswordCard` + `ChangePasswordCardProps`.
+- `useChangePassword` (react-query-free form state + validation + submit),
+  `ChangePasswordErrorKey`, `ChangePasswordResult`.
+- `createBffChangePasswordClient` (ready same-origin BFF client, CSRF marker
+  header attached) + `ChangePasswordCapableClient` / `ChangePasswordRequest` /
+  `CHANGE_PASSWORD_ENDPOINT` / `CreateBffChangePasswordClientOptions`.
+- `AccountSettingsLabels` + `DEFAULT_ACCOUNT_SETTINGS_LABELS`.
+
+Backend contract required by adopters: `POST /bff/account/change-password`,
+body `{ currentPassword, newPassword }` → `204` on success, `400` on
+wrong-current/policy-fail, `401` when unauthenticated.
+
+## 1.14.0 (2026-07-19)
+
+Three defects found by measuring the DEPLOYED portals rather than reading the
+source. All three had passing tests over them.
+
+### Fixed
+
+- **The auth card no longer vertically centres, so expanding anything stops
+  moving the inputs.** Measured on `app.zygos.dloizides.com/login` at 1.13.0:
+  expanding the demo disclosure grew the card 445.6 → 589.6px and pulled the
+  username input from `y=275.2` to `y=203.2` and the password from `y=368.8` to
+  `y=296.8` — **72px UP each**, mid-interaction. `<DemoCredentialsHint>` was
+  deliberately mounted BELOW the form to avoid exactly this; centring defeated
+  the placement, because a centred card re-centres as it grows and drags
+  everything above the growth upward.
+
+  `useAuthScreenStyles.screen` and `useAuthStyles.screen` are now top-anchored
+  (`justifyContent: 'flex-start'` + a 64dp `paddingTop`) instead of centred.
+  ⚠️ **This is a visible change on every portal**: the login card now sits below
+  a fixed gap rather than floating in the middle of tall viewports.
+
+  Chosen over the alternatives because the defect is not specific to the
+  disclosure — ANY growth shifted the fields (a validation error under an input,
+  a passkey button arriving after the config fetch, an OTP tab swap), and only
+  top-anchoring fixes the whole class. Reserving the disclosure's height would
+  have left ~144px of permanent dead space on every login; absolutely
+  positioning the expanded panel would have removed it from the scrollable area,
+  making the credentials unreachable on a short viewport. Top-anchoring is also
+  strictly safer at small viewports than what it replaces: overflow now runs
+  downward only, where centring pushed the top of the card past the top edge
+  where no scroll could reach it.
+
+- **Selection and expansion states are now announced on the web.** Three
+  components declared `accessibilityState` and announced nothing:
+  `<DemoCredentialsHint>` (`expanded`), `<DevicePinLengthPicker>` (`selected`)
+  and `<PreferredMethodSettingsCard>` (`selected`). Each now passes the ARIA
+  attribute **explicitly** (`aria-expanded` / `aria-checked`) alongside the RN
+  prop, which is kept for native.
+
+  Root cause is systemic, not a typo. Measured against react-native-web 0.21.2:
+  a `<TouchableOpacity>` given `accessibilityLabel`, `accessibilityRole`,
+  `accessibilityHint` and `accessibilityState={{ expanded: true, selected: true }}`
+  renders `<button role="button" aria-label="…">` — **no `aria-expanded`, no
+  `aria-selected`, and no trace of the hint at all**. `accessibilityState` is not
+  read by react-native-web; `accessibilityHint` produces zero DOM output.
+
+  For `<DevicePinLengthPicker>` the practical effect was WCAG 1.4.1: the chosen
+  PIN length was distinguishable only by the pill's fill colour. Its options also
+  move from `accessibilityRole="button"` to `"radio"` inside a `radiogroup`,
+  since `aria-checked` is only meaningful on a checkable role.
+
+- **Field labels now speak the shared contract's `field` voice — 13/600, not
+  14/600.** The forms contract (mirrored in `@dloizides/ui-forms`'
+  `labelVariants.ts`) defines exactly two label voices: `field` (13/600, sentence
+  case) and `control` (11/700, uppercase). `defaultAuthTheme.typography.label`
+  was 14, which is neither — drift, inherited uniformly by every portal, since
+  they all reuse `defaultAuthTheme.typography` verbatim. It read against the 13px
+  `Field` labels those same apps use on every non-auth form.
+
+### Tests
+
+- **New DOM-level guards** (`*.dom.test.tsx`), rendered through the real
+  `react-native-web` in a `jsdom` environment, asserting the rendered
+  **attribute** rather than the React prop. This is the point: the pre-existing
+  suite mocked `react-native` down to host strings and asserted
+  `props.accessibilityState` — so it passed, unchanged, against a button that
+  announced nothing in every browser. A prop assertion cannot catch this class of
+  bug, and did not.
+- `authVisualContract.test.ts` guards the two visual contracts by naming the
+  defect they forbid (`justifyContent` must NOT be `'center'`; labels must be
+  13/600 written as a literal, not read back from the token under test).
+
+`<DemoCredentialsHint>` gets a **discreet** presentation, and it is now the
+default. The demo stops competing with the sign-in form on login pages that real
+customers use every day.
+
+### Added
+
+- **`DemoCredentialsHintVariant`** (`Panel` | `Disclosure`), exported from the
+  package root.
+- **`Disclosure` variant** — one quiet, centred "Try the demo" line that expands
+  the credentials and the fill button on tap. Collapsed on mount.
+- **`toggle` / `toggleHint` labels** on `DemoCredentialsHintLabels`, so the
+  trigger copy is localised by the host like every other string in the package.
+- **`AuthTestIds.demoCredentialsToggle`** (`auth-demo-credentials-toggle`).
+
+### Changed
+
+- ⚠️ **`<DemoCredentialsHint>` now defaults to `Disclosure`.** A consumer that
+  wants the old always-open block must pass
+  `variant={DemoCredentialsHintVariant.Panel}`. No API broke — every existing
+  prop, `testID` and callback behaves identically — but the rendered output
+  changes, so this is called out as loudly as a breaking change.
+- The credential rows + fill button moved into an internal
+  `<DemoCredentialsBody>` shared by both variants, so the two presentations can
+  never drift apart.
+
+### Notes on the design
+
+Discretion is carried by **size, placement and the absence of chrome** — the
+trigger is caption-sized, centred, and has no fill, border or brand rail. It is
+NOT carried by lowering contrast: the trigger draws `colors.textSecondary`, the
+same AA-held token as the rest of the package's helper copy, so it inherits
+whatever contrast guarantee the consuming app's theme already makes.
+
+The trigger stays a real focusable `accessibilityRole="button"` carrying
+`accessibilityState.expanded`, so screen readers announce that it exists and
+whether it is open. Visually quiet is not the same as hidden.
+
+The expanded body renders **below** the trigger, and the component is intended to
+sit **below** `<LoginForm>`. Expanding therefore grows the card downward and never
+displaces the inputs the visitor is using — mounting it above the form is what
+would make every expansion shove the fields down the page.
+
+
+## 1.12.1 (2026-07-17)
+
+Internal refactor only — **no API change, no behaviour change**. The public
+export surface (`src/index.ts`) is byte-identical to 1.12.0; every consumer
+(zygos, katalogos, erevna, kefi, ichnos) keeps importing the same symbols with
+the same types from the same entry point.
+
+Two oversized source files from the demo-credential work were split to satisfy
+the repo size limits (files < 300 lines, components < 200):
+
+- **`src/components/labels.ts` (511 lines) → `src/components/labels/`.** The
+  single label bag is now one file per component family (`loginLabels.ts`,
+  `forgotPasswordLabels.ts`, `otpLabels.ts`, `pinLabels.ts`, `devicePinLabels.ts`,
+  `passkeyLabels.ts`, `preferredMethodLabels.ts`, `demoLabels.ts`,
+  `resetPasswordLabels.ts`) behind a `labels/index.ts` barrel that re-exports the
+  exact same names, so `./labels` remains a single import site.
+- **`src/components/LoginForm.tsx` (253 lines) → render body slimmed.** The
+  prop-doc-heavy `LoginFormProps` interface moved to a co-located
+  `LoginForm.types.ts` (re-exported from `LoginForm.tsx`), and the submit branch
+  logic moved into a unit-tested `useLoginSubmit` hook.
+
+### Changed
+
+- No runtime change. Splitting only; identical bundled output.
+
+Completes the demo-credential feature for **BFF-fronted apps**, whose demo pair
+arrives ASYNChronously from `GET /bff/config` rather than a module-level const (a
+const would bake the credentials into a bundle handed to a customer to
+self-deploy). Two gaps closed:
+
+1. `prefillOnMount` was inert for async credentials (1.11.0 bug).
+2. `useBffLoginConfig().config` dropped the `demo` field the BFF now serves.
+
+Requires `@dloizides/auth-client` **>= 4.2.0** (which surfaces `demo` on
+`BffLoginConfig`) — the peer floor is raised accordingly. Additive for existing
+consumers: the new `LoginForm` prop is optional and the synchronous /
+module-const path is byte-identical.
+
+### Fixed
+
+- **`prefillOnMount` now honours credentials that arrive AFTER mount.** `useState`
+  reads its initial argument on the first render only, so a demo pair landing a
+  render later (every BFF app) was silently dropped and the form stayed empty
+  beside a populated hint. `useDemoCredentials` now seeds when the resolved pair
+  transitions to non-null (or to a genuinely different pair), gated by VALUE so a
+  react-query refetch handing back a fresh-but-equal object does not re-seed on a
+  loop.
+
+### Added
+
+- **`config.demo` carries through `useBffLoginConfig`.** `BffLoginConfig` gains
+  `demo?: DemoCredentials | null`, so the intended wiring works end-to-end:
+  ```tsx
+  const { config } = useBffLoginConfig(bffAuthClient);
+  const demo = useDemoCredentials({ credentials: config.demo ?? undefined, prefillOnMount: true });
+  ```
+- **`PrefillIntent`** enum + **`LoginForm` gains `prefillIntent`** — the "don't
+  fight the user" control. An `Opportunistic` re-seed (a late config fetch) is
+  DROPPED unless both fields are still empty, so it never overwrites what a real
+  account holder is typing while `/bff/config` is in flight; an `Explicit` re-seed
+  (the user tapped "use these credentials") always applies. `useDemoCredentials`
+  sets the right intent automatically — most apps never touch this prop.
+- **`DemoCredentials` is now re-exported from `@dloizides/auth-client`** (its
+  canonical owner) rather than defined locally, so there is exactly ONE shape
+  across the two packages. Structurally identical to 1.11.0 — no consumer change.
+
+### "Don't fight the user" — what the hook can and cannot know
+
+`useDemoCredentials` does not own the input fields (`<LoginForm>` does), so it
+cannot observe keystrokes. The interaction test it CAN make is on the field
+values: an opportunistic seed applies only when both fields are still empty
+(pristine). This is intentionally conservative — a user who typed and then
+cleared a field keeps control for the rest of the session (a dropped
+opportunistic bump is not retried). An explicit user request is never subject to
+this test.
+
+## 1.11.0 (2026-07-17)
+
+Additive release adding **public demo-credential support** for products with an
+open, published demo account (Zygos is the first). Purely additive — every 1.10.0
+export is unchanged, and an app that imports none of the new exports renders
+byte-identically: the three new `<LoginForm>` props are all optional and inert
+when omitted.
+
+It fills form fields and nothing else. **No auth bypass**: the demo login travels
+the ordinary path (same BFF, same Keycloak, same session cookie, same roles), and
+no credential ships inside this package — the host supplies the pair.
+
+### Added
+
+- **`<DemoCredentialsHint>`** — a themed panel for the login card showing a
+  published demo username + password with a one-tap "use these credentials"
+  action. Takes the usual `AuthTheme` / `labels` / `testIdPrefix` props. Values
+  render as selectable monospace chips (an `l`/`1` in a published password must
+  not be a guess). Omit `onUse` for a read-only panel.
+
+  **Fails closed**: no credentials — or a half-configured pair (blank username,
+  blank password, or a field that is `undefined` at runtime because an env var
+  was never set) — renders `null`. Zero DOM. A misconfigured demo can never
+  publish an empty credentials panel.
+
+- **`useDemoCredentials({ credentials?, prefillOnMount? })`** — the hint↔form
+  wiring, so no app hand-rolls it. Returns two prop bags to spread:
+  `hintProps` (`{ credentials, onUse }`) and `loginFormProps`
+  (`{ initialUsername, initialPassword, prefillNonce }`).
+
+  `prefillOnMount` (default `false`) makes the form arrive already filled, so
+  signing in as the demo user is a single tap on "Sign in".
+
+- **`resolveDemoCredentials(credentials?)`** — the exported fail-closed gate the
+  above share: returns a trimmed pair, or `null` when there is no usable demo.
+
+- **`DemoCredentials`** type and `DEFAULT_DEMO_CREDENTIALS_HINT_LABELS` /
+  `DemoCredentialsHintLabels` (all copy stays app-supplied, as everywhere else).
+
+- **`<LoginForm>` gains `initialUsername` / `initialPassword` / `prefillNonce`.**
+  The `initial*` props **seed** the fields; they do not own them — every value
+  stays editable and clearable, so a real account holder can always wipe the demo
+  values and sign in with their own. `prefillNonce` is the re-seed signal:
+  changing it re-applies the seed over fields the user has edited or cleared.
+
+  The nonce is not ceremony. `useState` ignores its initial argument on
+  re-render, so a fill button wired to `initialUsername` alone would render a
+  form that stays stubbornly empty — the nonce is what makes "click the hint →
+  form fills" work at all. `useDemoCredentials` manages it for you.
+
+### Internal
+
+- `useLoginPrefill` — extracts `<LoginForm>`'s credential field state (the only
+  part of that component with real logic), so the seed/re-seed contract is unit
+  tested directly rather than through the JSX.
+
+## 1.10.0 (2026-07-17)
+
+Additive release adding the shared **logout sequencer**. Purely additive — every
+1.9.x export is unchanged, no component behaviour changes, and apps that do not
+import `performBffLogout` are byte-identical.
+
+### Added
+
+- **`performBffLogout({ client, onClearSession?, onRedirect?, onError?, navigateToIdp? })`**
+  — the shared logout sequence, extracted because all six consuming apps
+  hand-rolled it in their own `AuthProvider` and the orderings disagreed. Runs:
+  1. `onClearSession()` — local state first, so the UI reflects the sign-out
+     immediately.
+  2. `await client.logout({ redirect: false })` — lets the `POST /bff/logout`
+     SETTLE, and takes the IdP logout URL rather than letting the client navigate
+     mid-sequence.
+  3. Navigates exactly once, last: to the IdP logout URL when the BFF returned
+     one (ending the IdP browser session), otherwise `onRedirect()`. When it
+     navigates to the IdP it deliberately does NOT also call `onRedirect` — two
+     competing navigations would race, and the IdP round-trip already returns the
+     user to the app.
+
+  Never rejects; always navigates, even when the BFF logout fails (a down BFF
+  must not trap the user on a page they asked to leave).
+- **`BffLogoutClient`** / **`PerformBffLogoutOptions`** types.
+
+### Why
+
+`zygos-web` and `agora-web` navigated FIRST and called the BFF second:
+
+```ts
+redirectTo('/(auth)/login');   // → window.location.replace() → document unload
+await bffAuthClient.logout();  // races the unload — may never be sent
+```
+
+That is wrong twice over:
+
+1. **The BFF call can be cancelled.** A document navigation kills in-flight
+   fetches, so `POST /bff/logout` may never reach the server: the SPA looks
+   logged out while the httpOnly session cookie stays alive. The `catch` logged
+   it "non-fatal", so the defect was silent.
+2. **The IdP session survives.** `BffAuthClient.logout()` ends the identity
+   provider's browser session with a top-level navigation to its RP-initiated
+   logout URL (only a real navigation carries the IdP's own cookie — a
+   back-channel POST cannot clear it). An app that navigates to its own login
+   route first pre-empts that navigation, so the IdP still considers the user
+   signed in and the next authorize round-trip silently re-authenticates them —
+   the "sign-out that signs you back in" bug the client's own docs warn about.
+
+Synthetic tests that stub the client never reproduce either failure (there is no
+real navigation to cancel the request), which is why they survived. The helper
+owns the sequence so neither can be reintroduced per-app.
+
+## 1.8.0 (2026-07-09)
+
+Additive release for the Move 2b passkey in-app rebuild — the passkey ceremony
+now runs **in-page** (`navigator.credentials.*` against the BFF's same-origin
+`/bff/passkey/*` fetch endpoints) instead of a full-page redirect to Keycloak.
+**Inert by default / no behaviour change until the BFF's WebAuthn RP is
+configured:** when the RP is off the options endpoint returns 501 and the hook
+transparently falls back to the legacy redirect. No breaking changes; every
+1.7.x export is unchanged and the legacy `startPasskeyLogin` /
+`startPasskeyRegistration` navigation helpers stay exported (they ARE the
+fallback).
+
+### Added
+
+- **`usePasskeyCeremony({ mode, returnUrl, onSuccess })`** — the react-query-free
+  in-page ceremony hook: options fetch → `navigator.credentials.create/get` →
+  verify fetch. Returns `{ status, error, isSupported, start, reset }`. Falls
+  back to the legacy Keycloak redirect on a 501 (RP not configured), any non-2xx
+  options response, or an unsupported browser — so nothing regresses until the
+  owner flips `Bff:Passkey`. A cancelled/timed-out ceremony (`NotAllowedError` /
+  `AbortError`) surfaces as `'cancelled'`, anything else as `'failed'`.
+- **`PasskeyCeremonyMode`** (`Login` / `Register`) and **`PasskeyCeremonyStatus`**
+  (`Idle` / `Running` / `Success` / `Error`) `const enum`s.
+
+### Changed
+
+- **`<PasskeyLoginButton>`** and **`<PasskeySettingsCard>`** now drive
+  `usePasskeyCeremony` instead of `window.location.assign`. Same exported props,
+  same testIDs — a drop-in bump for consumers; the in-page path only activates
+  once the BFF RP is configured, otherwise they behave exactly as before.
+
+## 1.7.0 (2026-07-07)
+
+Additive release for the Kefi multi-role overhaul — the shared machinery for a
+cross-dashboard nav. No breaking changes; every 1.6.x export is unchanged.
+
+### Added
+
+- **`resolveAccessibleRoutes(user, table)`** — the multi-role companion to
+  `resolvePostLoginRoute`. Returns the full, ordered list of `RoleRoute` entries
+  the user's role-set unlocks (not just the top one), reusing the same
+  `collectUserRoles` reader and `RoleRouteTable`. Table (priority) order is
+  preserved; the table `fallback` is never included; a role-less user gets `[]`.
+  Pure and app-agnostic — an app renders the result as a cross-dashboard nav.
+- **`RoleRoute.labelKey?`** — optional translation key carried per route so a
+  consuming app can render a localized label per accessible dashboard. Ignored
+  by `resolvePostLoginRoute`; the package stays i18n-agnostic (carries the key,
+  the app resolves it).
+
+## 1.3.0 (2026-05-31)
+
+Additive release for the auth-UX reuse roll-out (feature-reuse-roadmap #1).
+Promotes the "Forgot password?" modal body the product apps each hand-rolled
+into a single shared, **react-query-free** export so katalogos / erevna / kefi
+stop duplicating it. No breaking changes; every 1.2.x export is unchanged.
+
+### Added
+
+- **`<ForgotPasswordFields>`** — the embedded, themeable "request a reset link"
+  body, sized to live inside an app-owned modal shell (no screen/card wrapper,
+  no title — the host modal owns those). Adds the two modal affordances a
+  screen-shaped form lacks: a `Cancel` button beside submit and a `Close` button
+  on the success state, each rendered only when its handler is supplied. Clears
+  itself when `visible` flips to `false` so reopening starts fresh.
+- **`useForgotPasswordSubmit`** — the headless, **react-query-free** forgot-
+  password logic: a plain `useState` + `client.forgotPassword(...)` promise
+  chain that runs on a provider-less login route (where the existing
+  `useBffForgotPassword` `useMutation` crashes with "No QueryClient set"). Email
+  validation gating via `canSubmit`, anti-enumeration success, `hasNetworkError`,
+  and `reset()`. Also exports the `isValidForgotPasswordEmail` helper.
+- **`ForgotPasswordFieldsLabels`** + **`DEFAULT_FORGOT_PASSWORD_FIELDS_LABELS`** —
+  the forgot-password label bag plus the modal `cancel` / `close` strings.
+- New `AuthTestIds` entries `forgotPasswordCancelButton` /
+  `forgotPasswordCloseButton`.
+
+### Notes
+
+- The existing screen-shaped `<ForgotPasswordForm>` (react-query-based) is
+  unchanged. A future cleanup may re-base it on `useForgotPasswordSubmit` to drop
+  its react-query coupling; deferred to keep this release additive.
+
+## 1.2.0 (2026-05-22)
+
+Additive release for Phase 3d of the unified-auth plan — the event-scoped PIN
+UI. Adds the native, branded event-PIN login surface so an app (Kefi) can offer
+"sign in with your event PIN" for operational staff (door / DJ / media) without
+the user ever bouncing to Keycloak's hosted UI. No breaking changes; every
+1.1.0 export is unchanged.
+
+### Added
+
+- **`<PinForm>`** — the ready-made, themeable single-step event-PIN login form,
+  built on `usePinLogin`. A PIN field + a "sign in" button; the
+  `eventExternalId` is a prop (the event context comes from the route/page, it
+  is never typed by the user). Styled by the same `AuthTheme` token bag as the
+  other forms; copy is supplied through the i18n-agnostic `PinFormLabels` bag
+  (English `DEFAULT_PIN_LABELS` fallback). `onSuccess` hands back the signed-in
+  `BffUser`.
+- **`usePinLogin`** — the headless PIN hook (the custom-layout escape hatch). A
+  single-step flow: `submit(pin)` → `POST /bff/pin/login` → `BffUser`, with
+  `reset()`. Mirrors `useOtpLogin` (mounted-guard, memoised result,
+  latest-`eventExternalId` ref).
+- **`PinFormLabels`** + **`DEFAULT_PIN_LABELS`** — the PIN label bag.
+- New `AuthTestIds` entries for every PIN interactive element.
+- Re-exports `BffPinLoginRequest` from `@dloizides/auth-client`.
+
+### Changed
+
+- Peer dependency `@dloizides/auth-client` raised to `>=3.2.0` — the version
+  that adds `BffAuthClient.pinLogin`.
+
+## 1.1.0 (2026-05-22)
+
+Additive release for Phase 2d of the unified-auth plan — the email-OTP UI. Adds
+the native, branded email-OTP login surface so an app can offer "sign in with a
+code" without the user ever bouncing to Keycloak's hosted UI. No breaking
+changes; every 1.0.0 export is unchanged.
+
+### Added
+
+- **`<OtpForm>`** — the ready-made, themeable two-step email-OTP login form,
+  built on `useOtpLogin`. Step 1 collects the email and sends a code; step 2
+  collects the code, verifies it, and offers "resend code" and "use a different
+  email". Styled by the same `AuthTheme` token bag as the other forms; copy is
+  supplied through the i18n-agnostic `OtpFormLabels` bag (English
+  `DEFAULT_OTP_LABELS` fallback). `onSuccess` hands back the signed-in `BffUser`.
+- **`useOtpLogin`** — the headless OTP hook (the custom-layout escape hatch). A
+  small forward state machine over `OtpLoginStep`: `requestCode(identifier)` →
+  `EnterCode`, then `verifyCode(otp)` → `BffUser`, with `resend()` and
+  `reset()`. Mirrors `useBffAuth` (mounted-guard, memoised result).
+- **`OtpLoginStep`** — the `RequestCode` / `EnterCode` step enum.
+- **`OtpFormLabels`** + **`DEFAULT_OTP_LABELS`** — the OTP label bag.
+- New `AuthTestIds` entries for every OTP interactive element.
+- Re-exports `BffOtpRequestRequest`, `BffOtpVerifyRequest` and
+  `BffOtpRequestResult` from `@dloizides/auth-client`.
+
+### Changed
+
+- Peer dependency `@dloizides/auth-client` raised to `>=3.1.0` — the version
+  that ships `BffAuthClient.requestOtp` / `.verifyOtp` (`POST /bff/otp/request`
+  and `POST /bff/otp/verify`).
+
+### Notes
+
+- Still strictly thin: UI + the same-origin `/bff/*` client. The OTP client
+  methods carry the `X-BFF-Csrf` header like every other state-changing call;
+  no token handling, no secrets in the browser.
+- This release adds the OTP surface to the package only. Wiring an app onto it
+  (the Kefi pilot) is Phase 3.
+
+## 1.0.0 (2026-05-22)
+
+Initial release — the frontend half of the unified-auth plan (Phase 1b).
+
+`@dloizides/auth-web` is the shared, themeable, branded auth UI for the
+dloizides.com portfolio. It is extracted and generalised from the per-app auth
+code that lived inside `apps/katalogos-web` so katalogos, erevna and kefi can
+share one implementation instead of copy-pasting auth adapters.
+
+### Added
+
+- **Themeable components**
+  - `<LoginForm>` — password login, built on `useBffAuth`.
+  - `<ForgotPasswordForm>` — request-a-reset-link, built on
+    `useBffForgotPassword`; no-enumeration confirmation state.
+  - `<ResetPasswordForm>` — choose-a-new-password, built on
+    `useResetPasswordForm`.
+  - All three are styled by an `AuthTheme` design-token bag so visually
+    distinct apps share one implementation.
+- **Theming** — `AuthThemeProvider`, `useAuthTheme`, `defaultAuthTheme`, and
+  the `AuthTheme` token contract (colors / radii / spacing / typography).
+  Precedence: explicit `theme` prop → `<AuthThemeProvider>` context → default.
+- **i18n-agnostic label bags** — `LoginFormLabels`, `ForgotPasswordFormLabels`,
+  `ResetPasswordFormLabels` plus English `DEFAULT_*` constants. The package
+  ships no `t()` / `FM()`; consuming apps pass already-localised strings.
+- **Headless hooks** (the custom-layout escape hatch)
+  - `useBffAuth` — login / logout / `/bff/me` session, lifecycle status.
+  - `useBffForgotPassword`, `useBffResetPassword` — React Query mutations.
+  - `useResetPasswordForm` — reset-password form-state + validation logic.
+- **`createBffAuthClient`** — one-line wiring of a same-origin `BffAuthClient`
+  with a lazily-resolved `fetch` (load-time side-effect-free).
+- **Role-based post-login router** — `resolvePostLoginRoute(user, table)` and
+  `collectUserRoles`. The consuming app supplies the role → route table.
+- **Password policy** — `validatePasswordPolicy`, `isPasswordValid`,
+  `PasswordPolicyError`; mirrors the TenantService backend rules.
+- **Test IDs** — `AuthTestIds` + `withTestIdPrefix` for E2E targeting.
+- Re-exports `BffAuthClient`, `createFetchHttpClient` and the BFF request /
+  response types from `@dloizides/auth-client` so consumers have a single
+  import surface.
+
+### Notes
+
+- Strictly thin: UI + a same-origin `/bff/*` fetch client + the router helper.
+  **No secrets, no token handling, no Keycloak calls** — the per-app BFF owns
+  all of that server-side.
+- Built on `@dloizides/auth-client` (peer dependency `>=3.0.0`), which ships
+  `BffAuthClient`.
+- This release creates the package only. Porting `apps/katalogos-web` onto it
+  is Phase 1c.