@opengeni/react 2.5.0-canary.2 → 3.0.1-canary.38817070914001

package/README.md

@@ -1,6 +1,6 @@
 # @opengeni/react
 
-React hooks and styled components for OpenGeni, built on
+React hooks and styled components for Opengeni, built on
 [`@opengeni/sdk`](../sdk): live session streaming, a chat composer, a message
 timeline that renders streaming deltas / tool calls / spawned-worker status,
 session status badges, and fleet tiles for workspace overviews. Two opt-in
@@ -19,11 +19,308 @@ island for back-compat, deprecated per #144.)
 
 Design-system-first: every visual decision routes through CSS-variable tokens
 (`styles/tokens.css`) — color, typography, radius, shadow, motion. Dark mode is
-the first-class default; light is an opt-in via `data-og-theme="light"` on any
-ancestor. Components are styled with Tailwind v4 utilities mapped onto the
+the first-class token default; light is an opt-in via `data-og-theme="light"` on
+any ancestor. The embedded chat roots (`OpenGeniChat`, `SessionConversation`)
+resolve light or dark from the host page instead; see
+[Conversation UI](#conversation-ui). Components are styled with Tailwind v4 utilities mapped onto the
 tokens, Radix primitives for behavior, and Motion for state-communicating
 animation. Override the tokens to rebrand everything.
 
+## Embedded connections and Sites
+
+For a child chat's capability selection, `prepareSessionCapabilityAccess` reads
+an ancestor-to-child access plan without writing. Show the parent chats whose
+`request` is non-null and obtain an explicit confirmation before calling
+`applySessionCapabilityAccess`. The plan preserves existing choices, applies
+version-fenced updates root first, and grants no authority: each ordinary API
+request still authorizes its caller. Invalidate the review on actor/workspace
+changes. A partial failure may leave approved parent changes saved; prepare a
+new plan for retry instead of rolling them back. Existing
+`attachSessionCapability` remains a single-chat operation and never changes
+parents implicitly.
+
+Optional `@opengeni/react/connect` exports `useConnect`, `ConnectChooser`,
+`ConnectSetup`, `ConnectAccounts`, and the composed `ConnectPanel`. Inject one
+`@opengeni/connect` controller per authenticated actor/workspace and dispose it
+when that scope changes. The controller uses your authenticated backend proxy;
+never place an organization key in browser props. Import
+`@opengeni/react/connect.css` for opt-in, scoped styles without Tailwind.
+`DeviceAuthorization` also accepts an optional `render` callback for host presentation;
+it receives shared copy state, the copy action, and the validated verification URL.
+Omitting it preserves the default embedded presentation.
+
+`CapabilityCatalogRow` gives connections, skills, and plugins one consistent
+icon/name/description button with a decorative plus/check and visible exception
+states. Supply `onOpen` and an explicit `status`; the host owns setup and
+installation. `ConnectionCatalog` accepts the same states through each option's
+`state`. Older callers that omit `state` keep their visible status labels, so
+provider warnings are not hidden during migration.
+
+`PluginDiscovery` accepts `defaultProvider="openai"` or `"anthropic"` to choose
+the initial registry. Omitting it starts with All. Users can still switch among
+All, OpenAI, and Anthropic; changing the search preserves their selection. The
+Opengeni Plugins page starts with OpenAI.
+
+```tsx
+import { ConnectPanel } from "@opengeni/react/connect";
+import "@opengeni/react/connect.css";
+
+<ConnectPanel
+  controller={controller}
+  returnUrl={hostSelectedReturnUrl}
+  onAuthorize={hostAuthorizeFromClick}
+/>;
+```
+
+The host owns synchronous popup/full-redirect navigation and pending-attempt
+recovery. Backend state, not a popup message or URL query, proves completion.
+Operation installation uses explicit selection; OAuth success alone is not
+installation. Account disconnect requires an observed version and confirmation,
+revokes local Opengeni access only, and never silently retries an unknown outcome.
+Provider readiness is deployment-dependent; use the server catalog rather than
+assuming every OAuth application or operator-managed provider is configured.
+
+Optional `@opengeni/react/sites` exports `SiteList`, `SiteDetail`, and `SiteClient`.
+Pass the public SDK client through your host proxy. `onOpen` owns list
+navigation. Authoring buttons and prompts belong to the host and use the ordinary
+session SDK; they are not part of the Site component API. `SiteDetail` reuses `PublishedHtmlArtifactFrame`, accepts
+an optional authenticated/filtered tool bridge, and removes the frame after
+read-authority refresh failure. Loaded Sites revalidate every 15 seconds;
+downloaded HTML cannot be recalled and every tool call still needs live authority.
+
+`canPublish` is only a presentation hint. Version-checked rollback/archive/restore
+remain subject to backend `artifacts:publish` permission. Sites stay workspace
+shared, even if a source session is private. See
+[`examples/embedded-product`](../../examples/embedded-product/README.md) for the
+runnable loopback host reference. Native route reuse and full visual acceptance
+are not implied by these optional package surfaces.
+## Conversation UI
+
+For an account-aware header, `useLastStartedTurnPolicy(sessionId, { events,
+includeServingModel: true })` overlays the latest lease-backed serving receipt
+only when it belongs to the last started turn. This requires the optional
+`getSessionModelAccount` client method. Without the option, the hook continues
+to return the accepted turn policy. Neither mode changes the composer's
+preferred model. `useSessionModelAccount` reads authorized accounts and choices;
+pass `provider` so Automatic resets only that provider's choice. Its optional
+`choice.serving` is the last committed placement, not a queued next-turn choice.
+The timeline renders neutral account-switch events without exposing account
+identity or duplicating provider compatibility events.
+
+`OpenGeniChat` and `SessionConversation` are the default product integration.
+Back them with `createSessionProxyHandler` from `@opengeni/sdk`, mounted on your
+server, and pass its mount as `baseUrl`. No provider, client, or workspace id
+is needed: the component creates the browser client and uses the workspace the
+proxy resolved for the signed-in user (from the proxy's client config).
+
+```tsx
+import "@opengeni/react/compiled.css";
+
+<OpenGeniChat baseUrl="/api/opengeni" />;
+// or one conversation: <SessionConversation baseUrl="/api/opengeni" sessionId={sessionId} />
+```
+
+Bearer-token apps pass `headers` (a function runs per request) or a custom
+`fetch`; a `client` passed with `baseUrl` replaces the one the component
+creates:
+
+```tsx
+<OpenGeniChat baseUrl="/api/opengeni" headers={() => ({ Authorization: `Bearer ${getToken()}` })} />
+```
+
+The provider form keeps working, for example for several components sharing one
+client or the headless hooks:
+
+```tsx
+<OpenGeniProvider client={new OpenGeniClient({ baseUrl: "/api/opengeni" })} workspaceId={workspaceId}>
+  <SessionConversation sessionId={sessionId} />
+</OpenGeniProvider>
+```
+
+Compose `MessageTimeline` and `ChatComposer` with the session hooks only when
+the product needs a materially different interaction model. These components do
+not consume the text-only `@opengeni/sdk/chat` fallback protocol.
+
+`OpenGeniChat` adds the user's chat list to the conversation: a sidebar when
+the component is wide and a drawer behind a menu button when narrow (measured on
+its own container, so it works inside panels), a new-chat composer that creates
+the session from its first message, and inline rename and archive. It is
+composed from `SessionList` and `SessionConversation`, which you can also mount
+separately. Pass `conversationProps` for message rendering and tool renderers,
+`createSession` to create chats through your own endpoint, or `sessionId` /
+`onSessionChange` to control the selection (for example from the URL).
+
+Live voice is opt-in, because a call spends your credits and asks the browser
+for the microphone. Turn it on with `realtimeVoice={true}` (via `OpenGeniChat`'s
+`conversationProps` too) or `createSessionProxyHandler({ realtimeVoice: true })`.
+The composer then shows a voice button when the workspace offers an available
+voice model (for example hosted GPT Live with credits): the user talks, the
+voice model answers and hands work to the agent in the same chat, and the
+transcript lands in the timeline. It stays hidden when no model is available,
+when the proxy sets `realtimeVoice: false`, or when you pass
+`realtimeVoice={false}`. The voice code loads lazily on first display.
+
+The working indicator before the first reply says "Thinking…". Pass
+`genieLoading` (`phrases`, `messages`, `orb`, or a whole `render`) to use your
+own copy or visual. File attachments follow the proxy: it reports them off when
+`files: false`, and for anonymous visitors (`visitor: true` from `resolve`)
+unless it sets `visitorUploads: true`.
+
+`SessionConversation` and `OpenGeniChat` are built to look native inside
+someone else's product with zero styling:
+
+- **Theme follows the host**, not the OS: an enclosing `data-og-theme`, then
+  `class="dark"`/`data-theme` (and similar) on `<html>`/`<body>`, the host's
+  `color-scheme`, then the luminance of the background the chat sits on. Pass
+  `theme="light" | "dark"` to force one.
+- **Surfaces blend into the host** (`surface="host"`, default): backgrounds and
+  cards are opaque mixes of the host background, so a navy app gets navy cards.
+  Host-customized `--og-color-*` tokens are kept; `surface="theme"` uses the
+  token surfaces as they are.
+- **Run control is Stop, not Pause**: a Stop control appears only while a
+  response runs, and the next message continues a stopped conversation. Opt
+  into the console's workstream Pause with `composerProps={{ runControl: "pause" }}`
+  (`"none"` hides both).
+- **No model picker by default**: end users rarely choose models. Pass
+  `modelPicker`, or report `modelSelection: true` from the proxy
+  (`createSessionProxyHandler({ modelSelection: true })`); `modelSelection: false`
+  also fixes the policy server-side.
+
+Attachments appear when the deployment enables uploads (`attachments={false}`
+opts out), the microphone appears when it reports voice input available
+(`voiceInput={false}` opts out), generated images, video, published files and
+screenshots display through the conversation's session scope, actions a
+session proxy reports unavailable (`sessionCreation`, `archive`, `artifacts`)
+are hidden, the session goal shows with Pause/Resume/Clear, sub-agent cards
+open the child through `onOpenSession` (`OpenGeniChat` opens it in place),
+pending tool approvals render Approve/Reject, a yes/no question
+renders as two buttons, a failed load offers Try again, and `toolRegistry`
+customizes tool rendering.
+
+The root keeps all existing exports, including workbench components, but never
+imports their optional peers. Conversation-only Next.js/Vite hosts do not need
+terminal, desktop, editor, or diff packages. Hosts mounting those surfaces opt
+in through the [per-surface setup entries](#optional-peer-dependencies).
+
+Highlighted diffs use the optional `@pierre/diffs` peer only after an explicit
+opt-in, so a host without it still builds with any bundler (Turbopack resolves
+every reachable `import()`). Hosts that install it call `enablePierreDiffs()`
+once; call it from the lazily loaded route that renders diffs to keep the peer
+out of your initial bundle. Views already on screen upgrade when it registers:
+
+```ts
+import { enablePierreDiffs } from "@opengeni/react/diffs";
+enablePierreDiffs();
+```
+
+Without it, diffs and file views render as plain text.
+
+`OpenGeniProvider` never blocks or reloads the host page when Opengeni deploys
+a new API contract revision. The stock Opengeni console opts into that
+stale-tab protection with `reloadOnApiContractChange`; embedded products
+should leave it off.
+
+Subscription account lists and their usage readings (`useCodexAccounts`,
+`useSuperGrokAccounts`) are shared per `client` object: readers mounted at the
+same time share one request and one result, and account changes made through
+these hooks re-read every mounted list (also when the component that made the
+change has already unmounted). By default nothing is kept after the last reader
+unmounts, so a host that reuses one `client` for different people never shows
+one person's accounts to the next, also when it re-keys its tree for the next
+person in a single render: the new reader and its children never render the
+previous rows, and a read still in flight for the previous person is
+discarded. (A reader joining one already on screen shows its rows before the
+browser paints, after one extra render.) Set `retainReadsAcrossMounts` on
+`OpenGeniProvider` to keep them across navigation instead: returning to a page
+renders the last accounts at once and re-reads them in the background once
+they are older than 10 seconds. Failed reads are never kept, and a
+401/403/404 drops what was kept. Retained reads are dropped when `client`
+changes or the provider unmounts.
+
+> **Host action item:** only set `retainReadsAcrossMounts` when every signed-in
+> person gets their own `client` object (create a new client on sign-in,
+> sign-out and account switch), as the stock Opengeni console does. With a
+> shared client, leave it off.
+
+### Exact conversation search navigation
+
+`useSessionEvents().initialHistoryReady` becomes true when a history window has
+loaded successfully, including an empty tail. It stays true through later stream
+errors, history navigation, and tip reloads, and resets for a new session/replay
+identity. Use it rather than inferring initial success from `initialLoading` or
+the combined `error`. A failed first load stays unready until recovery;
+`jumpToLatest()` clears its stale error and retries. Full replay has no history
+snapshot-completion watermark, so SSE alone does not set this flag.
+
+`useSessionEvents(sessionId).jumpToSequence(sequence)` replaces the current
+window with at most two bounded cursor reads around an exact durable event.
+It resolves `true` only when that event is retained, `false` for a missing or
+superseded target, and rejects current request errors. `loadingTarget` exposes
+the pending state. New targets supersede older targets/pages; session/client
+changes fence stale results. Search enters history mode; use the existing
+`loadOlder`, `loadNewer`, and `jumpToLatest` controls to navigate onward. It does
+not download the intervening session history.
+Pass `jumpToSequence(sequence, { signal })` to cancel one navigation: an
+aborted signal fences the pending jump before its fetched window is applied
+(the underlying reads may still complete), resolves `false`, and settles
+`loadingTarget` without disturbing any newer navigation that superseded it.
+
+Pass the selected hit to `MessageTimeline` independently of loading:
+
+```tsx
+const history = useSessionEvents(sessionId);
+const [target, setTarget] = useState<TimelineSearchTarget | null>(null);
+
+function selectHit(hit: { sequence: number; eventId: string }, query: string, occurrence = 0) {
+  setTarget({ ...hit, query, occurrence });
+  void history.jumpToSequence(hit.sequence);
+}
+
+<MessageTimeline events={history.events} items={history.timeline} searchTarget={target} />;
+```
+
+The host owns search results, error handling, next/previous controls and query
+state. `TimelineSearchTarget` is exported from the root and `session-ui` entry:
+`{ sequence: number; eventId?: string; query: string; occurrence?: number; offset?: number }`.
+Matching is literal, case-insensitive, non-overlapping; `occurrence` is zero-based
+within the message, defaulting to zero. When the backend all-occurrence search
+returns `messageMatchOffset`, pass it as `offset`: the zero-based UTF-16 position
+of the match in the original message text. An explicit `offset` takes precedence
+over `occurrence` and is validated against the query, so a stale offset simply
+produces no highlight. `buildTimeline` supplies `sourceEvents`
+identities so completed assistant events remain addressable when the renderer
+keeps a first-delta ID. Hosts supplying their own items should preserve those
+identities (or the canonical `annotationSource`).
+
+The active message's group and long-user disclosure open persistently. Setting
+`searchTarget={null}` removes the active highlight without collapsing content or
+restoring a former scroll position. The package mounts its complete bounded
+window. The default Markdown renderer shows a labeled, bounded **message source**
+excerpt for the active match, including Markdown syntax and link destinations;
+closing find removes the highlight but retains that excerpt and its layout.
+An explicit **Show formatted message** action restores the full body; this can
+expand a huge message, so it is never done automatically on closing Find.
+Raw UTF-16 offsets are never applied
+to rendered Markdown text. Custom hosts can use
+`<Markdown searchTarget={searchTarget}>{text}</Markdown>` for the same behavior.
+A custom virtualized renderer receives
+`renderMessageText(text, item, { searchTarget })` and must materialize the exact
+occurrence when that context is non-null. Existing two-argument renderers remain
+compatible. If previous occurrences are omitted from the virtualized DOM, wrap
+the materialized match in an element with `data-og-search-occurrence` (zero-based
+index), `data-og-search-sequence` and `data-og-search-query`, each set from the
+target; when the target carries an `offset`, set `data-og-search-offset` to it
+alongside `data-og-search-occurrence` (which can be zero). This lets navigation
+identify that exact occurrence without recounting an incomplete DOM. Keep the
+materialized window when the context clears to
+preserve position. Navigation waits for the mounted text and highlights the active
+DOM range using the CSS Custom Highlight API, without rewriting React-owned
+text. Explicit source-offset targets require this marker: matching characters
+at the same rendered offset are not proof of source identity. A custom renderer
+that omits source text or puts it in an opaque iframe must reveal that text
+itself. Existing renderers without this mapping remain render-compatible but
+cannot provide exact source-offset navigation.
+
 ## Editable Office artifacts
 
 The optional artifact workbench is isolated from the ordinary session and
@@ -76,6 +373,29 @@ import { EditablePresentationArtifactSurface } from "@opengeni/react/artifacts/p
 <EditablePresentationArtifactSurface session={presentationSession} title="Launch deck" />;
 ```
 
+The spreadsheet surface supports typing, formulas, rectangular paste, clear,
+and durable row/column resizing. Drag a header boundary for immediate visual
+feedback and one command on release. Focus a boundary and use arrows to resize
+(Shift for 1 px), Home to reset, or Escape to cancel. Pending saves do not block
+typing; the sync indicator remains pending until server acknowledgement. Failed
+independent edits stay visible, and retry cannot overwrite newer overlapping
+edits. The same component is used in the dock and full-page artifact view;
+dimensions and values remain authoritative in the SDK Worker.
+The console supplies an XLSX Download action in both dock and full-page views.
+Custom hosts can supply `download(signal): Promise<Blob>` on the spreadsheet
+surface, or `downloadSpreadsheet(opened, signal): Promise<Blob>` on
+`EditableArtifactView`. Use the authenticated artifact SDK to pin the saved native
+head, materialize XLSX, poll its job, and download its bytes; never return the
+original imported file. Forward the abort signal through every request. The
+control waits for live sync without pending edits, shows progress and retryable
+errors, and cancels on teardown or revoked access. Omit the callback when the host
+does not support export; other modalities do not gain an unsupported download.
+Double-click a sheet tab or focus it and press F2 to rename it. Enter/Save submits
+the canonical `sheet.rename` command; Escape/Cancel discards an unsent name.
+Validation and failed submissions keep the name editor open. Pending cell edits
+show submitted input until the Worker projection catches up; pending formulas
+show their source, not an invented result.
+
 The durable document surface composes bounded summary, body, section, and
 review queries at one native revision. Text edits become UTF-16-correct minimal
 `paragraph.edit` commands; formatting becomes `paragraph.format`. Empty
@@ -97,7 +417,7 @@ or permissive fallback.
 
 `DocumentProjectionEditor`, `PresentationProjectionEditor`, and
 `SpreadsheetProjectionGrid` expose the same host-owned projection/async-command
-boundary without requiring the OpenGeni sync session. Pending, failure, retry,
+boundary without requiring the Opengeni sync session. Pending, failure, retry,
 read-only, focus, and reconciliation behavior stays inside the components.
 
 Projection editors use browser-safe structural views and do not load
@@ -135,6 +455,21 @@ can therefore implement only the methods used by each hook. A shared event feed
 also avoids requiring a client-owned event stream at runtime. Workspace-level
 Resume is an optional authority.
 
+Use `createEmbeddedSessionClient(base, options)` to bind that narrow surface
+from a full SDK client or host proxy. Delegated methods preserve their SDK
+receiver, `options.overrides.submitComposerDraft` can route atomic submission
+through a host-authenticated endpoint, and `mapComposerDraft` can project every
+read/save/submit draft before React adopts it. Construction fails immediately
+when a required method is missing, and submit returns the host/native
+`SubmitComposerDraftResponse` unchanged apart from an explicitly configured
+draft projection.
+
+The styled file surfaces accept a presentation-only node predicate:
+`FileBrowser.isNodeVisible`, `SandboxFiles.isNodeVisible`, and
+`SandboxWorkspace.isFileNodeVisible`. Hidden parents never expose orphaned
+children, hidden selections/reveal requests are ignored, and omitting the prop
+preserves the complete authoritative tree. This is not an authorization seam.
+
 The styled root surface ships with ready-to-use CSS. Import it once; the host
 does not need Tailwind:
 
@@ -154,7 +489,7 @@ derived defaults use scoped effective values so changing a base accent, radius,
 motion, or surface token updates its dependents at runtime.
 
 The original Tailwind v4 bridge remains available for hosts that intentionally
-want OpenGeni utilities compiled into their own Tailwind entry:
+want Opengeni utilities compiled into their own Tailwind entry:
 
 ```css
 @import "tailwindcss";
@@ -295,7 +630,7 @@ export function App() {
 
 ## Realtime composer controls (`@opengeni/react/realtime`)
 
-The realtime subpath is the exact OpenGeni composer experience: model catalog
+The realtime subpath is the exact Opengeni composer experience: model catalog
 and selection, split-button motion, start/stop/retry states, microphone and
 audio mute controls, diagnostics, recovery, and the same copy, ARIA, classes,
 and styling used by the web console. It is deliberately separate from the root
@@ -361,7 +696,7 @@ The reference consumer is `demo/realtime.html`. Run `bun run demo` from
 `packages/react`, then open `http://localhost:3100/realtime.html?mode=mock` for
 deterministic selection/start/mute/stop/reconnect/error testing. Use
 `?mode=live&workspaceId=…&sessionId=…` against the web server's same-origin
-`/demo-api` proxy for a real local OpenGeni environment. Configure
+`/demo-api` proxy for a real local Opengeni environment. Configure
 `OPENGENI_DEMO_API_URL` and, only on the server, optional demo API/access
 credentials; the browser receives neither credential. Prefer the deployment's
 normal browser authentication. If the proxy needs a server credential, create a
@@ -386,11 +721,46 @@ through published package APIs only.
 ## Browser and computer surfaces (`@opengeni/react/interaction`)
 
 The interaction subpath renders the same browser-native and semantic computer
-surfaces used by the OpenGeni web app. It consumes only the public SDK client:
+surfaces used by the Opengeni web app. It consumes only the public SDK client:
 workspace discovery, peer switching, tabs/windows, live frames, human input,
 identity versions, interventions, diagnostics, reconnect, and lifecycle state do
 not require app-private controller glue.
 
+Managed browser actions keep the foreground tab in place. Target-local Chromium
+focus emulation keeps animation callbacks running without an open preview;
+explicit activation brings a tab forward. The override ends when its controller
+detaches. Native **App controls** also work in the background where supported.
+Physical desktop mouse/keyboard input shares the foreground seat; **Bring to front**
+makes that change explicit.
+Computer frames fit the dock while preserving their proportions. Resizing or
+reopening the dock refits the visible image without changing capture resolution
+or the coordinates sent to the computer.
+Desktop opens a whole screen by default. Multiple screens use a compact screen
+selector; app controls and window views are available from **Advanced**. Explicit
+view choices survive refreshes while the target remains available.
+
+Desktop IME candidates and their selection keys stay local; only committed text is sent.
+
+A managed browser's attachment authority error keeps a same-browser **Reconnect**
+action available. It obtains a fresh server-authorized attachment without creating
+a replacement browser or replaying input. The fresh Connected Chrome instruction
+is reserved for the selected extension-attached browser's generation loss; a
+different lost browser in the workspace cannot change that recovery path.
+
+The browser viewer negotiates bounded typing batches from the active controller's
+short-lived attachment. Supporting helpers recheck the original controller,
+target, document and frame fence before every action; old helpers retain one
+request per action. Only queued text actions share a request (at most 16), with
+each text/input event preserved. Keys, pointer input and clipboard operations
+remain ordering barriers. A failed or uncertain action discards the queued suffix
+without replay.
+IME candidate-selection keys stay local to the viewer; only committed text is
+sent to the remote page. A later ordinary Enter remains a remote key action.
+Live image props use opaque byte buffers so React development timing diagnostics
+cannot expand and retain every screenshot byte. Normal timing diagnostics remain enabled.
+Queued inputs retain only immutable frame fences, not screenshot bytes or prior
+render callbacks. Replacing the selected viewer invalidates its queued suffix.
+
 ```tsx
 import { OpenGeniProvider } from "@opengeni/react";
 import { BrowserViewer, ComputerViewer } from "@opengeni/react/interaction";
@@ -416,6 +786,33 @@ returned ComputerSession must be the exact placement/window the browser uses.
 `onOpenComputer` then changes the host layout to that resource—it must not open a
 lookalike desktop. Closing either viewer never ends its durable resource.
 
+`ComputerViewer` disables input when its control service is unavailable, even if
+frames keep arriving. Reconnect refreshes the selected desktop's controls and
+frames. App accessibility inspection failures leave independent live input
+available; `useComputerSession().controlError` reports service loss separately
+from the hook's general `error`.
+
+If the chat's latest browser was lost or failed, the viewer names it and explains
+why it is unavailable instead of showing the ordinary empty state. It offers the
+existing new-browser controls without reopening the lost controller or selecting
+another chat's browser. Explicitly closed browsers still use the empty state;
+older failures do not replace a newer closed browser. This loss notice also takes
+precedence over `renderEmpty`. Preview the deadline-loss case with
+`browser.html?mode=mock&lost=1` (add `width=360&theme=light` for a narrow light dock).
+
+Native dropdown popups may not appear in page frames. With a controller that
+advertises focused input observations, clicking one opens its choices beside
+the click. Ordinary clicks use a bounded focus probe instead of a full page
+snapshot; only a focused native dropdown (or a child-frame focus hint) requests
+semantic options. Current controllers show no permanent **Choose option** button
+over the page; older controllers retain that explicit fallback. **Alt+Down** opens
+the focused dropdown and reads its options on either controller generation.
+Selection uses the normal browser action API. The viewer retains that
+observation's target/document/frame fence. Private, oversized, or ambiguous
+choices remain unavailable; the page's keyboard controls still work. This
+fallback requires a controller with focused native-select metadata support and
+does not rewrite the page or capture the desktop.
+
 The provider opens one shared workspace interaction-revision stream and every
 catalog refreshes only when its revision advances; hidden or disconnected pages
 fall back to bounded polling and reconcile from the retained cursor. Hosts that
@@ -428,6 +825,18 @@ same-origin `/demo-api` proxy and the exact published SDK/React entrypoints.
 
 ## Composer customization (`@opengeni/react/composer`)
 
+`SessionChrome` accepts `onComposerFocus` for queue editing. Connect it to
+`controller.focusInput` from `useChatComposerController`, or focus a custom
+input through its ref. Chrome calls it after a successful checkout and
+`composer.applyDraft`, including confirmed draft replacement; failed checkout
+and pending/cancelled replacement do not request focus. The host retains
+ownership of the input and no DOM selector or global focus event is needed.
+
+When sharing `useSessionEvents().events` with `useGoal`, the hook still fetches
+the authoritative goal on mount and target changes, even when the supplied log
+already contains goal events. The shared log drives subsequent invalidations
+without opening another event stream. A 404 remains a normal goal-less state.
+
 Use `ChatComposer` for the standard layout and its `controlsStart`, `header`,
 and `messages` props for small additions. For a different layout, import the
 headless controller and compound primitives as a namespace. The controller is
@@ -506,7 +915,8 @@ state remains application-owned; durable draft and session state remain in
 
 - `useSessionEvents(sessionId)` — loads a compact, bounded tail window by
   default, then live-streams on the SDK's exactly-once/ordered event delivery.
-  Initial replay is capped at three 5000-row raw pages and `loadOlder` at two;
+  Initial replay reads one 1000-row raw page, with at most one extra page to
+  recover a dense turn's boundary; `loadOlder` is capped at two such pages;
   timeline group density is only an early stop. It returns the raw windowed
   `events`, projected `timeline`, latest `sessionStatus`, connection state, and
   older-history controls (`hasOlder`, `loadingOlder`, `loadOlder`). Pass
@@ -519,13 +929,32 @@ state remains application-owned; durable draft and session state remain in
   callback return type. Custom loaders can use `createOlderHistoryLoadReceipt`
   and call `markCommitted` immediately before publishing their accepted older
   window.
+- Browser retention limits are exported as `SESSION_EVENT_BROWSER_MAX_BYTES`
+  and `SESSION_EVENT_BROWSER_MAX_COUNT`; they do not change fetch page sizes.
+  The live working set is at most 16 MiB or 20,000 events. One event larger than
+  the byte target stays complete in a window of its own.
+  Live appends reuse the retained window's byte total, measuring only incoming
+  and evicted events. History still pages when either retention limit is reached.
+- Newer history uses `hasNewer`, `loadingNewer`, and `loadNewer`. A failed
+  `loadNewer()` preserves the retained events and cursors, exposes the original
+  failure through `error`, and still rejects for the caller to handle. Pass
+  `onLoadNewer={loadNewer}` (or return its promise from your wrapper) to
+  `MessageTimeline`: it catches the request failure, shows the error and an
+  explicit **Retry later activity** action, and does not automatically retry
+  the failed boundary. A successful retry, jump to the start/latest window,
+  or session change clears that failure. Loading older rows alone does not
+  resolve a failed newer read. Late failures from a previous session are ignored.
+  A host that discards the promise must handle its own rejected request.
 - `useComposer(sessionId, { sendExtras, effectiveControl })` — revisioned private
   draft, Send, Steer, and workstream Pause/Resume state. `send()` appends in
   visible queue order (including while paused); `steer()` puts the new direction
   directly in chat and supersedes the current direction. Resume is always an
   explicit control action and never an implicit side effect of Send. Drafts
   autosave with optimistic concurrency, survive failed sends, and reuse one
-  `clientEventId` across retries so the server dedupes. `composer.policy` and
+  `clientEventId` across retries so the server dedupes. Draft reads retry transient
+  failures, including request timeouts, with backoff. Successful refreshes clear
+  draft-read errors without dismissing Send, Steer, or control errors; a draft
+  sync timeout does not mean the agent turn has stopped. `composer.policy` and
   `setModel` / `setReasoningEffort` / `setLatencyMode` expose the exact policy
   owned by that actor/session draft; policy is `null` until hydration completes.
   `sendExtras` (object or function evaluated at send time) is only for
@@ -557,16 +986,24 @@ state remains application-owned; durable draft and session state remain in
   plus the `defaultModel` to preselect (from the client config) for a picker.
 - `useCodexAccounts()` — connected Codex (ChatGPT) accounts, the active/next-run
   pointer, and per-session account pinning for multi-account subscriptions.
+  `refreshUsage({ maxAgeMs })` reuses live usage readings only when every
+  listed account was read within `maxAgeMs`; concurrent refreshes share one
+  provider read. `liveUsageUpdatedAt` is the time of the oldest account
+  reading. See `retainReadsAcrossMounts` above for keeping the list and
+  readings across navigation.
 - `useSlashCommands(...)` — the slash-command palette state (registry + parsing +
   handlers) behind `CommandPalette`.
 - `useWorkspaceSessions()` / `useScheduledTasks()` — workspace lists for
-  fleet/manager views (optional polling).
-- `useVariableSets()` — workspace variable sets with metadata-only generic
-  reads and create/update/remove/set/delete operations. Dedicated permissioned
-  exact-value reveal is part of the held React/UI train rather than an
-  implicit field on ordinary reads.
-- `usePacks()` — capability packs + installations with
-  register/enable/remove and `installationFor(packId)`.
+  fleet/manager views (optional polling). `useWorkspaceSessions({ projection:
+  "summary" })` returns compact list entries; omit the option for full sessions.
+  Scripted clients can omit the summary method and the hook projects full pages
+  locally while retaining cancellation and causal read revisions.
+- `useVaults()` / `useVault()` / `useVaultItems()` / `useVaultItem()` /
+  `useVaultFieldVersions()` / `useSessionSecrets()` — vaults, items, field
+  history and a session's vault policy, metadata only. `useVaultsApi()` returns
+  the SDK's `client.vaults(workspaceId)` routes for writes and the one audited
+  `revealField` call; keep revealed values in component state, never in a
+  cache. Variable Sets and `useVariableSets()` were removed in 2.0.0.
 - `useWorkspaces()` — the caller's workspaces with create/update (client-only;
   not bound to the provider's workspace).
 - `useBillingUsage({ accountId?, workspaceId? })` — credit balance + recent
@@ -614,22 +1051,44 @@ intentional changes should regenerate those snapshots and review the diff.
 - `MessageTimeline` — the session timeline with stick-to-bottom scrolling, a
   "jump to latest" affordance, streaming caret, collapsible activity clusters,
   and worker cards (wire `onOpenSession` to drill into a worker). Pass
-  `renderMessageText` to plug a markdown renderer. Pass
+  `renderMessageText` to plug a markdown renderer. The default renderer shows a
+  single newline in a message as a line break, like other chat apps; a custom
+  renderer gets the same result with `<Markdown softLineBreaks>{text}</Markdown>`
+  (off by default for non-chat Markdown). Pass
   `loadRetainedArtifact` to render permanent generated-image receipts; a loader
   may return verified bytes or a short-lived signed URL. The stock web app uses
   the URL path to avoid copying multi-megabyte images into JavaScript memory.
+  `createWorkspaceRetainedArtifactLoader`, `createSessionRetainedScreenshotLoader`,
+  and `createWorkspaceRetainedVideoLoader` bind the SDK reads to a workspace
+  (and session); `SessionConversation` uses them by default.
 - `UserMessageBody` — the shared lossless rendered-height disclosure for
   already-sent user text. Use it inside a custom `renderMessageText` user branch
   so attachments and voice identity remain outside the clipped Markdown region.
+  Pass `disclosureLabels={{ showMore: "Afficher davantage", showLess: "Réduire" }}`
+  to localize a direct instance. For the default timeline, pass the same object
+  as `MessageTimeline.userMessageDisclosureLabels` or
+  `SessionConversation.userMessageDisclosureLabels`; custom `UserMessageBody`
+  renderers inside that timeline inherit these labels too. Each direct label
+  overrides its timeline label independently, then falls back to `Show more`
+  or `Show less`. Changing labels does not reset a message's expanded state.
+  `UserMessageDisclosureLabels` is exported from both `@opengeni/react` and
+  `@opengeni/react/session-ui`.
 - `SessionStatus` / `StatusDot` — status badges; live states breathe.
 - `FleetTile` — one session in a fleet grid: title, status, model, recency.
 - `ModelPicker` — a compact model dropdown for a composer slot, grouping the
   host-exposed models by provider.
-- `ModelPolicyPicker` — the full model policy control used by the OpenGeni web
+- `ModelPolicyPicker` — the full model policy control used by the Opengeni web
   app: provider/billing rails, model availability, reasoning effort, and
   runnable latency modes such as Fast. It accepts either `ClientModel[]` or
   catalog-backed `PickerModelRow[]`, and supports host-supplied labels.
 - `Markdown` — the timeline's markdown renderer (GFM), also usable standalone.
+  Top-level assistant tables in `MessageTimeline` can expand beyond the prose
+  column into the actual conversation panel's available space. Small tables,
+  paragraphs, user bubbles, and nested or standalone Markdown keep their normal
+  width; oversized tables retain table-only horizontal scrolling. No host prop
+  or viewport-wide layout override is required.
+  Remeasurement during host rerenders or tail streaming does not temporarily
+  resize the live table or displace an unpinned history reader.
   With `onSandboxFile`, a valid `sandbox:<path>[:line]` application link becomes
   an in-session Open action. The callback receives the decoded path unchanged;
   the optional line is positive and 1-based. Invalid sandbox references render
@@ -680,6 +1139,97 @@ remaining built-ins in supplied order. Duplicate IDs keep their first
 definition; remove a built-in before adding a custom facet with the same ID.
 `replace` is type-exclusive with `add` and `remove`.
 
+`turnSummary={{ rolling: true }}` selects the readable per-turn presentation:
+startup shows the preparation orb outside any disclosure, then hands over to
+Working without resetting the startup-inclusive elapsed clock. While work is
+live, assistant progress messages stay fully formatted and visible,
+followed by one Working or Waiting disclosure with the rolling latest step.
+When the turn finishes, earlier assistant messages and tools share the Worked
+disclosure; the final response remains visible. Expanding reveals that turn's
+earlier prose and activity in chronological order, not a fold of multiple turns.
+An already expanded or actively read view is preserved through settlement.
+Routine machine inputs get one compact reason per resumed turn. Normal tip-follow
+continues through long answers, and manual scrolling never auto-repins on new work.
+Expanded outer work headers stay reachable at the top of the timeline until
+their own details end; nested headers never stick. The contextual navigation
+pill stays below the sticky-header strip and avoids interactive controls. If
+no horizontal slot fits beside a toolbar, only the pill moves below it; the
+timeline's size and scroll position do not change.
+
+The single **Back to your message** button returns to the loaded user prompt
+associated with the response or work being read: the latest prompt preceding
+the viewport midpoint. It appears only when that prompt's start is more than
+24 px above the viewport and its entire body and attachments are out of view.
+Clicking synchronously scrolls and focuses that exact
+mounted prompt near the top and leaves tip-follow. Later messages and queued
+prompts do not change the destination while the reader remains in older work.
+An older bounded window uses its own loaded context; a window with no associated
+prompt shows no action. Navigation never replaces the history window or looks up
+the globally newest message. There are no previous/next arrows.
+
+`SessionConversation` includes this behavior automatically. Custom timelines
+need no prompt-navigation callback:
+
+```tsx
+const events = useSessionEvents(sessionId);
+<MessageTimeline
+  events={events.events}
+  items={events.timeline}
+  turnSummary={{ rolling: true }}
+  hasNewer={events.hasNewer}
+  onJumpToLatest={events.jumpToLatest}
+/>;
+```
+
+`onJumpToLatest` retains its separate live-bottom behavior. The deprecated
+`MessageTimeline.onJumpToLatestQuestion` prop remains source-compatible but is
+not invoked by contextual navigation.
+
+### Optional global newest-message lookup
+
+The public `useSessionEvents().jumpToLatestQuestion()` hook remains available for
+hosts that deliberately build a **separate** global lookup action. It is not wired
+to `MessageTimeline` or the first-party conversation's contextual button.
+The hook checks the authoritative queue and normally uses one filtered forensic
+lookup plus, if needed, two bounded context reads. It pages past legacy worker
+completions and withdrawn/cancelled-before-start prompts, never substituting an
+arbitrary question from a loaded old page. Queued/legacy admission uses filtered
+lifecycle evidence to locate its real turn start. A distant prompt is retained as
+one projection-only witness in `events.timeline`; `events.events` remains the
+bounded contiguous raw window, so pass `items` as above.
+The optional resolver loads on its first invocation, not when opening a session.
+Identity and navigation guards also cover that module-loading delay.
+
+Custom hosts can provide their own queue destination when invoking this hook:
+
+```tsx
+const navigateToNewest = () => events.jumpToLatestQuestion({
+  onQueuedQuestion: async (turn, navigation) => {
+    await queue.refresh();
+    if (!navigation.isCurrent()) return;
+    // Check the host's latest queue/error state before applying its focus request.
+    setQueueFocusTarget((previous) => ({
+      turnId: turn.id,
+      requestId: (previous?.requestId ?? 0) + 1,
+    }));
+  },
+});
+// Pass queueFocusTarget to SessionChrome; each new request opens/focuses once.
+```
+
+A queue destination returns `null`, not an invisible transcript sequence. Without
+`onQueuedQuestion`, a pending prompt rejects with `LatestQuestionQueuedError`;
+the custom host can show guidance. Transitional queue state can be retried.
+Check `navigation.isCurrent()` after awaits and immediately before queue UI effects:
+an explicit history jump can supersede a queued lookup without changing the session.
+The shared projection predicate supplies execution evidence for older queued turns
+without `turn.started`, including tools, agent/sandbox activity, startup, recovery,
+and capacity events. Compact cursor coverage skips coalesced delta runs.
+`groupTimeline(items)` retains classic
+grouping; `{ readableTurns: true }` selects the new projection. The deprecated
+`foldExchanges` option aliases readable turns, not the removed cross-turn fold. See
+[`docs/design/genie-loading.md`](../../docs/design/genie-loading.md).
+
 ## Sandbox surfacing
 
 An opt-in workbench that surfaces a session's live sandbox — files, terminal,
@@ -707,6 +1257,16 @@ capability document so every surface degrades to a reason instead of crashing.
 These surfaces pull in [optional peer dependencies](#optional-peer-dependencies)
 — install only the ones for surfaces you actually mount.
 
+`SandboxWorkspace` keeps capture-backed file browsing passive, but an explicit
+live-file open acquires a viewer. Failed opens show the connection error and a
+retry that renegotiates the viewer instead of leaving a waking spinner running.
+When composing `SandboxFiles` directly, pass `workspaceError` alongside
+`liveWorkspaceReady` and supply an `onWakeWorkspace` callback that can retry a
+failed negotiation. Complete PNG, JPEG, GIF, and WebP reads render as read-only
+image previews; truncated reads and other binary formats remain non-editable
+notices. Image previews use the existing bounded file-read path and do not
+publish or retain additional files.
+
 ## Connected Machines (`@opengeni/react/machines`)
 
 Bring-your-own-compute UI: the Machines dashboard, per-machine metrics, the
@@ -752,11 +1312,62 @@ function Fleet({ sessionId }: { sessionId: string }) {
 See the [Connected Machines guide](../../docs/connected-machines.md) for the
 end-to-end embedder story (create-on-machine, discover, swap, enroll, revoke).
 
+## Usage allowances (`@opengeni/react/usage`)
+
+Show people where they stand against a workspace or member usage allowance.
+A separate subpath, so hosts that don't meter usage never load it.
+
+- `useUsage({ workspaceId? })` — the signed-in person's own `/usage/me`
+  (through `getMyUsage` or any client with `requestJson`) plus a summary of
+  which limit binds first. `refreshKey` re-reads when work settles.
+- `UsageMeter` — "38% left · Resets Nov 1". Shares only; pass `formatAmount`
+  for money, credits or plan multiples. `density="compact"` for menus,
+  `"hero"` to lead a page.
+- `UsageLimitNotice` — the calm composer line: nothing while comfortable, a
+  dismissible heads-up near the limit, then who can raise it and when it
+  resets. `labels` rewords it; `action` adds your own "Upgrade" button.
+- `UsageMemberList` — the admin roster with a share-of-budget slider,
+  optional fixed amounts, and a visible note when shares add up to more than
+  the pool. Save rules through your backend in `onChangeRule`.
+
+```tsx
+import { UsageLimitNotice, UsageMeter } from "@opengeni/react/usage";
+
+<UsageMeter workspaceId={workspaceId} />
+<SessionConversation
+  sessionId={sessionId}
+  composerProps={{ header: <UsageLimitNotice workspaceId={workspaceId} /> }}
+  allowanceExhaustedLabels={{ memberRemedy: "Ask your team admin for more." }}
+/>
+```
+
+The conversation's "usage limit reached" row is customized on
+`MessageTimeline`/`SessionConversation` with `allowanceExhaustedLabels` or
+replaced with `renderAllowanceExhausted`. See
+[usage allowances](../../docs/usage-allowances.md#react-components-and-the-console).
+
+## Terminal startup input
+
+`SandboxTerminal` captures bounded early typing while attaching. Supported stock
+sandbox images negotiate explicit Bash Readline readiness; banners and first
+output do not release queued commands. Silent prompts work too. If a startup
+profile asks for input or disables line editing, **Use manual input** clears
+buffered typing before enabling unguaranteed input. Old images/running ttyd
+daemons retain labelled **legacy input** behavior; wait for their shell startup
+before typing. Relay PTYs retain their existing OPEN_ACK behavior.
+
+Custom consumers of `useTerminalStream` can inspect `inputReadiness` and expose
+`useLegacyInput()` for `waiting` states. That action discards queued typing; it
+is not an acknowledgement of shell readiness. A new React package alone cannot
+upgrade an old sandbox image. See the [native readiness contract](../../agent/native/terminal-ready/README.md)
+for compatibility, startup limits and coordinated release requirements.
+
 ## Optional peer dependencies
 
-The chat/timeline surface has none. The sandbox workspace and diff surfaces pull
-their heavy libraries from **optional** `peerDependencies`, so you install only
-what the surfaces you mount need:
+The chat/timeline surface needs only the required React/React DOM peers. All
+existing root exports remain available without optional workbench peers, even
+when a bundler resolves every reachable dynamic import. Install and enable
+only the surfaces you mount, once in their client route or bootstrap:
 
 - Terminal (`SandboxTerminal`): `@xterm/xterm`, `@xterm/addon-fit`,
   `@xterm/addon-web-links`.
@@ -766,6 +1377,37 @@ what the surfaces you mount need:
   language packs you need (`css`, `html`, `javascript`, `json`, `markdown`,
   `python`).
 
+```ts
+import { enableSandboxTerminal } from "@opengeni/react/terminal";
+import { enableDesktopViewer } from "@opengeni/react/desktop";
+import { enableCodeEditor } from "@opengeni/react/editor";
+
+enableSandboxTerminal();
+enableDesktopViewer();
+enableCodeEditor({
+  javascript: async () =>
+    (await import("@codemirror/lang-javascript")).javascript({ jsx: true, typescript: true }),
+});
+```
+
+Omit imports and calls for surfaces you do not use. These entries also re-export
+their components; root component imports continue to work after setup. The
+libraries load on mount, not during setup or SSR. Import the setup from a lazy
+route to keep its peer chunks outside the initial conversation graph.
+
+For optional terminal WebGL acceleration, install `@xterm/addon-webgl` and call
+`enableSandboxTerminal({ webgl: () => import("@xterm/addon-webgl") })`. Without
+it, or if it fails, the terminal uses its DOM renderer. Only supply editor
+grammar loaders for packages you installed; absent/failed grammars use plain
+CodeMirror. Without editor setup, the existing textarea fallback remains usable.
+Without terminal/VNC setup, those surfaces show a setup error; relay-frame
+desktops and a custom `rfbFactory` need no noVNC setup.
+
+Custom hosts may supply `registerSandboxTerminal`, `registerCodeEditor`, or
+`registerDesktopViewer` loaders from the root instead. Mounted fallbacks retry
+when registration changes. Do not hide peer imports behind runtime bare strings
+or `@vite-ignore`: browsers cannot resolve those without an import map.
+
 ## Demo harness
 
 `bun run demo` (from this package) serves a harness that drives the real hooks
@@ -774,3 +1416,123 @@ with streaming, tool calls, and a worker spawn, plus fleet and scheduled-task
 views and a dark/light toggle. `realtime.html` is the public-package reference
 consumer described above, with deterministic mock and same-origin live modes.
 `bun run demo:build` is part of the repo gate.
+
+### Model selection
+
+`ModelPolicyPicker` opens a flat, searchable list grouped by payment source, with
+the selected model checked in its provider group. Choosing a model applies it and closes the popover.
+Thinking and supported speed controls remain in a fixed footer instead of a
+nested page. Model changes preserve supported reasoning effort and latency;
+unsupported effort falls back to the new model's default, and unsupported speed
+returns to Standard. Thinking uses inline radio choices and is hidden when the
+model has no adjustable reasoning levels. Availability and Codex-only session restrictions still disable choices.
+
+Use `allowModelOptions={false}` for policies that save only a model identity,
+such as a fallback order. This hides effort and speed controls without changing
+the catalog, payment-source labels, or model eligibility.
+
+The trigger renders immediately; the searchable popover loads when opened. Hosts
+can translate its search, current-selection, empty-result, attachment-warning, and
+thinking labels through `messages`, and override payment descriptions through
+`messages.billingHints`.
+
+The stock deployment-provided group is labeled **Models**, with a generic model
+icon. It can contain both credit-backed and free models; the **Free** badge
+depends on the model's explicit cost, not its group. Genuine external-provider
+and subscription identities retain their own labels and marks.
+
+Hosts can rebrand the full picker without replacing its interaction logic:
+
+```tsx
+<ModelPolicyPicker
+  {...pickerProps}
+  groupPresentation={{
+    opengeni_credits: {
+      label: "Acme Assist",
+      icon: <AcmeMark aria-hidden="true" />,
+      description: "Provided by your workspace",
+    },
+    codex_subscription: { description: null },
+  }}
+/>
+```
+
+`groupPresentation` is a partial map keyed by `PickerBillingClass`. Labels apply
+to group headings, search, and trigger-icon accessibility. Icons apply to both
+the menu and trigger; supply decorative, non-interactive content (SVG or image)
+that fits the existing 14px slot. Explicit `null` hides an icon or description;
+omitted fields retain defaults. Descriptions override `messages.billingHints`,
+can also be shown for the deployment-provided group, and are searchable. Existing
+`rows[].billingClassLabel` remains the fallback when no label override is supplied.
+This is presentation only: model IDs, billing, ordering, availability and callbacks
+are unchanged. The type `ModelPolicyPickerGroupPresentation` is exported from
+both `@opengeni/react` and `@opengeni/react/composer`. The native `ModelPicker`
+is a separate control; this API targets the full `ModelPolicyPicker` shown above.
+
+The complete conversation uses this same neutral picker. Customize its appearance
+without replacing composer controls through `SessionConversation.modelPickerProps`,
+or through `OpenGeniChat.conversationProps`:
+
+```tsx
+<OpenGeniChat
+  client={client}
+  workspaceId={workspaceId}
+  conversationProps={{
+    modelPickerProps: {
+      groupPresentation: {
+        opengeni_credits: { label: "Acme Assist", icon: <AcmeMark aria-hidden="true" /> },
+      },
+      messages: { label: "Choose a model" },
+    },
+  }}
+/>
+```
+
+`modelPickerProps` accepts only `groupPresentation` and `messages`; it does not
+enable a hidden picker or change policy, model availability or callbacks. Keep
+model-picker visibility controlled by `modelPicker` and the client configuration.
+
+For a rendered example, open the composer-responsive demo with `?branding=host`.
+
+Models always show their clean name and maker logo: picker rows carry
+`modelDisplayName(model)` (`claude-opus-4-8` and
+`organization-claude-subscription/claude-opus-5-5` read `Claude Opus 4.8` and
+`Claude Opus 5.5`) and a `ModelMark`. Organization- and workspace-connected API
+keys share one "API keys" group, and identical copies of one model in a
+connection group show once. Render a model anywhere else with
+`<ModelName model={id} />`, or `modelDisplayName` / `modelVendor` from
+`@opengeni/react` or `@opengeni/sdk/model-display`. The trigger keeps a host's
+explicit group icon; otherwise API-key models show the maker's logo.
+
+Subscription descriptions appear once per provider group. Free models carry a
+Free badge. Pass `hasImageAttachments` for the current draft to show an image
+compatibility warning only when the selected model cannot view those images.
+
+`MessageTimeline.renderMessageActions(item)` places host-owned controls beside
+Copy and the timestamp for user messages and completed assistant messages.
+The host owns feedback, fork authorization, and mutations; streaming assistant
+messages omit this slot. Use the `group/copy` hover/focus state and preserve
+visible touch targets when styling actions.
+
+### Portable action reviews
+
+`ApprovalSurface` accepts `loadReview(approval)` and `onViewDetails(review, path)`;
+load the versioned facts with `client.getToolActionReview`. It shows one selected
+action, counts and bounded fields instead of raw argument JSON. Keep
+`selectedApprovalId` and `onSelectedApprovalChange` in the host if a full-page
+detail route unmounts the surface, so returning cannot silently select a different
+action. The native `onApprove` / `onReject` identity is unchanged and duplicate
+submission is fenced until authoritative events remove the request.
+
+Render `ToolActionReviewDetails` on the host's normal page with
+`client.getToolReviewDetails`, passing the review's `actionDigest`, path and offset.
+Details are immutable, authenticated, paginated, and redact protected values.
+Restore focus to the original `data-review-path` button on return. No web-app
+imports, iframe, second confirmation, or nested scrolling pane is required.
+The standalone fallback retains bounded details for older SDK approvals.
+
+Wrap `MessageTimeline` in `ToolReviewHistoryProvider` with its visible events,
+authenticated `load(approvalId)` callback and `onViewDetails` to keep recorded
+reviews readable inside the corresponding tool activity. Historical receipts
+never render decision buttons. The same semantic tokens support light/dark
+embeds; `demo/approval-review.html` is the synthetic state gallery.