@tesouro/embedded-components-react 0.5.224 → 0.5.226

package/README.md

@@ -13,7 +13,7 @@ npm install @tesouro/embedded-components-react
 # or: yarn add @tesouro/embedded-components-react
 ```
 
-**Import the stylesheet once** at your app's entry point — widgets render
+**Import the stylesheet once** at your app's entry point. Widgets render
 unstyled without it:
 
 ```ts
@@ -42,70 +42,42 @@ export function App() {
 }
 ```
 
-Every provider and widget prop is fully typed in the shipped declarations, so
-your editor documents the full auth/config model inline — per-widget
-`WidgetProvider`, config inheritance, token refresh, and the built-in error
-boundary.
+Every provider and widget prop is typed in the shipped declarations, so your
+editor documents them inline.
 
 ### Entry points
 
-| Import path                                       | What you get                                                                                           |
-| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| `@tesouro/embedded-components-react`              | All widgets, `WidgetSuite`, plus `RootWidgetProvider` / `WidgetProvider`.                              |
-| `@tesouro/embedded-components-react/styles.css`   | The widget stylesheet — see [About the stylesheet](#about-the-stylesheet).                             |
-| `@tesouro/embedded-components-react/core`         | Framework-agnostic token utilities (`createWidgetTokenManager`).                                       |
-| `@tesouro/embedded-components-react/monite-sdk`   | Legacy Monite surface, being removed — no compatibility promise. See [below](#monite-sdk-entry-point). |
-| `@tesouro/embedded-components-react/experimental` | Work in progress — no compatibility promise. See [below](#experimental-entry-point).                   |
+| Import path                                       | What you get                                                                                       |
+| ------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `@tesouro/embedded-components-react`              | All widgets, `WidgetSuite`, plus `RootWidgetProvider` / `WidgetProvider`.                          |
+| `@tesouro/embedded-components-react/styles.css`   | The widget stylesheet. See [About the stylesheet](#about-the-stylesheet).                          |
+| `@tesouro/embedded-components-react/core`         | Framework-agnostic token utilities (`createWidgetTokenManager`).                                   |
+| `@tesouro/embedded-components-react/monite-sdk`   | Legacy surface being removed, with no compatibility promise. See [below](#monite-sdk-entry-point). |
+| `@tesouro/embedded-components-react/experimental` | Work in progress, with no compatibility promise. See [below](#experimental-entry-point).           |
 
 ### Experimental entry point
 
-`@tesouro/embedded-components-react/experimental` (and the per-module
-`@tesouro/embedded-components-react/experimental/<Module>`) is a staging area for
-work in progress. It is **currently empty** — nothing ships on it today — and it
-is **outside this package's semver contract**:
-
-- Anything exported there can change shape or be **removed outright in any
-  release, including a patch**. There is no deprecation window.
-- Its exports are deliberately not documented here — no prop tables, no
-  reference entry. Read the shipped types.
-- It is unsupported. If you hit a problem with it, use the released widget on
-  the main entry point instead.
-
-Use it only when we have pointed you at a specific module, and pin the package
-to an exact version if you do.
-
-The supported surface — the main entry point, `./core`, `./lib/*` and the
-stylesheet — carries the normal compatibility promise and is unaffected by churn
-on this path. `./monite-sdk` does not; see below.
+`@tesouro/embedded-components-react/experimental` (and `.../experimental/<Module>`)
+holds work in progress. It is **outside semver**: exports
+can change or disappear in any release, including a patch, and aren't documented
+here. Use it only if we point you at a specific module, and pin an exact version.
 
 ### Monite SDK entry point
 
-`@tesouro/embedded-components-react/monite-sdk` is a **legacy compatibility
-export, not an integration surface.** It exists because an earlier generation of
-Tesouro's own apps mounted Monite components directly. It was never meant for
-anyone else to build on, and it is **outside this package's compatibility
-promise**, on the same footing as `./experimental`:
-
-- Its exports are **being removed**, surface by surface, as each Monite-backed
-  screen is replaced by a native Tesouro widget. Names disappear from it with no
-  deprecation window.
-- It is deliberately undocumented here — no prop tables, no reference entries.
-- The subpath itself goes away once nothing needs it.
-
-Every Monite-backed widget on the main entry point already wraps Monite for you
-and exposes Tesouro props. That is the surface to build on. Reach for
-`./monite-sdk` only if we have pointed you at it, and pin an exact version if
-you do.
+`@tesouro/embedded-components-react/monite-sdk` is a **legacy export being
+removed** and is **outside the compatibility promise**, like `./experimental`.
+Its exports disappear with no deprecation window as native widgets replace them.
+Widgets on the main entry point that use it already wrap it for you, so build on
+those. Use `./monite-sdk` only if we point you at it, and pin an exact
+version.
 
 ### About the stylesheet
 
-The stylesheet is host-safe by design. It ships **no
-global CSS reset**: Tailwind's Preflight is omitted and instead re-expressed
-scoped under the `.tesouro-embedded` wrapper that every widget renders, and all
-utilities are `ttw`-prefixed — so loading it won't restyle your host page or
-collide with your own Tailwind. Design tokens (`--ttw-*`) are declared on
-`:root`/`.dark`; dark mode follows an ancestor `.dark` class, and the widget
-font can be white-labeled via `--ttw-font-family`.
+The stylesheet won't restyle your host page. It ships no global CSS reset (the
+reset is scoped under the `.tesouro-embedded` wrapper every widget renders), and
+all utilities are `ttw`-prefixed, so it won't collide with your own Tailwind.
+Design tokens (`--ttw-*`) are declared on `:root` / `.dark`. Dark mode follows an
+ancestor `.dark` class, and you can set the widget font with `--ttw-font-family`.
 
 <!-- BEGIN GENERATED REFERENCE -->
 
@@ -127,21 +99,21 @@ App-level provider. Resolves `baseUrl` / `widgetToken` / `organizationId` (falli
 
 #### Props
 
-| Prop                            | Type                                         | Description                                                                                                                                                                                                                                                                                                                                                                      |
-| ------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `baseUrl`                       | `string`                                     | Base URL of the Tesouro embedded API (e.g. `"https://api.tesouro.com"`). Falls back to `global.baseUrl` when omitted.                                                                                                                                                                                                                                                            |
-| `widgetToken`                   | `string \| null`                             | Bearer token for widget auth. Falls back to `global.widgetToken` when omitted. Pass `null` to suppress auth.                                                                                                                                                                                                                                                                     |
-| `organizationId`                | `string \| null`                             | Org ID forwarded to data-access hooks. Falls back to `global.organizationId` when omitted; if still unset, defaults to `initResponse.organizationId` once the fetch resolves. Pass `null` to clear org scoping (never falls back).                                                                                                                                               |
-| `configClient`                  | `(client: EmbeddedClient) => EmbeddedClient` | Optional post-creation hook for the HTTP client. Called after the built-in auth and gateway-routing interceptors. Falls back to `global.configClient`.                                                                                                                                                                                                                           |
-| `gatewayRouting`                | `boolean`                                    | Overrides widget-gateway routing (the `/api/widget-gateway/proxy` path prefix plus the `X-Widget-Token` header). Unset, routing applies per request when the request origin is a known Tesouro API host; `true` forces it on (e.g. a custom domain in front of the gateway), `false` forces it off (a host that routes its own requests). Falls back to `global.gatewayRouting`. |
-| `linkComponent`                 | `LinkComponent`                              | Host link component widgets use to render navigational links. Falls back to `global.linkComponent`.                                                                                                                                                                                                                                                                              |
-| `uiFramework`                   | `'shadcn' \| 'tecton' \| null`               | UI framework the widget UI layer renders with for this tree. Falls back to `global.uiFramework`, then to `'shadcn'`. See UI framework selection.                                                                                                                                                                                       |
-| `implementation`                | `'native' \| 'monite' \| null`               | Which implementation the widgets render with for this tree. Falls back to `global.implementation`, then to `'native'`. See Implementation selection.                                                                                                                                                                                 |
-| `analytics`                     | `boolean`                                    | Enables anonymous analytics for this provider tree (default `true`). `RootWidgetProvider` is the analytics owner; set `false` to disable capture and skip loading PostHog.                                                                                                                                                                                                       |
-| `unstable_initResponseOverride` | `WidgetInitResponse`                         | First-party hosts only. Skips the `GET /api/widget-gateway/init` fetch and exposes this host-authored object as `initResponse` to the subtree. Use when the host authenticates users directly against the Tesouro issuer and passes the user's bearer access token as `widgetToken`. Embed integrations minting widget JWEs must leave this unset.                               |
-| `disclosuresAcceptance`         | `ReactNode`                                  | Accept surface shown when the caller owes disclosures (`INVITED`, or `REQUIRED` with `disclosuresAccepted: false`). Pass `<AcceptDisclosuresWidget />`. Cascades to nested providers.                                                                                                                                                                                            |
-| `providerLabels`                | `Partial<WidgetProviderLabels>`              | Overrides the copy a provider renders in place of a widget: the error-boundary fallback and the disclosures gate. Any subset; unlisted keys keep their defaults. Cascades to nested providers. See Provider copy.                                                                                                                                              |
-| `children`                      | `ReactNode`                                  | The React subtree that consumes the widget context.                                                                                                                                                                                                                                                                                                                              |
+| Prop                            | Type                                         | Description                                                                                                                                                    |
+| ------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `baseUrl`                       | `string`                                     | Base URL of the Tesouro embedded API, such as `"https://api.tesouro.com"`. Falls back to `global.baseUrl`.                                                     |
+| `widgetToken`                   | `string \| null`                             | Bearer token for widget auth. Falls back to `global.widgetToken`; `null` suppresses auth.                                                                      |
+| `organizationId`                | `string \| null`                             | Org ID sent with data requests. Falls back to `global.organizationId`, then to `initResponse.organizationId`; `null` clears org scoping.                       |
+| `configClient`                  | `(client: EmbeddedClient) => EmbeddedClient` | Post-creation hook for the HTTP client, applied after the built-in auth and routing interceptors. Falls back to `global.configClient`.                         |
+| `gatewayRouting`                | `boolean`                                    | Forces widget-gateway routing on (`true`) or off (`false`); unset, it applies automatically to known Tesouro API hosts. Falls back to `global.gatewayRouting`. |
+| `linkComponent`                 | `LinkComponent`                              | Host link component widgets use for navigational links. Falls back to `global.linkComponent`.                                                                  |
+| `uiFramework`                   | `'shadcn' \| 'tecton' \| null`               | UI framework for this tree; falls back to `global.uiFramework`, then `'shadcn'`.                                                                               |
+| `implementation`                | `'native' \| 'monite' \| null`               | Widget implementation for this tree; falls back to `global.implementation`, then `'native'`.                                                                   |
+| `analytics`                     | `boolean`                                    | Enables anonymous analytics (default `true`); `false` disables capture and skips loading PostHog.                                                              |
+| `unstable_initResponseOverride` | `WidgetInitResponse`                         | First-party hosts only: skips the init fetch and uses this object as `initResponse`. Embed integrations minting widget JWEs must leave this unset.             |
+| `disclosuresAcceptance`         | `ReactNode`                                  | Accept surface shown when the user owes disclosures; pass `<AcceptDisclosuresWidget />`. Cascades to nested providers.                                         |
+| `providerLabels`                | `Partial<WidgetProviderLabels>`              | Overrides the copy a provider renders in place of a widget (error fallback, disclosures gate). Cascades to nested providers.                                   |
+| `children`                      | `ReactNode`                                  | The React subtree that consumes the widget context.                                                                                                            |
 
 ### `WidgetProvider`
 
@@ -149,22 +121,22 @@ Mid-tree or standalone provider. With no props it is a transparent pass-through
 
 #### Props
 
-| Prop                    | Type                                               | Description                                                                                                                                                                                                                                                                                                                 |
-| ----------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `baseUrl`               | `string`                                           | Override the base URL for this subtree. Recreates the HTTP client. When omitted, inherits from the nearest ancestor.                                                                                                                                                                                                        |
-| `widgetToken`           | `string \| null`                                   | Override the widget token for this subtree. Triggers a new `/api/widget-gateway/init` fetch. Pass `null` to suppress auth at this level. When omitted, inherits from parent.                                                                                                                                                |
-| `organizationId`        | `string \| null`                                   | Override the org ID for this subtree. Does **not** trigger a re-fetch on its own. When omitted, inherits from parent; if unset through the whole cascade, defaults to this level's `initResponse.organizationId` (an ancestor's explicit org wins over it). Pass `null` to explicitly clear org scoping (never falls back). |
-| `configClient`          | `(client: EmbeddedClient) => EmbeddedClient`       | Optional post-creation hook for the scoped HTTP client. Only called when this provider creates its own client (i.e. not in pass-through mode). When omitted, inherits from parent.                                                                                                                                          |
-| `gatewayRouting`        | `boolean`                                          | Overrides widget-gateway routing (the `/api/widget-gateway/proxy` path prefix plus the `X-Widget-Token` header) for this subtree's scoped client. Unset, routing applies per request when the request origin is a known Tesouro API host; `true` forces it on, `false` forces it off. When omitted, inherits from parent.   |
-| `linkComponent`         | `LinkComponent`                                    | Override the host link component for this subtree. When omitted, inherits from parent.                                                                                                                                                                                                                                      |
-| `uiFramework`           | `'shadcn' \| 'tecton' \| null`                     | Override the UI framework for this subtree. When omitted (or `null`), inherits the nearest ancestor's selection, defaulting to `'shadcn'`. See UI framework selection.                                                                                                            |
-| `implementation`        | `'native' \| 'monite' \| null`                     | Override the implementation for this subtree. When omitted (or `null`), inherits the nearest ancestor's selection, defaulting to `'native'`. See Implementation selection.                                                                                                      |
-| `errorFallback`         | `ReactNode \| (props: FallbackProps) => ReactNode` | Custom fallback for the built-in error boundary in this subtree. A `ReactNode` is rendered as-is; a function receives `{ error, resetErrorBoundary }`. Defaults to a generic `role="alert"` message.                                                                                                                        |
-| `onError`               | `(error: unknown, info: ErrorInfo) => void`        | Optional telemetry hook. Runs once per caught error before the fallback renders.                                                                                                                                                                                                                                            |
-| `analytics`             | `boolean`                                          | Enables anonymous analytics (default `true`). Honored only when this is a standalone analytics owner (no `RootWidgetProvider` ancestor); on a nested provider it is a no-op.                                                                                                                                                |
-| `disclosuresAcceptance` | `ReactNode`                                        | Accept surface shown when the caller owes disclosures (`INVITED`, or `REQUIRED` with `disclosuresAccepted: false`). Pass `<AcceptDisclosuresWidget />`. When omitted, inherits from the nearest ancestor.                                                                                                                   |
-| `providerLabels`        | `Partial<WidgetProviderLabels>`                    | Overrides the copy this provider renders in place of the widget: the error-boundary fallback and the disclosures gate. Any subset; unlisted keys keep their defaults. When omitted, inherits from the nearest ancestor. See Provider copy.                                                                |
-| `children`              | `ReactNode`                                        | The React subtree that consumes the overridden context.                                                                                                                                                                                                                                                                     |
+| Prop                    | Type                                               | Description                                                                                                                             |
+| ----------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `baseUrl`               | `string`                                           | Overrides the base URL for this subtree and creates a new client. Inherits when omitted.                                                |
+| `widgetToken`           | `string \| null`                                   | Overrides the token for this subtree and reloads init; `null` suppresses auth here. Inherits when omitted.                              |
+| `organizationId`        | `string \| null`                                   | Overrides the org ID for this subtree without reloading init; `null` clears org scoping. Inherits when omitted.                         |
+| `configClient`          | `(client: EmbeddedClient) => EmbeddedClient`       | Post-creation hook for this provider's client; not called in pass-through mode. Inherits when omitted.                                  |
+| `gatewayRouting`        | `boolean`                                          | Forces widget-gateway routing on or off for this subtree's client; unset, it applies to known Tesouro API hosts. Inherits when omitted. |
+| `linkComponent`         | `LinkComponent`                                    | Overrides the host link component for this subtree. Inherits when omitted.                                                              |
+| `uiFramework`           | `'shadcn' \| 'tecton' \| null`                     | Overrides the UI framework for this subtree; omitted or `null` inherits, defaulting to `'shadcn'`.                                      |
+| `implementation`        | `'native' \| 'monite' \| null`                     | Overrides the implementation for this subtree; omitted or `null` inherits, defaulting to `'native'`.                                    |
+| `errorFallback`         | `ReactNode \| (props: FallbackProps) => ReactNode` | Custom error-boundary fallback: a node, or a function receiving `{ error, resetErrorBoundary }`.                                        |
+| `onError`               | `(error: unknown, info: ErrorInfo) => void`        | Telemetry hook, called once per caught error before the fallback renders.                                                               |
+| `analytics`             | `boolean`                                          | Enables anonymous analytics (default `true`); honored only in standalone mode, ignored on a nested provider.                            |
+| `disclosuresAcceptance` | `ReactNode`                                        | Accept surface shown when the user owes disclosures; pass `<AcceptDisclosuresWidget />`. Inherits when omitted.                         |
+| `providerLabels`        | `Partial<WidgetProviderLabels>`                    | Overrides the copy this provider renders in place of the widget. Inherits when omitted.                                                 |
+| `children`              | `ReactNode`                                        | The React subtree that consumes the overridden context.                                                                                 |
 
 ### `WidgetTokenRefreshProvider`
 
@@ -172,12 +144,12 @@ Owns the token-refresh lifecycle: calls your `fetcher`, proactively refreshes be
 
 #### Props
 
-| Prop          | Type                                                   | Default | Description                                                                                                                                                                                                                                                                                                                                |
-| ------------- | ------------------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `fetcher`     | `() => Promise<{ widgetToken: string; exp?: number }>` | —       | Required. Called on mount and whenever a refresh is scheduled or requested. `exp` is unix seconds; if omitted, no proactive refresh is scheduled.                                                                                                                                                                                          |
-| `leadSeconds` | `number`                                               | `60`    | Schedule the next refresh `leadSeconds` before `exp`. Lower this if your tokens have a very short lifetime.                                                                                                                                                                                                                                |
-| `onToken`     | `(widgetToken: string) => void`                        | —       | Optional callback fired once per **distinct** token produced by the manager. Useful for telemetry, persistence, or — for non-React hosts (web components, cross-React-root setups) — mirroring the token into the global store via `updateGlobalWidgetConfig`. React consumers should drive `widgetToken` from `useWidgetToken()` instead. |
-| `children`    | `ReactNode`                                            | —       | The React subtree that consumes the manager via `useWidgetToken()`.                                                                                                                                                                                                                                                                        |
+| Prop          | Type                                                   | Default      | Description                                                                                                                   |
+| ------------- | ------------------------------------------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------- |
+| `fetcher`     | `() => Promise<{ widgetToken: string; exp?: number }>` | **Required** | Returns a token and its `exp` (unix seconds); see The fetcher.                                                |
+| `leadSeconds` | `number`                                               | `60`         | Refresh this many seconds before `exp`. Lower it for very short-lived tokens.                                                 |
+| `onToken`     | `(widgetToken: string) => void`                        | `undefined`  | Called once per distinct token, for telemetry, persistence, or mirroring the token into the global store for non-React hosts. |
+| `children`    | `ReactNode`                                            | `undefined`  | The subtree that reads the token via `useWidgetToken()`.                                                                      |
 
 ### `RefreshingRootWidgetProvider`
 
@@ -185,23 +157,23 @@ Bundles `WidgetTokenRefreshProvider` + `RootWidgetProvider` and wires the live t
 
 #### Props
 
-| Prop                            | Source                       | Notes                                                                                                                                             |
-| ------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `baseUrl`                       | `RootWidgetProvider`         | Falls back to the global store when omitted.                                                                                                      |
-| `organizationId`                | `RootWidgetProvider`         | Pass `null` to clear the org scope; falls back to the global store when omitted.                                                                  |
-| `configClient`                  | `RootWidgetProvider`         | Optional post-creation hook for the scoped HTTP client.                                                                                           |
-| `gatewayRouting`                | `RootWidgetProvider`         | Overrides widget-gateway routing; unset, it applies per request when the request origin is a known Tesouro API host.                              |
-| `linkComponent`                 | `RootWidgetProvider`         | Component used in place of plain `<a>` tags inside widgets.                                                                                       |
-| `uiFramework`                   | `RootWidgetProvider`         | `'shadcn'` (default) or `'tecton'`; inherits down the provider cascade.                                                                           |
-| `implementation`                | `RootWidgetProvider`         | `'native'` (default) or `'monite'`; inherits down the provider cascade.                                                                           |
-| `analytics`                     | `RootWidgetProvider`         | Enables anonymous analytics (default `true`); set `false` to disable capture.                                                                     |
-| `unstable_initResponseOverride` | `RootWidgetProvider`         | First-party hosts only. Skips the gateway init fetch and supplies host-authored identity for the subtree.                                         |
-| `disclosuresAcceptance`         | `RootWidgetProvider`         | Accept surface shown when the caller owes disclosures (`INVITED`, or `REQUIRED` with `disclosuresAccepted: false`). Cascades to nested providers. |
-| `providerLabels`                | `RootWidgetProvider`         | Overrides the copy a provider renders in place of a widget (error-boundary fallback, disclosures gate). Any subset. Cascades to nested providers. |
-| `fetcher`                       | `WidgetTokenRefreshProvider` | Required.                                                                                                                                         |
-| `leadSeconds`                   | `WidgetTokenRefreshProvider` | Default `60`.                                                                                                                                     |
-| `onToken`                       | `WidgetTokenRefreshProvider` | Fires once per distinct token; useful for telemetry, persistence, or — for non-React hosts — mirroring the token via `updateGlobalWidgetConfig`.  |
-| `children`                      | —                            | Render inside both providers' contexts (so `useWidgetToken()` and `useWidgetConfig()` both work in descendants).                                  |
+| Prop                            | Source                       | Notes                                                                                                    |
+| ------------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `baseUrl`                       | `RootWidgetProvider`         | Falls back to the global store when omitted.                                                             |
+| `organizationId`                | `RootWidgetProvider`         | Pass `null` to clear the org scope; falls back to the global store when omitted.                         |
+| `configClient`                  | `RootWidgetProvider`         | Optional post-creation hook for the scoped HTTP client.                                                  |
+| `gatewayRouting`                | `RootWidgetProvider`         | Overrides widget-gateway routing; unset, it applies automatically for known Tesouro API hosts.           |
+| `linkComponent`                 | `RootWidgetProvider`         | Component used in place of plain `<a>` tags inside widgets.                                              |
+| `uiFramework`                   | `RootWidgetProvider`         | `'shadcn'` (default) or `'tecton'`; inherits down the provider cascade.                                  |
+| `implementation`                | `RootWidgetProvider`         | `'native'` (default) or `'monite'`; inherits down the provider cascade.                                  |
+| `analytics`                     | `RootWidgetProvider`         | Enables anonymous analytics (default `true`); set `false` to disable capture.                            |
+| `unstable_initResponseOverride` | `RootWidgetProvider`         | First-party hosts only. Skips the init fetch and supplies host-authored identity for the subtree.        |
+| `disclosuresAcceptance`         | `RootWidgetProvider`         | Accept surface shown when the user owes disclosures. Cascades to nested providers.                       |
+| `providerLabels`                | `RootWidgetProvider`         | Overrides the copy a provider renders in place of a widget (error fallback, disclosures gate). Cascades. |
+| `fetcher`                       | `WidgetTokenRefreshProvider` | Required.                                                                                                |
+| `leadSeconds`                   | `WidgetTokenRefreshProvider` | Default `60`.                                                                                            |
+| `onToken`                       | `WidgetTokenRefreshProvider` | Fires once per distinct token.                                                                           |
+| `children`                      | Both                         | Rendered inside both providers.                                                                          |
 
 ## Components
 
@@ -212,43 +184,35 @@ listed here.
 
 ### WidgetSuite
 
-A whole banking page in one component: a section menu over the widgets behind it, served by a single widget-init call. Unlike a widget — a content area you drop onto a page you own — a suite owns the page it is placed on, exists once per page, and decides which widgets appear on it.
+A whole banking page in one component: a section menu over the widgets behind it, served by a single widget-init call. Unlike a widget, a suite owns the page it is placed on, so mount one per page.
 
 #### Props
 
-| Prop                        | Type                              | Default                         | Description                                                                                                                                                                                                                                                                                                              |
-| --------------------------- | --------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `sections`                  | `readonly WidgetSuiteSectionId[]` | `WIDGET_SUITE_DEFAULT_SECTIONS` | Which sections the suite offers, in menu order. A listed section is still hidden when the token does not earn it.                                                                                                                                                                                                        |
-| `section`                   | `WidgetSuiteSectionId`            | —                               | Which section is showing. Supplying it puts the menu in controlled mode for the lifetime of the mount, so pair it with `onSectionChange`.                                                                                                                                                                                |
-| `defaultSection`            | `WidgetSuiteSectionId`            | first of `sections`             | Which section the suite opens on. Read once per mount, and ignored when `section` is supplied.                                                                                                                                                                                                                           |
-| `onSectionChange`           | `(section) => void`               | `undefined`                     | Called when a person moves the suite. Never fired on mount, and never for the entitlement fallback, so a URL mirroring it cannot erase a deep link.                                                                                                                                                                      |
-| `labels`                    | `WidgetSuiteLabelOverrides`       | `WIDGET_SUITE_LABELS_EN`        | Every string on the page, in one tree: a group for the shell, the menu names, the section heading, the disclosure states, and one per section carrying that section's widget copy. Override any leaf and its siblings keep their defaults.                                                                               |
-| `showSectionTitle`          | `boolean`                         | `true`                          | Shows a heading above each section, named as its menu item is. Set `false` when your page already heads the suite.                                                                                                                                                                                                       |
-| `onboardingDisclosureLinks` | `DisclosureLinks`                 | `undefined`                     | Legal disclosure URLs (Terms, Privacy, Electronic Communication, Patriot Act) for the entry-point onboarding widget's business-details agreement step, shown to a session whose organization has no application yet. Omitted fields render as plain, non-clickable text.                                                 |
-| `cardArtSrc`                | `string`                          | `undefined`                     | Card artwork URL for the debit list's built-in Create card sheet and details card face. Omit it and the sheet uses a built-in neutral plastic while the face falls back to the bank logo. Create card shows when the token holds the issue, roster and funding scopes. Credit Create card is always hidden in the suite. |
+| Prop                        | Type                              | Default                         | Description                                                                                                                                                 |
+| --------------------------- | --------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `sections`                  | `readonly WidgetSuiteSectionId[]` | `WIDGET_SUITE_DEFAULT_SECTIONS` | Which sections the suite offers, in menu order. A listed section is still hidden when the token doesn't earn it.                                            |
+| `section`                   | `WidgetSuiteSectionId`            | `undefined`                     | Which section is showing. Supplying it makes the menu controlled for the lifetime of the mount, so pair it with `onSectionChange`.                          |
+| `defaultSection`            | `WidgetSuiteSectionId`            | first of `sections`             | Which section the suite opens on. Read once per mount, and ignored when `section` is supplied.                                                              |
+| `onSectionChange`           | `(section) => void`               | `undefined`                     | Called when the user moves the suite. Never fired on mount or for the entitlement fallback.                                                                 |
+| `labels`                    | `WidgetSuiteLabelOverrides`       | `WIDGET_SUITE_LABELS_EN`        | Every string on the page in one tree, including the copy of each section's widget. Override any leaf and its siblings keep their defaults.                  |
+| `showSectionTitle`          | `boolean`                         | `true`                          | Shows a heading above each section, named as its menu item is. Set `false` when your page already heads the suite.                                          |
+| `onboardingDisclosureLinks` | `DisclosureLinks`                 | `undefined`                     | Legal disclosure URLs for the onboarding agreement step, shown when the organization has no application yet. Omitted fields render as non-clickable text.   |
+| `cardArtSrc`                | `string`                          | `undefined`                     | Card artwork URL for the debit Create card sheet and card face; omitted, a neutral plastic and the bank logo are used. Credit Create card is always hidden. |
 
 ### AcceptDisclosuresWidget
 
-A self-contained widget for reviewing and accepting required banking disclosures. Fetches the caller's disclosure document set (title/url pairs, in presentation order) from `GET /identity/v1/disclosures` and renders an inline bordered card with those links, an agreement checkbox, and an Accept action. The host supplies no document URLs — the document set, its titles, and its order are entirely backend configuration for the bank partner's program. The provider attribution and agreement copy come from the widget init tenant identity.
-
-The widget token identifies the caller on both the disclosures lookup and the accept. Mount this when widget init reports `status: 'INVITED'`, **or** `disclosuresRequired: 'REQUIRED'` with `disclosuresAccepted: false`. The first covers an invited teammate who is not yet active — including orgs whose requirement is `NOT_REQUIRED`, where Accept still posts a `null` version to activate them. The second covers an already-active user who owes a newly published version. Do not gate on `REQUIRED` alone: that would skip `INVITED` users in `NOT_REQUIRED` orgs and leave them stuck.
-
-Accept posts `POST /api/widget-gateway/disclosure-acceptance` with the version that was on screen, after a second `GET /identity/v1/disclosures` confirms that version is still in force (hosts rewrite that onto `/api/widget-gateway/proxy/identity/v1/disclosures` the same way as other identity calls — do not call the generated catch-all proxy helper, which percent-encodes path slashes and surfaces as a browser CORS error). If a newer version was published while the caller was reading, accept is refused (no POST) and the widget refetches so they can review the documents that are now in force. `version` may be `null` when the org's requirement is `NOT_REQUIRED`; that value is posted through and ignored by the gateway so invitees in those orgs can still activate. The accept is one transaction: it activates the invitee (when they are still invited) and records disclosure acceptance together, so a failed second hop cannot leave an `ACTIVE` user with no acceptance on record. After accept succeeds, the widget awaits any async `onAccepted` continuation, then kicks a widget-init refresh so host gates keyed on `INVITED` — or on the disclosure flags — can clear. Accept and `onAccepted` failures are handled separately — a rejected host continuation does not look like (or re-run) a failed gateway accept. The refresh is fire-and-forget and runs only after `onAccepted` settles — hosts that unmount this widget when status leaves `INVITED` would otherwise hide a rejected continuation. Auth uses the normal `widgetToken` provider contract — **never** pass an application (APP) / M2M bearer as `widgetToken`. This widget does not take invite-link credentials and does not read URL search params.
-
-A failed disclosures fetch renders an error surface with retry instead of a blank INVITED screen. The widget otherwise renders nothing until the disclosures fetch resolves **and** init resolves a `bankName` — it never substitutes another tenant's legal copy, and never falls back to a Tesouro-hosted document (a published embeddable library must not depend on infrastructure a consumer's content-security policy cannot see). An empty document list (`requirement: NOT_REQUIRED`, `version: null`) is a resolved payload, not missing data: the widget still renders Accept so those invitees can activate. Agreement copy names the returned document titles, in backend order, so the sentence cannot list instruments the links do not show. If init omits `vspName`, provider attribution falls back to the bank name so the sentence remains complete.
-
-Once the atomic accept _and_ any async `onAccepted` continuation succeed, the checkbox and Accept control stay disabled, so a legal acceptance is never posted twice even if the host does not navigate away. A failed accept or rejected `onAccepted` shows an inline error and leaves the control usable for a retry; a successful accept is skipped on retry after a later failure. Init refresh is kicked only after `onAccepted` succeeds.
+Shows the bank partner's required disclosure documents with an agreement checkbox and an Accept button. The document set, titles and order come from your program's backend configuration, so you pass no URLs.
 
 #### Props
 
-| Prop         | Type                                     | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| ------------ | ---------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `labels`     | `Partial<AcceptDisclosuresWidgetLabels>` | —       | Override shell copy (title, Accept, agreement/attribution templates). `{documents}` in `agreementTextTemplate` is replaced with the backend-returned titles; a template that omits `{documents}` still has those titles appended. When the backend returns no documents, `noDocumentsTitle` / `noDocumentsAgreementTextTemplate` / `noDocumentsAgreementCheckboxAriaLabel` replace the disclosures copy (including the checkbox `aria-label`). Document titles themselves are not overridable. |
-| `onAccepted` | `() => void \| Promise<void>`            | —       | Called after the atomic accept succeeds and before init refresh; awaited before the widget locks. Reject to surface an error and keep Accept retryable.                                                                                                                                                                                                                                                                                                                                        |
+| Prop         | Type                                     | Default        | Description                                                                                                                                                                                           |
+| ------------ | ---------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `labels`     | `Partial<AcceptDisclosuresWidgetLabels>` | English labels | Override widget copy. `{documents}` in `agreementTextTemplate` is replaced with the document titles. The `noDocuments*` labels apply when there are no documents. Document titles aren't overridable. |
+| `onAccepted` | `() => void \| Promise<void>`            | `undefined`    | Called after the atomic accept succeeds and before init refresh; awaited before the widget locks. Reject to surface an error and keep Accept retryable.                                               |
 
 ### BankAccountsWidget
 
-A self-contained banking widget for listing Tesouro bank accounts, creating an account with team access, and viewing account details.
+Lists the organization's Tesouro bank accounts, lets the user open an account with team access, and shows each account's details.
 
 #### Props
 
@@ -257,7 +221,7 @@ A self-contained banking widget for listing Tesouro bank accounts, creating an a
 | `isBankingTaglineVisible`   | `boolean`                                  | `true`         | Shows the banking tagline at the top of the widget. The page heading above it belongs to your page.               |
 | `bankLogoSrc`               | `string`                                   | `undefined`    | Bank logo for the tagline row. Omit and the row shows the bank name alone.                                        |
 | `bankLogoAlt`               | `string`                                   | `undefined`    | Alt text when `bankLogoSrc` is set.                                                                               |
-| `depositAgreementUrl`       | `string`                                   | `undefined`    | Deposit-agreement PDF linked from the create-account legal copy. Omit and the clause naming it is not rendered.   |
+| `depositAgreementUrl`       | `string`                                   | `undefined`    | Deposit-agreement PDF linked from the create-account legal copy. Omit and the clause naming it isn't rendered.    |
 | `bankAddress`               | `string`                                   | `undefined`    | Bank postal address shown in the account-details domestic wire panel.                                             |
 | `supportTeamUrl`            | `string`                                   | `undefined`    | Support URL linked from the account-details domestic wire copy.                                                   |
 | `labels`                    | `Partial<BankAccountsWidgetLabels>`        | English labels | Overrides list/create-account UI copy.                                                                            |
@@ -270,371 +234,345 @@ A self-contained banking widget for listing Tesouro bank accounts, creating an a
 
 ### BillPayWidget
 
-A Monite-backed bill pay widget wrapped in Tesouro widget auth and theming.
+A bill pay widget with Tesouro widget auth and theming. It renders the `'monite'` implementation unless you set `implementation="native"`.
 
 #### Props
 
-| Prop                 | Type                                 | Default      | Description                                                                                                                                                                                                                                                                         |
-| -------------------- | ------------------------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `pageTitleComponent` | `(children: ReactNode) => ReactNode` | Pass-through | Customizes Monite's page title action region.                                                                                                                                                                                                                                       |
-| `finopsThemeColors`  | `FinopsThemeColors`                  | `undefined`  | Optional Monite theme color overrides.                                                                                                                                                                                                                                              |
-| `initialTab`         | `'bills' \| 'vendors'`               | `'bills'`    | Tab to open on initial mount. Native implementation only (`implementation="native"`); has no effect under the default Monite implementation.                                                                                                                                        |
-| `poweredByBankName`  | `string`                             | `undefined`  | Bank shown as "Powered by {bank}" next to the source account when paying a bill. Native implementation only (`implementation="native"`); has no effect under the default Monite implementation.                                                                                     |
-| `onSettingsClick`    | `() => void`                         | `undefined`  | Opens your bill pay settings surface from a cog beside the bill list's "Add bill" button. The cog renders only when this is supplied and the user's scopes reach that surface. Native implementation only; under Monite, build a settings button into `pageTitleComponent` instead. |
+| Prop                 | Type                                 | Default      | Description                                                                                                                                                                                                                                                                             |
+| -------------------- | ------------------------------------ | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pageTitleComponent` | `(children: ReactNode) => ReactNode` | Pass-through | Customizes the page title action region.                                                                                                                                                                                                                                                |
+| `finopsThemeColors`  | `FinopsThemeColors`                  | `undefined`  | Optional theme color overrides for the `'monite'` implementation.                                                                                                                                                                                                                       |
+| `initialTab`         | `'bills' \| 'vendors'`               | `'bills'`    | Tab to open on initial mount. Native implementation only (`implementation="native"`); has no effect under the default `'monite'` implementation.                                                                                                                                        |
+| `poweredByBankName`  | `string`                             | `undefined`  | Bank shown as "Powered by {bank}" next to the source account when paying a bill. Native implementation only (`implementation="native"`); has no effect under the default `'monite'` implementation.                                                                                     |
+| `onSettingsClick`    | `() => void`                         | `undefined`  | Opens your bill pay settings surface from a cog beside the bill list's "Add bill" button. The cog renders only when this is supplied and the user's scopes reach that surface. Native implementation only; under `'monite'`, build a settings button into `pageTitleComponent` instead. |
 
 ### CreditCardsWidget
 
-One page of an organization's **credit** cards, with a scope-gated "Show my cards" toggle and a per-row Activate affordance. Selecting a row opens that card's read-only details in a side sheet. Create card is host-owned: supply `onCreateCard` or the button is not rendered.
+Lists an organization's **credit** cards one page at a time, with a "Show my cards" toggle and per-row Activate. Selecting a row opens the card's details in a side sheet. There is no built-in credit issuance flow, so Create card appears only when you supply `onCreateCard`.
 
 #### Props
 
-| Prop                        | Type                                    | Default        | Description                                                                                                                                                                                          |
-| --------------------------- | --------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `pagination`                | `{ paginationToken?, pageSize? }`       | `undefined`    | Controlled cursor and page size. Supply with `onPaginationChange` when your app owns the list position.                                                                                              |
-| `defaultPagination`         | `{ paginationToken?, pageSize? }`       | First page, 10 | Initial cursor and page size when uncontrolled. Ignored when `pagination` is supplied.                                                                                                               |
-| `onPaginationChange`        | `(pagination: CardsPagination) => void` | `undefined`    | Called whenever the widget moves page or changes page size. Persist the whole object, not the token alone.                                                                                           |
-| `labels`                    | `PartialDeep<CardsLabels>`              | English labels | Overrides the copy of the list screen — its controls, columns, states, and the details sheet's screen-reader name under `detailsSheet`. Nested groups merge per group.                               |
-| `featureLabels`             | `PartialDeep<CardsFeatureLabels>`       | English labels | Overrides the copy this widget resolves rather than passes through — status and form-factor vocabulary, the empty-cell placeholder, and name fallbacks.                                              |
-| `selectedCardId`            | `string \| null`                        | `undefined`    | Controlled selection of the card whose details panel is open. `null` closes it; omit for uncontrolled. See **Selection** below.                                                                      |
-| `defaultSelectedCardId`     | `string \| null`                        | `undefined`    | Initial selection when uncontrolled. Ignored when `selectedCardId` is supplied.                                                                                                                      |
-| `onSelectedCardIdChange`    | `(cardId: string \| null) => void`      | `undefined`    | Fires whenever the open card changes, including on close (`null`). Supplying it does **not** change what renders.                                                                                    |
-| `cardDetailsLabels`         | `PartialDeep<CardDetailsWidgetLabels>`  | English labels | Label overrides forwarded into the details panel.                                                                                                                                                    |
-| `cardDetailsFeatureLabels`  | `PartialDeep<CardDetailsFeatureLabels>` | English labels | Overrides for the copy the panel's feature layer resolves — status vocabulary, form-factor copy, program label, copy-success toast. Distinct from `featureLabels`.                                   |
-| `cardDetailsActivateLabels` | `PartialDeep<ActivateCardPanelLabels>`  | English labels | Overrides for the Activate Card form the details panel opens — its heading, the two field labels, and its validation and status copy.                                                                |
-| `bankLogoSrc`               | `string`                                | `undefined`    | Bank logo for the details panel's card face. Omit and the face renders without a logo rather than with a placeholder.                                                                                |
-| `bankLogoAlt`               | `string`                                | `undefined`    | Alt text for `bankLogoSrc`.                                                                                                                                                                          |
-| `onCreateCard`              | `() => void`                            | `undefined`    | Host-owned Create card handler. Required for the button to render at all. See **Create card** below.                                                                                                 |
-| `headerStart`               | `ReactNode`                             | `undefined`    | Your own markup for the start of the header row, beside Create card. Pass your heading here so the two share one row; the widget renders no heading of its own, so you choose the element and level. |
-| `onActivateCard`            | `(cardId: string) => void`              | `undefined`    | Called when a row's Activate button is clicked. Omit it and the button is not rendered.                                                                                                              |
+| Prop                        | Type                                    | Default        | Description                                                                                                               |
+| --------------------------- | --------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `pagination`                | `{ paginationToken?, pageSize? }`       | `undefined`    | Controlled cursor and page size. Supply with `onPaginationChange`.                                                        |
+| `defaultPagination`         | `{ paginationToken?, pageSize? }`       | First page, 10 | Initial cursor and page size when uncontrolled. Ignored when `pagination` is supplied.                                    |
+| `onPaginationChange`        | `(pagination: CardsPagination) => void` | `undefined`    | Called on every page or page-size change. Persist the whole object, not the token alone.                                  |
+| `labels`                    | `PartialDeep<CardsLabels>`              | English labels | Overrides the list screen's copy, including the details sheet's screen-reader name under `detailsSheet`.                  |
+| `featureLabels`             | `PartialDeep<CardsFeatureLabels>`       | English labels | Overrides status and form-factor vocabulary, the empty-cell placeholder and name fallbacks.                               |
+| `selectedCardId`            | `string \| null`                        | `undefined`    | Controlled selection of the card whose details panel is open. `null` closes it; omit for uncontrolled.                    |
+| `defaultSelectedCardId`     | `string \| null`                        | `undefined`    | Initial selection when uncontrolled. Ignored when `selectedCardId` is supplied.                                           |
+| `onSelectedCardIdChange`    | `(cardId: string \| null) => void`      | `undefined`    | Fires whenever the open card changes, including on close (`null`). Supplying it does **not** change what renders.         |
+| `cardDetailsLabels`         | `PartialDeep<CardDetailsWidgetLabels>`  | English labels | Label overrides forwarded into the details panel.                                                                         |
+| `cardDetailsFeatureLabels`  | `PartialDeep<CardDetailsFeatureLabels>` | English labels | Overrides the details panel's status, form-factor and program copy and its copy-success toast.                            |
+| `cardDetailsActivateLabels` | `PartialDeep<ActivateCardPanelLabels>`  | English labels | Overrides the copy of the Activate Card form the details panel opens.                                                     |
+| `bankLogoSrc`               | `string`                                | `undefined`    | Bank logo for the details panel's card face. Omit it and the face renders no logo.                                        |
+| `bankLogoAlt`               | `string`                                | `undefined`    | Alt text for `bankLogoSrc`.                                                                                               |
+| `onCreateCard`              | `() => void`                            | `undefined`    | Your own Create card handler. Required for the button to render.                                                          |
+| `headerStart`               | `ReactNode`                             | `undefined`    | Your markup for the start of the header row, beside Create card. Put your heading here; you choose the element and level. |
+| `onActivateCard`            | `(cardId: string) => void`              | `undefined`    | Called when a row's Activate button is clicked. Omit it and the button isn't rendered.                                    |
 
 ### DebitCardsWidget
 
-One page of an organization's **debit** cards, with a scope-gated "Show my cards" toggle, Create card and per-row Activate affordances. Selecting a row opens that card's read-only details in a side sheet. Create card opens the same sheet with the built-in debit issuance flow.
+Lists an organization's **debit** cards one page at a time, with a "Show my cards" toggle, Create card and per-row Activate. Selecting a row opens the card's details in a side sheet, and Create card opens the built-in debit issuance flow in the same sheet.
 
 #### Props
 
-| Prop                        | Type                                    | Default        | Description                                                                                                                                                                                                                    |
-| --------------------------- | --------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `pagination`                | `{ paginationToken?, pageSize? }`       | `undefined`    | Controlled cursor and page size. Supply with `onPaginationChange` when your app owns the list position.                                                                                                                        |
-| `defaultPagination`         | `{ paginationToken?, pageSize? }`       | First page, 10 | Initial cursor and page size when uncontrolled. Ignored when `pagination` is supplied.                                                                                                                                         |
-| `onPaginationChange`        | `(pagination: CardsPagination) => void` | `undefined`    | Called whenever the widget moves page or changes page size. Persist the whole object, not the token alone.                                                                                                                     |
-| `labels`                    | `PartialDeep<CardsLabels>`              | English labels | Overrides the copy of the list screen — its controls, columns, states, the details sheet's screen-reader name under `detailsSheet` and the create sheet's under `createSheet`. Nested groups merge per group.                  |
-| `featureLabels`             | `PartialDeep<CardsFeatureLabels>`       | English labels | Overrides the copy this widget resolves rather than passes through — status and form-factor vocabulary, the empty-cell placeholder, and name fallbacks.                                                                        |
-| `selectedCardId`            | `string \| null`                        | `undefined`    | Controlled selection of the card whose details panel is open. `null` closes it; omit for uncontrolled. See **Selection** below.                                                                                                |
-| `defaultSelectedCardId`     | `string \| null`                        | `undefined`    | Initial selection when uncontrolled. Ignored when `selectedCardId` is supplied.                                                                                                                                                |
-| `onSelectedCardIdChange`    | `(cardId: string \| null) => void`      | `undefined`    | Fires whenever the open card changes, including on close (`null`). Supplying it does **not** change what renders.                                                                                                              |
-| `cardDetailsLabels`         | `PartialDeep<CardDetailsWidgetLabels>`  | English labels | Label overrides forwarded into the details panel.                                                                                                                                                                              |
-| `cardDetailsFeatureLabels`  | `PartialDeep<CardDetailsFeatureLabels>` | English labels | Overrides for the copy the panel's feature layer resolves — status vocabulary, form-factor copy, program label, copy-success toast. Distinct from `featureLabels`.                                                             |
-| `cardDetailsActivateLabels` | `PartialDeep<ActivateCardPanelLabels>`  | English labels | Overrides for the Activate Card form the details panel opens — its heading, the two field labels, and its validation and status copy.                                                                                          |
-| `bankLogoSrc`               | `string`                                | `undefined`    | Bank logo for the details panel's card face. Ignored there when `cardArtSrc` is set. Omit both and the face renders without a logo rather than with a placeholder.                                                             |
-| `bankLogoAlt`               | `string`                                | `undefined`    | Alt text for `bankLogoSrc`.                                                                                                                                                                                                    |
-| `cardArtSrc`                | `string`                                | `undefined`    | Plastic art for the built-in create sheet **and** the details panel's card face. Omit it and the create sheet draws a built-in neutral plastic, while the details face falls back to `bankLogoSrc`. See **Create card** below. |
-| `createCardLabels`          | `PartialDeep<CreateCardWidgetLabels>`   | English labels | Label overrides forwarded into the nested create-card panel.                                                                                                                                                                   |
-| `createCardFeatureLabels`   | toast / untitled-funding overrides      | English labels | Overrides for the copy the create panel's feature layer resolves — mutation toasts, untitled funding-account fallback, pending-activation success copy.                                                                        |
-| `onCreateCard`              | `() => void`                            | `undefined`    | Host-owned Create card handler. When supplied, the built-in sheet does not open — use it for a custom issuance flow.                                                                                                           |
-| `headerStart`               | `ReactNode`                             | `undefined`    | Your own markup for the start of the header row, beside Create card. Pass your heading here so the two share one row; the widget renders no heading of its own, so you choose the element and level.                           |
-| `onActivateCard`            | `(cardId: string) => void`              | `undefined`    | Called when a row's Activate button is clicked. Omit it and the button is not rendered.                                                                                                                                        |
+| Prop                        | Type                                    | Default        | Description                                                                                                               |
+| --------------------------- | --------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `pagination`                | `{ paginationToken?, pageSize? }`       | `undefined`    | Controlled cursor and page size. Supply with `onPaginationChange`.                                                        |
+| `defaultPagination`         | `{ paginationToken?, pageSize? }`       | First page, 10 | Initial cursor and page size when uncontrolled. Ignored when `pagination` is supplied.                                    |
+| `onPaginationChange`        | `(pagination: CardsPagination) => void` | `undefined`    | Called on every page or page-size change. Persist the whole object, not the token alone.                                  |
+| `labels`                    | `PartialDeep<CardsLabels>`              | English labels | Overrides the list screen's copy, including the sheets' screen-reader names under `detailsSheet` and `createSheet`.       |
+| `featureLabels`             | `PartialDeep<CardsFeatureLabels>`       | English labels | Overrides status and form-factor vocabulary, the empty-cell placeholder and name fallbacks.                               |
+| `selectedCardId`            | `string \| null`                        | `undefined`    | Controlled selection of the card whose details panel is open. `null` closes it; omit for uncontrolled.                    |
+| `defaultSelectedCardId`     | `string \| null`                        | `undefined`    | Initial selection when uncontrolled. Ignored when `selectedCardId` is supplied.                                           |
+| `onSelectedCardIdChange`    | `(cardId: string \| null) => void`      | `undefined`    | Fires whenever the open card changes, including on close (`null`). Supplying it does **not** change what renders.         |
+| `cardDetailsLabels`         | `PartialDeep<CardDetailsWidgetLabels>`  | English labels | Label overrides forwarded into the details panel.                                                                         |
+| `cardDetailsFeatureLabels`  | `PartialDeep<CardDetailsFeatureLabels>` | English labels | Overrides the details panel's status, form-factor and program copy and its copy-success toast.                            |
+| `cardDetailsActivateLabels` | `PartialDeep<ActivateCardPanelLabels>`  | English labels | Overrides the copy of the Activate Card form the details panel opens.                                                     |
+| `bankLogoSrc`               | `string`                                | `undefined`    | Bank logo for the details panel's card face, ignored when `cardArtSrc` is set. Omit both and the face renders no logo.    |
+| `bankLogoAlt`               | `string`                                | `undefined`    | Alt text for `bankLogoSrc`.                                                                                               |
+| `cardArtSrc`                | `string`                                | `undefined`    | Card art for the create sheet and the details card face. Omitted, the sheet uses a neutral plastic.                       |
+| `createCardLabels`          | `PartialDeep<CreateCardWidgetLabels>`   | English labels | Label overrides forwarded into the built-in create sheet.                                                                 |
+| `createCardFeatureLabels`   | toast / untitled-funding overrides      | English labels | Overrides the create sheet's toasts, untitled funding-account fallback and pending-activation success copy.               |
+| `onCreateCard`              | `() => void`                            | `undefined`    | Your own Create card handler. When supplied, the built-in sheet doesn't open.                                             |
+| `headerStart`               | `ReactNode`                             | `undefined`    | Your markup for the start of the header row, beside Create card. Put your heading here; you choose the element and level. |
+| `onActivateCard`            | `(cardId: string) => void`              | `undefined`    | Called when a row's Activate button is clicked. Omit it and the button isn't rendered.                                    |
 
 ### CardDetailsWidget
 
-Details for one credit **or** debit card — status, form factor, program, masked card number, and copyable cardholder, nickname and billing-address rows. A debit card can also reveal its number, expiry and security code on demand, lock and unlock itself, and be renamed in place. It renders panel content rather than its own drawer, so it sits on a page of your own as readily as inside chrome you already have.
+Details for one credit or debit card: status, form factor, program, masked number, and copyable cardholder, nickname and billing-address rows. It renders panel content rather than its own drawer, so it fits on a page of your own or inside chrome you already have.
 
 #### Props
 
-| Prop             | Type                                    | Default        | Description                                                                                                                                                                                                                                              |
-| ---------------- | --------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `cardId`         | `string`                                | **Required**   | Id of the card to show.                                                                                                                                                                                                                                  |
-| `cardProgram`    | `'credit' \| 'debit'`                   | **Required**   | Which issuing program `cardId` belongs to. Selects the endpoint the card is fetched from.                                                                                                                                                                |
-| `onClose`        | `() => void`                            | `undefined`    | Called when the reader is finished with the widget: the details panel's close control, and **Done** on the activation success screen. Omit it and neither is rendered. The activation form keeps its own close either way, which returns to the details. |
-| `labels`         | `PartialDeep<CardDetailsWidgetLabels>`  | English labels | Overrides the panel's own copy — header, card face alt text, row headings, copy-button accessible names, the nickname editor, the lock control and its locked notice, and the loading/error/not-found screens.                                           |
-| `activateLabels` | `PartialDeep<ActivateCardPanelLabels>`  | English labels | Overrides the Activate Card form's copy — its heading, the two field labels, the security-code explanation, and the validation and status text.                                                                                                          |
-| `featureLabels`  | `PartialDeep<CardDetailsFeatureLabels>` | English labels | Overrides the copy this widget resolves rather than passes through — status, form-factor and program vocabulary, the copy-success and nickname-updated toasts, the activation, lock and nickname conflict toasts, and the refused-reveal sentence.       |
-| `cardArtSrc`     | `string`                                | `undefined`    | Full per-tenant plastic art for the card face — the same asset you pass `CreateCardWidget`. Takes priority over `bankLogoSrc`; see **Card art** below.                                                                                                   |
-| `bankLogoSrc`    | `string`                                | `undefined`    | Bank logo for the card face. Ignored when `cardArtSrc` is set. Omit and the face renders without a logo rather than with a placeholder.                                                                                                                  |
-| `bankLogoAlt`    | `string`                                | `undefined`    | Alt text for `bankLogoSrc`. Falls back to `labels.cardFace.bankLogoAlt`.                                                                                                                                                                                 |
+| Prop             | Type                                    | Default        | Description                                                                                                                    |
+| ---------------- | --------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `cardId`         | `string`                                | **Required**   | Id of the card to show.                                                                                                        |
+| `cardProgram`    | `'credit' \| 'debit'`                   | **Required**   | Which issuing program `cardId` belongs to.                                                                                     |
+| `onClose`        | `() => void`                            | `undefined`    | Called by the panel's close control and the activation **Done** button. Omit it and neither is rendered.                       |
+| `labels`         | `PartialDeep<CardDetailsWidgetLabels>`  | English labels | Overrides the panel's copy. See the exported `CardDetailsWidgetLabels` type for every key.                                     |
+| `activateLabels` | `PartialDeep<ActivateCardPanelLabels>`  | English labels | Overrides the Activate Card form's copy. See the exported `ActivateCardPanelLabels` type for every key.                        |
+| `featureLabels`  | `PartialDeep<CardDetailsFeatureLabels>` | English labels | Overrides status, form-factor and program wording, toasts, and the refused-reveal sentence. See `CardDetailsFeatureLabels`.    |
+| `cardArtSrc`     | `string`                                | `undefined`    | Full plastic art for the card face (the same asset you pass `CreateCardWidget`). Takes priority over `bankLogoSrc`.            |
+| `bankLogoSrc`    | `string`                                | `undefined`    | Bank logo for the card face; ignored when `cardArtSrc` is set. The widget ships no bank artwork, so omit it and no logo shows. |
+| `bankLogoAlt`    | `string`                                | `undefined`    | Alt text for `bankLogoSrc`. Falls back to `labels.cardFace.bankLogoAlt`.                                                       |
 
 ### CounterpartsWidget
 
-A self-contained widget for managing an organization's customers or vendors with searchable lists, money columns, details, editing, and deletion.
+Manages an organization's customers or vendors: a searchable list with money columns, a details sheet, and create, edit and delete flows, including addresses and a vendor's ACH payment method.
 
 #### Props
 
-| Prop                 | Type                                             | Default             | Description                                                                                                                                                                                                                                                                                                                  |
-| -------------------- | ------------------------------------------------ | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `counterpartType`    | `'customer' \| 'vendor'`                         | —                   | Required. Selects receivables/customer copy and queries or payables/vendor copy and queries.                                                                                                                                                                                                                                 |
-| `pageSizeOptions`    | `number[]`                                       | `[10, 25, 50, 100]` | Page-size choices shown by the table.                                                                                                                                                                                                                                                                                        |
-| `onViewAllDocuments` | `(counterpart: CounterpartActionTarget) => void` | `undefined`         | Reveals a "View all" action beside the recent-bills/invoices heading in the details sheet, and hands over the counterpart's `id` and `name` so the destination can filter to them. Omit when the host has no document list to navigate to; the action stays hidden rather than dead.                                         |
-| `onCreateDocument`   | `(counterpart: CounterpartActionTarget) => void` | `undefined`         | Runs the details sheet's primary CTA — "Send a payment" for a vendor, "Issue an invoice" for a customer — with the counterpart's `id` and `name`, so the host can open its create flow pre-linked to them. Omit and the button renders disabled. The destination's own scope (payable/invoice write) is the host's to check. |
-
-| Prop                | Type                                      | Description                                                                                                      |
-| ------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| `screenLabels`      | `Partial<CounterpartsScreenLabels>`       | Table title, columns, search/filter, empty, error, access-restricted, and row-action copy.                       |
-| `formLabels`        | `Partial<CounterpartFormSheetLabels>`     | Create/edit counterpart form copy.                                                                               |
-| `detailsLabels`     | `Partial<CounterpartDetailsSheetLabels>`  | Details sheet sections, summary labels, subtitle/entity/reminder/payment-method labels, row labels, and actions. |
-| `bankAccountLabels` | `PartialDeep<BankAccountFormSheetLabels>` | Vendor payment-method form copy, including nested field-marker labels.                                           |
-| `addressLabels`     | `PartialDeep<AddressFormSheetLabels>`     | Address form copy.                                                                                               |
-| `deleteLabels`      | `Partial<ConfirmDeleteDialogLabels>`      | Delete-dialog copy.                                                                                              |
-| `messageLabels`     | `Partial<CounterpartMessageLabels>`       | Validation, API failure, and delete-prompt messages produced by feature logic.                                   |
+| Prop                 | Type                                             | Default             | Description                                                                                                                                       |
+| -------------------- | ------------------------------------------------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `counterpartType`    | `'customer' \| 'vendor'`                         | **Required**        | Selects the customer or vendor surface.                                                                                                           |
+| `pageSizeOptions`    | `number[]`                                       | `[10, 25, 50, 100]` | Page-size choices shown by the table.                                                                                                             |
+| `onViewAllDocuments` | `(counterpart: CounterpartActionTarget) => void` | `undefined`         | Shows a "View all" action by the details sheet's recent bills/invoices and passes the counterpart's `id` and `name`. Hidden when omitted.         |
+| `onCreateDocument`   | `(counterpart: CounterpartActionTarget) => void` | `undefined`         | Runs the details sheet's "Send a payment" (vendor) or "Issue an invoice" (customer) button. Disabled when omitted; you check the scopes it needs. |
+| `screenLabels`       | `Partial<CounterpartsScreenLabels>`              | English labels      | Table, search/filter, empty, error and access-restricted copy.                                                                                    |
+| `formLabels`         | `PartialDeep<CounterpartFormSheetLabels>`        | English labels      | Create/edit form copy.                                                                                                                            |
+| `detailsLabels`      | `Partial<CounterpartDetailsSheetLabels>`         | English labels      | Details sheet copy.                                                                                                                               |
+| `bankAccountLabels`  | `PartialDeep<BankAccountFormSheetLabels>`        | English labels      | Vendor payment-method form copy.                                                                                                                  |
+| `addressLabels`      | `PartialDeep<AddressFormSheetLabels>`            | English labels      | Address form copy.                                                                                                                                |
+| `deleteLabels`       | `Partial<ConfirmDeleteDialogLabels>`             | English labels      | Delete-dialog copy.                                                                                                                               |
+| `messageLabels`      | `Partial<CounterpartMessageLabels>`              | English labels      | Validation, API failure and delete-prompt messages.                                                                                               |
 
 ### CustomersWidget
 
-A self-contained widget for managing an organization's customers: searchable list, money columns, details, editing, and deletion.
+Manages an organization's customers: a searchable list with money columns, a details sheet, and create, edit and delete flows.
 
 #### Props
 
-| Prop                 | Type                                          | Default             | Description                                                                                                                                                                                                                                                                                                       |
-| -------------------- | --------------------------------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `pageSizeOptions`    | `number[]`                                    | `[10, 25, 50, 100]` | Page-size choices shown by the table.                                                                                                                                                                                                                                                                             |
-| `onViewAllDocuments` | `(customer: CounterpartActionTarget) => void` | `undefined`         | Reveals a "View all" action beside the recent-invoices heading in the details sheet, and hands over the customer's `id` and `name` so the destination can filter to them. Omit when the host has no invoice list to navigate to. Under `implementation="monite"`, `name` is always empty.                         |
-| `onCreateDocument`   | `(customer: CounterpartActionTarget) => void` | `undefined`         | Runs the details sheet's "Issue an invoice" action with the customer's `id` and `name`, so the host can open its create flow pre-linked to them. Omit and the button renders disabled. The destination's own invoice-write scope is the host's to check. Under `implementation="monite"`, `name` is always empty. |
-
-| Prop            | Type                                     | Description                                                                                       |
-| --------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------- |
-| `screenLabels`  | `Partial<CounterpartsScreenLabels>`      | Table title, columns, search/filter, empty, error, and access-restricted copy.                    |
-| `formLabels`    | `Partial<CounterpartFormSheetLabels>`    | Create/edit customer form copy.                                                                   |
-| `detailsLabels` | `Partial<CounterpartDetailsSheetLabels>` | Details sheet sections, summary labels, subtitle/entity/reminder labels, row labels, and actions. |
-| `addressLabels` | `PartialDeep<AddressFormSheetLabels>`    | Address form copy.                                                                                |
-| `deleteLabels`  | `Partial<ConfirmDeleteDialogLabels>`     | Delete-dialog copy.                                                                               |
-| `messageLabels` | `Partial<CounterpartMessageLabels>`      | Validation, API failure, and delete-prompt messages produced by feature logic.                    |
+| Prop                 | Type                                          | Default             | Description                                                                                                                  |
+| -------------------- | --------------------------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `pageSizeOptions`    | `number[]`                                    | `[10, 25, 50, 100]` | Page-size choices shown by the table.                                                                                        |
+| `onViewAllDocuments` | `(customer: CounterpartActionTarget) => void` | `undefined`         | Shows a "View all" action on the details sheet's recent invoices and passes the customer's `id` and `name`; omit to hide it. |
+| `onCreateDocument`   | `(customer: CounterpartActionTarget) => void` | `undefined`         | Handles "Issue an invoice" with the customer's `id` and `name`; omit and the button is disabled. You check invoice scopes.   |
+| `screenLabels`       | `Partial<CounterpartsScreenLabels>`           | English labels      | Table, search, filter, empty and error copy.                                                                                 |
+| `formLabels`         | `Partial<CounterpartFormSheetLabels>`         | English labels      | Create/edit customer form copy.                                                                                              |
+| `detailsLabels`      | `Partial<CounterpartDetailsSheetLabels>`      | English labels      | Details sheet copy.                                                                                                          |
+| `addressLabels`      | `PartialDeep<AddressFormSheetLabels>`         | English labels      | Address form copy.                                                                                                           |
+| `deleteLabels`       | `Partial<ConfirmDeleteDialogLabels>`          | English labels      | Delete-dialog copy.                                                                                                          |
+| `messageLabels`      | `Partial<CounterpartMessageLabels>`           | English labels      | Validation, API failure and delete-prompt copy.                                                                              |
 
 ### ExpenseManagementWidget
 
-A self-contained expenses widget: a bank-attribution header, My/Team transactions tabs with count badges, per-tab Action Items, a searchable/filterable/paginated transactions table, receipt upload (mailbox or drag-and-drop), and a full-screen transaction review dialog opened from a row or an Action Item.
+A complete expenses surface: My and Team transactions tabs with Action Items, a searchable transactions table, receipt upload, and a full-screen transaction review dialog.
 
 #### Props
 
-| Prop                              | Type                                           | Default | Description                                                                                                               |
-| --------------------------------- | ---------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
-| `bankDisplayName`                 | `string`                                       | —       | Bank name shown in the attribution header.                                                                                |
-| `bankLogoSrc`                     | `string`                                       | —       | URL for the bank logo in the attribution header.                                                                          |
-| `bankLogoAlt`                     | `string`                                       | —       | Alt text for the bank logo.                                                                                               |
-| `isBankingTaglineVisible`         | `boolean`                                      | —       | Shows the "Business Banking provided by" tagline beside the header.                                                       |
-| `onSettingsClick`                 | `() => void`                                   | —       | Renders a settings entry point in the header (host routing ban — the widget never navigates itself). Gated on scopes.     |
-| `receiptUpload`                   | `UploadReceiptWidgetProps`                     | —       | Overrides the built-in receipt-upload control's `onFileUpload` / `onAwaitMatching` and other `UploadReceiptWidget` props. |
-| `screenLabels`                    | `Partial<ExpensesScreenLabels>`                | English | Tab labels and other `ExpensesScreen` shell copy.                                                                         |
-| `headerLabels`                    | `Partial<ExpensesHeaderLabels>`                | English | Bank-attribution header copy.                                                                                             |
-| `transactionsTableLabels`         | `Partial<ExpensesTransactionsTableLabels>`     | English | Transactions table column headers and empty/loading copy.                                                                 |
-| `filterBarLabels`                 | `Partial<ExpensesTransactionsFilterBarLabels>` | English | Search/filter bar copy.                                                                                                   |
-| `actionItemsLabels`               | `Partial<ActionItemsListLabels>`               | English | Action Items list copy.                                                                                                   |
-| `statusBadgeLabels`               | `Partial<ExpenseStatusBadgeLabels>`            | English | Status pill copy, shared between the table and the review dialog.                                                         |
-| `transactionDetailsLabels`        | `Partial<TransactionDetailsLabels>`            | English | Copy for the full-screen review dialog opened from a row or an Action Item.                                               |
-| `transactionDetailsCardLabels`    | `Partial<AccordionItemCardLabels>`             | English | Copy for the accordion cards inside the review dialog.                                                                    |
-| `transactionDetailsActionsLabels` | `Partial<TransactionDetailsActionsLabels>`     | English | Copy for the review dialog's action buttons.                                                                              |
-| `fileViewerLabels`                | `Partial<FileViewerLabels>`                    | English | Copy for the receipt/attachment file viewer inside the review dialog.                                                     |
+| Prop                              | Type                                           | Default     | Description                                                                               |
+| --------------------------------- | ---------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
+| `bankDisplayName`                 | `string`                                       | `undefined` | Bank name shown in the attribution header.                                                |
+| `bankLogoSrc`                     | `string`                                       | `undefined` | URL for the bank logo in the attribution header.                                          |
+| `bankLogoAlt`                     | `string`                                       | `undefined` | Alt text for the bank logo.                                                               |
+| `isBankingTaglineVisible`         | `boolean`                                      | `undefined` | Shows the "Business Banking provided by" tagline beside the header.                       |
+| `onSettingsClick`                 | `() => void`                                   | `undefined` | Renders a scope-gated settings entry point in the header; navigate from this callback.    |
+| `receiptUpload`                   | `UploadReceiptWidgetProps`                     | `undefined` | Overrides the receipt-upload control's props, such as `onFileUpload` / `onAwaitMatching`. |
+| `screenLabels`                    | `Partial<ExpensesScreenLabels>`                | English     | Tab labels and other screen shell copy.                                                   |
+| `headerLabels`                    | `Partial<ExpensesHeaderLabels>`                | English     | Bank-attribution header copy.                                                             |
+| `transactionsTableLabels`         | `Partial<ExpensesTransactionsTableLabels>`     | English     | Transactions table column headers and empty/loading copy.                                 |
+| `filterBarLabels`                 | `Partial<ExpensesTransactionsFilterBarLabels>` | English     | Search/filter bar copy.                                                                   |
+| `actionItemsLabels`               | `Partial<ActionItemsListLabels>`               | English     | Action Items list copy.                                                                   |
+| `statusBadgeLabels`               | `Partial<ExpenseStatusBadgeLabels>`            | English     | Status pill copy, shared between the table and the review dialog.                         |
+| `transactionDetailsLabels`        | `Partial<TransactionDetailsLabels>`            | English     | Review dialog copy.                                                                       |
+| `transactionDetailsCardLabels`    | `Partial<AccordionItemCardLabels>`             | English     | Copy for the accordion cards inside the review dialog.                                    |
+| `transactionDetailsActionsLabels` | `Partial<TransactionDetailsActionsLabels>`     | English     | Copy for the review dialog's action buttons.                                              |
+| `fileViewerLabels`                | `Partial<FileViewerLabels>`                    | English     | Copy for the receipt/attachment file viewer inside the review dialog.                     |
 
 ### UploadReceiptWidget
 
-A self-contained "Upload receipts" control: a toggle button that opens a popover with a drag-and-drop / click-to-browse file picker plus a copyable forwarding email address. It is a controlled, presentational widget — the host owns the actual upload via `onFileUpload` and toasts batch progress, success, and failure.
+An "Upload receipts" button that opens a popover with a drag-and-drop file picker and a copyable forwarding email address. It makes no network calls: your `onFileUpload` does the upload, and the widget shows progress and result toasts.
 
 _Standalone presentational widget — it does not take the shared auth/scope props._
 
 #### Props
 
-| Prop              | Type                                                      | Default     | Description                                                                                                                                                                                                              |
-| ----------------- | --------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `emailAddress`    | `string`                                                  | `undefined` | Forwarding email address shown in the popover with a copy button. Omit it to hide the email option.                                                                                                                      |
-| `onFileUpload`    | `(file: File) => unknown \| Promise<unknown>`             | `undefined` | Called once per selected file. The widget awaits each call and counts resolutions vs. rejections to drive its toasts. Omit to disable uploading.                                                                         |
-| `onAwaitMatching` | `(uploadedCount: number) => Promise<ReceiptMatchSummary>` | `undefined` | Awaited after every file in a batch has uploaded. Resolve once the backend has finished OCR and auto-matching, and the widget reports the aggregate outcome in its batch toast. Omit to stop at the upload confirmation. |
-| `isUploading`     | `boolean`                                                 | `false`     | Host-controlled loading flag. While `true` (or while a batch is in flight) the popover shows a processing state and blocks new uploads.                                                                                  |
+| Prop              | Type                                                      | Default     | Description                                                                                                          |
+| ----------------- | --------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------- |
+| `emailAddress`    | `string`                                                  | `undefined` | Forwarding email address shown with a copy button. Omit it to hide the email option.                                 |
+| `onFileUpload`    | `(file: File) => unknown \| Promise<unknown>`             | `undefined` | Called once per selected file and awaited; a rejection counts as a failed upload. Omit to disable uploading.         |
+| `onAwaitMatching` | `(uploadedCount: number) => Promise<ReceiptMatchSummary>` | `undefined` | Awaited after every file in a batch uploads. Resolve once matching finishes. Omit to stop at upload.                 |
+| `isUploading`     | `boolean`                                                 | `false`     | Host loading flag. While `true` (or while a batch runs) the popover shows a processing state and blocks new uploads. |
 
 ### BalancesWidget
 
-A self-contained widget that loads embedded bank accounts for the organization, shows up to a configurable number of account balance rows, optionally aggregates a total when multiple accounts exist, and can link out to a host “view all accounts” destination.
+Shows the organization's embedded bank account balances, up to a configurable number of rows, with a total when there are several accounts and an optional **View all accounts** link.
 
 #### Props
 
-| Prop                     | Type                            | Default | Description                                                                 |
-| ------------------------ | ------------------------------- | ------- | --------------------------------------------------------------------------- |
-| `maxAccounts`            | `number`                        | `5`     | Maximum rows rendered in-card; additional accounts use the view-all CTA.    |
-| `labels`                 | `Partial<BalancesWidgetLabels>` | —       | Override shell copy (title, errors, view-all label, total balance tooltip). |
-| `onBalanceRowClick`      | `(accountId: string) => void`   | —       | When set, balance rows are clickable and receive the account id.            |
-| `onViewAllAccountsClick` | `() => void`                    | —       | When set and more than `maxAccounts` exist, shows **View all accounts**.    |
+| Prop                     | Type                            | Default        | Description                                                                 |
+| ------------------------ | ------------------------------- | -------------- | --------------------------------------------------------------------------- |
+| `maxAccounts`            | `number`                        | `5`            | Maximum rows rendered in-card; additional accounts use the view-all CTA.    |
+| `labels`                 | `Partial<BalancesWidgetLabels>` | English labels | Override shell copy (title, errors, view-all label, total balance tooltip). |
+| `onBalanceRowClick`      | `(accountId: string) => void`   | `undefined`    | When set, balance rows are clickable and receive the account id.            |
+| `onViewAllAccountsClick` | `() => void`                    | `undefined`    | When set and more than `maxAccounts` exist, shows **View all accounts**.    |
 
 ### InsightsWidget
 
-A self-contained widget that derives onboarding-style insights from embedded and external bank account data, persists dismissed insight ids via the embed **user-data** API, and exposes optional host callbacks for routing and linking external accounts.
+Shows onboarding-style insights derived from the organization's embedded and external bank accounts, in **Active** and **Dismissed** tabs. Users can dismiss insights, and the widget remembers dismissals per organization.
 
 #### Props
 
-| Prop                         | Type                             | Default | Description                                                                                         |
-| ---------------------------- | -------------------------------- | ------- | --------------------------------------------------------------------------------------------------- |
-| `routingEnabled`             | `boolean`                        | `false` | Controlled switch state for the routing onboarding insight.                                         |
-| `onRoutingToggleChange`      | `(enabled: boolean) => void`     | —       | When set, controls the routing switch from the host; otherwise the widget keeps local toggle state. |
-| `onLinkExternalAccountClick` | `() => void`                     | —       | When set, the connect-external-account insight shows a **Link account** CTA.                        |
-| `labels`                     | `Partial<InsightsWidgetLabels>`  | —       | Shell copy (tabs, empty, error).                                                                    |
-| `singleInsightLabels`        | `Partial<SingleInsightLabels>`   | —       | Per-row UI strings (e.g. dismiss aria label).                                                       |
-| `featureLabels`              | `Partial<InsightsFeatureLabels>` | —       | Generated insight body copy and action labels.                                                      |
+| Prop                         | Type                             | Default        | Description                                                                                         |
+| ---------------------------- | -------------------------------- | -------------- | --------------------------------------------------------------------------------------------------- |
+| `routingEnabled`             | `boolean`                        | `false`        | Controlled switch state for the routing onboarding insight.                                         |
+| `onRoutingToggleChange`      | `(enabled: boolean) => void`     | `undefined`    | When set, controls the routing switch from the host; otherwise the widget keeps local toggle state. |
+| `onLinkExternalAccountClick` | `() => void`                     | `undefined`    | When set, the connect-external-account insight shows a **Link account** CTA.                        |
+| `labels`                     | `Partial<InsightsWidgetLabels>`  | English labels | Shell copy (tabs, empty, error).                                                                    |
+| `singleInsightLabels`        | `Partial<SingleInsightLabels>`   | English labels | Per-row UI strings, such as the dismiss button's `aria-label`.                                      |
+| `featureLabels`              | `Partial<InsightsFeatureLabels>` | English labels | Generated insight body copy and action labels.                                                      |
 
 ### InvoicingWidget
 
-A self-contained invoicing widget that renders the Monite SDK receivables experience (invoices, quotes, and credit notes) against your widget auth — the host only supplies credentials and optional theming.
+A full invoicing experience: invoices, quotes and credit notes. You supply widget auth and, optionally, theme colors and a page-title wrapper.
 
 #### Props
 
-| Prop                 | Type                                 | Default     | Description                                                                                                                                                                                        |
-| -------------------- | ------------------------------------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `finopsThemeColors`  | `FinopsThemeColors`                  | `undefined` | Overrides the Monite theme's primary colors. Omit to use Monite defaults.                                                                                                                          |
-| `embeddedBankName`   | `string`                             | `undefined` | Display name of the sponsor bank powering embedded bank accounts (e.g. `"Zenith Bank"`). Shown next to embedded accounts in the invoice payment-account picker as "Powered by {embeddedBankName}". |
-| `pageTitleComponent` | `(children: ReactNode) => ReactNode` | Passthrough | Wraps the page header region. The default returns its children unchanged; supply a wrapper to add a title, branding, or toolbar around the widget's action buttons.                                |
+| Prop                 | Type                                 | Default     | Description                                                                                                  |
+| -------------------- | ------------------------------------ | ----------- | ------------------------------------------------------------------------------------------------------------ |
+| `finopsThemeColors`  | `FinopsThemeColors`                  | `undefined` | `{ primary?: string; primaryForeground?: string }` overriding the theme's primary colors.                    |
+| `embeddedBankName`   | `string`                             | `undefined` | Sponsor bank name, shown as "Powered by {embeddedBankName}" next to embedded accounts in the payment picker. |
+| `pageTitleComponent` | `(children: ReactNode) => ReactNode` | Passthrough | Wraps the header region (which holds the widget's action buttons) to add a title or toolbar.                 |
 
 ### LinkedAccountsWidget
 
-A self-contained widget that lists and manages external bank accounts, including connect, edit, micro-deposit initiation, micro-deposit validation, and unlink actions.
+Lists the organization's external bank accounts and lets the user connect, edit, verify with micro-deposits, and unlink them.
 
 #### Props
 
-| Prop            | Type                                         | Default        | Description                                                                                                                                                                                 |
-| --------------- | -------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `labels`        | `Partial<LinkedAccountsWidgetLabels>`        | English labels | Overrides visible UI copy such as button, dialog, empty-state, loading, and error labels. Unspecified labels fall back to defaults.                                                         |
-| `featureLabels` | `Partial<LinkedAccountsWidgetFeatureLabels>` | English labels | Overrides strings produced by the feature layer, such as row title fallback, account-number subtitle fragments, and the success toast messages shown after editing or unlinking an account. |
+| Prop            | Type                                         | Default        | Description                                                                                                                             |
+| --------------- | -------------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `labels`        | `Partial<LinkedAccountsWidgetLabels>`        | English labels | Override UI copy. `stepIndicator` takes `{current}` and `{total}`; `verifySuccessDescription` and `unlinkDescription` take `{account}`. |
+| `featureLabels` | `Partial<LinkedAccountsWidgetFeatureLabels>` | English labels | Override row fallback text, the account-number prefix, and the edit/unlink success toasts.                                              |
 
 ### BankAccountOnboardingWidget
 
-A self-contained widget that walks an applicant through the embedded bank-account onboarding flow: business details, personal details, optional additional owners, and a result screen. It owns all REST mutations (`createApplication`, `updateApplication`, `submitApplication`), step navigation, validation, and polling for provisioning to complete — the host application only supplies auth credentials and two callbacks.
+Walks an applicant through bank-account onboarding: business details, personal details, optional additional owners, and a result screen. The widget handles saving, validation, submission and waiting for the account to open; you supply auth and two callbacks.
 
 #### Props
 
-| Prop                                        | Type                                           | Required | Description                                                                                                                                                                                                                                                                                                                                                        |
-| ------------------------------------------- | ---------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `onEmbeddedOnboardingCompletedSuccessfully` | `() => void`                                   | Yes      | Called when the application is submitted and approved.                                                                                                                                                                                                                                                                                                             |
-| `onNavigateToDashboard`                     | `() => void`                                   | Yes      | Called when the user clicks the dashboard CTA on the result screen.                                                                                                                                                                                                                                                                                                |
-| `initialBusinessDetails`                    | `Partial<HostSupplied<BusinessDetailsValues>>` | No       | Prefills step 1 (business details). Unset fields start empty; the user can still edit before continuing. Excludes the resume-only `taxIdOnFileLast4` / `taxIdOnFileStructure`, which only a stored application may set.                                                                                                                                            |
-| `initialPersonalDetails`                    | `Partial<HostSupplied<PersonalDetailsValues>>` | No       | Prefills step 2 (personal / about-you details). Unset fields start empty; the user can still edit before continuing. Excludes the resume-only `ssnOnFileLast4`.                                                                                                                                                                                                    |
-| `initialAdditionalOwners`                   | `HostSuppliedOwner[]`                          | No       | Prefills step 3 (additional owners). Defaults to an empty list when omitted. Excludes `id`, which names an owner the server already stores, so a seeded one would update instead of create.                                                                                                                                                                        |
-| `open`                                      | `boolean`                                      | No       | Controlled open state for the modal. When provided the host owns open/close and must update it via `onOpenChange`. Omit for uncontrolled mode.                                                                                                                                                                                                                     |
-| `defaultOpen`                               | `boolean`                                      | No       | Initial open state when uncontrolled. Defaults to `false` so the modal stays closed until the host opens it. Ignored when `open` is set.                                                                                                                                                                                                                           |
-| `onOpenChange`                              | `(open: boolean) => void`                      | No       | Notified whenever the modal opens or closes — fires on overlay click, escape key, the close button, and any controlled state update. Used both as the change handler in controlled mode and a side hook.                                                                                                                                                           |
-| `labels`                                    | `BankAccountOnboardingWidgetLabels`            | No       | Per-step label overrides — see Labels section. Accepts a `modalTitle` override for the modal's accessible title (default: `Bank account onboarding`).                                                                                                                                                                                                              |
-| `bankLogoSrc`                               | `string`                                       | No       | URL for the bank logo rendered on the result screen; falls back to bank name text.                                                                                                                                                                                                                                                                                 |
-| `disclosureLinks`                           | `DisclosureLinks`                              | No       | Host-resolved URLs for Terms of Use, Privacy Policy, Electronic Communication, and Patriot Act on the business-details agreement step. Omit to leave those links unset.                                                                                                                                                                                            |
-| `isFullScreenInline`                        | `boolean`                                      | No       | Renders the widget inline — filling the width/height of its host container — instead of in a modal. `open` / `defaultOpen` are ignored in this mode; the widget always renders once mounted, and the host controls mounting instead. `onOpenChange` still fires for gestures like Cancel, so hosts can react (e.g. by unmounting the widget). Defaults to `false`. |
+| Prop                                        | Type                                           | Default        | Description                                                                                                                        |
+| ------------------------------------------- | ---------------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `onEmbeddedOnboardingCompletedSuccessfully` | `() => void`                                   | **Required**   | Called when the application is approved and the account is open.                                                                   |
+| `onNavigateToDashboard`                     | `() => void`                                   | **Required**   | Called when the user clicks the dashboard CTA on the result screen.                                                                |
+| `initialBusinessDetails`                    | `Partial<HostSupplied<BusinessDetailsValues>>` | `undefined`    | Prefills step 1 (business details); the user can still edit.                                                                       |
+| `initialPersonalDetails`                    | `Partial<HostSupplied<PersonalDetailsValues>>` | `undefined`    | Prefills step 2 (personal details); the user can still edit.                                                                       |
+| `initialAdditionalOwners`                   | `HostSuppliedOwner[]`                          | `[]`           | Prefills step 3 (additional owners).                                                                                               |
+| `open`                                      | `boolean`                                      | `undefined`    | Controlled open state for the modal; update it from `onOpenChange`. Omit for uncontrolled mode.                                    |
+| `defaultOpen`                               | `boolean`                                      | `false`        | Initial open state when uncontrolled. Ignored when `open` is set.                                                                  |
+| `onOpenChange`                              | `(open: boolean) => void`                      | `undefined`    | Fires whenever the modal opens or closes (overlay click, Escape, close button, Cancel, save or delete).                            |
+| `labels`                                    | `BankAccountOnboardingWidgetLabels`            | English labels | Per-step and shell copy overrides, merged with the English defaults.                                                               |
+| `bankLogoSrc`                               | `string`                                       | `undefined`    | Bank logo URL for the result screen; falls back to the bank name as text.                                                          |
+| `disclosureLinks`                           | `DisclosureLinks`                              | `undefined`    | URLs for Terms of Use, Privacy Policy, Electronic Communication and Patriot Act on step 1. You resolve these; omit to leave unset. |
+| `isFullScreenInline`                        | `boolean`                                      | `false`        | Renders inline, filling its container, instead of in a modal. `open` / `defaultOpen` are ignored.                                  |
 
 ### MarketingWidget
 
-A self-contained marketing card and modal that presents host-supplied banking product copy (logo, captions, "How it works" steps, benefits, colors). The card renders two CTAs — Apply now and Learn more — and the modal's own CTA. The host wires all three to whatever should happen next — typically opening `BankAccountOnboardingWidget`.
-
-The widget renders nothing until widget init and the organization's `application-status` read resolve. It hides itself when the caller is already onboarded (`ACTIVE` / `INACTIVE`), invited (`INVITED`), or their organization's bank-account application is `COMPLETE`.
-
-Otherwise the card follows the organization's bank-account application:
-
-| Application status     | Started by the caller                      | Started by a colleague         |
-| ---------------------- | ------------------------------------------ | ------------------------------ |
-| none                   | Normal offer                               | Normal offer                   |
-| `DRAFT`                | Normal offer, CTA reads Resume application | Status chip + message, no CTAs |
-| `SUBMITTED`            | Status chip + message, no CTAs             | Status chip + message, no CTAs |
-| `DENIED`               | Status chip + message, no CTAs             | Status chip + message, no CTAs |
-| `DELETED` / `CANCELED` | Normal offer                               | Normal offer                   |
-| `COMPLETE`             | Hidden                                     | Hidden                         |
-
-Resume application calls the same `onPrimaryCtaClick`: `BankAccountOnboardingWidget` resumes the caller's own draft by itself. The bank's name in the messages comes from widget init (`bankName`). Tenant-specific assets and copy are always passed in as `content` — the published package does not look up white-label or bank maps.
+A marketing card and modal that presents your banking product copy (logo, captions, "How it works" steps, benefits, colors). Its Apply now and modal CTAs call `onPrimaryCtaClick`, which you typically wire to open `BankAccountOnboardingWidget`.
 
 #### Props
 
-| Prop                | Type                                       | Required | Description                                                                                                                                                     |
-| ------------------- | ------------------------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `content`           | `MarketingWidgetContent`                   | Yes      | Host-resolved card and modal copy, images, "How it works" steps, benefits, and appearance.                                                                      |
-| `onPrimaryCtaClick` | `() => void`                               | Yes      | Called when the applicant clicks Apply now on the card or the modal CTA (default label: Start application). Closes the modal first.                             |
-| `labels`            | `PartialDeep<MarketingWidgetLabels>`       | No       | Override Apply now, Learn more, the modal CTA + subtext, and the modal dismiss `aria-label`.                                                                    |
-| `statusLabels`      | `PartialDeep<MarketingWidgetStatusLabels>` | No       | Override the Resume application label and the chip, heading and body copy of each application-status message. Heading and body are functions of `{ bankName }`. |
+| Prop                | Type                                       | Default        | Description                                                                                                                         |
+| ------------------- | ------------------------------------------ | -------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `content`           | `MarketingWidgetContent`                   | **Required**   | Host-resolved card and modal copy, images, "How it works" steps, benefits, and appearance.                                          |
+| `onPrimaryCtaClick` | `() => void`                               | **Required**   | Called when the applicant clicks Apply now on the card or the modal CTA (default label: Start application). Closes the modal first. |
+| `labels`            | `PartialDeep<MarketingWidgetLabels>`       | English labels | Override the card and modal copy. See the exported `MarketingWidgetLabels` type for every key.                                      |
+| `statusLabels`      | `PartialDeep<MarketingWidgetStatusLabels>` | English labels | Override the Resume application label and each status message. Heading and body are functions of `{ bankName }`.                    |
 
 ### ProductsWidget
 
-A self-contained widget for managing an organization's products and services: it lists them in a filterable, sortable, cursor-paginated table and handles creating, editing, viewing, and deleting them — including full measure-unit management. The host only supplies auth credentials and optional label overrides.
+Manages an organization's products and services: a filterable, sortable table with create, edit, view and delete flows, plus measure-unit management.
 
 #### Props
 
-| Prop                      | Type                                     | Description                                          |
-| ------------------------- | ---------------------------------------- | ---------------------------------------------------- |
-| `pageSizeOptions`         | `number[]`                               | Rows-per-page choices (default `[10, 25, 50, 100]`). |
-| `screenLabels`            | `Partial<ProductsScreenLabels>`          | Table/header/filter/empty/error copy.                |
-| `formLabels`              | `Partial<ProductFormSheetLabels>`        | Create/edit form copy.                               |
-| `detailsLabels`           | `Partial<ProductDetailsSheetLabels>`     | Details sheet copy.                                  |
-| `deleteLabels`            | `Partial<ProductDeleteDialogLabels>`     | Product delete confirmation copy.                    |
-| `measureUnitsLabels`      | `Partial<MeasureUnitsManagerLabels>`     | Measure-units manager copy.                          |
-| `measureUnitDeleteLabels` | `Partial<MeasureUnitDeleteDialogLabels>` | Measure-unit delete confirmation copy.               |
-| `messageLabels`           | `Partial<ProductMessageLabels>`          | Validation / error messages produced by the widget.  |
+| Prop                      | Type                                     | Default             | Description                                         |
+| ------------------------- | ---------------------------------------- | ------------------- | --------------------------------------------------- |
+| `pageSizeOptions`         | `number[]`                               | `[10, 25, 50, 100]` | Rows-per-page choices.                              |
+| `screenLabels`            | `Partial<ProductsScreenLabels>`          | English labels      | Table/header/filter/empty/error copy.               |
+| `formLabels`              | `Partial<ProductFormSheetLabels>`        | English labels      | Create/edit form copy.                              |
+| `detailsLabels`           | `Partial<ProductDetailsSheetLabels>`     | English labels      | Details sheet copy.                                 |
+| `deleteLabels`            | `Partial<ProductDeleteDialogLabels>`     | English labels      | Product delete confirmation copy.                   |
+| `measureUnitsLabels`      | `Partial<MeasureUnitsManagerLabels>`     | English labels      | Measure-units manager copy.                         |
+| `measureUnitDeleteLabels` | `Partial<MeasureUnitDeleteDialogLabels>` | English labels      | Measure-unit delete confirmation copy.              |
+| `messageLabels`           | `Partial<ProductMessageLabels>`          | English labels      | Validation / error messages produced by the widget. |
 
 ### ReceivablesWidget
 
-A self-contained native widget for listing, creating, editing, and acting on customer receivables.
+Lists, creates, edits and acts on an organization's invoices, quotes and credit notes, including sending by email and recording payments. It's the in-progress native replacement for `InvoicingWidget`.
 
 #### Props
 
-| Prop                      | Type                                                 | Default                                  | Description                                                                                                     |
-| ------------------------- | ---------------------------------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| `defaultTab`              | `ReceivablesWidgetTab`                               | `'invoices'`                             | Initial tab when that tab is enabled. If it is omitted or disabled, the widget starts on the first enabled tab. |
-| `enabledTabs`             | `ReceivablesWidgetTab[]`                             | `['invoices', 'quotes', 'credit_notes']` | Tabs visible to the user. Duplicate or unknown values are ignored.                                              |
-| `pageSizeOptions`         | `number[]`                                           | `[10, 25, 50, 100]`                      | Rows-per-page choices shown by the table. The first page loads with a page size of `10`.                        |
-| `onReceivableCreated`     | `(id: string, type: ReceivableDocumentType) => void` | `undefined`                              | Called after create or clone succeeds. The widget switches to the new document's tab and opens its details.     |
-| `onReceivableOpened`      | `(id: string, type: ReceivableDocumentType) => void` | `undefined`                              | Called when the user opens a row's detail sheet.                                                                |
-| `onTemplateSettingsClick` | `() => void`                                         | `undefined`                              | Shows a template settings action in the header and calls this handler when selected.                            |
-
-| Prop                       | Type                                     | Default          | Description                                                                                                                                                                                                            |
-| -------------------------- | ---------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `embeddedBankName`         | `string`                                 | `undefined`      | Display name of the sponsor bank powering embedded bank accounts (e.g. `"Zenith Bank"`). Shown next to embedded accounts in the invoice payment-account picker as "Powered by {embeddedBankName}"; omitted when unset. |
-| `screenLabels`             | `Partial<ReceivablesScreenLabels>`       | English defaults | Overrides table, tab, filter, empty, error, action, and status badge copy.                                                                                                                                             |
-| `formLabels`               | `Partial<ReceivableFormSheetLabels>`     | English defaults | Overrides create/edit form labels and button copy.                                                                                                                                                                     |
-| `detailsLabels`            | `Partial<ReceivableDetailsSheetLabels>`  | English defaults | Overrides detail sheet headings, actions, empty copy, and status badge copy.                                                                                                                                           |
-| `sendLabels`               | `Partial<ReceivableSendDialogLabels>`    | English defaults | Overrides send-email dialog labels and buttons.                                                                                                                                                                        |
-| `paymentLabels`            | `Partial<ReceivablePaymentDialogLabels>` | English defaults | Overrides manual payment dialog labels and buttons.                                                                                                                                                                    |
-| `actionLabels`             | `Partial<ReceivableActionDialogLabels>`  | English defaults | Overrides generic confirmation dialog buttons. Action-specific title and body copy come from `messageLabels`.                                                                                                          |
-| `counterpartFormLabels`    | `Partial<CounterpartFormSheetLabels>`    | English defaults | Overrides inline customer creation copy from the shared counterpart-management flow.                                                                                                                                   |
-| `measureUnitsLabels`       | `Partial<MeasureUnitsManagerLabels>`     | English defaults | Overrides copy of the measure-unit manager opened from a line item's unit select.                                                                                                                                      |
-| `measureUnitDeleteLabels`  | `Partial<MeasureUnitDeleteDialogLabels>` | English defaults | Overrides measure-unit delete confirmation copy.                                                                                                                                                                       |
-| `messageLabels`            | `Partial<ReceivableMessageLabels>`       | English defaults | Overrides validation, fallback, summary, activity, reminder, and action-confirmation messages generated by the feature layer, including the subject and body saved on a reminder created from the form.                |
-| `productMessageLabels`     | `Partial<ProductMessageLabels>`          | English defaults | Overrides product flow validation and error messages.                                                                                                                                                                  |
-| `counterpartMessageLabels` | `Partial<CounterpartMessageLabels>`      | English defaults | Overrides customer flow validation and error messages.                                                                                                                                                                 |
+| Prop                       | Type                                                 | Default                                  | Description                                                                                                                                                     |
+| -------------------------- | ---------------------------------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `defaultTab`               | `ReceivablesWidgetTab`                               | `'invoices'`                             | Initial tab; if omitted or disabled, the widget starts on the first enabled tab.                                                                                |
+| `enabledTabs`              | `ReceivablesWidgetTab[]`                             | `['invoices', 'quotes', 'credit_notes']` | Tabs visible to the user. Duplicate or unknown values are ignored.                                                                                              |
+| `pageSizeOptions`          | `number[]`                                           | `[10, 25, 50, 100]`                      | Rows-per-page choices. The first page loads with a page size of `10`.                                                                                           |
+| `onReceivableCreated`      | `(id: string, type: ReceivableDocumentType) => void` | `undefined`                              | Called after a create or clone succeeds.                                                                                                                        |
+| `onReceivableOpened`       | `(id: string, type: ReceivableDocumentType) => void` | `undefined`                              | Called when the user opens a row's detail sheet.                                                                                                                |
+| `onTemplateSettingsClick`  | `() => void`                                         | `undefined`                              | Shows a template settings action in the header and calls this handler when clicked.                                                                             |
+| `embeddedBankName`         | `string`                                             | `undefined`                              | Sponsor bank name shown as "Powered by {embeddedBankName}" next to embedded accounts in the invoice payment-account picker. Omitted when unset.                 |
+| `screenLabels`             | `ReceivablesScreenLabelOverrides`                    | English labels                           | Table, tab, filter, empty, error, action and status badge copy.                                                                                                 |
+| `formLabels`               | `Partial<ReceivableFormSheetLabels>`                 | English labels                           | Create/edit form copy; the save and issue buttons are in `messageLabels`.                                                                                       |
+| `detailsLabels`            | `ReceivableDetailsSheetLabelOverrides`               | English labels                           | Detail sheet copy, including status badges.                                                                                                                     |
+| `sendLabels`               | `Partial<ReceivableSendDialogLabels>`                | English labels                           | Send-email dialog copy.                                                                                                                                         |
+| `paymentLabels`            | `Partial<ReceivablePaymentDialogLabels>`             | English labels                           | Manual payment dialog copy.                                                                                                                                     |
+| `actionLabels`             | `Partial<ReceivableActionDialogLabels>`              | English labels                           | Confirmation dialog buttons; per-action titles come from `messageLabels`.                                                                                       |
+| `counterpartFormLabels`    | `PartialDeep<CounterpartFormSheetLabels>`            | English labels                           | Inline customer creation copy.                                                                                                                                  |
+| `measureUnitsLabels`       | `Partial<MeasureUnitsManagerLabels>`                 | English labels                           | Measure-unit manager copy.                                                                                                                                      |
+| `measureUnitDeleteLabels`  | `Partial<MeasureUnitDeleteDialogLabels>`             | English labels                           | Measure-unit delete confirmation copy.                                                                                                                          |
+| `messageLabels`            | `Partial<ReceivableMessageLabels>`                   | English labels                           | Validation, fallback, summary, activity, reminder and confirmation messages, including the form's save and issue buttons and a new reminder's subject and body. |
+| `productMessageLabels`     | `Partial<ProductMessageLabels>`                      | English labels                           | Product validation and error messages.                                                                                                                          |
+| `counterpartMessageLabels` | `Partial<CounterpartMessageLabels>`                  | English labels                           | Customer validation and error messages.                                                                                                                         |
 
 ### SettingsWidget
 
-A composite settings widget that combines profile, team, invoice, bill-pay, expense, accounting, legal and help settings in one navigable surface.
+A single navigable settings surface combining profile, team, invoice, bill-pay, expense, accounting, legal and help sections.
 
 #### Props
 
-| Prop                      | Type                                         | Default                           | Description                                                                                                                                                                                                                                                                                                                            |
-| ------------------------- | -------------------------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `acceptInviteRedirectUri` | `string`                                     | Same-origin `/accept-invite`      | Forwarded to the Team section's widget — allowlisted URL invite emails link to. Defaults to `${window.location.origin}/accept-invite`; set it when the host app's registered landing route differs from the widget's same-origin default, or the origin is not on the OIDC redirect-URI allowlist (preview/localhost).                 |
-| `labels`                  | `Partial<Labels>`                            | English labels                    | Overrides the settings heading copy.                                                                                                                                                                                                                                                                                                   |
-| `featureLabels`           | `Partial<FeatureLabels>`                     | English labels                    | Overrides section labels.                                                                                                                                                                                                                                                                                                              |
-| `profileContent`          | `ReactNode`                                  | Profile widget                    | Replaces the profile section content.                                                                                                                                                                                                                                                                                                  |
-| `teamContent`             | `ReactNode`                                  | Empty                             | Supplies the team section content.                                                                                                                                                                                                                                                                                                     |
-| `invoiceContent`          | `ReactNode`                                  | Invoice settings widget           | Replaces invoice settings content.                                                                                                                                                                                                                                                                                                     |
-| `billPayContent`          | `ReactNode`                                  | Approval policies settings        | Replaces bill-pay settings content.                                                                                                                                                                                                                                                                                                    |
-| `accountingContent`       | `ReactNode`                                  | Chart of accounts widget          | Replaces accounting content.                                                                                                                                                                                                                                                                                                           |
-| `expenseContent`          | `ReactNode`                                  | Expense policies and requirements | Replaces expense content.                                                                                                                                                                                                                                                                                                              |
-| `legalContent`            | `ReactNode`                                  | Bank disclosures widget           | Replaces the Legal section content.                                                                                                                                                                                                                                                                                                    |
-| `profileContactUrl`       | `string`                                     | `undefined`                       | Forwarded to the Profile section's widget — where its "to change this information, contact your bank" line links. Left unset, the card shows the plain unlinked sentence instead; the bank name comes from widget init.                                                                                                                |
-| `selectedSection`         | `SettingsWidgetSectionId`                    | `undefined`                       | The section to show. Leave unset to let the widget own the selection; supply it (with `onSelectedSectionChange`) to drive navigation from a route or search param. A section the user's scopes hide falls back to the first visible one.                                                                                               |
-| `defaultSelectedSection`  | `SettingsWidgetSectionId`                    | First visible section             | The section to open on, for a host that wants a deep link without owning the selection. Read once per mount and ignored when `selectedSection` is supplied. Scopes arrive with widget init, so a section this names opens as soon as it becomes visible; one the user's scopes never grant leaves the first visible section on screen. |
-| `onSelectedSectionChange` | `(section: SettingsWidgetSectionId) => void` | `undefined`                       | Called with the id of the section the user selected. Fires whether or not `selectedSection` is supplied, so a host can mirror the selection into its URL without taking ownership of it.                                                                                                                                               |
-| `additionalSections`      | `SettingsWidgetAdditionalSection[]`          | `undefined`                       | Host-owned sections rendered alongside the built-in ones. Each is `{ id, label, content }` plus an optional `after` naming the built-in section to place it behind. Unlike the built-ins, these are not scope-gated.                                                                                                                   |
-| `helpContactUrl`          | `string`                                     | `undefined`                       | Forwarded to the Help section's widget — where its "Contact Us" line links (a support page URL or a `mailto:`). The line is hidden while unset, since the package has no tenant-agnostic support address to fall back on; the bank name in that line comes from widget init.                                                           |
-| `helpFaq`                 | `HelpFaqSection[]`                           | `HELP_FAQ_EN`                     | Forwarded to the Help section: the FAQ it renders. Extend the exported `HELP_FAQ_EN` and pass the result to answer questions the package cannot (passwords, for example) without replacing the whole section.                                                                                                                          |
-| `helpContent`             | `ReactNode`                                  | Help widget                       | Replaces the help section content.                                                                                                                                                                                                                                                                                                     |
-| `finopsThemeColors`       | `FinopsThemeColors`                          | `undefined`                       | Optional Monite theme color overrides. Nothing under this widget renders Monite any more, so it currently changes nothing here; it is still accepted rather than removed in the same release as the section it themed.                                                                                                                 |
+| Prop                      | Type                                         | Default                           | Description                                                                                                  |
+| ------------------------- | -------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `acceptInviteRedirectUri` | `string`                                     | Same-origin `/accept-invite`      | Where Team invite emails link to; set it when your landing route differs or the origin isn't allowlisted.    |
+| `labels`                  | `Partial<Labels>`                            | English labels                    | Overrides the settings heading copy.                                                                         |
+| `featureLabels`           | `Partial<FeatureLabels>`                     | English labels                    | Overrides section labels.                                                                                    |
+| `profileContent`          | `ReactNode`                                  | Profile widget                    | Replaces the profile section content.                                                                        |
+| `teamContent`             | `ReactNode`                                  | Team widget                       | Replaces the team section content.                                                                           |
+| `invoiceContent`          | `ReactNode`                                  | Invoice settings widget           | Replaces invoice settings content.                                                                           |
+| `billPayContent`          | `ReactNode`                                  | Approval policies settings        | Replaces bill-pay settings content.                                                                          |
+| `accountingContent`       | `ReactNode`                                  | Chart of accounts widget          | Replaces accounting content.                                                                                 |
+| `expenseContent`          | `ReactNode`                                  | Expense policies and requirements | Replaces expense content.                                                                                    |
+| `legalContent`            | `ReactNode`                                  | Bank disclosures widget           | Replaces the Legal section content.                                                                          |
+| `profileContactUrl`       | `string`                                     | `undefined`                       | Link for the Profile section's "contact your bank" line; unlinked when unset.                                |
+| `selectedSection`         | `SettingsWidgetSectionId`                    | `undefined`                       | The section to show (controlled). Pair with `onSelectedSectionChange`; leave unset to let the widget own it. |
+| `defaultSelectedSection`  | `SettingsWidgetSectionId`                    | First visible section             | The section to open on; read once per mount and ignored when `selectedSection` is set.                       |
+| `onSelectedSectionChange` | `(section: SettingsWidgetSectionId) => void` | `undefined`                       | Called with the section the user selected, whether or not `selectedSection` is supplied.                     |
+| `additionalSections`      | `SettingsWidgetAdditionalSection[]`          | `undefined`                       | Host-owned `{ id, label, content, after? }` sections; `after` names the built-in section to place it behind. |
+| `helpContactUrl`          | `string`                                     | `undefined`                       | Link (URL or `mailto:`) for the Help section's "Contact Us" line; hidden when unset.                         |
+| `helpFaq`                 | `HelpFaqSection[]`                           | `HELP_FAQ_EN`                     | FAQ shown in the Help section. Extend the exported `HELP_FAQ_EN` to add your own questions.                  |
+| `helpContent`             | `ReactNode`                                  | Help widget                       | Replaces the help section content.                                                                           |
+| `finopsThemeColors`       | `FinopsThemeColors`                          | `undefined`                       | Legacy theme overrides; currently has no effect.                                                             |
 
 ### TransfersWidget
 
-A self-contained banking widget for creating book or ACH transfers and reviewing recent movement across embedded accounts.
+Lists recent transfers across the organization's embedded bank accounts and lets the user send a book or ACH transfer.
 
 #### Props
 
-| Prop                         | Type                                    | Default          | Description                                                                                                                                                                        |
-| ---------------------------- | --------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `labels`                     | `Partial<TransfersWidgetLabels>`        | English labels   | Override shell and modal copy.                                                                                                                                                     |
-| `featureLabels`              | `Partial<TransfersWidgetFeatureLabels>` | English defaults | Override routing copy, fallbacks, default currency, and ACH SEC code.                                                                                                              |
-| `isTransferMoneyOpen`        | `boolean`                               | Uncontrolled     | Whether the transfer money modal is showing. Supplying it makes the modal controlled: the widget reports every open and close and changes nothing until you re-supply a new value. |
-| `defaultIsTransferMoneyOpen` | `boolean`                               | `false`          | The modal's state on first render, for a host that only wants to seed it. Ignored when `isTransferMoneyOpen` is supplied.                                                          |
-| `onTransferMoneyOpenChange`  | `(open: boolean) => void`               | `undefined`      | Called on every open and close — the **Transfer money** CTA, the modal's own dismissals (Esc, overlay, close), and the close after a completed transfer.                           |
+| Prop                         | Type                                    | Default          | Description                                                                                             |
+| ---------------------------- | --------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------- |
+| `labels`                     | `Partial<TransfersWidgetLabels>`        | English labels   | Override list and modal copy.                                                                           |
+| `featureLabels`              | `Partial<TransfersWidgetFeatureLabels>` | English defaults | Override route separator, fallback text, default currency and ACH SEC code.                             |
+| `isTransferMoneyOpen`        | `boolean`                               | Uncontrolled     | Controls the transfer modal. When set, the widget only reports open/close requests and waits for you.   |
+| `defaultIsTransferMoneyOpen` | `boolean`                               | `false`          | Initial modal state when uncontrolled. Ignored when `isTransferMoneyOpen` is set.                       |
+| `onTransferMoneyOpenChange`  | `(open: boolean) => void`               | `undefined`      | Called on every open and close: the button, the modal's own dismissals, and the close after a transfer. |
 
 <!-- END GENERATED REFERENCE -->
 
 ## UI frameworks (shadcn default, Tecton optional)
 
-Widgets render with the default shadcn/native surface out of the box — no extra
-install, no configuration. An alternate UI framework (Tecton, built on the Q2 /
-Stencil design system) is shipped as a **separate, opt-in package** so the core
-package never carries Stencil or its build-time/runtime weight:
+Widgets render with the default shadcn surface and need no configuration. Tecton
+(the Q2 / Stencil design system) ships as a separate, opt-in package:
 
 ```bash
 npm i @tesouro/embedded-components-react-tecton-ui
@@ -642,38 +580,22 @@ npm i @tesouro/embedded-components-react-tecton-ui
 
 ```ts
 import { registerTectonUI } from '@tesouro/embedded-components-react-tecton-ui';
-registerTectonUI(); // once, at app startup
+registerTectonUI();
 ```
 
-Then select it via the provider cascade (`uiFramework="tecton"`). Without the
-extension installed, `uiFramework="tecton"` degrades gracefully to shadcn. See
-the extension's README for setup, the migration guide, and the Turbopack /
-`@stencil/core` note that applies only when the Tecton extension is installed.
+Call `registerTectonUI()` once at app startup, then set `uiFramework="tecton"` on a provider. Without the extension installed it
+falls back to shadcn. See the extension's README for setup.
 
 ### TypeScript module resolution
 
-This package ships ESM with TypeScript declarations and is intended for
-**bundler-based** consumers — Vite, webpack, esbuild, Next.js — which is how
-React apps are built. Its types are exposed through the package `exports` map, so
-set TypeScript's `"moduleResolution"` to **`"bundler"`** (the modern default) and
-every entrypoint (`.`, `./core`, `./monite-sdk`, `./lib/*`, `./experimental`,
-`./experimental/*`) resolves cleanly.
-
-The published declarations are **self-contained**: the build bundles each
-entrypoint's `.d.ts` (`scripts/bundle-dts.mjs`) so it inlines the internal
-workspace types instead of re-exporting them from unpublished `@tesouro-fe/*`
-packages, and only genuine dependencies (react, MUI, …) remain as bare imports.
-An ESM consumer therefore type-checks cleanly under `"bundler"` **and**
-`"node16"` / `"nodenext"`, even with `skipLibCheck: false`.
-
-Legacy `"moduleResolution": "node"` (a.k.a. `node10` / classic) is **not
-supported**: it ignores the `exports` map, and this package carries no top-level
-`types` field, so the type checker reports `TS2307` for the package and its
-subpaths. Use `"bundler"` instead — every bundler-based toolchain supports it.
-As an ESM-only package it is not `require()`-able from CommonJS.
+Set `"moduleResolution"` to **`"bundler"`** (or `"node16"` / `"nodenext"`); every
+entry point then resolves, and the declarations type-check with
+`skipLibCheck: false`. Legacy `"node"` / `node10` resolution is **not supported**
+(it ignores the `exports` map and reports `TS2307`). The package is ESM-only and
+can't be `require()`d from CommonJS.
 
 ## Contributing
 
-Maintainer notes — the monorepo build/publishing model, the publish-verification
-gate, and how to run the unit tests — live in `CONTRIBUTING.md` in the source
-repository.
+Maintainer notes live in `CONTRIBUTING.md` in the source repository: the
+monorepo build and publishing model, the publish-verification gate, and how to
+run the unit tests.