themelia-react-ui 1.0.2 → 2.0.1

package/docs/consumer-skill/references/composition.md

@@ -35,7 +35,12 @@ a detail workspace or a form; they need different information hierarchies.
 
 For a DataTable composition, put queries in `topbarContent`, exports or collection
 tools in `topbarEnd`, selection commands in `bulkActions`, and record commands
-in `rowActions`. Other arrangements are valid when the product has a distinct
+in `rowActions`. `bulkActions` render in the shared `BatchActionBar`, docked to
+the viewport while rows are selected (`selectionToolbarPlacement="inline"` keeps
+it in flow); they need no disabled state for an empty selection. Any other list
+with a selection mounts `BatchActionBar` from
+`themelia-react-ui/base/batch-action-bar` rather than a hand-built selection
+toolbar. Other arrangements are valid when the product has a distinct
 query region; choose one owner deliberately and keep queries close to their
 results. DataView already owns coordinated filtering; do not add a second filter
 store around it without inspecting its contract.
@@ -54,11 +59,51 @@ accessibility needs and the task can justify richer rows. Explain the priority.
 Custom ResourceCell metadata is caller content; use shared supporting typography
 and CellStack where its smaller secondary-value contract fits.
 
-Commands need explicit importance as well as scope. PageActions does not infer
-primary tone from a label such as “New contact”; choose `tone="primary"` when
-that is the route's main command. Permissions and destructive intent remain
-application decisions. A back link, export and destructive command should not
-all inherit the same visual emphasis by accident.
+Commands need explicit importance as well as scope. Describe page commands by
+role in Page's header: `primaryAction` is the route's one main command, and
+`secondaryActions` lists supporting commands in priority order. The header owns
+their treatment and order: outline secondary buttons, the solid primary button,
+then a More actions menu for overflow, destructive commands and narrow screens,
+which always ends the row. WorkspaceRecordHeader, ResourceHeader, the resource
+shells and SettingsShell take the same props and render the same row. Choosing which
+command is primary, which are `destructive`, and which are `visible` remains an
+application decision; confirm destructive commands in their handler. Use
+`actions` only for non-command controls such as a period select. A back link,
+export and destructive command should not all inherit the same visual emphasis.
+
+```tsx
+<Page header={{
+  title: 'Contacts',
+  primaryAction: { label: 'New contact', icon: Plus, onClick: onCreate },
+  secondaryActions: [
+    { label: 'Export', onClick: onExport },
+    { label: 'Delete list', destructive: true, onClick: confirmDelete },
+  ],
+}}>{/* route content */}</Page>
+```
+
+A record split into sections adds `header.tabs`. The tabs sit under the header's
+copy and commands, a `badge` shows a count, tabs that do not fit move into a More
+menu, and `onValueChange` switches the section or routes. Labels name the
+command; an icon on every command repeats it, so keep `+` on an add command and
+leave the others plain.
+
+```tsx
+<Page header={{
+  title: member.name,
+  titleBadges: [{ label: 'Needs attention', tone: 'warning' }],
+  primaryAction: { label: 'Generate report', onClick: onReport },
+  secondaryActions: [
+    { label: 'Update profile', onClick: onEdit },
+    { label: 'Record membership decision', onClick: onDecision },
+  ],
+  tabs: { value: section, onValueChange: setSection, items: [
+    { id: 'documents', label: 'Documents', badge: documents.length },
+    { id: 'hours', label: 'CPD hours', badge: hours },
+    { id: 'privacy', label: 'Privacy' },
+  ] },
+}}>{/* active section */}</Page>
+```
 
 | Drift | Better decision |
 | --- | --- |
@@ -81,6 +126,20 @@ MetricGrid's default peers and UsageCard own their surfaces. A distinct custom
 Card subject remains valid; compare the complete subject contract before rebuilding
 formatting, hierarchy or request-state presentation from lower text primitives.
 
+For rows, grids, main/aside regions and matching peer gaps, use the
+[layout-owner map](#structure-and-spacing).
+
+### Headed blocks inside surfaces
+
+AddressCard, PaymentMethod, SeoListingCard and ProductVariantsManager accept
+Card's `surface`, `padding` and `headerDivider` props. Use `surface="card"` when
+that owner is the framed subject; it supplies the header and aligned body insets
+and inherits provider dividers. Do not add an untitled padded Card around it.
+Omit surface for an unframed embedded subject; its header rule defaults off.
+An explicit divider still wins. ProductVariantsManager also forwards
+`footerDivider` for its footer slot. Separate reusable body content can still be
+composed in a caller-owned Card; choose one owner for each headed boundary.
+
 ## Public websites and service overviews
 
 Compose a landing page or public website from its content. `Container` owns the
@@ -125,6 +184,13 @@ is appropriate only for inline content. The allowlist strips arbitrary styling,
 embedded media and unsafe links; it is not a Markdown parser or email-layout
 renderer. Keep outer width/padding on the surrounding structure. RichTextEditor
 owns editing; EmailComposer owns structured email/variable/delivery contracts.
+Images are opt-in on both: create one object with `useRichTextImages({ upload,
+renderImage })` from `features/rich-text-editor` and pass it as `images` to the
+editor and to RichText. Your `upload(file, { signal })` stores the file and
+resolves `{ src, alt?, width?, height? }`; the editor owns insertion, the upload
+placeholder, retry, alt text and the source policy (http, https, `blob:` and
+relative sources only), and `renderImage` draws read-only images with your
+component.
 Read the relevant declarations and [integration](integration.md) before choosing
 the content owner. Embedded React UI can opt out of reading rhythm through
 `not-typeset` or `data-not-typeset` on its subtree; those opt-outs do not bypass
@@ -149,9 +215,11 @@ Choose one ordinary Card surface through UIProvider's `card.defaultSurface` and
 let sibling subjects inherit it. Explicit per-card surfaces win: mixing `card`
 and `framed` intentionally changes their visible treatment. Header placement is
 independent: `inside` keeps the heading with the body; `frame` puts context and
-commands on the outer frame above the inset body. Use `icon={<Icon />}` for a
-routine heading glyph and plain `title`; embedding raw SVG in title JSX bypasses
-the owner's icon sizing. Custom titles remain appropriate for richer content.
+commands on the outer frame above the inset body. A Card title needs no icon;
+pass `icon={<Icon />}` only when the glyph carries meaning (state, a brand, a type
+users scan for), never as raw SVG in title JSX. Custom titles remain appropriate
+for richer content. Facts and rows follow the same rule: one glyph repeated on
+every MetadataList item or Item row is decoration, so leave `icon`/media empty.
 
 Card `gap` owns spacing between regions; `contentGap` owns direct body-child
 spacing; `textGap` owns title/supporting-copy rhythm. Region spacing defaults to
@@ -164,9 +232,14 @@ compact subject; it is not the default for forms, settings, metrics or resource
 pages. Component size and
 density do not choose Card padding. `lg` uses 1.8 times the inset (36px), while
 `none` removes it. All sizes follow the surface roots and space-scale.
-UIProvider can configure both
+Dividers are off by default and
+should stay off: separate a card's sections with `contentGap` or a Stack gap
+clearly larger than the row gap (`2xl` between sections). UIProvider can configure
 `card.defaultHeaderDivider` and `card.defaultFooterDivider`; explicit per-card
 booleans win. Header/footer-only cards still render one shared divider.
+Overlays are the exception: `ActionDialog`, `ActionDrawer` and `ConfirmDialog`
+draw one rule between header, body and footer (one rule when there is no body),
+owned by the overlay; do not add borders to their content.
 
 Use titleSuffix for status/count/version badges. Long titles/suffixes wrap through the shared owner; no literal spaces/local margins to manufacture gaps. headerAction/actions are trailing controls, headerStart pre-title context. footerSlot/footer definitions own card-level actions; footerDivider owns the rule and inset. Do not simulate a footer inside children. SmartCard and ContentBlock are deprecated migration names; use Card in new code.
 
@@ -174,17 +247,56 @@ Reusable blocks/features stay card-free unless their explicit purpose is a card.
 
 ## Structure and spacing
 
-Shells own gutters, surfaces own padding, sections own rhythm, Stack/Grid own sibling gaps, typography owns none. Prefer gap/padding/size props to local appearance overrides.
-
-Grid exposes viewport columns; AdaptiveGrid responds to parent width and a semantic minimum column size. GridCell spans belong to the nearest Grid. Keep narrow DOM order meaningful. Horizontal Stack wraps by default; disable it only when overflow is intentionally handled. Tailwind is appropriate for min-w-0, positioning, overflow and drawing geometry.
+Choose the smallest owner that describes the region. These layout blocks are
+published primitives and layouts, not the domain compositions under `blocks/*`.
 
-Independent surfaces need peer rhythm, usually `gap="xl"`; Stack's default
-`md` is general sibling spacing, not a card-grid prescription. Framed Card rings
-extend outside layout rectangles, so two rings can consume a small DOM gap.
-Inspect visible edge clearance in both axes rather than accepting token use alone.
-Copy gaps normal/dense are for supporting text, not spacing independent cards.
-
-MetadataList owns medium-weight labels and normal-weight routine values. Its
+| Responsibility | Exact family and owner | Contract to preserve |
+| --- | --- | --- |
+| Vertical siblings or an action row | `base/structure`: Stack | Vertical by default; `direction="horizontal"` creates a row and wraps by default. Default gap is `md` (8px). There is no separate Row export. |
+| Known responsive tracks | `base/structure`: Grid | Scalar columns are literal; use `columns={{base:1,lg:3}}` for breakpoints. Omitted columns use one, then two from md. Default gap is `xl` (16px). |
+| Track spans | `base/structure`: GridCell | Use `span={{base:1,lg:2}}` inside the nearest Grid; keep meaningful DOM order. |
+| Equal tiles that fit their parent | `base/structure`: AdaptiveGrid | Select `minColumnWidth`; tracks follow available width. Use Grid for prescribed breakpoints or TwoColumnLayout for a supporting rail. |
+| Centered measure and inline gutters | `layout/containers`: Container | Defaults to xl measure and md gutter. Owns no vertical inset, scrolling or surface chrome. |
+| A semantic content section | `layout/containers`: Section | Owns sibling rhythm, default `xl`; it adds no Card frame or page gutter. |
+| Main content with a supporting rail | `layout/containers`: TwoColumnLayout | Owns header/main/aside/footer order and `2xl` gaps (24px). Main/aside contents choose their own Stack gaps. Page rhythm (header to body, major Sections) uses `3xl` (32px). |
+| A bounded page scroll region | `layout/containers`: PageViewport | Owns scrolling and query containment, with no padding. AppLayout already supplies one. |
+| Route title, commands and page content | `layout/page`: Page | Owns measure, inline/block gutters and header/body rhythm. Use `narrow` for a focused resource. |
+| Application header/sidebar chrome | `layout/app-shell`: AppLayout | Select the shell variant, compose slots and router callbacks, and let its viewport contain Page. |
+| A framed subject | `base/cards`: Card | Owns surface padding, header/body/footer alignment and separators; layout blocks own the space between Cards. |
+
+See the typed [layout-block composition](../examples/layout-blocks.tsx) when composing these owners.
+
+Use these public structures for repeated passive composition rather than
+rebuilding the same flex/grid spacing on divs. Tailwind remains appropriate for
+positioning, overflow, chart/table geometry and custom intrinsic tracks. Structure
+preserves child identity; it does not inspect, clone, reorder or frame children.
+
+### Main and aside Card gaps
+
+Peer Cards in a Page/TwoColumnLayout workspace use `gap="2xl"` on both main and
+aside Stacks to match its 24px grid gap. Give a peer Grid the same gap when it
+belongs to that rhythm. A compact local card grid may deliberately keep Grid's
+16px default. Stack's 8px default is general sibling spacing, not an automatic
+Card rhythm; choose the role explicitly. Values above use shipped roots and
+scale through the existing space-scale contract.
+
+The [region recipe](../examples/layout-blocks.tsx) keeps both inner Stacks on that same peer gap.
+
+Use `textGap="normal"|"dense"` for title/description copy; keep action gaps,
+form groups, peer regions and surface insets independent. Do not use small copy
+gaps between independent Cards or shrink Card padding to match control density.
+Framed Card rings extend outside layout rectangles: inspect visible clearance
+in both axes as well as computed gaps.
+
+### Horizontal rows
+
+See the typed [layout-block composition](../examples/layout-blocks.tsx): Page
+supplies its boundary, TwoColumnLayout splits the regions, inner Stacks share
+peer rhythm, and a horizontal Stack wraps footer actions. The app supplies the
+subjects and commands. For viewport-responsive columns use Grid; for available
+parent width use AdaptiveGrid or `TwoColumnLayout adaptTo="container"`.
+
+MetadataList owns semibold labels and normal-weight routine values. Its
 compact density tightens gaps/rows without shrinking primary values. Plain values
 and typed descriptors retain the shared roles; React nodes, `display` and `render`
 preserve supplied typography. Keep custom formatted values consistent with value
@@ -213,12 +325,14 @@ PopoverContent defaults to display/default; Command defaults to compact. An expl
 
 At shipped roots, compact shell padding is 8px; row inline padding is 12px; default row block padding is 8px and minimum height 36px. Compact/comfortable rows use 6/10px block padding and 32/40px minimum heights. Content can grow when it wraps. These are token-derived measurements, not app constants. Flush compact header/footer shell padding matches the list (8px inline). Header text bodies without a leading control and footer captions add the row inset once, aligning text at 20px. Actions keep the 8px shell edge. Nested public slots do not repeat these insets.
 
-Input frames use the input semantic token; collection dividers use border/60; focus uses ring separately. Equal responsibilities share recipes, while different semantic roles retain their own treatment. CommandInput keeps its existing onValueChange search contract and native refs; use the actual public Input through its default composition rather than restyling an unframed native field.
+Input frames and outline buttons share the input semantic token; collection dividers use border/60; focus uses ring separately and draws one indicator everywhere (a full-strength edge inside a soft halo). Equal responsibilities share recipes, while different semantic roles retain their own treatment. CommandInput keeps its existing onValueChange search contract and native refs; use the actual public Input through its default composition rather than restyling an unframed native field.
 
 ActionMenu density="table" remains a legacy table/overflow adapter. AsyncPreview padding="lg" owns a compatibility content boundary. Neither expands the default/compact surface vocabulary.
 
 Button separates tone from buttonStyle (solid, outline, ghost). ActionButtons renders the same definitions as ActionMenu. Badge tones describe actual states, not a decorative palette.
 
+Overflow menus use ActionMenu's own trigger: the ⋯ glyph named "More actions", context="inline" (default) for the ghost square in rows, cards and footers, context="commands" for the outline square beside outline commands. Pass buttonProps.size only to match the controls beside it; otherwise it follows the provider scale. Place the menu after the row's primary command and keep destructive entries last. Do not pass a MoreVertical icon, buttonStyle, tone or size-action classes to restyle it.
+
 ## Migration
 
 Use exact themelia-react-ui paths. Presentation imports use blocks/<family>, replacing composed/<family>. Raw UI, Radix, cmdk and routers are not consumer foundations. Read installed types instead of assuming historical CSS-kit props.
@@ -350,9 +464,10 @@ TwoColumnLayout. A wide comparison/directory can deliberately use `maxWidth="ful
 Setting full on every route defeats the resource measure. Do not remove Page's
 gutters to make its title touch the sidebar; align the header and body through
 the same Page. Density, container measure and page inset are separate choices.
-The [detail recipe](../examples/detail.tsx) includes `AccountDetailPage`: a
-centered resource measure, route-level commands, native Card icon/frame anatomy
-and MetadataList facts, with no duplicated subject header or gutter.
+The [detail recipe](../examples/detail.tsx) includes `AccountDetailPage`: the
+default record measure, a status badge, route-level commands and section tabs in
+the header, and MetadataList facts in one framed Card, with no duplicated subject
+header or gutter.
 
 Compose HeaderUserMenu in topbar `slots.headerEnd` or a local toolbar, and
 SidebarNavigationUser in AppSidebar `slots.footer` when account access belongs

package/docs/consumer-skill/references/design-contract.md

@@ -31,9 +31,17 @@ than rebuilding its accessible interaction behavior.
 | Action geometry and centered text | Button/IconButton/Badge recipes | Supported size/tone/style/variant |
 | Row labels, icons and selection indicators | Item and collection recipes | Supported row content, descriptions and density |
 | Semantic surfaces and states | Central theme and family state recipes | Theme foreground/surface pairs and supported tone/state props |
+| Hover, selection, current, pressed and disabled states | Shared interaction recipes: rows and selection use `--accent`, toggles hover with `--muted`, tables use a quieter muted ladder, disabled content dims to 50% | Theme `--accent`, `--muted` and `--card`; supported `active`, `selected`, `pressed` and `disabled` props |
+| Status tints | One tint scale per tone (wash, tint, edge, halo, line), contrast-tested with its ink | `tone` on Badge, Alert, IconBadge, StackedAvatars and toned blocks; the theme's tone colours |
+| Neutral regions, chips and elevation | One neutral strength per role (quiet wash, header band, track, chip) and one theme shadow per role (resting, card, raised, lifted, modal) | Theme `--muted`, `--foreground` and the `--shadow-*` ladder; supported surface variants |
 | Corners and elevation | Shared radius and theme shadow ladder | Theme roots and supported surface variants |
 | Presence, dismissal and focus | Base UI plus library overlay/motion owners | Public open/state/dismissal callbacks and library overlays |
 
+Restyle states through the theme roles so every family moves together: a
+darker `--accent` changes every row hover and selection at once. Passing
+`bg-success/15` or `hover:bg-muted/40` to one library row creates a second scale
+that the contrast contract does not test.
+
 An inset has one owner. A searchable menu needs the search region's outer inset
 and the Input's inner text inset; it does not need a third padded wrapper. A
 card-free block can be framed by a Card at its composition boundary.
@@ -96,9 +104,10 @@ a divider, or recolor a divider to simulate focus. Theme status colors keep thei
 foreground pairs; a status tone is not a decorative brand palette.
 
 Native fields, field-shaped triggers and compound field frames share the same
-focus and invalid treatment. Invalid state marks the frame and error copy;
-editable values keep their normal semantic foreground. Compound fields show one
-outer ring. Use validation and disabled/loading props instead of supplying a
+focus and invalid treatment. Every focused element draws one indicator: a 1px
+`ring` edge inside a soft 3px halo. Invalid state marks the frame and error copy
+(and tints the halo while focused); editable values keep their normal semantic
+foreground. Compound fields show one outer focus frame. Use validation and disabled/loading props instead of supplying a
 second local state recipe. Selected rows retain the owning primitive's indicator;
 highlighted, selected and destructive states are distinct responsibilities.
 

package/docs/consumer-skill/references/discovery.md

@@ -80,6 +80,10 @@ kind, exact `matchedSymbols`, `relevantSymbols`, `nextReads` and up to three
 relevant guidance entries. Exact symbol queries keep that symbol; intent queries
 derive relevantSymbols from selected catalogue API sections and current public
 exports. An exact family import retains the complete public symbol vocabulary.
+Deprecated migration names such as `SmartCard` or `ContentBlockProps` never
+appear in intent recommendations. When a result touches one, its `deprecated`
+map names the replacement, for example `{ "SmartCard": "Use Card." }`; write
+new code with the replacement. The public index carries the same map per family.
 Exact guide aliases precede generic overlap, and unrelated family pages
 do not fill the result merely to reach three entries.
 

package/docs/consumer-skill/references/installation.md

@@ -47,7 +47,11 @@ if (fs.realpathSync(selectedSkill) !== fs.realpathSync(installedSkill)) {
   }
   compareAssets(installedSkill);
 }
-console.log(JSON.stringify({ package: manifest.name, version: manifest.version, root, skill: selectedSkill }, null, 2));
+// The app's project instructions block records the version it was pasted from.
+const instructions = ['AGENTS.md', 'CLAUDE.md'].find(file => fs.existsSync(file));
+const marker = instructions && fs.readFileSync(instructions, 'utf8').match(/<!-- themelia-react-ui:start (\S+) -->/);
+const agentsBlock = !marker ? 'missing' : marker[1] === manifest.version ? 'current' : `stale (${marker[1]})`;
+console.log(JSON.stringify({ package: manifest.name, version: manifest.version, root, skill: selectedSkill, agentsBlock }, null, 2));
 JS
 ```
 
@@ -64,6 +68,34 @@ files or publisher markers in the copy are not checked. Keep local product polic
 outside the package guidance. Recopy the complete folder after upgrades, and
 read declarations from the installed package.
 
+`agentsBlock` reports whether the app's `AGENTS.md` (or `CLAUDE.md`) carries the
+[project instructions block](agents-md.md) for the installed version: `missing`,
+`current` or `stale` with the version it was pasted from. Paste or replace the
+whole block between its markers; it is how agents that never open a skill still
+find this one and its done condition.
+
+## Upgrading to the neutral button default
+
+An untoned `Button` is now the neutral outline (`tone="secondary"`,
+`buttonStyle="outline"`); a Button with a `tone` and no `buttonStyle` stays
+solid. Screens that relied on untoned Buttons being the solid primary can keep
+their look with the bundled codemod. It reports by default and edits only with
+`--write`; review the diff before committing:
+
+```sh
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/pin-button-defaults.mjs src
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/pin-button-defaults.mjs --write src
+```
+
+It adds `tone="primary"` to every Button, BaseButton or BaseButtonLink imported
+from the package without a `tone`. Add `--solid-only` to skip untoned outline
+and ghost Buttons so they turn neutral instead of keeping the brand color.
+Buttons whose props come from a spread are listed as `unresolved` for review.
+Apps that already set `UIProvider` `button.defaultTone` keep that tone and do not
+need the codemod; `button: { defaultTone: 'primary', defaultButtonStyle: 'solid' }`
+restores the previous default app-wide. Afterwards, demote extra primaries so
+each page or surface keeps one.
+
 ## Manual skill copying
 
 1. Choose an agent skill destination in the user's configured skills directory,

package/docs/consumer-skill/references/integration.md

@@ -50,7 +50,38 @@ does not replace the single mount-time UIProvider configuration boundary.
 
 Routing comes through href, callbacks or Base UI render composition. React Router is not required. Component chunks preserve client boundaries; pure utilities remain separate.
 
-Use ActionDialog, ActionDrawer, ConfirmDialog and useOverlayVisibility from features/overlays. Pass overlayProps for visibility. onAsyncConfirm awaits the operation; onError reports failure. Do not also pass onConfirm, which takes precedence. Sheet is structural infrastructure, not another workflow API.
+## Dialogs, confirmations and drawers
+
+Every dialog-like surface comes from `themelia-react-ui/features/overlays`; it is
+the only modal system. The overlay owners hold focus entry and trapping, Escape
+and outside-click dismissal, focus return to the trigger, pending and error
+states, portal theming and the shared scrim (a plain tint, never a blur).
+
+| Need | Owner |
+| --- | --- |
+| A focused edit or form with confirm/cancel | `ActionDialog` |
+| A yes/no question, or a destructive confirmation | `ConfirmDialog` (destructive tone for irreversible actions) |
+| A longer form, filters or record details beside the page | `ActionDrawer` |
+| Open state, triggers and several overlays on one screen | `useOverlayVisibility` (`overlayProps`, `show`, `hide`) |
+
+Pass `overlayProps` for visibility. `onAsyncConfirm` awaits the operation and
+keeps the overlay open on failure; `onError` reports it. Do not also pass
+`onConfirm`, which takes precedence. Each overlay owns one primary command, its
+confirm button; compose the body with the ordinary Stack, FormField and Card
+anatomy and leave its insets to the overlay.
+
+Do not hand-roll a modal (a `fixed inset-0` scrim, `role="dialog"`,
+`aria-modal`), do not import the lower-level `Dialog`, `AlertDialog` or `Sheet`
+building blocks, and do not add another modal library (Radix Dialog,
+react-modal, vaul, Headless UI or React Aria dialogs). The optional checker
+warns on each of these. Popovers, menus, selects and tooltips are anchored
+surfaces, not dialogs: use their own owners.
+
+To show a table full screen, use `DataTable`'s own mode (`fullscreen` or
+`defaultFullscreen`, `onFullscreenChange`, `showFullscreenToggle`) instead of
+moving the table into a dialog. It maximises the table in place, so scroll
+position, focus and column state survive; Escape leaves, Tab stays inside and
+focus returns to the toggle.
 
 PlaceAutocomplete from themelia-react-ui/features/map uses Photon by default. Supply a stable or useCallback-memoized searchPlaces: PlaceSearchCallback to use your geocoder; it receives PlaceSearchOptions and an AbortSignal and returns Promise<PlaceFeature[]>. Adapt provider results to the existing place shape and OSM identifiers (duplicates are removed by osm_id). Changing provider identity or search options cancels the old lookup and searches the current query. Respect the signal; superseded responses are ignored even if a provider cannot cancel. Keep provider identity stable during ordinary renders. Notification callbacks may be inline. onSearchError reports current failures; the built-in Retry action repeats the lookup and strings.retry localizes its label.