@opengeni/react 0.48.0 → 0.52.1

package/src/lib/terminal-capability.ts

@@ -0,0 +1,10 @@
+import type { TerminalCapability } from "@opengeni/sdk";
+
+/** Whether an explicit viewer grant can upgrade this cell to a real PTY.
+ * Keep acquisition feasibility separate from the current transport: a cold
+ * real-PTY backend reports sse-events until the just-in-time grant warms it. */
+export function terminalCanAcquirePty(cell: TerminalCapability | null | undefined): boolean {
+  if (!cell?.ptyCapable) return false;
+  if (cell.transport === "pty-ws") return true;
+  return cell.reason === "lease_cold" || cell.reason === "not_provisioned";
+}

package/src/session-context.ts

@@ -4,6 +4,9 @@ import type {
   EmbeddedFileAttachmentClientLike,
   EmbeddedGoalClientLike,
   EmbeddedHumanInputSessionClientLike,
+  EmbeddedBrowserInteractionClientLike,
+  EmbeddedComputerInteractionClientLike,
+  EmbeddedInteractionClientLike,
   EmbeddedRealtimeSessionClientLike,
   EmbeddedSessionClientLike,
   EmbeddedSessionLineageClientLike,
@@ -76,6 +79,21 @@ export type EmbeddedFileAttachmentClientOverride = {
   workspaceId?: string | undefined;
 };
 
+export type EmbeddedInteractionClientOverride = {
+  client?: EmbeddedInteractionClientLike | undefined;
+  workspaceId?: string | undefined;
+};
+
+export type EmbeddedBrowserInteractionClientOverride = {
+  client?: EmbeddedBrowserInteractionClientLike | undefined;
+  workspaceId?: string | undefined;
+};
+
+export type EmbeddedComputerInteractionClientOverride = {
+  client?: EmbeddedComputerInteractionClientLike | undefined;
+  workspaceId?: string | undefined;
+};
+
 export type EmbeddedSessionContextValue = Omit<OpenGeniContextValue, "client"> & {
   client: EmbeddedSessionClientLike;
 };
@@ -145,6 +163,78 @@ export function useOpenGeni(override: ClientOverride = {}): OpenGeniContextValue
   };
 }
 
+const BROWSER_INTERACTION_METHODS = [
+  "listAttachedBrowsers",
+  "getAttachedBrowser",
+  "listBrowserIdentities",
+  "getBrowserIdentity",
+  "createBrowserIdentity",
+  "listBrowserRevisions",
+  "listBrowserSessions",
+  "getBrowserSession",
+  "createBrowserSession",
+  "listBrowserTargets",
+  "openBrowserTarget",
+  "selectBrowserTarget",
+  "closeBrowserTarget",
+  "observeBrowserTarget",
+  "actInBrowser",
+  "getBrowserActionReceipt",
+  "listBrowserDiagnostics",
+  "attachBrowserSession",
+  "heartbeatBrowserSession",
+  "publishBrowserRevision",
+  "suspendBrowserSession",
+  "resumeBrowserSession",
+  "endBrowserSession",
+] as const;
+
+const COMPUTER_INTERACTION_METHODS = [
+  "listComputerSessions",
+  "getComputerSession",
+  "createComputerSession",
+  "listComputerTargets",
+  "observeComputerTarget",
+  "actInComputer",
+  "getComputerActionReceipt",
+  "attachComputerSession",
+  "heartbeatComputerSession",
+  "endComputerSession",
+] as const;
+
+/** Resolve only BrowserSession methods for a standalone Browser embed. */
+export function useEmbeddedBrowserInteraction(
+  override: EmbeddedBrowserInteractionClientOverride = {},
+): EmbeddedClientContextValue<EmbeddedBrowserInteractionClientLike> {
+  return useEmbeddedClientRefinement(
+    override,
+    BROWSER_INTERACTION_METHODS,
+    "browser interaction hooks",
+  );
+}
+
+/** Resolve only ComputerSession methods for a standalone Computer embed. */
+export function useEmbeddedComputerInteraction(
+  override: EmbeddedComputerInteractionClientOverride = {},
+): EmbeddedClientContextValue<EmbeddedComputerInteractionClientLike> {
+  return useEmbeddedClientRefinement(
+    override,
+    COMPUTER_INTERACTION_METHODS,
+    "computer interaction hooks",
+  );
+}
+
+/** Resolve the complete Browser + Computer client surface. */
+export function useEmbeddedInteraction(
+  override: EmbeddedInteractionClientOverride = {},
+): EmbeddedClientContextValue<EmbeddedInteractionClientLike> {
+  return useEmbeddedClientRefinement(
+    override,
+    [...BROWSER_INTERACTION_METHODS, ...COMPUTER_INTERACTION_METHODS],
+    "interaction hooks",
+  );
+}
+
 /**
  * Resolve the narrow client required by the session-only hooks. The full
  * provider client is structurally compatible, while an explicit host proxy

package/src/timeline/activity-rail.tsx

@@ -12,9 +12,9 @@ import { cn } from "../lib/cn";
 import { truncate } from "../lib/format";
 import { defaultToolRegistry } from "./tool-renderers";
 import { useEntranceAnimation, useEntranceAnimationLive } from "./entrance";
-import type { RetainedScreenshotLoader, ToolRegistry } from "./registry";
+import type { RetainedArtifactLoader, RetainedScreenshotLoader, ToolRegistry } from "./registry";
 import { useSeenActivityIds } from "./seen-activity-ids";
-import { BodyNote, PayloadBlock, ActivityDisclosure } from "./shared";
+import { BodyNote, PayloadBlock, ActivityDisclosure, ToolCallTruncationProvider } from "./shared";
 import { toolDisplayName } from "./tool-display-name";
 import type { ActivityItem, MemoryItem, ReasoningItem, SandboxItem, WorkerItem } from "./types";
 
@@ -44,6 +44,8 @@ export type ActivityRailProps = {
    */
   onMemoryClick?: ((memoryId: string) => void) | undefined;
   loadRetainedScreenshot?: RetainedScreenshotLoader | undefined;
+  /** Resolve permanent generated-image receipts through the authenticated host SDK. */
+  loadRetainedArtifact?: RetainedArtifactLoader | undefined;
   /** Drop the left rule + indent (used inside a folded turn summary). */
   bare?: boolean | undefined;
   className?: string | undefined;
@@ -67,6 +69,7 @@ export function ActivityRail({
   onOpenSession,
   onMemoryClick,
   loadRetainedScreenshot,
+  loadRetainedArtifact,
   bare,
   className,
 }: ActivityRailProps) {
@@ -120,11 +123,15 @@ export function ActivityRail({
           onOpenSession,
           onMemoryClick,
           loadRetainedScreenshot,
+          loadRetainedArtifact,
         );
         return (
           <div
             key={item.id}
             data-og-timeline-row-anchor=""
+            data-og-annotation-source-key={
+              item.kind === "tool-call" ? item.annotationSource?.eventId : undefined
+            }
             className={cn(newFamily && "mt-3", enteringIds.has(item.id) && "animate-og-row-enter")}
           >
             {row}
@@ -146,13 +153,22 @@ function renderActivity(
   onOpenSession: ((sessionId: string) => void) | undefined,
   onMemoryClick: ((memoryId: string) => void) | undefined,
   loadRetainedScreenshot: RetainedScreenshotLoader | undefined,
+  loadRetainedArtifact: RetainedArtifactLoader | undefined,
 ) {
   switch (item.kind) {
     case "reasoning":
       return <ReasoningRow item={item} />;
     case "tool-call": {
       const Renderer = toolRegistry.resolve(item);
-      return <Renderer item={item} loadRetainedScreenshot={loadRetainedScreenshot} />;
+      return (
+        <ToolCallTruncationProvider value={item.truncation ?? null}>
+          <Renderer
+            item={item}
+            loadRetainedScreenshot={loadRetainedScreenshot}
+            loadRetainedArtifact={loadRetainedArtifact}
+          />
+        </ToolCallTruncationProvider>
+      );
     }
     case "worker":
       return <WorkerRow item={item} onOpenSession={onOpenSession} />;

package/src/timeline/index.ts

@@ -45,6 +45,7 @@ export type {
   SessionStatusItem,
   TimelineGroup,
   TimelineItem,
+  TimelineAnnotationSourceDescriptor,
   TurnEndItem,
   ToolCallItem,
   UserMessageItem,
@@ -56,7 +57,9 @@ export type {
 export { createToolRegistry, rawTypeOf } from "./registry";
 export type {
   CreateToolRegistryOptions,
+  RetainedArtifactLoader,
   RetainedScreenshotLoader,
+  VideoArtifactPlaybackLoader,
   ToolRegistry,
   ToolRegistryEntry,
   ToolRenderer,

package/src/timeline/parsers.ts

@@ -1,6 +1,14 @@
-import { normalizeMcpOutput, type GitFileDiff, type RetainedArtifactMetadata } from "@opengeni/sdk";
+import {
+  normalizeMcpOutput,
+  parseGeneratedImageReceipt,
+  type GeneratedImageReceipt,
+  type GitFileDiff,
+  type RetainedArtifactMetadata,
+} from "@opengeni/sdk";
 import { tryParseJson } from "../lib/format";
 
+export type { GeneratedImageReceipt };
+
 /* ----------------------------------------------------------------------------
    Pure parsers for the provider-native tool shapes that the timeline renders.
 
@@ -571,6 +579,11 @@ export function retainedScreenshotMetadata(out: unknown): RetainedArtifactMetada
     : null;
 }
 
+/** Parse the closed permanent generated-image receipt from native/function tools. */
+export function generatedImageReceipt(out: unknown): GeneratedImageReceipt | null {
+  return parseGeneratedImageReceipt(out);
+}
+
 export type TimelineMediaPreview = {
   type: "media_preview";
   mediaType: string;

package/src/timeline/projection.ts

@@ -1,5 +1,10 @@
-import type { SessionEvent, SessionStatus } from "@opengeni/sdk";
-const { default: fleetDecisionItem } = await import("./fleet-decision-projection");
+import {
+  parseMediaGenerationResult,
+  type SessionEvent,
+  type SessionStatus,
+  type TimelineAnnotation,
+} from "@opengeni/sdk";
+import fleetDecisionItem from "./fleet-decision-projection";
 import {
   CREDIT_EXHAUSTION_MESSAGE,
   humanizeFailureReason,
@@ -21,6 +26,7 @@ import type {
   TimelineItem,
   TurnEndItem,
   ToolCallItem,
+  ToolCallTruncation,
   WorkerItem,
 } from "./types";
 
@@ -61,6 +67,56 @@ const WORKER_MESSAGE_TOOL = "session_send_message";
  * render as machine-input rows.
  */
 const LANDMARK_ONLY_TOOL_LEAVES = new Set(["memory_save", "memory_correct"]);
+const TIMELINE_ANNOTATION_ANSI_SEQUENCE = new RegExp("\\u001B\\[[0-?]*[ -/]*[@-~]", "g");
+
+function safeTimelineAnnotationJson(value: unknown): string {
+  try {
+    return JSON.stringify(value) ?? "";
+  } catch {
+    return String(value ?? "");
+  }
+}
+
+function timelineAnnotationToolOutputValue(value: unknown, depth = 0): string {
+  if (depth > 8 || value === null || value === undefined) {
+    return value == null ? "" : safeTimelineAnnotationJson(value);
+  }
+  if (typeof value === "string") return value;
+  if (typeof value !== "object" || Array.isArray(value)) {
+    return safeTimelineAnnotationJson(value);
+  }
+  const record = value as Record<string, unknown>;
+  if (record.type === "text" && typeof record.text === "string") return record.text;
+  if (Array.isArray(record.content)) {
+    const text = record.content.find(
+      (part) =>
+        part !== null &&
+        typeof part === "object" &&
+        (part as { type?: unknown }).type === "text" &&
+        typeof (part as { text?: unknown }).text === "string",
+    ) as { text: string } | undefined;
+    if (text) return text.text;
+  }
+  if ("structuredContent" in record) {
+    return timelineAnnotationToolOutputValue(record.structuredContent, depth + 1);
+  }
+  if ("result" in record) return timelineAnnotationToolOutputValue(record.result, depth + 1);
+  return safeTimelineAnnotationJson(value);
+}
+
+/** Browser mirror of the server's canonical annotation source projection. */
+function timelineAnnotationToolOutputText(output: unknown): string | null {
+  const raw = timelineAnnotationToolOutputValue(output);
+  const marker = raw.indexOf("\nOutput:\n");
+  const text = (
+    marker >= 0
+      ? raw.slice(marker + "\nOutput:\n".length)
+      : raw.startsWith("Output:\n")
+        ? raw.slice("Output:\n".length)
+        : raw
+  ).replace(TIMELINE_ANNOTATION_ANSI_SEQUENCE, "");
+  return text.length > 0 ? text : null;
+}
 
 export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
   const items: TimelineItem[] = [];
@@ -134,6 +190,15 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
           kind: "user-message",
           id: event.id,
           text: voiceMessage?.text ?? stringValue(payload.text),
+          annotations: timelineAnnotations(payload.annotations),
+          annotationSource: {
+            kind: "user_message",
+            eventId: event.id,
+            eventType: "user.message",
+            sequence: event.sequence,
+            turnId,
+            text: voiceMessage?.text ?? stringValue(payload.text),
+          },
           ...(voiceMessage ? { presentation: voiceMessage.presentation } : {}),
           resources: resourceRefs(payload.resources),
           tools: toolRefs(payload.tools),
@@ -212,6 +277,17 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
           // Completion time is what the footer shows ("finished at"); keep the
           // first-delta stamp only until this event arrives.
           open.occurredAt = event.occurredAt;
+          open.annotationSource =
+            text && open.text === text
+              ? {
+                  kind: "assistant_message",
+                  eventId: event.id,
+                  eventType: "agent.message.completed",
+                  sequence: event.sequence,
+                  turnId,
+                  text,
+                }
+              : undefined;
           // The SDK can emit a hosted-tool item only after its provider-native
           // operation has completed, even though answer deltas were already
           // streamed. The completed message event is the durable ordering
@@ -231,6 +307,14 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
             text,
             streaming: false,
             occurredAt: event.occurredAt,
+            annotationSource: {
+              kind: "assistant_message",
+              eventId: event.id,
+              eventType: "agent.message.completed",
+              sequence: event.sequence,
+              turnId,
+              text,
+            },
           });
         }
         break;
@@ -312,6 +396,7 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
           name,
           arguments: args,
           output: undefined,
+          truncation: null,
           // The provider-native item drives the per-tool renderers (apply_patch
           // operation, computer_call action, web_search providerData, …).
           raw: payload.raw,
@@ -336,8 +421,30 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
         }
         // An output carrying an explicit error flag (or an MCP isError result)
         // settles the tool to "failed" so the renderer can surface it loudly.
+        const truncation = toolCallTruncation(payload);
         target.status = isErrorOutput(payload) ? "failed" : "complete";
-        target.output = payload.output;
+        target.output = Object.prototype.hasOwnProperty.call(payload, "output")
+          ? payload.output
+          : truncation && typeof payload.preview === "string"
+            ? payload.preview
+            : payload.output;
+        target.truncation = truncation;
+        const sourceText = timelineAnnotationToolOutputText(
+          Object.prototype.hasOwnProperty.call(payload, "output")
+            ? payload.output
+            : payload.preview,
+        );
+        if (sourceText !== null) {
+          target.annotationSource = {
+            kind: "tool_output",
+            eventId: event.id,
+            eventType: "agent.toolCall.output",
+            sequence: event.sequence,
+            turnId,
+            text: sourceText,
+            label: target.name,
+          };
+        }
         break;
       }
 
@@ -540,6 +647,7 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
 
       case "tool.auth_needed":
       case "credential.auth_needed": {
+        const capability = capabilityAuthorizationRequest(payload.capability);
         if (
           event.type === "tool.auth_needed" &&
           !stringValue(payload.toolName) &&
@@ -562,7 +670,11 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
           id: event.id,
           turnId,
           serverId: typeof payload.serverId === "string" ? payload.serverId : null,
-          source: event.type === "tool.auth_needed" ? "tool" : "credential",
+          source: capability
+            ? "capability"
+            : event.type === "tool.auth_needed"
+              ? "tool"
+              : "credential",
           providerDomain: stringValue(payload.providerDomain),
           connectionId: typeof payload.connectionId === "string" ? payload.connectionId : null,
           reason: authNeededReason(payload.reason),
@@ -571,6 +683,7 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
           toolName: typeof payload.toolName === "string" ? payload.toolName : null,
           authorizationUrl:
             typeof payload.authorizationUrl === "string" ? payload.authorizationUrl : null,
+          capability,
           occurredAt: event.occurredAt,
         });
         break;
@@ -1315,6 +1428,7 @@ function machineInputMembers(value: unknown): MachineInputBatchItem["members"] {
     "agent_message",
     "agent_steer_instruction",
     "child_terminal_result",
+    "media_generation_result",
   ]);
   const classifications = new Set<MachineInputBatchItem["members"][number]["classification"]>([
     "success",
@@ -1333,16 +1447,24 @@ function machineInputMembers(value: unknown): MachineInputBatchItem["members"] {
             member.classification as MachineInputBatchItem["members"][number]["classification"],
           ) &&
           typeof member.sourceId === "string"
-          ? [
-              {
-                id: member.id,
-                kind: member.kind as MachineInputBatchItem["members"][number]["kind"],
-                classification:
-                  member.classification as MachineInputBatchItem["members"][number]["classification"],
-                sourceId: member.sourceId,
-                summary: stringValue(member.summary),
-              },
-            ]
+          ? (() => {
+              const kind = member.kind as MachineInputBatchItem["members"][number]["kind"];
+              const result =
+                kind === "media_generation_result"
+                  ? parseMediaGenerationResult(member.result)
+                  : null;
+              return [
+                {
+                  id: member.id,
+                  kind,
+                  classification:
+                    member.classification as MachineInputBatchItem["members"][number]["classification"],
+                  sourceId: member.sourceId,
+                  summary: stringValue(member.summary),
+                  ...(result ? { result } : {}),
+                },
+              ];
+            })()
           : [];
       })
     : [];
@@ -1378,6 +1500,25 @@ function resourceRefs(value: unknown): import("@opengeni/sdk").ResourceRef[] {
   });
 }
 
+function timelineAnnotations(value: unknown): TimelineAnnotation[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((candidate): candidate is TimelineAnnotation => {
+    const annotation = asRecord(candidate);
+    const source = asRecord(annotation.source);
+    return (
+      typeof annotation.id === "string" &&
+      typeof annotation.ordinal === "number" &&
+      typeof annotation.quote === "string" &&
+      typeof annotation.note === "string" &&
+      typeof source.eventId === "string" &&
+      typeof source.eventType === "string" &&
+      typeof source.sequence === "number" &&
+      typeof source.startOffset === "number" &&
+      typeof source.endOffset === "number"
+    );
+  });
+}
+
 function toolRefs(value: unknown): import("@opengeni/sdk").ToolRef[] {
   if (!Array.isArray(value)) {
     return [];
@@ -1440,6 +1581,31 @@ function isErrorOutput(payload: Record<string, unknown>): boolean {
   );
 }
 
+function toolCallTruncation(payload: Record<string, unknown>): ToolCallTruncation | null {
+  const truncation = asRecord(payload.truncation);
+  const fullEvidence = asRecord(truncation.fullEvidence);
+  const surface = stringValue(truncation.surface);
+  const reason = stringValue(truncation.reason);
+  if (
+    truncation.truncated !== true ||
+    !surface ||
+    !reason ||
+    typeof fullEvidence.available !== "boolean"
+  ) {
+    return null;
+  }
+  return {
+    truncated: true,
+    surface,
+    reason,
+    omittedBytes: numberOrNull(truncation.omittedBytes),
+    fullEvidence: {
+      available: fullEvidence.available,
+      reason: stringValue(fullEvidence.reason) || null,
+    },
+  };
+}
+
 function findOpenCall(
   items: TimelineItem[],
   callId: string | null,
@@ -1563,6 +1729,37 @@ function authNeededReason(value: unknown): AuthNeededItem["reason"] {
     : null;
 }
 
+function capabilityAuthorizationRequest(
+  value: unknown,
+): NonNullable<AuthNeededItem["capability"]> | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const record = value as Record<string, unknown>;
+  const kind = record.kind;
+  const source = record.source;
+  const action = record.action;
+  if (
+    typeof record.id !== "string" ||
+    typeof record.name !== "string" ||
+    !["pack", "mcp", "api", "skill", "plugin"].includes(String(kind)) ||
+    !["built_in", "library", "configured", "public_registry", "registry", "manual"].includes(
+      String(source),
+    ) ||
+    !["connect", "add_credentials", "enable"].includes(String(action)) ||
+    typeof record.rationale !== "string"
+  ) {
+    return null;
+  }
+  return {
+    id: record.id,
+    name: record.name,
+    kind: kind as NonNullable<AuthNeededItem["capability"]>["kind"],
+    source: source as NonNullable<AuthNeededItem["capability"]>["source"],
+    action: action as NonNullable<AuthNeededItem["capability"]>["action"],
+    rationale: record.rationale,
+    requiredVariables: stringList(record.requiredVariables),
+  };
+}
+
 function stringList(value: unknown): string[] {
   return Array.isArray(value)
     ? value.filter((entry): entry is string => typeof entry === "string" && entry.trim().length > 0)

package/src/timeline/registry.ts

@@ -1,4 +1,4 @@
-import type { RetainedArtifactReference } from "@opengeni/sdk";
+import type { RetainedArtifactReference, VideoArtifactPlaybackSource } from "@opengeni/sdk";
 import type { ComponentType } from "react";
 import { mcpToolLeaf } from "./tool-display-name";
 import type { ToolCallItem } from "./types";
@@ -24,6 +24,7 @@ import type { ToolCallItem } from "./types";
 export type ToolRendererProps = {
   item: ToolCallItem;
   loadRetainedScreenshot?: RetainedScreenshotLoader | undefined;
+  loadRetainedArtifact?: RetainedArtifactLoader | undefined;
 };
 
 export type RetainedScreenshotLoader = (
@@ -31,6 +32,17 @@ export type RetainedScreenshotLoader = (
   signal: AbortSignal,
 ) => Promise<Uint8Array | null>;
 
+export type RetainedArtifactLoader = (
+  artifact: RetainedArtifactReference,
+  signal: AbortSignal,
+) => Promise<Uint8Array | { url: string } | null>;
+
+/** Mint an expiring source for native browser playback without loading video bytes in JS. */
+export type VideoArtifactPlaybackLoader = (
+  artifactId: string,
+  signal: AbortSignal,
+) => Promise<VideoArtifactPlaybackSource>;
+
 export type ToolRenderer = ComponentType<ToolRendererProps>;
 
 /** A registry entry: which key it matches and the component that renders it. */

package/src/timeline/screenshot-lightbox.tsx

@@ -19,7 +19,7 @@ import { usePortalTokenStyle } from "../lib/use-portal-token-style";
    -------------------------------------------------------------------------- */
 
 type LightboxController = {
-  open: (src: string, caption?: string, source?: HTMLElement | null) => void;
+  open: (src: string, caption?: string, source?: HTMLElement | null, label?: string) => void;
 };
 
 const LightboxContext = createContext<LightboxController | null>(null);
@@ -59,14 +59,21 @@ export function LightboxProvider({ children }: { children: ReactNode }) {
 }
 
 function LightboxRoot({ children }: { children: ReactNode }) {
-  const [state, setState] = useState<{ src: string; caption?: string } | null>(null);
+  const [state, setState] = useState<{
+    src: string;
+    caption?: string;
+    label: string;
+  } | null>(null);
   const [tokenSource, setTokenSource] = useState<HTMLElement | null>(null);
   const portalStyle = usePortalTokenStyle(tokenSource);
 
-  const open = useCallback((src: string, caption?: string, source?: HTMLElement | null) => {
-    setTokenSource(source ?? null);
-    setState(caption ? { src, caption } : { src });
-  }, []);
+  const open = useCallback(
+    (src: string, caption?: string, source?: HTMLElement | null, label = "Screenshot") => {
+      setTokenSource(source ?? null);
+      setState(caption ? { src, caption, label } : { src, label });
+    },
+    [],
+  );
 
   const close = useCallback(() => {
     setState(null);
@@ -95,7 +102,7 @@ function LightboxRoot({ children }: { children: ReactNode }) {
               <Dialog.Content
                 asChild
                 forceMount
-                aria-label="Screenshot"
+                aria-label={state.label}
                 onOpenAutoFocus={(event) => event.preventDefault()}
               >
                 <motion.div
@@ -117,7 +124,10 @@ function LightboxRoot({ children }: { children: ReactNode }) {
                   className="og-root fixed inset-0 z-50 flex items-center justify-center p-6 sm:p-12"
                   style={portalStyle}
                 >
-                  <Dialog.Title className="sr-only">Screenshot</Dialog.Title>
+                  <Dialog.Title className="sr-only">{state.label}</Dialog.Title>
+                  <Dialog.Description className="sr-only">
+                    {state.caption ?? `Expanded ${state.label.toLowerCase()}`}
+                  </Dialog.Description>
                   {/* The figure is one self-contained object: image, caption, and
                       its own close control. The close button anchors to a wrapper
                       sized to the IMAGE (w-fit), so it hugs the real top-right
@@ -128,7 +138,7 @@ function LightboxRoot({ children }: { children: ReactNode }) {
                       {/* A plain <img>: this SDK is framework-agnostic, with no host Image component. */}
                       <img
                         src={state.src}
-                        alt={state.caption ?? "Screenshot"}
+                        alt={state.caption ?? state.label}
                         className="min-h-0 max-h-[82vh] w-auto max-w-full rounded-og-md border border-white/10 object-contain shadow-og-lg"
                       />
                       <Dialog.Close