@opengeni/react 1.0.1 → 1.0.2-canary.37202341988001

package/dist/components/message-timeline.d.ts

@@ -1,15 +1,36 @@
+import { type TimelineSearchTarget } from "./timeline-search.js";
+import { type GenieLoadingOptions } from "../timeline/genie-loading.js";
 import type { DraftTimelineAnnotation, SessionEvent, SessionStatus } from "@opengeni/sdk";
 import { type ReactNode } from "react";
+import { type OlderHistoryLoader } from "../older-history.js";
+import { type MarkdownProps } from "./markdown.js";
+import { type OpenGeniLinkResolver } from "./open-geni-links.js";
+import { type UserMessageDisclosureLabels } from "./user-message-body.js";
 import { type AgentMessageItem, type AuthNeededItem, type TimelineGroup, type TimelineItem, type RetainedArtifactLoader, type RetainedScreenshotLoader, type VideoArtifactPlaybackLoader, type ToolRegistry, type TurnSummaryOptions, type UserMessageItem } from "../timeline/index.js";
+import { type RenderAllowanceExhausted } from "../timeline/allowance-exhausted-row.js";
+import type { AllowanceLabels } from "../usage/allowance-copy.js";
 export type MessageTimelineProps = {
+    /** Exact durable search hit; clearing it removes highlighting without moving the reader. */
+    searchTarget?: TimelineSearchTarget | null | undefined;
+    /** Localized user-message disclosure actions, including custom UserMessageBody renderers. */
+    userMessageDisclosureLabels?: UserMessageDisclosureLabels | undefined;
     /** Raw session events (projected internally) … */
     events?: SessionEvent[] | undefined;
     /** … or pre-projected items (e.g. from `useSessionEvents().timeline`). */
     items?: TimelineItem[] | undefined;
     /** Current session status (reserved; tip "Working…" chrome removed for now). */
     status?: SessionStatus | null | undefined;
+    /** Host-owned controls beside Copy and the timestamp on settled message rows. */
+    renderMessageActions?: ((item: AgentMessageItem | UserMessageItem) => ReactNode) | undefined;
     /** Plug a markdown renderer for message bodies (e.g. streamdown). */
-    renderMessageText?: ((text: string, item: AgentMessageItem | UserMessageItem) => ReactNode) | undefined;
+    renderMessageText?: ((text: string, item: AgentMessageItem | UserMessageItem, context: {
+        searchTarget: TimelineSearchTarget | null;
+    }) => ReactNode) | undefined;
+    /**
+     * Render assistant `opengeni-html` / `opengeni-site` fences in the default
+     * message renderer (`SessionConversation` supplies the inline Site preview).
+     */
+    renderInteractiveBlock?: MarkdownProps["renderInteractiveBlock"];
     /** Drill into a spawned worker session. */
     onOpenSession?: ((sessionId: string) => void) | undefined;
     /**
@@ -29,6 +50,17 @@ export type MessageTimelineProps = {
      * a Reconnect button without a handler to run it.
      */
     onReconnect?: ((item: AuthNeededItem) => void | Promise<void>) | undefined;
+    /** Host-owned inline connection setup. Return undefined to use the default recovery card. */
+    renderAuthNeeded?: ((item: AuthNeededItem) => ReactNode | undefined) | undefined;
+    /**
+     * Replace the "usage limit reached" row shown when a workspace or member
+     * usage allowance stops work (an `allowance_exhausted` refusal). Receives the
+     * typed refusal (scope, reset time) and the default row; return undefined to
+     * keep the default. Use it to point people at your own plan or admin page.
+     */
+    renderAllowanceExhausted?: RenderAllowanceExhausted | undefined;
+    /** Replace the words of the default "usage limit reached" row. */
+    allowanceExhaustedLabels?: Partial<AllowanceLabels> | undefined;
     /**
      * Decide which durable authentication notices this timeline presents.
      * Defaults to showing every notice. Embedded hosts can suppress notices for
@@ -49,9 +81,19 @@ export type MessageTimelineProps = {
      * `createDefaultToolRegistry({ entries })` to add custom tool renderers.
      */
     toolRegistry?: ToolRegistry | undefined;
+    /**
+     * Open OpenGeni object links the agent writes in replies and progress notes:
+     * `artifact:<file>`, `sandbox:<path>`, editable artifacts, and Sites. Return
+     * a host URL (`{ href }`) or action (`{ open }`); unhandled targets render as
+     * unavailable text instead of a console link that 404s inside the host.
+     * Applies to the default message renderer and to any `Markdown` a custom
+     * `renderMessageText` renders. `SessionConversation` supplies file and
+     * sandbox downloads by default.
+     */
+    resolveLink?: OpenGeniLinkResolver | undefined;
     /** Resolve opaque retained screenshot receipts through the authenticated host SDK. */
     loadRetainedScreenshot?: RetainedScreenshotLoader | undefined;
-    /** Resolve permanent generated-image receipts through the authenticated host SDK. */
+    /** Resolve permanent workspace image/file receipts through the authenticated host SDK. */
     loadRetainedArtifact?: RetainedArtifactLoader | undefined;
     /** Mint short-lived native playback sources for retained generated videos. */
     loadVideoArtifactPlayback?: VideoArtifactPlaybackLoader | undefined;
@@ -61,17 +103,32 @@ export type MessageTimelineProps = {
      */
     computeLabel?: string | null | undefined;
     /** Customize collapsed turn facets for this timeline instance. */
+    genieLoading?: GenieLoadingOptions | undefined;
     turnSummary?: TurnSummaryOptions | undefined;
     /** Follow new events when pinned to the bottom. Defaults to true. */
     autoFollow?: boolean | undefined;
     /** Capture a same-row text selection into the host's canonical composer draft. */
     onAnnotate?: ((annotation: DraftTimelineAnnotation) => void) | undefined;
+    /**
+     * Hide the floating "Back to your message" pill while the timeline viewport
+     * is shorter than this (px), e.g. a narrow embed above a decision card.
+     * Defaults to 0 (always available).
+     */
+    questionNavMinViewportHeight?: number | undefined;
+    /** Composer draft quotes currently attached to the next send. */
+    draftAnnotations?: readonly DraftTimelineAnnotation[] | undefined;
+    /** Open the composer review list for one numbered draft badge. */
+    onDraftAnnotationSelect?: ((id: string) => void) | undefined;
     /** Older durable history exists above the current window (see useSessionEvents). */
     hasOlder?: boolean | undefined;
     /** An older window is being fetched; shows the quiet top shimmer. */
     loadingOlder?: boolean | undefined;
-    /** Called when the reader nears the top and older history should backfill. */
-    onLoadOlder?: (() => void) | undefined;
+    /**
+     * Called when older history should backfill. Existing void, synchronous-value,
+     * and arbitrary-promise callbacks remain supported. Receipt-aware loaders
+     * preserve committed-page direction through wrappers and bounded windows.
+     */
+    onLoadOlder?: OlderHistoryLoader | undefined;
     /** Jump to the durable session start (bounded oldest window, no middle). */
     onJumpToStart?: (() => void | Promise<void>) | undefined;
     /** True while the oldest window is loading. */
@@ -80,13 +137,16 @@ export type MessageTimelineProps = {
     hasNewer?: boolean | undefined;
     /** A newer history page is being fetched. */
     loadingNewer?: boolean | undefined;
-    /** Page forward through history without loading the whole gap to the tip. */
-    onLoadNewer?: (() => void) | undefined;
+    /** Page forward through history. Return the request promise to enable inline error/retry. */
+    onLoadNewer?: (() => unknown) | undefined;
     /**
      * Reload the live tip window. When omitted, Jump to latest only re-pins and
      * scrolls the in-memory window.
      */
     onJumpToLatest?: (() => void | Promise<void>) | undefined;
+    /** @deprecated Retained for source compatibility; contextual prompt navigation
+     * uses only mounted prompts and never invokes this global resolver. */
+    onJumpToLatestQuestion?: (() => Promise<number | null>) | undefined;
     /** Host-owned content appended after timeline groups, such as startup progress. */
     trailingState?: ReactNode | undefined;
     emptyState?: ReactNode | undefined;
@@ -98,7 +158,7 @@ export type MessageTimelineProps = {
  * cards, goal markers, and status transitions. Owns stick-to-bottom scrolling
  * with a "jump to latest" affordance when the reader scrolls back.
  */
-export declare function MessageTimeline({ events, items, status: _status, renderMessageText, onOpenSession, onMemoryClick, onReconnect, shouldRenderAuthNeeded, resolveProviderLogo, toolRegistry, loadRetainedScreenshot, loadRetainedArtifact, loadVideoArtifactPlayback, computeLabel, turnSummary, autoFollow, onAnnotate, hasOlder, loadingOlder, onLoadOlder, onJumpToStart, loadingOldest, hasNewer, loadingNewer, onLoadNewer, onJumpToLatest, trailingState, emptyState, className, }: MessageTimelineProps): import("react").JSX.Element;
+export declare function MessageTimeline({ resolveLink, renderInteractiveBlock, userMessageDisclosureLabels, searchTarget, events, items, status: _status, renderMessageActions, renderMessageText, onOpenSession, onMemoryClick, onReconnect, renderAuthNeeded, renderAllowanceExhausted, allowanceExhaustedLabels, shouldRenderAuthNeeded, resolveProviderLogo, toolRegistry, loadRetainedScreenshot, loadRetainedArtifact, loadVideoArtifactPlayback, computeLabel, genieLoading, turnSummary, autoFollow, onAnnotate, questionNavMinViewportHeight, draftAnnotations, onDraftAnnotationSelect, hasOlder, loadingOlder, onLoadOlder, onJumpToStart, loadingOldest, hasNewer, loadingNewer, onLoadNewer, onJumpToLatest, trailingState, emptyState, className, }: MessageTimelineProps): import("react").JSX.Element;
 /**
  * Settled turns lift the final agent answer out as a sibling group. Include it
  * in "Copy turn" when present so the chip copies the full assistant reply.
@@ -110,11 +170,14 @@ export declare function trailingAgentTextAfterTurn(group: TimelineGroup, next: T
  * landmark, notice). Exported so the component demo draws the EXACT same rows as
  * the live app — no forked bubble/goal markup.
  */
-export declare function TimelineRow({ item, renderMessageText, onReconnect, resolveProviderLogo, onOpenSession, loadVideoArtifactPlayback, }: {
+export declare function TimelineRow({ item, renderMessageActions, renderMessageText, onReconnect, renderAuthNeeded, resolveProviderLogo, onOpenSession, loadVideoArtifactPlayback, }: {
     item: TimelineItem;
+    renderMessageActions?: ((item: AgentMessageItem | UserMessageItem) => ReactNode) | undefined;
     renderMessageText?: ((text: string, item: AgentMessageItem | UserMessageItem) => ReactNode) | undefined;
     onReconnect?: ((item: AuthNeededItem) => void | Promise<void>) | undefined;
+    /** Host-owned inline connection setup. Return undefined to use the default recovery card. */
+    renderAuthNeeded?: ((item: AuthNeededItem) => ReactNode | undefined) | undefined;
     resolveProviderLogo?: ((providerDomain: string) => string | null | undefined) | undefined;
     onOpenSession?: ((sessionId: string) => void) | undefined;
     loadVideoArtifactPlayback?: VideoArtifactPlaybackLoader | undefined;
-}): import("react").JSX.Element | null;
+}): string | number | bigint | boolean | import("react").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | Iterable<ReactNode> | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | import("react").ReactPortal | null | undefined> | null;

package/dist/components/model-mark.d.ts

@@ -0,0 +1,29 @@
+import { type ModelDisplayInput } from "@opengeni/sdk/model-display";
+import type { ReactNode, SVGProps } from "react";
+/** ChatGPT / OpenAI mark (Simple Icons path), currentColor like the other marks. */
+export declare function ChatGptMark(props: SVGProps<SVGSVGElement>): import("react").JSX.Element;
+/** True when `ModelMark` has a real maker logo for this model (not the neutral fallback). */
+export declare function modelHasMark(model: ModelDisplayInput): boolean;
+/**
+ * The model maker's logo (OpenAI, Claude, Grok), never the connection that
+ * serves it. Makers without a bundled logo get a neutral mark, so an org- and
+ * a workspace-connected copy of one model always look the same.
+ */
+export declare function ModelMark(props: {
+    model: ModelDisplayInput;
+    className?: string | undefined;
+    /** Shown when the maker has no bundled logo. Defaults to a neutral sparkle. */
+    fallback?: ReactNode;
+    "aria-label"?: string | undefined;
+}): import("react").JSX.Element | null;
+/**
+ * A model as people should see it outside model settings: the maker's mark and
+ * the clean display name. Never a routing prefix, connection id or scope.
+ */
+export declare function ModelName(props: {
+    model: ModelDisplayInput;
+    /** Hide the maker mark for dense text-only contexts. */
+    mark?: boolean | undefined;
+    className?: string | undefined;
+    markClassName?: string | undefined;
+}): import("react").JSX.Element;

package/dist/components/model-policy-picker-menu.d.ts

@@ -0,0 +1,9 @@
+import { type RefObject, type CSSProperties } from "react";
+import { type ModelPolicyPickerProps } from "./model-policy-picker.js";
+/** Model selection stays flat; reasoning never becomes a navigation destination. */
+export declare function ModelPolicyPickerMenu(props: ModelPolicyPickerProps): import("react").JSX.Element;
+export declare function ModelPolicyPickerPopover(props: ModelPolicyPickerProps & {
+    anchor: RefObject<HTMLButtonElement | null>;
+    contentId: string;
+    portalStyle: CSSProperties;
+}): import("react").JSX.Element;

package/dist/components/model-policy-picker.d.ts

@@ -1,27 +1,44 @@
 import type { ClientModel, LatencyMode, ReasoningEffort } from "@opengeni/sdk";
 import { type CSSProperties, type ReactNode } from "react";
 import { type PickerBillingClass, type PickerModelRow } from "../model-policy.js";
-type NavLevel = "providers" | "models" | "thinking";
-type PickerNavState = {
-    level: NavLevel;
-    rail: PickerBillingClass | null;
-    modelId: string | null;
-};
-type NavUpdater = PickerNavState | ((previous: PickerNavState) => PickerNavState);
+type ClientPickerModelRow = PickerModelRow<ClientModel>;
+/** Presentation only; never changes model identity, billing or availability. */
+export type ModelPolicyPickerGroupPresentation = Partial<Record<PickerBillingClass, {
+    label?: string | undefined;
+    /** Omit to preserve the default; null hides the supporting text. */
+    description?: string | null | undefined;
+    /** Decorative, non-interactive content. Omit for the default; null hides it. */
+    icon?: ReactNode | undefined;
+}>>;
 export type ModelPolicyPickerMessages = {
     label: string;
     loading: string;
     noModels: string;
+    connectTitle: string;
+    connectBody: string;
+    connectAction: string;
     thinking: string;
     fast: string;
     fastRateHint: string;
     codexOnly: string;
+    searchLabel?: string;
+    searchPlaceholder?: string;
+    currentModel?: string;
+    noMatches?: string;
+    unsupportedAttachments?: string;
+    thinkingEffort?: string;
+    selected?: string;
+    free?: string;
     billingHints: Record<PickerBillingClass, string>;
 };
 export declare const defaultModelPolicyPickerMessages: ModelPolicyPickerMessages;
 export type ModelPolicyPickerProps = {
+    /** Host branding for payment-source groups, shared by menu and trigger. */
+    groupPresentation?: ModelPolicyPickerGroupPresentation | undefined;
     /** Lightweight deployment models. Catalog rows take precedence when supplied. */
     models?: ClientModel[] | undefined;
+    /** Warn only when the draft actually contains images this model cannot view. */
+    hasImageAttachments?: boolean | undefined;
     /** Catalog-backed rows with availability and billing-class truth. */
     rows?: PickerModelRow[] | undefined;
     model: string;
@@ -37,15 +54,35 @@ export type ModelPolicyPickerProps = {
     onOpenChange?: ((open: boolean) => void) | undefined;
     /** Non-Codex models stay visible but cannot be selected. */
     codexOnly?: boolean | undefined;
-    /** Resets drill-down navigation when the session scope changes. */
+    /** Identity of the current session scope. */
     sessionKey?: string | undefined;
     /** Prefer bottom on new-chat surfaces and top for bottom-docked composers. */
     menuSide?: "top" | "bottom" | undefined;
+    /**
+     * Default true: show models the way people choose them, with clean names,
+     * maker marks, one "API keys" group for organization- and workspace-connected
+     * keys, and one row for identical copies. Models settings passes false to
+     * keep its scope-aware presentation (raw catalog labels, scoped groups).
+     */
+    collapseScopes?: boolean | undefined;
+    /** Hide latency controls on surfaces whose saved policy does not include latency. */
+    allowLatencyMode?: boolean | undefined;
+    /** Settings → Models. Shown when the catalog has no model that can run. */
+    connectModelsHref?: string | undefined;
     /** Classes for the portalled menu surface. Prefer --og-* tokens for theming. */
     contentClassName?: string | undefined;
     /** Inline styles for the portalled menu, applied after inherited --og-* tokens. */
     contentStyle?: CSSProperties | undefined;
     className?: string | undefined;
+    /**
+     * "pill" (default) is the composer's quiet rounded trigger with the effort.
+     * "field" is a settings control: a bordered rectangle with the model name
+     * and `triggerMeta` (for example the payer) in muted text. The effort stays
+     * in the menu.
+     */
+    triggerStyle?: "pill" | "field" | undefined;
+    /** Muted text after the model name in the "field" trigger. */
+    triggerMeta?: ReactNode;
     messages?: Partial<ModelPolicyPickerMessages> | undefined;
     onModelChange: (modelId: string) => void;
     onEffortChange: (effort: ReasoningEffort) => void;
@@ -53,9 +90,18 @@ export type ModelPolicyPickerProps = {
 };
 export declare function BillingClassMark(props: {
     billingClass: PickerBillingClass;
+    presentation?: ModelPolicyPickerGroupPresentation[PickerBillingClass] | undefined;
     className?: string | undefined;
     "aria-label"?: string | undefined;
-}): import("react").JSX.Element;
+}): import("react").JSX.Element | null;
+/** Models settings keeps naming who is billed for a key. */
+export declare const SCOPED_BILLING_HINTS: Partial<Record<PickerBillingClass, string>>;
+/**
+ * Host branding for a payment group. While scopes are collapsed, API keys are
+ * one group, so either API-key presentation serves both.
+ */
+export declare function groupPresentationFor(props: Pick<ModelPolicyPickerProps, "groupPresentation" | "collapseScopes">, billingClass: PickerBillingClass): ModelPolicyPickerGroupPresentation[PickerBillingClass];
+export declare function effectiveRows(props: ModelPolicyPickerProps): ClientPickerModelRow[];
 export declare function PickerNavRow(props: {
     label: string;
     hint?: string | undefined;
@@ -64,6 +110,7 @@ export declare function PickerNavRow(props: {
     showChevron?: boolean | undefined;
     disabled?: boolean | undefined;
     title?: string | undefined;
+    description?: string | undefined;
     active?: boolean | undefined;
     testId?: string | undefined;
     onClick: () => void;
@@ -79,9 +126,11 @@ export declare function PickerAnimatedPage(props: {
     direction: 1 | -1;
     children: ReactNode;
 }): import("react").JSX.Element;
-export declare function ModelPolicyPickerMenu(props: ModelPolicyPickerProps & {
-    nav?: PickerNavState | undefined;
-    onNavChange?: ((next: NavUpdater) => void) | undefined;
-}): import("react").JSX.Element;
+/** @internal Shared controlled/uncontrolled state seam. */
+export declare function useModelPolicyPickerState(props: ModelPolicyPickerProps): {
+    open: boolean;
+    setOpen: (next: boolean) => void;
+    rows: ClientPickerModelRow[];
+};
 export declare function ModelPolicyPicker(props: ModelPolicyPickerProps): import("react").JSX.Element;
 export {};

package/dist/components/open-geni-chat.d.ts

@@ -0,0 +1,58 @@
+import { type CSSProperties } from "react";
+import { type HostSurfacePreference, type HostThemePreference } from "../lib/host-theme.js";
+import { type ClientOverride } from "../session-context.js";
+import { type SessionConversationProps } from "./session-conversation.js";
+import { type SessionListLabels, type SessionListProps } from "./session-list.js";
+import { type SessionProxyBaseUrl } from "./session-proxy-scope.js";
+export type OpenGeniChatLabels = SessionListLabels & {
+    openChats: string;
+    closeChats: string;
+    newChatPlaceholder: string;
+    /** Heading above the new-chat composer; empty hides it. */
+    newChatTitle: string;
+    send: string;
+    newChatUnavailable: string;
+};
+export type OpenGeniChatProps = ClientOverride & SessionProxyBaseUrl & {
+    /** Controlled selection. `null` shows the new-chat composer. */
+    sessionId?: string | null | undefined;
+    /** Initial selection when uncontrolled. Defaults to a new chat. */
+    defaultSessionId?: string | null | undefined;
+    onSessionChange?: ((sessionId: string | null) => void) | undefined;
+    /**
+     * Create a chat from its first message. Defaults to `client.createSession`
+     * with `{ initialMessage, idempotencyKey }`, which `createSessionProxyHandler`
+     * accepts when the server supplies a `createSession` hook. Return the new id.
+     */
+    createSession?: ((initialMessage: string, idempotencyKey: string) => Promise<string>) | undefined;
+    /** Hide the "New chat" entry point. */
+    newChat?: boolean | undefined;
+    /** Forwarded to the conversation (message rendering, tool renderers, composer...). */
+    conversationProps?: Omit<SessionConversationProps, "sessionId" | "client" | "workspaceId" | "baseUrl">;
+    /** Forwarded to the list (rename/archive toggles, page size). */
+    listProps?: Pick<SessionListProps, "rename" | "archive" | "pageSize"> | undefined;
+    labels?: Partial<OpenGeniChatLabels> | undefined;
+    className?: string | undefined;
+    /** Defaults to filling the host. */
+    height?: CSSProperties["height"];
+    /**
+     * Light or dark. Defaults to `auto`: follow the host page (an enclosing
+     * `data-og-theme`, `class="dark"`/`data-theme` on <html> or <body>, the
+     * host's `color-scheme`, then its background), not the OS setting alone.
+     */
+    theme?: HostThemePreference | undefined;
+    /**
+     * `host` (default) derives backgrounds and cards from the host background so
+     * the chat blends in; `theme` uses the `--og-color-*` surface tokens as they
+     * are. Customized surface tokens are always kept.
+     */
+    surface?: HostSurfacePreference | undefined;
+};
+/**
+ * A complete chat experience: the user's chat list plus the conversation.
+ * The list is a sidebar when the component is wide and a drawer when narrow
+ * (container-based, so it adapts inside panels as well as full pages).
+ * `<OpenGeniChat baseUrl="/api/opengeni" />` needs no provider: it talks to
+ * your session proxy and uses the workspace the proxy resolves.
+ */
+export declare function OpenGeniChat({ baseUrl, ...props }: OpenGeniChatProps): import("react").JSX.Element;

package/dist/components/open-geni-links.d.ts

@@ -0,0 +1,68 @@
+import type { OpenGeniClient, OpenGeniLinkTarget } from "@opengeni/sdk";
+import { type ReactNode } from "react";
+export type { OpenGeniLinkTarget };
+/**
+ * How the host opens one OpenGeni object an agent linked in chat Markdown.
+ *
+ * - `{ href }` renders a real link (new tab) — use it for a host page URL.
+ * - `{ open }` renders a button that runs the action (download, open a panel,
+ *   client-side navigation) with loading and retry states.
+ * - `null` / `undefined` means "not handled here": the next resolver is asked,
+ *   and when none handles it the text renders as an unavailable reference —
+ *   never as a navigation that would 404 inside the host.
+ */
+export type OpenGeniLinkResolution = {
+    href: string;
+    open?: undefined;
+} | {
+    open: () => void | Promise<void>;
+    href?: undefined;
+};
+export type OpenGeniLinkResolver = (target: OpenGeniLinkTarget) => OpenGeniLinkResolution | null | undefined;
+/** First resolver that handles a target wins. */
+export declare function chainLinkResolvers(...resolvers: ReadonlyArray<OpenGeniLinkResolver | null | undefined>): OpenGeniLinkResolver | null;
+/**
+ * Resolve OpenGeni object links (`artifact:`, `sandbox:`, editable artifacts,
+ * Sites) for every {@link Markdown} body below. An inner provider is asked
+ * before an outer one, so a host can override a single kind and keep defaults.
+ */
+export declare function OpenGeniLinkProvider({ resolveLink, children, }: {
+    resolveLink: OpenGeniLinkResolver | null | undefined;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** The effective resolver from the nearest {@link OpenGeniLinkProvider}. */
+export declare function useOpenGeniLinkResolver(): OpenGeniLinkResolver | null;
+type SessionLinkClient = Partial<Pick<OpenGeniClient, "createFileDownloadUrl" | "fsRead">>;
+/**
+ * Default resolver for a session conversation that talks to OpenGeni through
+ * the normal SDK client (for example behind `createSessionProxyHandler`):
+ *
+ * - `artifact:<file>` downloads the retained file through a short-lived URL.
+ * - `sandbox:<path>` downloads when enabled by the host proxy capability.
+ *
+ * Editable artifacts and Sites have no default: they need a host surface
+ * (see `@opengeni/react/artifacts/*` and `@opengeni/react/sites`), so they stay
+ * unavailable until the host resolves them.
+ */
+export declare function sessionLinkResolver(input: {
+    client: SessionLinkClient;
+    workspaceId: string;
+    sessionId: string;
+    sandboxFiles?: boolean;
+}): OpenGeniLinkResolver;
+/** An editable artifact or Site to open in a host-mounted viewer. */
+export type OpenGeniViewerTarget = Readonly<{
+    kind: "editable-artifact" | "site";
+    artifactId: string;
+    /** The link text the agent wrote, until the viewer loads the real title. */
+    title?: string | undefined;
+}>;
+/**
+ * "Open in host viewer": resolve agent links to editable artifacts and Sites
+ * in this workspace to `open(target)`, for example to mount
+ * `SessionArtifactViewer` beside the conversation. Other targets fall through.
+ */
+export declare function viewerLinkResolver(input: {
+    workspaceId: string;
+    open: (target: OpenGeniViewerTarget) => void;
+}): OpenGeniLinkResolver;

package/dist/components/openrouter-mark.d.ts

@@ -0,0 +1,6 @@
+import type { SVGProps } from "react";
+/**
+ * Simple Icons, CC0; https://github.com/simple-icons/simple-icons
+ * Source: https://raw.githubusercontent.com/simple-icons/simple-icons/develop/icons/openrouter.svg
+ */
+export declare function OpenRouterMark(props: SVGProps<SVGSVGElement>): import("react").JSX.Element;

package/dist/components/pierre-file.d.ts

@@ -1,6 +1,6 @@
 import { type ReactNode } from "react";
 export type PierreFileProps = {
-    /** Workspace-relative path (used for the header + language inference). */
+    /** Target path (used for the header + language inference). */
     path: string;
     /** The decoded text contents. */
     contents: string;

package/dist/components/preview-loading.d.ts

@@ -0,0 +1,2 @@
+/** Private loading surface: never receives or executes the unfinished fence. */
+export declare function PreviewLoading(): import("react").JSX.Element;

package/dist/components/queue-item-content.d.ts

@@ -0,0 +1,9 @@
+/**
+ * One presentation rule for a queued item, shared by the full queue and the
+ * compact session-chrome dock so the two cannot drift. A turn with an empty
+ * prompt and timeline annotations is valid content; an item with neither is a
+ * malformed or legacy object that gets an explicit fallback, never a blank row.
+ */
+export type QueueItemContent = "text" | "annotations" | "unavailable";
+export declare const QUEUE_ITEM_CONTENT_UNAVAILABLE = "Content unavailable";
+export declare function queueItemContent(text: string, annotationCount: number): QueueItemContent;

package/dist/components/sandbox-files.d.ts

@@ -1,5 +1,6 @@
 import { type UseSandboxFilesResult } from "../hooks/use-sandbox-files.js";
 import type { UseSandboxGitResult } from "../hooks/use-sandbox-git.js";
+import { type FileNodeVisibilityPredicate } from "../file-node-visibility.js";
 export type SandboxFilesProps = {
     /** From `useSandboxFiles(...)`. */
     files: UseSandboxFilesResult;
@@ -19,8 +20,16 @@ export type SandboxFilesProps = {
      *  dock warms the box on this so the save lands fast; opening/reading never fires
      *  it. Browsing the tree/diff must not warm a box. */
     onEditIntent?: (() => void) | undefined;
-    /** A guarded diff path routed here by the parent workspace. */
+    /** Restore the file last viewed in this task. Invalid/missing paths still
+     * surface the ordinary file-view error instead of changing files silently. */
+    initialSelectedPath?: string | null | undefined;
+    onSelectedPathChange?: ((path: string | null) => void) | undefined;
+    /** Presentation-only node filter shared with the tree and selected-file view. */
+    isNodeVisible?: FileNodeVisibilityPredicate | undefined;
+    /** A deliberate file-open path routed here by the parent workspace. */
     requestedPath?: string | undefined;
+    /** 1-based line to reveal after `requestedPath` opens. */
+    requestedLine?: number | null | undefined;
     /** Identity for one guarded-file request. Increment this when the same path is
      *  deliberately requested again; it also lets a pending request be consumed
      *  without overriding later manual tree navigation. Defaults to the path. */
@@ -34,6 +43,8 @@ export type SandboxFilesProps = {
     workspaceWaking?: boolean | undefined;
     /** Whether live reads are currently authoritative. */
     liveWorkspaceReady?: boolean | undefined;
+    /** Failed live negotiation; never present a failure as an ongoing wake. */
+    workspaceError?: Error | null | undefined;
     /** Deliberately wake the machine to read content absent from the capture. */
     onWakeWorkspace?: (() => void) | undefined;
     themeType?: "dark" | "light" | undefined;
@@ -46,4 +57,4 @@ export type SandboxFilesProps = {
  * surface deliberately does NOT replicate the changed-files list, and does not
  * diff here — one job per tab). The agent commits; the human reviews.
  */
-export declare function SandboxFiles({ files, git, fileSystemAvailable, usePierre, editable, onEditIntent, requestedPath, requestedPathRequestId, requestedPathReady, workspaceResting, workspaceWaking, liveWorkspaceReady, onWakeWorkspace, themeType, className, }: SandboxFilesProps): import("react").JSX.Element;
+export declare function SandboxFiles({ files, git, fileSystemAvailable, usePierre, editable, onEditIntent, initialSelectedPath, onSelectedPathChange, isNodeVisible, requestedPath, requestedLine, requestedPathRequestId, requestedPathReady, workspaceResting, workspaceWaking, liveWorkspaceReady, workspaceError, onWakeWorkspace, themeType, className, }: SandboxFilesProps): import("react").JSX.Element;

package/dist/components/sandbox-workspace.d.ts

@@ -3,6 +3,7 @@ import type { SessionEvent } from "@opengeni/sdk";
 import { type ClientOverride } from "../provider.js";
 import type { BrowserFrameWebSocketFactory } from "../hooks/use-browser-frame-stream.js";
 import type { ComputerFrameWebSocketFactory } from "../hooks/use-computer-frame-stream.js";
+import type { FileNodeVisibilityPredicate } from "../file-node-visibility.js";
 import { type MachineChip } from "../hooks/use-machine-chip.js";
 import type { MachineView } from "../types/machines.js";
 import { type WorkspaceDockProps, type WorkspaceTab } from "./workspace-dock.js";
@@ -38,7 +39,7 @@ export declare function initialWorkspaceTab(events: SessionEvent[] | undefined,
 export type WorkspaceMachine = {
     /** Whether at least one built-in workbench surface is enabled. */
     enabled: boolean;
-    /** The derived live/waking/offline chip model. */
+    /** The derived live/waking/sleeping-or-offline chip model. */
     chip: MachineChip;
     /** The machine these surfaces are bound to (the Modal group box or a
      *  self-hosted machine), or null while the fleet is still resolving. */
@@ -72,14 +73,27 @@ export type UseSandboxWorkspaceTabsOptions = ClientOverride & {
     browserWebSocketFactory?: BrowserFrameWebSocketFactory | undefined;
     /** Alternate Computer frame transport for non-browser runtimes and deterministic tests. */
     computerWebSocketFactory?: ComputerFrameWebSocketFactory | undefined;
+    /** Host-owned setup page or store listing for attaching an existing Chrome profile. */
+    browserExtensionSetupUrl?: string | undefined;
     /** File requested by a Changes guard. The Files surface defers the read until
      *  the sandbox is live, then reveals this path. */
     requestedFilePath?: string | null | undefined;
     /** Unique identity for `requestedFilePath`, including repeated requests for the
      *  same path. */
     requestedFileRequestId?: string | number | null | undefined;
+    /** 1-based line to reveal after `requestedFilePath` opens. */
+    requestedFileLine?: number | null | undefined;
     /** Route a guarded diff into the host's Files tab. */
     onOpenFile?: ((path: string) => void) | undefined;
+    /** Restore and report navigation inside the built-in workbench surfaces. */
+    initialFilePath?: string | null | undefined;
+    onFilePathChange?: ((path: string | null) => void) | undefined;
+    /** Presentation-only filter for Files tree nodes and selected-file viewing. */
+    isFileNodeVisible?: FileNodeVisibilityPredicate | undefined;
+    initialBrowserSessionId?: string | null | undefined;
+    onBrowserSessionIdChange?: ((browserSessionId: string | null) => void) | undefined;
+    initialComputerSessionId?: string | null | undefined;
+    onComputerSessionIdChange?: ((computerSessionId: string | null) => void) | undefined;
     /** Navigate the host dock to one exact linked ComputerSession. */
     onOpenComputerSession?: ((computerSessionId: string) => void) | undefined;
     requestedComputerSessionId?: string | null | undefined;
@@ -89,7 +103,8 @@ export type UseSandboxWorkspaceTabsResult = {
     /** Changes | Files | Terminal | Browser | Desktop (capability-gated where noted). */
     tabs: WorkspaceTab[];
     /** The source-driven default tab: Changes when the first authoritative capture
-     *  or live Git result has changes, else Files (a host `initialTab` overrides).
+     *  has changes, else Files (a host `initialTab` overrides). Choosing a tab
+     *  never performs hidden live workspace I/O.
      *  null while that source resolves, or permanently when neither Changes nor
      *  Files is enabled; the choice latches once. */
     defaultTab: string | null;
@@ -119,14 +134,39 @@ export type SandboxWorkspaceProps = ClientOverride & {
     /** Host tabs injected AFTER the workbench tabs (e.g. a "Debug" tab). */
     trailingTabs?: WorkspaceTab[] | undefined;
     /** Override the pre-paint default tab (e.g. a host landing tab id). When
-     *  omitted the workbench decides from capture, then live Git when no capture exists. */
+     *  omitted the workbench decides from the durable workspace capture. */
     initialTab?: string | undefined;
+    onActiveTabChange?: ((activeTab: string) => void) | undefined;
+    /** Open a built-in or host-injected tab. A new requestId reopens the same tab. */
+    openTabRequest?: {
+        tab: string;
+        requestId: number;
+    } | null | undefined;
+    initialFilePath?: string | null | undefined;
+    onFilePathChange?: ((path: string | null) => void) | undefined;
+    /** Presentation-only filter for Files tree nodes and selected-file viewing. */
+    isFileNodeVisible?: FileNodeVisibilityPredicate | undefined;
+    /**
+     * Host request to open a workspace file (and optional line) in Files. A new
+     * `requestId` re-opens even the same path.
+     */
+    openFileRequest?: {
+        path: string;
+        line?: number | null;
+        requestId: number;
+    } | null | undefined;
+    initialBrowserSessionId?: string | null | undefined;
+    onBrowserSessionIdChange?: ((browserSessionId: string | null) => void) | undefined;
+    initialComputerSessionId?: string | null | undefined;
+    onComputerSessionIdChange?: ((computerSessionId: string | null) => void) | undefined;
     /** Host-routed notifications (no toast dependency in the package). */
     onNotify?: ((notification: WorkspaceNotification) => void) | undefined;
     /** Alternate Browser frame transport for non-browser runtimes and deterministic tests. */
     browserWebSocketFactory?: BrowserFrameWebSocketFactory | undefined;
     /** Alternate Computer frame transport for non-browser runtimes and deterministic tests. */
     computerWebSocketFactory?: ComputerFrameWebSocketFactory | undefined;
+    /** Host-owned setup page or store listing for attaching an existing Chrome profile. */
+    browserExtensionSetupUrl?: string | undefined;
     /** Controlled collapsed state for hosts with their own dock toggle. */
     collapsed?: boolean | undefined;
     onCollapsedChange?: ((collapsed: boolean) => void) | undefined;