@dloizides/auth-web 1.12.1 → 1.14.0

package/CHANGELOG.md

@@ -1,386 +1,501 @@
-# Changelog
-
-## 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.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.