@opengeni/react 7.4.0 → 7.5.0-canary.36927100590001

package/README.md

@@ -115,6 +115,11 @@ separately. Pass `conversationProps` for message rendering and tool renderers,
 deployment enables uploads (`attachments={false}` opts out), pending tool
 approvals render Approve/Reject, 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()`
@@ -639,13 +644,22 @@ 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.
 
+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. **Choose option** remains an explicit fallback for older
-controllers and controls that cannot be identified automatically. Selection uses the
-normal browser action API. The viewer retains that
+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
@@ -906,6 +920,8 @@ intentional changes should regenerate those snapshots and review the diff.
   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
@@ -967,12 +983,25 @@ 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 (below
-Latest question when shown) until their own details end; nested headers never stick.
-
-Wire the newest-question resolver when history can be unloaded:
-
-`SessionConversation` includes the readable-turn presentation and this wiring automatically.
+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);
@@ -982,28 +1011,32 @@ const events = useSessionEvents(sessionId);
   turnSummary={{ rolling: true }}
   hasNewer={events.hasNewer}
   onJumpToLatest={events.jumpToLatest}
-  onJumpToLatestQuestion={events.jumpToLatestQuestion}
 />;
 ```
 
-The single **Latest question** button targets the newest durable user message,
-not the viewport-relative question or the newest message in an older loaded page.
-The resolver checks the authoritative queue and normally uses one filtered forensic
+`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 the first click, not when opening a session.
+The optional resolver loads on its first invocation, not when opening a session.
 Identity and navigation guards also cover that module-loading delay.
 
-`SessionConversation` also opens and focuses the newest pending prompt in
-`SessionChrome`. Custom hosts can provide the same destination without changing
-the existing `Promise<number | null>` timeline callback:
+Custom hosts can provide their own queue destination when invoking this hook:
 
 ```tsx
-onJumpToLatestQuestion={() => events.jumpToLatestQuestion({
+const navigateToNewest = () => events.jumpToLatestQuestion({
   onQueuedQuestion: async (turn, navigation) => {
     await queue.refresh();
     if (!navigation.isCurrent()) return;
@@ -1013,21 +1046,19 @@ onJumpToLatestQuestion={() => events.jumpToLatestQuestion({
       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 produces explicit queue guidance in the
-timeline; transitional queue state can be retried rather than silently no-oping.
+`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.
-Without `onJumpToLatestQuestion`, local navigation is available only at the live history
-window; the component never guesses from an older page. `onJumpToLatest` retains
-its separate bottom-follow behavior. `groupTimeline(items)` retains classic
+`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).
@@ -1114,11 +1145,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`.
@@ -1128,6 +1194,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

package/dist/artifacts-document.js

@@ -4,8 +4,9 @@ import {
   DocumentProjectionArtifactSurface,
   DocumentProjectionEditor,
   EditableDocumentArtifactSurface
-} from "./chunk-3E2AITTZ.js";
-import "./chunk-DUEBTL3N.js";
+} from "./chunk-WUISZ3WU.js";
+import "./chunk-WEHMPOXK.js";
+import "./chunk-Y2PRMYLC.js";
 import "./chunk-22KP6LR5.js";
 export {
   DocumentArtifactSurface,

package/dist/artifacts-presentation.js

@@ -4,8 +4,9 @@ import {
   PresentationEditor,
   PresentationProjectionArtifactSurface,
   PresentationProjectionEditor
-} from "./chunk-KNDIXZN6.js";
-import "./chunk-DUEBTL3N.js";
+} from "./chunk-7UAMYXJY.js";
+import "./chunk-WEHMPOXK.js";
+import "./chunk-Y2PRMYLC.js";
 import "./chunk-22KP6LR5.js";
 export {
   EditablePresentationArtifactSurface,

package/dist/artifacts-spreadsheet.js

@@ -4,8 +4,8 @@ import {
   SpreadsheetArtifactSurface,
   SpreadsheetGrid,
   SpreadsheetProjectionGrid
-} from "./chunk-SEEVCT36.js";
-import "./chunk-DUEBTL3N.js";
+} from "./chunk-A4UJB2MM.js";
+import "./chunk-Y2PRMYLC.js";
 import "./chunk-22KP6LR5.js";
 export {
   EditableSpreadsheetArtifactSurface,

package/dist/artifacts.d.ts

@@ -1,4 +1,5 @@
 export { inlineHtmlDocument } from "./components/artifacts/inline-html-document.js";
 export { isRetainedImageContentType, useRetainedImageObjectUrl } from "./timeline/retained-image.js";
+export { ArtifactBadge, ArtifactLabelsProvider, DEFAULT_ARTIFACT_LABELS, useArtifactLabels, type ArtifactLabels, ArtifactButton, ArtifactLoading, ArtifactProblem, ArtifactSelect, ArtifactViewerHeader, artifactKindIcon, artifactKindSubtitle, artifactLoadErrorMessage, artifactLoadErrorView, type ArtifactKind, type ArtifactLoadErrorKind, type ArtifactLoadErrorView, ArtifactSandbox, type ArtifactSandboxProps, DeferredChatMedia, SiteView, type SiteViewProps, ChatInteractiveBlock, type ChatInteractiveBlockProps, type SiteSnapshotClient, type SiteToolBridgeFactory, type SiteToolScope, EditableArtifactView, type EditableArtifactRuntimes, type EditableArtifactViewProps, type OpenedEditableArtifact, SessionArtifactViewer, type SessionArtifactTarget, type SessionArtifactViewerLabels, type SessionArtifactViewerProps, } from "./components/artifacts/index.js";
 /** Public artifact surfaces. Import from `@opengeni/react/artifacts`. */
 export { ArtifactSurface, DocumentArtifactSurface, DocumentEditor, DocumentProjectionArtifactSurface, DocumentProjectionEditor, BrowserEditableArtifactWorkbench, EditableDocumentArtifactSurface, EditableArtifactWorkbench, EditableArtifactWorkbenchHost, EditablePresentationArtifactSurface, EditableSpreadsheetArtifactSurface, EditableSpreadsheetGrid, PresentationArtifactSurface, PresentationEditor, PresentationProjectionArtifactSurface, PresentationProjectionEditor, PublishedHtmlArtifactFrame, PUBLISHED_HTML_ARTIFACT_IFRAME_SANDBOX, openGeniSiteBridgePortFromBootstrap, publishedHtmlArtifactDocument, SpreadsheetArtifactSurface, SpreadsheetGrid, SpreadsheetProjectionGrid, type ArtifactModality, type ArtifactSurfaceProps, type DocumentArtifactSurfaceProps, type DocumentCommit, type DocumentCommitHandler, type DocumentEditorProps, type DocumentEditorProjection, type DocumentLayoutMode, type DocumentProjectionArtifactSurfaceProps, type DocumentProjectionBlock, type DocumentProjectionChange, type DocumentProjectionComment, type DocumentProjectionEditorProps, type DocumentProjectionPageBreak, type DocumentProjectionPageGeometry, type DocumentProjectionParagraph, type DocumentProjectionParagraphStyle, type DocumentProjectionSection, type DocumentProjectionTable, type DocumentProjectionTextRun, type DocumentProjectionTextStyle, type DocumentSelection, type BrowserEditableArtifactWorkbenchOptions, type BrowserEditableArtifactWorkbenchProps, type EditableDocumentArtifactSurfaceProps, type EditableArtifactWorkbenchHostProps, type EditableArtifactWorkbenchProps, type EditablePresentationArtifactSurfaceProps, type EditableSpreadsheetArtifactSurfaceProps, type EditableSpreadsheetGridProps, type PresentationArtifactSurfaceProps, type PresentationCommit, type PresentationCommitHandler, type PresentationEditorProps, type PresentationEditorProjection, type PresentationProjectionArtifactSurfaceProps, type PresentationProjectionChart, type PresentationProjectionChartSeries, type PresentationProjectionConnector, type PresentationProjectionEditorProps, type PublishedHtmlArtifactFrameProps, type PublishedHtmlArtifactToolBridge, type PresentationProjectionElementMetadata, type PresentationProjectionElement, type PresentationProjectionFill, type PresentationProjectionGroup, type PresentationProjectionImage, type PresentationProjectionLine, type PresentationProjectionPosition, type PresentationProjectionRichText, type PresentationProjectionShape, type PresentationProjectionTable, type PresentationProjectionTableCell, type PresentationProjectionTextParagraph, type PresentationProjectionTextRun, type PresentationProjectionTextStyle, type PresentationSlideProjection, type SpreadsheetArtifactSurfaceProps, type SpreadsheetCommit, type SpreadsheetRangeCommit, type SpreadsheetGridProps, type SpreadsheetGridProjection, type SpreadsheetProjectionCell, type SpreadsheetProjectionGridProps, type SpreadsheetSelection, type SpreadsheetViewport, } from "./components/artifacts/index.js";