@opengeni/react 1.0.1 → 1.0.2-canary.37191796234001

package/README.md

@@ -19,11 +19,225 @@ 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
+
+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
+
+`SessionConversation` is the default product integration for an existing
+session. Back it with `createSessionProxyHandler` from `@opengeni/sdk`, mounted
+on your server, and point an unmodified browser
+`new OpenGeniClient({ baseUrl: "/api/opengeni" })` at it:
+
+```tsx
+import "@opengeni/react/compiled.css";
+
+<OpenGeniProvider client={client} 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).
+
+`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), 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.
+
+### 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
@@ -135,6 +349,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:
 
@@ -272,7 +501,7 @@ function OpsChannel({ sessionId }: { sessionId: string }) {
         status={sessionStatus}
         hasOlder={hasOlder}
         loadingOlder={loadingOlder}
-        onLoadOlder={() => void loadOlder()}
+        onLoadOlder={loadOlder}
         className="min-h-0 flex-1"
       />
       <QueueSurface queue={queue} composer={composer} />
@@ -391,6 +620,41 @@ 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 +680,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 +719,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,20 +809,53 @@ 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
   `replay: "full"` to opt back into full replay; a nonzero `after` keeps the
-  previous resume semantics.
+  previous resume semantics. `loadOlder()` remains await-compatible and resolves
+  to the existing `boolean`, while its promise also carries the causal
+  `committed` receipt used by `MessageTimeline`. Pass it directly or through an
+  existing wrapper, including `onLoadOlder={() => void loadOlder()}`; synchronous
+  receipt capture preserves the commit signal without narrowing the historical
+  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; `steer()` supersedes the current direction. Drafts
+  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.
-  `sendExtras` (object or function evaluated at send time) merges
-  resources/tools/model/reasoningEffort into every message. All human input is
-  plain chat text by design; approvals flow as control events
+  `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
+  non-policy per-message fields such as live attachment resources and connection
+  authority. Disabling durable draft persistence requires an explicit
+  `initialPolicy`; no session or workspace fallback is invented. All human input
+  is plain chat text by design; approvals flow as control events
   (`useSessionControl`), not bespoke widgets.
 - `useTurnQueue(sessionId, { events })` — the one server-authoritative human
   prompt queue with `moveTurn`, crash-safe `editTurn`, identity-preserving
@@ -547,13 +883,14 @@ state remains application-owned; durable draft and session state remain in
 - `useSlashCommands(...)` — the slash-command palette state (registry + parsing +
   handlers) behind `CommandPalette`.
 - `useWorkspaceSessions()` / `useScheduledTasks()` — workspace lists for
-  fleet/manager views (optional polling).
+  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.
 - `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)`.
 - `useWorkspaces()` — the caller's workspaces with create/update (client-only;
   not bound to the provider's workspace).
 - `useBillingUsage({ accountId?, workspaceId? })` — credit balance + recent
@@ -591,8 +928,9 @@ intentional changes should regenerate those snapshots and review the diff.
 
 ## Components
 
-- `ChatComposer` — auto-growing textarea, Enter-to-send (IME-safe), pause/resume
-  controls, inline error recovery. Slots for app chrome:
+- `ChatComposer` — auto-growing textarea, Enter-to-send (IME-safe), direct
+  Cmd/Ctrl+Enter steering, pause/resume controls, and inline finite error
+  recovery. Paused sends visibly join the queue without resuming. Slots for app chrome:
   `controlsStart` (footer controls like model pickers / attach buttons),
   `header` (e.g. attachment chips above the field), and `onPaste`
   (paste-image-to-attach). Its advanced controller and compound primitives are
@@ -607,6 +945,15 @@ intentional changes should regenerate those snapshots and review the diff.
 - `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
@@ -616,8 +963,26 @@ intentional changes should regenerate those snapshots and review the diff.
   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
+  as disabled text, never as empty or browser-navigation links.
 - `CommandPalette` — the slash-command palette UI over `useSlashCommands`.
 
+`SandboxWorkspace.openFileRequest` is the host seam for that callback. Each new
+`requestId` selects Files, opens the exact path on the already selected session
+target, reveals its loaded/lazy ancestors in the file tree, selects and scrolls
+to the file, and optionally focuses the requested line. A request without a line
+opens the top of the file; file publication/download remains a separate explicit
+artifact action.
+
 The timeline is extensible: `createToolRegistry` / `defaultToolRegistry` plug
 per-tool renderers, and the rendering primitives (`ActivityDisclosure`,
 `ScreenshotFigure`, `TermBlock`, `LightboxProvider`, …) compose custom rows with
@@ -655,6 +1020,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,
@@ -674,13 +1130,24 @@ capability document so every surface degrades to a reason instead of crashing.
   firehose and the real interactive PTY over the minted `pty-ws` cell.
 - `useDesktopStream` — the noVNC socket, hot-swapped on box rollover via
   `stream.url.rotated`.
-- Components: `WorkspaceDock` (the resizable/collapsible right-hand dock),
+- Components: `WorkspaceDock` (the resizable/collapsible right-hand dock with a
+  vertical activity rail, persistent visited panels, and a panel-local Hide action),
   `FileBrowser` / `SandboxFiles`, `DiffView` / `PierreDiff` / `PierreFile`,
   `CodeEditor`, `SandboxTerminal`, and `DesktopViewer`.
 
 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
@@ -702,11 +1169,15 @@ never pull it in.
   plus the `MachineView` / `MachineState` / `MetricSample` view-model types.
 
 ```tsx
-import { MachinesDashboard, useMachines } from "@opengeni/react/machines";
+import {
+  MACHINES_SESSION_POLL_MS,
+  MachinesDashboard,
+  useMachines,
+} from "@opengeni/react/machines";
 
 function Fleet({ sessionId }: { sessionId: string }) {
   const { machines, activeSandboxId, attach, attachingSandboxId, refresh } =
-    useMachines({ sessionId, pollIntervalMs: 5000 });
+    useMachines({ sessionId, pollIntervalMs: MACHINES_SESSION_POLL_MS });
   return (
     <MachinesDashboard
       machines={machines}
@@ -722,11 +1193,46 @@ 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).
+
 ## 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`.
@@ -736,6 +1242,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
@@ -744,3 +1281,96 @@ 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.
+
+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.