@opengeni/react 0.57.0 → 1.0.2-canary.37191796234001

package/dist/components/session-capability-frame.d.ts

@@ -0,0 +1,35 @@
+import { type ReactNode, type RefObject } from "react";
+export type SessionCapabilityFrameProps = {
+    name: string;
+    subtitle: string;
+    logo: string | null;
+    typeLabel: string;
+    description: string;
+    skill: boolean;
+    expanded: boolean;
+    complete: boolean;
+    /** Completion copy must reflect the provider's actual scope of access. */
+    completeLabel?: string;
+    actionLabel: string;
+    /** Direct navigation actions should not announce a dialog on the card. */
+    opensDialog?: boolean;
+    note: string;
+    onOpen(): void;
+    onClose(): void;
+    busy?: boolean;
+    opener?: RefObject<HTMLButtonElement | null>;
+    cardRef?: RefObject<HTMLElement | null>;
+    children?: ReactNode;
+    /** A catalogue row can own the opener while reusing the same details dialog. */
+    dialogOnly?: boolean;
+    /**
+     * Replaces the action when the viewer cannot start setup here (the provider
+     * is not configured, or someone else must connect it). Say why and who can.
+     */
+    actionUnavailable?: ReactNode;
+    /** Host-owned content inside the card, under its status or actions. */
+    details?: ReactNode;
+};
+/** The same conversation card in the console and embedded clients. Setup
+ * content owns the provider flow; this frame owns identity and protected focus. */
+export declare function SessionCapabilityFrame({ name, subtitle, logo, typeLabel, description, skill, expanded, complete, completeLabel, actionLabel, opensDialog, note, onOpen, onClose, busy, opener, cardRef, children, dialogOnly, actionUnavailable, details, }: SessionCapabilityFrameProps): import("react").JSX.Element;

package/dist/components/session-chrome.d.ts

@@ -28,15 +28,23 @@
  * Inbox has no product dismiss API; pass `onDismissIncoming` when the host
  * wants a visible action (dev harness may use a local dummy).
  *
- * Segment switches keep the panel shell mounted and crossfade content while
- * animating measured height — no `mode="wait"` unmount flash.
+ * Queue opens by default when chrome is idle and at least one authoritative
+ * prompt is queued. Closing the queue dismisses that session's offer until
+ * occupancy drains; a different session on the same chrome instance may
+ * offer again. An in-flight optimistic Send never opens the drawer —
+ * admission stays a paint-only receipt on the chip so layout does not jump
+ * under the pointer.
+ *
+ * Segment switches keep the panel shell mounted and crossfade content. The
+ * shell uses one CSS grid-track transition for deliberate open/close actions;
+ * live queue reconciliation never feeds measurements back into layout.
  */
-import type { SessionGoal } from "@opengeni/sdk";
+import type { SessionGoal, SessionStatus, SessionTurn } from "@opengeni/sdk";
 import { type ReactNode } from "react";
-import type { ComposerState } from "../hooks/use-composer.js";
+import type { ComposerOptimisticMessage, ComposerState } from "../hooks/use-composer.js";
 import type { UseGoalResult } from "../hooks/use-goal.js";
 import type { UseTurnQueueResult } from "../hooks/use-turn-queue.js";
-export type SessionChromeSignalId = "incoming" | "steering" | "queue" | "goal" | "agents";
+export type SessionChromeSignalId = "incoming" | "steering" | "queue" | "goal" | "agents" | "commands";
 export type SessionChromeSignalTone = "neutral" | "accent" | "waiting" | "running";
 export type SessionChromeAgentsSignal = {
     count: number;
@@ -44,12 +52,27 @@ export type SessionChromeAgentsSignal = {
     tone?: SessionChromeSignalTone | undefined;
 };
 export type SessionChromeProps = {
+    /** Authoritative execution status; omitted by older embedding hosts. */
+    sessionStatus?: SessionStatus | undefined;
     queue: UseTurnQueueResult;
+    /** Open and focus an existing queued prompt without changing its delivery. */
+    queueFocusTarget?: {
+        turnId: string;
+        requestId: number;
+    } | undefined;
     /** Needed for queue edit → composer checkout. Omit with `readOnly`. */
     composer?: ComposerState | undefined;
+    /** Focus the composer after a successful queue checkout has applied its draft.
+     * Connect to the composer controller's `focusInput`, or a custom input ref.
+     * Never called for failed checkout or while replacement awaits confirmation.
+     */
+    onComposerFocus?: (() => void) | undefined;
     goal?: UseGoalResult | null | undefined;
     /** Expanded agents body (host supplies tree / list). */
     agentsPanel?: ReactNode;
+    /** Active commands only. The host mounts the body only when opened. */
+    commandsPanel?: ReactNode;
+    commandsCount?: number | undefined;
     /** Chip summary; when `count > 0` the agents segment appears. */
     agentsSignal?: SessionChromeAgentsSignal | undefined;
     /**
@@ -57,6 +80,8 @@ export type SessionChromeProps = {
      * (and the gallery) may still pass a handler so the action is visible.
      */
     onDismissIncoming?: ((inputId: string) => void) | undefined;
+    /** Open a typed child update's source through the host's normal authorized route. */
+    onOpenSession?: ((sessionId: string) => void) | undefined;
     readOnly?: boolean | undefined;
     className?: string | undefined;
     /** Controlled active segment; omit for uncontrolled. */
@@ -64,8 +89,41 @@ export type SessionChromeProps = {
     defaultActive?: SessionChromeSignalId | null | undefined;
     onActiveChange?: ((next: SessionChromeSignalId | null) => void) | undefined;
 };
-type GoalPillState = "pursuing" | "scheduled" | "blocked" | "held" | "paused" | "invariant_broken" | "completed";
+type GoalPillState = "pursuing" | "waiting" | "scheduled" | "session_failed" | "blocked" | "held" | "paused" | "invariant_broken" | "completed";
+type GoalPillRecord = Pick<SessionGoal, "status" | "pausedReason"> & {
+    continuation?: SessionGoal["continuation"] | null | undefined;
+};
+/** Pill label, with the pause reason spelled out: "Paused · cap" / "Paused · manually". */
+export declare function sessionChromeGoalPillLabel(state: GoalPillState, record: GoalPillRecord | null | undefined): string;
+/**
+ * One human sentence explaining WHY the goal is not pursuing right now: the
+ * pause reason, the agent's own `wait_for_input` hold (reason + deadline), or the
+ * next idle-backoff check time. Null when the state needs no explanation.
+ */
+export declare function sessionChromeGoalPillExplanation(state: GoalPillState, record: GoalPillRecord | null | undefined): string | null;
+export declare function countAuthoritativeQueuedTurns(turns: readonly SessionTurn[], mutationFor: UseTurnQueueResult["mutationFor"]): number;
+export declare function countOptimisticQueuedMessages(messages: readonly ComposerOptimisticMessage[] | undefined, queuedTurnIds: ReadonlySet<string>, snapshot: UseTurnQueueResult["snapshot"]): number;
+/**
+ * First uncontrolled segment. An existing authoritative queue opens itself
+ * when the host did not pick another default; optimistic-only occupancy
+ * stays collapsed so a live Send does not shove a drawer under the pointer.
+ */
+export declare function sessionChromeInitialActive(input: {
+    defaultActive: SessionChromeSignalId | null;
+    authoritativeQueuedCount: number;
+}): SessionChromeSignalId | null;
+/**
+ * Whether idle chrome should offer the queue panel. A dismissed session
+ * stays collapsed until occupancy drains. Controlled hosts own this.
+ */
+export declare function sessionChromeShouldOfferQueue(input: {
+    controlled: boolean;
+    active: SessionChromeSignalId | null;
+    activityOpen: boolean;
+    authoritativeQueuedCount: number;
+    suppressed: boolean;
+}): boolean;
 /** Select pill state from the goal's authoritative continuation projection. */
-export declare function sessionChromeGoalPillState(goalStatus: "active" | "paused" | "completed", continuation: SessionGoal["continuation"] | null | undefined): GoalPillState;
-export declare function SessionChrome({ queue, composer, goal, agentsPanel, agentsSignal, onDismissIncoming, readOnly, className, active: activeControlled, defaultActive, onActiveChange, }: SessionChromeProps): import("react").JSX.Element | null;
+export declare function sessionChromeGoalPillState(goalStatus: "active" | "paused" | "completed", continuation: SessionGoal["continuation"] | null | undefined, sessionStatus?: SessionStatus): GoalPillState;
+export declare function SessionChrome({ sessionStatus, queue, queueFocusTarget, composer, onComposerFocus, goal, agentsPanel, commandsPanel, commandsCount, agentsSignal, onDismissIncoming, onOpenSession, readOnly, className, active: activeControlled, defaultActive, onActiveChange, }: SessionChromeProps): import("react").JSX.Element | null;
 export {};

package/dist/components/session-commands-panel.d.ts

@@ -0,0 +1,6 @@
+import type { UseSessionBackgroundCommandsResult } from "../hooks/use-session-background-commands.js";
+/** The current session's live commands. Settled commands belong to the timeline. */
+export declare function SessionCommandsPanel({ commands: state, readOnly, }: {
+    commands: UseSessionBackgroundCommandsResult;
+    readOnly?: boolean;
+}): import("react").JSX.Element;

package/dist/components/session-commands.d.ts

@@ -0,0 +1,6 @@
+import { type UseSessionBackgroundCommandsOptions } from "../hooks/use-session-background-commands.js";
+/** Mount in the open activity panel so closed chrome never polls commands. */
+export declare function SessionCommands({ sessionId, readOnly, ...options }: UseSessionBackgroundCommandsOptions & {
+    sessionId: string;
+    readOnly?: boolean;
+}): import("react").JSX.Element;

package/dist/components/session-connection-request.d.ts

@@ -0,0 +1,8 @@
+import type { AuthNeededItem } from "../timeline/types.js";
+import { type SessionMcpCapabilityCardProps } from "./session-mcp-capability-card.js";
+export type SessionConnectionRequestProps = Omit<SessionMcpCapabilityCardProps, "capabilityId" | "name" | "rationale"> & {
+    request: AuthNeededItem;
+};
+/** Resolve native reauthorization notices with the same exact-identity rules
+ * as the console. Recommendations never supply endpoints or account authority. */
+export declare function SessionConnectionRequest(props: SessionConnectionRequestProps): import("react").JSX.Element;

package/dist/components/session-conversation.d.ts

@@ -0,0 +1,86 @@
+import { type CSSProperties } from "react";
+import { type ClientOverride } from "../session-context.js";
+import { type ModelPolicyPickerProps } from "./model-policy-picker.js";
+import { type ChatComposerProps } from "./chat-composer.js";
+import { type HumanInputSurfaceProps } from "./human-input-surface.js";
+import { type MessageTimelineProps } from "./message-timeline.js";
+import { type OpenGeniLinkResolver, type OpenGeniViewerTarget } from "./open-geni-links.js";
+import type { UserMessageDisclosureLabels } from "./user-message-body.js";
+import { type HostSurfacePreference, type HostThemePreference } from "../lib/host-theme.js";
+export type SessionConversationLabels = {
+    /** Banner action after a refresh failure; the conversation stays mounted. */
+    retry: string;
+    /** Action when the conversation could not load at all. */
+    tryAgain: string;
+};
+export type SessionConversationProps = ClientOverride & {
+    sessionId: string;
+    /** Host-owned artifact links, previews and other message presentation. */
+    renderMessageText?: MessageTimelineProps["renderMessageText"];
+    /**
+     * Open OpenGeni object links in agent replies (`artifact:`, `sandbox:`,
+     * editable artifacts, Sites). Asked first; by default retained files and
+     * sandbox files download only when the proxy explicitly enables them, while
+     * editable artifacts and Sites stay unavailable until the host resolves them.
+     */
+    resolveLink?: OpenGeniLinkResolver | undefined;
+    /**
+     * Open agent links to editable artifacts and Sites in a host viewer, for
+     * example `SessionArtifactViewer` mounted beside the conversation. Asked
+     * after `resolveLink`.
+     */
+    onOpenArtifact?: ((target: OpenGeniViewerTarget) => void) | undefined;
+    /**
+     * Inline previews for assistant `opengeni-site` / `opengeni-html` fences.
+     * Defaults to the OpenGeni preview (Site reads need the proxy's
+     * `artifacts` option); `false` shows the fence as code.
+     */
+    renderInteractiveBlock?: MessageTimelineProps["renderInteractiveBlock"] | false;
+    /** Product-specific tool-call renderers; defaults to the built-in registry. */
+    toolRegistry?: MessageTimelineProps["toolRegistry"];
+    /**
+     * Replace the "usage limit reached" row for an `allowance_exhausted`
+     * refusal, for example to link your own plan or admin page.
+     */
+    renderAllowanceExhausted?: MessageTimelineProps["renderAllowanceExhausted"];
+    /** Replace the words of the default "usage limit reached" row. */
+    allowanceExhaustedLabels?: MessageTimelineProps["allowanceExhaustedLabels"];
+    /**
+     * File attachments in the composer. Defaults to true; the attach control
+     * appears only when the deployment's client config enables file uploads.
+     */
+    attachments?: boolean | undefined;
+    /**
+     * Show the model/reasoning picker. End users of an embedded product rarely
+     * choose models, so it is hidden unless this is `true` or the client config
+     * reports `modelSelection: true` (`createSessionProxyHandler({ modelSelection: true })`).
+     */
+    modelPicker?: boolean | undefined;
+    /** Model-picker appearance only; visibility, policy and delivery remain owned here. */
+    modelPickerProps?: Pick<ModelPolicyPickerProps, "groupPresentation" | "messages"> | undefined;
+    /** Localized actions for already-sent user-message disclosure. */
+    userMessageDisclosureLabels?: UserMessageDisclosureLabels | undefined;
+    loadSkillReview?: HumanInputSurfaceProps["loadSkillReview"];
+    className?: string;
+    /** Defaults to filling the host. The host owns available height. */
+    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 conversation blends in; `theme` uses the `--og-color-*` surface tokens
+     * as they are. Customized surface tokens are always kept.
+     */
+    surface?: HostSurfacePreference | undefined;
+    /** Conversation-owned copy (error actions). */
+    labels?: Partial<SessionConversationLabels> | undefined;
+    /** Presentation/custom controls only; queue and delivery wiring stay owned here. */
+    composerProps?: Omit<ChatComposerProps, "composer" | "effectiveControl" | "queuedAheadCount" | "attachments">;
+};
+/** Complete existing-session conversation. Uses the provider's normal SDK client
+ * (including Site clients), one shared event feed, and authoritative queue state. */
+export declare function SessionConversation(props: SessionConversationProps): import("react").JSX.Element;

package/dist/components/session-list.d.ts

@@ -0,0 +1,36 @@
+import { type ClientOverride } from "../session-context.js";
+export type SessionListLabels = {
+    heading: string;
+    newChat: string;
+    empty: string;
+    loading: string;
+    loadMore: string;
+    rename: string;
+    archive: string;
+    save: string;
+    cancel: string;
+};
+export type SessionListProps = ClientOverride & {
+    selectedSessionId?: string | null | undefined;
+    onSelect: (sessionId: string) => void;
+    /** Shown as a "New chat" button when provided. */
+    onNewChat?: (() => void) | undefined;
+    /** Allow inline rename (`updateSession`). Defaults to true. */
+    rename?: boolean | undefined;
+    /** Allow archiving (`updateSessionArchive`). Defaults to true. */
+    archive?: boolean | undefined;
+    /** Called after the selected chat was archived, so the host can move on. */
+    onArchived?: ((sessionId: string) => void) | undefined;
+    pageSize?: number | undefined;
+    /** Change the reference to force a refetch (for example after creating a chat). */
+    refreshKey?: unknown;
+    labels?: Partial<SessionListLabels> | undefined;
+    className?: string | undefined;
+};
+/**
+ * The workspace's root chats for the current user, newest activity first.
+ * Through `createSessionProxyHandler` the list is limited to the chats the
+ * resolved user created (or everything they may read, with `sessionList:
+ * "visible"`); OpenGeni enforces visibility either way.
+ */
+export declare function SessionList({ client, workspaceId, selectedSessionId, onSelect, onNewChat, rename, archive, onArchived, pageSize, refreshKey, labels: labelOverrides, className, }: SessionListProps): import("react").JSX.Element;

package/dist/components/session-mcp-capability-card.d.ts

@@ -0,0 +1,41 @@
+import type { OpenGeniBrowserClient as OpenGeniClient } from "@opengeni/sdk/browser";
+export type SessionMcpCapabilityCardProps = {
+    client: OpenGeniClient;
+    workspaceId: string;
+    sessionId: string;
+    capabilityId: string;
+    name: string;
+    rationale?: string;
+    /** Exact host route; no console-specific routing is assumed. */
+    returnUrl: string;
+    onConfigured?: (() => void | Promise<void>) | undefined;
+};
+export type McpConnectionCardProps = Omit<SessionMcpCapabilityCardProps, "sessionId"> & {
+    /** Omit for connection management: no session tool selection is written. */
+    sessionId?: string;
+    dialogOnly?: boolean;
+    onClose?: (() => void) | undefined;
+    /**
+     * The provider only ever connects someone's own account (official Gmail,
+     * Slack's hosted MCP): no ownership choice, always personal.
+     */
+    personalOnly?: boolean;
+    /** The connect button's words, "Connect Gmail". Defaults to "Continue to <name>". */
+    connectLabel?: string;
+    /** The line under the dialog title. Defaults to the kind and provider domain. */
+    dialogSubtitle?: string;
+    /** The host's product copy for this connection, instead of the catalog description. */
+    description?: string;
+    /** The host's logo for this connection, when the catalog has no asset. */
+    logoSrc?: string | null;
+    /** The host's words for the ownership choice. */
+    ownershipCopy?: {
+        legend: string;
+        workspace: string;
+        personal: string;
+    };
+};
+/** Native OAuth recommendation flow. Identity and endpoint come from the live
+ * catalog, never from model-authored recommendation text. */
+export declare function SessionMcpCapabilityCard(props: SessionMcpCapabilityCardProps): import("react").JSX.Element;
+export declare function McpConnectionCard(props: McpConnectionCardProps): import("react").JSX.Element;

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

@@ -0,0 +1,24 @@
+import { Component, type ReactNode } from "react";
+type Anchor = {
+    element: HTMLElement;
+    key: string | null;
+    text: string | null;
+    top: number;
+    focused?: boolean;
+};
+export type TimelineAnchor = Anchor[];
+/** Read ownership synchronously: selectionchange may follow the next React commit. */
+export declare function timelineHasReader(scroller: HTMLElement | null): boolean;
+/** Read the old DOM immediately before React changes it, not when a fetch starts. */
+export declare class TimelineBeforeLayout extends Component<{
+    capture: () => void;
+    children: ReactNode;
+}> {
+    getSnapshotBeforeUpdate(): null;
+    componentDidUpdate(): void;
+    render(): ReactNode;
+}
+export declare function captureTimelineAnchor(scroller: HTMLElement): TimelineAnchor | null;
+/** Return only the correction native browser anchoring has not already made. */
+export declare function timelineAnchorCorrection(scroller: HTMLElement, anchors: TimelineAnchor): number | null;
+export {};

package/dist/components/timeline-annotation-chrome.d.ts

@@ -0,0 +1,25 @@
+import type { DraftTimelineAnnotation, TimelineAnnotation, TimelineAnnotationSource } from "@opengeni/sdk";
+import { type ReactNode } from "react";
+export type TimelineAnnotationLike = DraftTimelineAnnotation | TimelineAnnotation;
+export declare function AnnotationQuoteSourceButton({ annotation, lines, onRevealSource, onUnavailable, }: {
+    annotation: TimelineAnnotationLike;
+    lines?: 2 | 3;
+    onRevealSource?: ((source: TimelineAnnotationSource) => boolean) | undefined;
+    onUnavailable: (id: string | null) => void;
+}): import("react").JSX.Element;
+export declare function AnnotationAccentRow({ children, className, }: {
+    children: ReactNode;
+    className?: string | undefined;
+}): import("react").JSX.Element;
+export declare function AnnotationNotePreview({ note, annotationId, ordinal, className, }: {
+    note: string;
+    annotationId: string;
+    ordinal: number;
+    className?: string | undefined;
+}): import("react").JSX.Element | null;
+export declare function AnnotationNoteField({ annotation, inputRef, onUpdate, onCommit, }: {
+    annotation: TimelineAnnotationLike;
+    inputRef?: ((node: HTMLTextAreaElement | null) => void) | undefined;
+    onUpdate: (id: string, note: string) => void;
+    onCommit?: (() => void) | undefined;
+}): import("react").JSX.Element;

package/dist/components/timeline-annotation-layout.d.ts

@@ -0,0 +1,42 @@
+export type AnnotationBox = {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+};
+export type AnnotationBadgeAnchor = {
+    id: string;
+    ordinal: number;
+    left: number;
+    top: number;
+    incomplete: boolean;
+};
+export declare const ANNOTATION_BADGE_GAP_PX = 32;
+export declare const ANNOTATION_BADGE_MIN_GAP_PX = 12;
+export declare const ANNOTATION_REVIEW_DIALOG_WIDTH_PX = 400;
+export declare const ANNOTATION_REVIEW_DIALOG_MAX_HEIGHT_PX: number;
+export declare const ANNOTATION_REVIEW_DIALOG_MIN_HEIGHT_PX = 160;
+export declare const ANNOTATION_REVIEW_DIALOG_FLOOR_HEIGHT_PX = 80;
+export declare const ANNOTATION_REVIEW_MARGIN_PX = 12;
+export declare const ANNOTATION_NOTE_PREVIEW_CHARS = 280;
+export declare const ANNOTATION_CARD_STACK_SCROLL_AT = 4;
+export declare function annotationBoxIntersects(a: AnnotationBox, b: AnnotationBox): boolean;
+export declare function annotationViewportBox(viewportWidth: number, viewportHeight: number, scroller?: AnnotationBox | null): AnnotationBox;
+export declare function annotationNoteNeedsDisclosure(note: string): boolean;
+export declare function annotationBadgePackGap(viewport: AnnotationBox, count: number, preferred?: number): number;
+export declare function layoutAnnotationBadges(anchors: readonly AnnotationBadgeAnchor[], viewport: AnnotationBox, preferredGap?: number): AnnotationBadgeAnchor[];
+export declare function scrollAnnotationRowIntoList(list: HTMLElement | null | undefined, row: HTMLElement | null | undefined): void;
+export declare function clampAnnotationDialogPlacement(input: {
+    triggerLeft: number;
+    triggerTop: number;
+    triggerBottom: number;
+    contentHeight: number;
+    viewportWidth: number;
+    viewportHeight: number;
+    panelWidth?: number;
+}): {
+    left: number;
+    top: number;
+    maxHeight: number;
+    above: boolean;
+};

package/dist/components/timeline-annotation-markers.d.ts

@@ -0,0 +1,8 @@
+import type { DraftTimelineAnnotation } from "@opengeni/sdk";
+import { type RefObject } from "react";
+export declare function TimelineAnnotationMarkers({ annotations, onSelect, rootRef, }: {
+    annotations: readonly DraftTimelineAnnotation[];
+    onSelect?: ((id: string) => void) | undefined;
+    rootRef: RefObject<HTMLElement | null>;
+}): import("react").ReactPortal | null;
+export default TimelineAnnotationMarkers;

package/dist/components/timeline-annotation-reveal-context.d.ts

@@ -0,0 +1,4 @@
+import { type RefObject } from "react";
+/** Owning timeline scroller for quote-source navigation. */
+export declare const TimelineAnnotationSourceRootContext: import("react").Context<RefObject<HTMLElement | null> | null>;
+export declare function useTimelineAnnotationSourceRoot(): RefObject<HTMLElement | null> | null;

package/dist/components/timeline-annotation-shared.d.ts

@@ -0,0 +1,31 @@
+import type { TimelineAnnotationSource } from "@opengeni/sdk";
+export declare const ANNOTATION_CHROME_SELECTOR = "[data-og-annotation-chrome], [data-og-annotation-badge], [data-og-annotation-popover]";
+export declare function annotationHasNote(note: string): boolean;
+export declare function annotationDisplayOrdinal(annotation: {
+    readonly id?: string;
+    readonly ordinal?: number | undefined;
+}, index: number): number;
+export declare function sourceKindLabel(kind: TimelineAnnotationSource["kind"]): string;
+export declare function annotationSourceLabel(source: TimelineAnnotationSource): string;
+export declare function truncateAnnotationQuote(quote: string, maxChars?: number): string;
+export declare function cssEscapeAttribute(value: string): string;
+export declare function isAnnotationChromeNode(node: Node | null): boolean;
+export declare function occurrenceOffsets(text: string, quote: string): number[];
+export declare function matchingQuoteInSource(sourceText: string, quote: string): string | null;
+type AnnotatableSpan = {
+    node: Text;
+    start: number;
+    length: number;
+};
+export declare function annotatableText(root: HTMLElement): {
+    text: string;
+    spans: AnnotatableSpan[];
+};
+export declare function rangeFromOffsets(spans: AnnotatableSpan[], startOffset: number, endOffset: number): Range | null;
+export declare function buildQuoteRange(sourceEl: HTMLElement, quote: string, occurrenceIndex?: number): Range | null;
+export declare function quoteOccurrenceIndex(sourceEl: HTMLElement, range: Range, quote: string): number;
+export declare function clipRangeToSource(range: Range, sourceEl: HTMLElement): Range | null;
+export declare function visibleClientRect(range: Range): DOMRect | null;
+export declare function resolveAnnotationRevealRoot(from: Element | null | undefined): HTMLElement | null;
+export declare function revealLoadedAnnotationSource(source: TimelineAnnotationSource, root?: ParentNode | null): boolean;
+export {};

package/dist/components/timeline-annotations-dialog.d.ts

@@ -1,7 +1,7 @@
 import type { TimelineAnnotationSource } from "@opengeni/sdk";
 import { type RefObject } from "react";
-import type { TimelineAnnotationLike } from "./timeline-annotations.js";
-export declare function TimelineAnnotationsDialog({ annotations, editable, focusAnnotationId, onFocusConsumed, onUpdate, onRemove, onRevealSource, triggerRef, countLabel, onDismiss, }: {
+import { type TimelineAnnotationLike } from "./timeline-annotation-chrome.js";
+export declare function TimelineAnnotationsDialog({ annotations, editable, focusAnnotationId, onFocusConsumed, onUpdate, onRemove, onRevealSource, triggerRef, countLabel, onDismiss, onCommit, }: {
     annotations: readonly TimelineAnnotationLike[];
     editable: boolean;
     focusAnnotationId?: string | null | undefined;
@@ -12,5 +12,6 @@ export declare function TimelineAnnotationsDialog({ annotations, editable, focus
     triggerRef: RefObject<HTMLButtonElement | null>;
     countLabel: string;
     onDismiss: (restoreFocus: boolean) => void;
+    onCommit: () => void;
 }): import("react").ReactPortal | null;
 export default TimelineAnnotationsDialog;

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

@@ -1,13 +1,23 @@
-import type { DraftTimelineAnnotation, TimelineAnnotation, TimelineAnnotationSource } from "@opengeni/sdk";
-export type TimelineAnnotationLike = DraftTimelineAnnotation | TimelineAnnotation;
-export declare function TimelineAnnotationsChip({ annotations, editable, focusAnnotationId, onFocusConsumed, onUpdate, onRemove, onRevealSource, className, }: {
+import type { TimelineAnnotationSource } from "@opengeni/sdk";
+import { type TimelineAnnotationLike } from "./timeline-annotation-chrome.js";
+export type { TimelineAnnotationLike } from "./timeline-annotation-chrome.js";
+export declare function TimelineAnnotationCards({ annotations, onRevealSource, className, }: {
+    annotations: readonly TimelineAnnotationLike[];
+    onRevealSource?: ((source: TimelineAnnotationSource) => boolean) | undefined;
+    className?: string | undefined;
+}): import("react").JSX.Element | null;
+export declare function TimelineAnnotationsChip({ annotations, editable, focusAnnotationId, onFocusConsumed, onUpdate, onRemove, onRevealSource, className, compact, onCommit, }: {
     annotations: readonly TimelineAnnotationLike[];
     editable?: boolean | undefined;
     focusAnnotationId?: string | null | undefined;
     onFocusConsumed?: (() => void) | undefined;
     onUpdate?: ((id: string, note: string) => void) | undefined;
     onRemove?: ((id: string) => void) | undefined;
+    /** Return focus to the owning input after all notes are completed with Enter. */
+    onCommit?: (() => void) | undefined;
     onRevealSource?: ((source: TimelineAnnotationSource) => boolean) | undefined;
     className?: string | undefined;
+    /** Dense trigger for single-line rows such as the compact queue dock. */
+    compact?: boolean | undefined;
 }): import("react").JSX.Element | null;
 export default TimelineAnnotationsChip;

package/dist/components/timeline-reading-progress.d.ts

@@ -0,0 +1,11 @@
+import type { TimelineGroup } from "../timeline/types.js";
+/**
+ * Settlement may compact history, but cannot remove prose beneath a reader.
+ * Keep only progress that was already primary on the preceding commit; loading
+ * settled history never expands it. An explicit work toggle or tip return ends
+ * the protection. Keeping the original sibling keys also preserves selection.
+ */
+export declare function useReadingProgress(projected: TimelineGroup[], pinned: boolean, scroller: HTMLElement | null): {
+    groups: TimelineGroup[];
+    release: (id: string | null) => void;
+};

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

@@ -0,0 +1,34 @@
+import { type RefObject } from "react";
+import type { TimelineItem } from "../timeline/types.js";
+export type TimelineSearchTarget = {
+    sequence: number;
+    eventId?: string | undefined;
+    /** Literal, case-insensitive text. No regex interpretation. */
+    query: string;
+    /** Zero-based occurrence within the source message. Defaults to zero. */
+    occurrence?: number | undefined;
+    /**
+     * Zero-based UTF-16 offset of the match in the original message text, as
+     * reported by backend all-occurrence search (messageMatchOffset). When set
+     * it takes precedence over `occurrence` and is validated against `query`,
+     * so a stale offset degrades to no highlight rather than a wrong one.
+     */
+    offset?: number | undefined;
+};
+/** Scoped to the target's group; disclosure expansion persists after closing find. */
+export declare const TimelineSearchRevealContext: import("react").Context<string | null>;
+export declare const useTimelineSearchReveal: () => string | null;
+export declare function isTimelineSearchTarget(item: TimelineItem, target: TimelineSearchTarget): boolean;
+/** Scan without allocating an offset array proportional to a huge message. */
+export declare function literalSearchOffset(text: string, query: string, occurrence?: number): number;
+/**
+ * Validate a caller-supplied UTF-16 offset against the text and query. The
+ * sticky flag pins the match to exactly `offset`; like literalSearchOffset,
+ * regex escaping keeps offsets in UTF-16 units even for length-changing case
+ * folds. Returns -1 when the offset is stale or the text no longer matches.
+ */
+export declare function matchAtOffset(text: string, query: string, offset: number): number;
+/** Resolve a target to a UTF-16 offset: explicit offset wins, else the ordinal scan. */
+export declare function searchMatchOffset(text: string, target: TimelineSearchTarget): number;
+/** Range highlighting does not mutate React-owned text or its layout. */
+export declare function useTimelineSearchNavigation(root: RefObject<HTMLDivElement | null>, itemId: string | undefined, target: TimelineSearchTarget | null | undefined, releasePin: () => void, revision: unknown): void;

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

@@ -0,0 +1,16 @@
+import type { TimelineGroup } from "../timeline/types.js";
+export type TimelineSettlement = {
+    element: HTMLElement;
+    top: number;
+};
+/** Capture only a retained answer at a real live→settled boundary, never history load. */
+export declare function captureTimelineSettlement(scroller: HTMLElement, groups: readonly {
+    key: string;
+    group: TimelineGroup;
+}[]): TimelineSettlement | null;
+/**
+ * Folding earlier prose can clamp scrollTop before paint. Keep the retained
+ * answer visually continuous after the normal scroll authority has run. This
+ * is one local position transition, not a new scroll writer or a presence tree.
+ */
+export declare function animateTimelineSettlement(snapshot: TimelineSettlement): Animation | null;

package/dist/components/tip-follow.d.ts

@@ -160,6 +160,22 @@ export declare function tipFollowClearSoftRise(el: HTMLElement): void;
  * on screen: scrollTop -= Δh, clamped to the new max.
  */
 export declare function tipFollowCompensateShrink(scrollTop: number, previousHeight: number, nextHeight: number, clientHeight: number, epsPx?: number): number;
+export type TipFollowContentShrinkBaseline = {
+    scrollHeight: number;
+    scrollTop: number;
+};
+export type TipFollowContentShrinkObservation = {
+    baseline: TipFollowContentShrinkBaseline | null;
+    compensatedScrollTop: number | null;
+};
+/**
+ * Retain the geometry from the first sub-epsilon content-shrink frame until
+ * the cumulative collapse crosses the deadband. Browsers may clamp scrollTop
+ * after every tiny frame, so compensating from the latest DOM top would count
+ * those already-applied clamps twice and make the result animation-cadence
+ * dependent.
+ */
+export declare function tipFollowObserveContentShrink(baseline: TipFollowContentShrinkBaseline | null, previousHeight: number, previousScrollTop: number, nextHeight: number, clientHeight: number, epsPx?: number): TipFollowContentShrinkObservation;
 /**
  * Viewport shrank (SessionChrome / composer / window). maxScroll rises by ≈Δc;
  * keep the same tip distance: scrollTop += Δc. Without this, pinned follow only