@stigmer/react 3.9.0 → 3.11.0

package/src/conversation/ConversationComposer.tsx

@@ -93,38 +93,38 @@ export function ConversationComposer({
 
   if (disabledReason !== null) {
     return (
-      <div className={cn("border-t border-border px-4 py-3", className)}>
-        <p className="text-center text-xs text-muted-foreground">{disabledReason}</p>
+      <div className={cn("stg:border-t stg:border-border stg:px-4 stg:py-3", className)}>
+        <p className="stg:text-center stg:text-xs stg:text-muted-foreground">{disabledReason}</p>
       </div>
     );
   }
 
   return (
-    <div className={cn("border-t border-border px-4 py-3", className)}>
+    <div className={cn("stg:border-t stg:border-border stg:px-4 stg:py-3", className)}>
       {/* The persistent forecast sits above the transient send-outcome
           notice: the notice is the more recent event and belongs closest
           to the input it reacts to. */}
       {hasAdvisory && (
         <p
           id={advisoryId}
-          className="mb-2 flex items-start gap-1.5 rounded-md bg-status-degraded-subtle px-2.5 py-1.5 text-xs text-status-degraded"
+          className="stg:mb-2 stg:flex stg:items-start stg:gap-1.5 stg:rounded-md stg:bg-status-degraded-subtle stg:px-2.5 stg:py-1.5 stg:text-xs stg:text-status-degraded"
         >
-          <TriangleAlert aria-hidden="true" className="mt-0.5 size-3.5 shrink-0" />
-          <span className="min-w-0">{advisory}</span>
+          <TriangleAlert aria-hidden="true" className="stg:mt-0.5 stg:size-3.5 stg:shrink-0" />
+          <span className="stg:min-w-0">{advisory}</span>
         </p>
       )}
       {notice && (
         <p
           className={cn(
-            "mb-2 text-xs",
-            notice.kind === "queued" ? "text-muted-foreground" : "text-destructive",
+            "stg:mb-2 stg:text-xs",
+            notice.kind === "queued" ? "stg:text-muted-foreground" : "stg:text-destructive",
           )}
           role="status"
         >
           {notice.text}
         </p>
       )}
-      <div className="flex items-end gap-2">
+      <div className="stg:flex stg:items-end stg:gap-2">
         <textarea
           {...composer.textareaProps}
           rows={1}
@@ -132,9 +132,9 @@ export function ConversationComposer({
           aria-label="Reply to the customer"
           aria-describedby={hasAdvisory ? advisoryId : undefined}
           className={cn(
-            "min-h-9 flex-1 resize-none rounded-md border border-border bg-background",
-            "px-3 py-2 text-sm text-foreground placeholder:text-muted-foreground-faint",
-            "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+            "stg:min-h-9 stg:flex-1 stg:resize-none stg:rounded-md stg:border stg:border-border stg:bg-background",
+            "stg:px-3 stg:py-2 stg:text-sm stg:text-foreground stg:placeholder:text-muted-foreground-faint",
+            "stg:focus-visible:outline-none stg:focus-visible:ring-2 stg:focus-visible:ring-ring",
           )}
         />
         <Button
@@ -147,7 +147,7 @@ export function ConversationComposer({
           {/* The house in-flight glyph (the session composer's pattern):
               the spinner replaces the Send icon so the button itself
               reports progress, not just its label. */}
-          {isSending ? <SpinnerIcon /> : <Send aria-hidden="true" className="size-4" />}
+          {isSending ? <SpinnerIcon /> : <Send aria-hidden="true" className="stg:size-4" />}
           {isSending ? "Sending…" : "Send"}
         </Button>
       </div>

package/src/conversation/ConversationControlBanner.tsx

@@ -92,16 +92,16 @@ export function ConversationControlBanner({
   return (
     <div
       className={cn(
-        "border-b border-border px-4 py-2",
-        humanHeld ? "bg-primary-subtle" : "bg-muted-faint",
+        "stg:border-b stg:border-border stg:px-4 stg:py-2",
+        humanHeld ? "stg:bg-primary-subtle" : "stg:bg-muted-faint",
         className,
       )}
     >
-      <div className="flex flex-wrap items-center justify-between gap-2">
-        <p className="flex items-center gap-1.5 text-sm text-foreground">
+      <div className="stg:flex stg:flex-wrap stg:items-center stg:justify-between stg:gap-2">
+        <p className="stg:flex stg:items-center stg:gap-1.5 stg:text-sm stg:text-foreground">
           {humanHeld ? (
             <>
-              <User aria-hidden="true" className="size-4 text-muted-foreground" />
+              <User aria-hidden="true" className="stg:size-4 stg:text-muted-foreground" />
               {heldByMe
                 ? "You have this conversation — the agent is quiet until you hand it back."
                 : currentIdentityAccountId !== undefined
@@ -114,15 +114,15 @@ export function ConversationControlBanner({
             </>
           ) : (
             <>
-              <Bot aria-hidden="true" className="size-4 text-muted-foreground" />
+              <Bot aria-hidden="true" className="stg:size-4 stg:text-muted-foreground" />
               The agent is serving this conversation.
             </>
           )}
         </p>
 
         {confirmingHandBack ? (
-          <div className="flex items-center gap-2">
-            <span className="text-xs text-destructive">
+          <div className="stg:flex stg:items-center stg:gap-2">
+            <span className="stg:text-xs stg:text-destructive">
               The customer&apos;s last message has no reply — the agent stays
               quiet until they write again.
             </span>
@@ -157,14 +157,14 @@ export function ConversationControlBanner({
             {pendingCommands.has("handBack") ? "Handing back…" : "Hand back to agent"}
           </Button>
         ) : (
-          <div className="flex items-center gap-2">
+          <div className="stg:flex stg:items-center stg:gap-2">
             {!supportsStaffReplies && (
               // Visible text, never a native title (F-18): a disabled
               // Button swallows hover (disabled:pointer-events-none) and
               // leaves the tab order, so a title on it is unreachable by
               // every input method. Kept short — the composer's own
               // notice already explains the missing staff reply lane.
-              <span className="text-xs text-muted-foreground">
+              <span className="stg:text-xs stg:text-muted-foreground">
                 This channel&apos;s provider has no staff send lane yet — a
                 takeover would silence the agent with no way to reply.
               </span>
@@ -186,7 +186,7 @@ export function ConversationControlBanner({
       </div>
 
       {error && (
-        <p className="mt-1 text-xs text-destructive">{getUserMessage(error)}</p>
+        <p className="stg:mt-1 stg:text-xs stg:text-destructive">{getUserMessage(error)}</p>
       )}
     </div>
   );

package/src/conversation/ConversationListPane.tsx

@@ -120,16 +120,16 @@ export function ConversationListPane({
   return (
     <div
       aria-label="Conversation list"
-      className={cn("flex min-h-0 flex-col", className)}
+      className={cn("stg:flex stg:min-h-0 stg:flex-col", className)}
     >
       {(onFilterChange !== undefined || channels.length > 1) && (
-        <div className="flex flex-col gap-2 border-b border-border px-3 py-2">
+        <div className="stg:flex stg:flex-col stg:gap-2 stg:border-b stg:border-border stg:px-3 stg:py-2">
           {onFilterChange !== undefined && (
             <ConversationFilterToggle value={filter} onChange={onFilterChange} />
           )}
           {channels.length > 1 && (
             <>
-              <label className="sr-only" htmlFor="stgm-conversation-channel-filter">
+              <label className="stg:sr-only" htmlFor="stgm-conversation-channel-filter">
                 Filter by channel
               </label>
               <select
@@ -137,9 +137,9 @@ export function ConversationListPane({
                 value={channelFilter}
                 onChange={(e) => onChannelFilterChange(e.target.value)}
                 className={cn(
-                  "w-full rounded-md border border-border bg-background px-2 py-1.5",
-                  "text-sm text-foreground",
-                  "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+                  "stg:w-full stg:rounded-md stg:border stg:border-border stg:bg-background stg:px-2 stg:py-1.5",
+                  "stg:text-sm stg:text-foreground",
+                  "stg:focus-visible:outline-none stg:focus-visible:ring-2 stg:focus-visible:ring-ring",
                 )}
               >
                 <option value="">All channels</option>
@@ -154,18 +154,18 @@ export function ConversationListPane({
         </div>
       )}
 
-      <div className="min-h-0 flex-1 overflow-y-auto p-2">
+      <div className="stg:min-h-0 stg:flex-1 stg:overflow-y-auto stg:p-2">
         {isLoading ? (
           <ListSkeleton />
         ) : error ? (
-          <p className="px-2 py-6 text-center text-sm text-destructive">
+          <p className="stg:px-2 stg:py-6 stg:text-center stg:text-sm stg:text-destructive">
             {getUserMessage(error)}
           </p>
         ) : conversations.length === 0 ? (
           channels.length === 0 ? (
             <EmptyState
               variant="first-use"
-              icon={<MessageSquare className="size-8" />}
+              icon={<MessageSquare className="stg:size-8" />}
               title="No channels to watch"
               description="Conversations arrive through an agent's channels. Connect a channel — or ask a channel owner for access — and customer conversations appear here."
             />
@@ -175,14 +175,14 @@ export function ConversationListPane({
             // to an org with a full inbox and nothing needing a person.
             <EmptyState
               variant="first-use"
-              icon={<MessageSquare className="size-8" />}
+              icon={<MessageSquare className="stg:size-8" />}
               title="Nothing needs a human right now"
               description="Conversations appear here when the agent asks for attention, or when a human-held conversation has a customer message awaiting a reply."
             />
           ) : (
             <EmptyState
               variant="first-use"
-              icon={<MessageSquare className="size-8" />}
+              icon={<MessageSquare className="stg:size-8" />}
               title="No conversations yet"
               description="When a customer messages one of your channels, their conversation appears here."
             />
@@ -192,7 +192,7 @@ export function ConversationListPane({
             {/* One context-only provider arms every row's attention
                 tooltip (the WorkspaceSidebar recents-list precedent). */}
             <TooltipProvider>
-              <ul className="space-y-0.5">
+              <ul className="stg:space-y-0.5">
                 {conversations.map((conversation) => (
                   <ConversationRow
                     key={`${conversation.agentChannelId}:${conversation.conversationKey}`}
@@ -216,7 +216,7 @@ export function ConversationListPane({
               </ul>
             </TooltipProvider>
             {hasMore && (
-              <div className="flex justify-center py-2">
+              <div className="stg:flex stg:justify-center stg:py-2">
                 <Button
                   variant="ghost"
                   size="xs"
@@ -299,7 +299,7 @@ function ConversationFilterToggle({
     <div
       role="radiogroup"
       aria-label="Conversation filter"
-      className="inline-flex self-start rounded-md bg-muted p-0.5"
+      className="stg:inline-flex stg:self-start stg:rounded-md stg:bg-muted stg:p-0.5"
     >
       {FILTER_OPTIONS.map((option, index) => {
         const isSelected = value === option.value;
@@ -317,11 +317,11 @@ function ConversationFilterToggle({
             onClick={() => handleSelect(option.value)}
             onKeyDown={(e) => handleKeyDown(e, index)}
             className={cn(
-              "inline-flex cursor-pointer items-center rounded-sm px-2 py-1 text-xs font-medium transition-colors",
-              "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+              "stg:inline-flex stg:cursor-pointer stg:items-center stg:rounded-sm stg:px-2 stg:py-1 stg:text-xs stg:font-medium stg:transition-colors",
+              "stg:focus-visible:outline-none stg:focus-visible:ring-2 stg:focus-visible:ring-ring",
               isSelected
-                ? "bg-background text-foreground shadow-sm"
-                : "text-muted-foreground hover:text-foreground",
+                ? "stg:bg-background stg:text-foreground stg:shadow-sm"
+                : "stg:text-muted-foreground stg:hover:text-foreground",
             )}
           >
             {option.label}
@@ -364,17 +364,17 @@ const ConversationRow = memo(function ConversationRow({
         onClick={() => onSelect(conversation)}
         aria-current={isSelected ? "true" : undefined}
         className={cn(
-          "flex w-full items-center gap-2.5 rounded-md px-2.5 py-2 text-left",
-          "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
-          isSelected ? "bg-primary-subtle" : "hover:bg-accent",
+          "stg:flex stg:w-full stg:items-center stg:gap-2.5 stg:rounded-md stg:px-2.5 stg:py-2 stg:text-left",
+          "stg:focus-visible:outline-none stg:focus-visible:ring-2 stg:focus-visible:ring-ring",
+          isSelected ? "stg:bg-primary-subtle" : "stg:hover:bg-accent",
         )}
       >
-        <div className="min-w-0 flex-1">
-          <div className="flex items-center gap-1.5">
+        <div className="stg:min-w-0 stg:flex-1">
+          <div className="stg:flex stg:items-center stg:gap-1.5">
             {/* No truncation title on the label (F-18): the full name
                 renders in the open conversation's header, so a native
                 tooltip here added noise without adding reach. */}
-            <p className="truncate text-sm font-medium text-foreground">{label}</p>
+            <p className="stg:truncate stg:text-sm stg:font-medium stg:text-foreground">{label}</p>
             {conversation.needsAttention && (
               // The reason rides the house tooltip (F-18). The trigger
               // renders as a span — it sits INSIDE the row button, so a
@@ -383,12 +383,12 @@ const ConversationRow = memo(function ConversationRow({
               // accessible name. The full reason is also always visible
               // in the open conversation's attention banner.
               <Tooltip>
-                <TooltipTrigger render={<span className="shrink-0" />}>
+                <TooltipTrigger render={<span className="stg:shrink-0" />}>
                   <TriangleAlert
                     aria-hidden="true"
-                    className="size-3.5 text-destructive"
+                    className="stg:size-3.5 stg:text-destructive"
                   />
-                  <span className="sr-only">
+                  <span className="stg:sr-only">
                     {conversation.attentionReason
                       ? `Needs attention: ${conversation.attentionReason}`
                       : "Needs attention"}
@@ -401,21 +401,21 @@ const ConversationRow = memo(function ConversationRow({
             )}
           </div>
           {contact !== null && (
-            <p className="mt-0.5 truncate text-xs text-muted-foreground-faint">
+            <p className="stg:mt-0.5 stg:truncate stg:text-xs stg:text-muted-foreground-faint">
               {contact}
             </p>
           )}
           {humanHeld && (
-            <p className="mt-0.5 flex items-center gap-1 text-xs text-muted-foreground">
-              <User aria-hidden="true" className="size-3" />
+            <p className="stg:mt-0.5 stg:flex stg:items-center stg:gap-1 stg:text-xs stg:text-muted-foreground">
+              <User aria-hidden="true" className="stg:size-3" />
               Human has the conversation
             </p>
           )}
         </div>
         {(lastActivity !== null || awaiting !== null) && (
-          <span className="flex shrink-0 flex-col items-end gap-1">
+          <span className="stg:flex stg:shrink-0 stg:flex-col stg:items-end stg:gap-1">
             {lastActivity && (
-              <span className="text-xs text-muted-foreground-faint">
+              <span className="stg:text-xs stg:text-muted-foreground-faint">
                 {formatRelativeTime(lastActivity, now)}
               </span>
             )}
@@ -426,15 +426,15 @@ const ConversationRow = memo(function ConversationRow({
               // agent will not answer, a person must — muted when the
               // agent does. No tooltip and no tab stop (the F-18
               // discipline); the sr-only text is the accessible meaning.
-              <span className="flex">
+              <span className="stg:flex">
                 <span
                   aria-hidden="true"
                   className={cn(
-                    "size-2 rounded-full",
-                    awaiting === "strong" ? "bg-primary" : "bg-muted-foreground",
+                    "stg:size-2 stg:rounded-full",
+                    awaiting === "strong" ? "stg:bg-primary" : "stg:bg-muted-foreground",
                   )}
                 />
-                <span className="sr-only">
+                <span className="stg:sr-only">
                   {awaiting === "strong"
                     ? "Customer awaiting reply — the conversation is human-held"
                     : "Customer awaiting reply"}
@@ -450,9 +450,9 @@ const ConversationRow = memo(function ConversationRow({
 
 function ListSkeleton() {
   return (
-    <div className="space-y-1 p-1" aria-hidden="true">
+    <div className="stg:space-y-1 stg:p-1" aria-hidden="true">
       {[1, 2, 3, 4].map((i) => (
-        <div key={i} className="h-11 animate-pulse rounded-md bg-muted-faint" />
+        <div key={i} className="stg:h-11 stg:animate-pulse stg:rounded-md stg:bg-muted-faint" />
       ))}
     </div>
   );

package/src/conversation/ConversationMediaAttachment.tsx

@@ -0,0 +1,308 @@
+"use client";
+
+import { useCallback, useMemo, useState } from "react";
+import { create } from "@bufbuild/protobuf";
+import { cn } from "@stigmer/theme";
+import { getUserMessage } from "@stigmer/sdk";
+import type { ConversationMediaRef } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/conversation_io_pb";
+import { GetConversationMediaDownloadUrlInputSchema } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/conversation_io_pb";
+import { AttachmentImageLightbox } from "../attachment/AttachmentImageLightbox.js";
+import { formatFileSize } from "../attachment/attachment-utils.js";
+import { UNSTYLED_BUTTON } from "../internal/form-primitives.js";
+import { toError } from "../internal/toError.js";
+import { useStigmer } from "../hooks.js";
+import { useConversationMediaUrl } from "./useConversationMediaUrl.js";
+
+/**
+ * The full address of one timeline item's media — what
+ * `getMediaDownloadUrl` is addressed by. The storage key deliberately
+ * never rides the wire (whatsapp-media DD-001 D4); the server resolves
+ * it from its own row, so this address is all a client ever holds.
+ */
+export interface ConversationMediaAddress {
+  /** AgentChannel the conversation belongs to. */
+  readonly agentChannelId: string;
+  /** Conversation key within the channel (WhatsApp: the customer's wa_id). */
+  readonly conversationKey: string;
+  /** The timeline item carrying the media (its item_id, e.g. `"wa:<wamid>"`). */
+  readonly itemId: string;
+}
+
+/** Props for {@link ConversationMediaAttachment}. */
+export interface ConversationMediaAttachmentProps {
+  /** The item's media reference (filename, content type, size). */
+  readonly media: ConversationMediaRef;
+  /** Where to fetch the bytes from. */
+  readonly address: ConversationMediaAddress;
+  /** Additional CSS classes for the container. */
+  readonly className?: string;
+}
+
+/**
+ * One inbound timeline item's ingested media (stigmer/stigmer#367):
+ * images as a WhatsApp-style inline thumbnail (click opens the shared
+ * {@link AttachmentImageLightbox}), everything else as a document chip
+ * (filename + size, click opens the file in a new tab).
+ *
+ * This component calls `useStigmer()`, so it must only be MOUNTED when
+ * the timeline view holds a conversation address — that conditional
+ * mount is what keeps `ConversationTimelineView` renderable without a
+ * `StigmerProvider` (its presentational contract; see the view's
+ * `agentChannelId` prop).
+ *
+ * Deliberately a sibling of the execution thread's `MessageAttachments`,
+ * not a reuse of it: that row renders storage-key-addressed artifacts of
+ * an execution the viewer owns, while this one renders
+ * conversation-viewer-scoped media addressed by timeline position — the
+ * two read paths have different trust models (DD-001 D4) and different
+ * bubble treatments (chat thumbnail vs. attachment chip row).
+ */
+export function ConversationMediaAttachment({
+  media,
+  address,
+  className,
+}: ConversationMediaAttachmentProps) {
+  const isImage = media.contentType.startsWith("image/");
+  return isImage ? (
+    <MediaImageThumbnail media={media} address={address} className={className} />
+  ) : (
+    <MediaDocumentChip media={media} address={address} className={className} />
+  );
+}
+
+/**
+ * Display name for the media: the ingest-recorded filename (documents
+ * keep the provider's name; camera images get a platform-synthesized
+ * one, so this is never empty in practice), with a defensive fallback.
+ */
+function displayName(media: ConversationMediaRef): string {
+  return media.filename || "attachment";
+}
+
+// ---------------------------------------------------------------------------
+// Image — WhatsApp-style inline thumbnail, click-to-open lightbox
+// ---------------------------------------------------------------------------
+
+/**
+ * A bounded preview frame in the bubble, minted from the item address at
+ * view time. The frame is fixed-size for BOTH the pulse placeholder and
+ * the loaded image, so the load causes no layout shift (the
+ * content-agnostic auto-scroll then needs no special case). If the URL
+ * can't be minted (revoked media, transient API failure, the server's
+ * uniform NOT_FOUND), the treatment degrades to the document chip —
+ * never a broken-image glyph (the `MessageAttachments` precedent).
+ */
+function MediaImageThumbnail({
+  media,
+  address,
+  className,
+}: {
+  readonly media: ConversationMediaRef;
+  readonly address: ConversationMediaAddress;
+  readonly className?: string;
+}) {
+  const { url, error } = useConversationMediaUrl(
+    address.agentChannelId,
+    address.conversationKey,
+    address.itemId,
+  );
+  const [previewOpen, setPreviewOpen] = useState(false);
+  const name = displayName(media);
+
+  if (error) {
+    return <MediaDocumentChip media={media} address={address} className={className} />;
+  }
+
+  return (
+    <>
+      {/* UNSTYLED_BUTTON adds the pointer cursor — the media thumbnail
+          carries no other clickability cue. */}
+      <button
+        type="button"
+        onClick={() => setPreviewOpen(true)}
+        aria-label={`Preview ${name}`}
+        className={cn(
+          UNSTYLED_BUTTON,
+          "stg:block stg:rounded-md stg:focus-visible:outline-none stg:focus-visible:ring-2 stg:focus-visible:ring-ring",
+          className,
+        )}
+      >
+        <span className="stg:relative stg:block stg:h-40 stg:w-56 stg:max-w-full stg:overflow-hidden stg:rounded-md">
+          {url ? (
+            <img
+              src={url}
+              alt=""
+              aria-hidden="true"
+              loading="lazy"
+              className="stg:h-full stg:w-full stg:object-cover"
+            />
+          ) : (
+            // Pulse placeholder while the presigned URL is minted; same
+            // footprint as the image, so no layout shift.
+            <span
+              className="stg:block stg:h-full stg:w-full stg:animate-pulse stg:bg-muted"
+              aria-hidden="true"
+            />
+          )}
+        </span>
+      </button>
+      {previewOpen && (
+        <AttachmentImageLightbox
+          src={url}
+          filename={name}
+          open
+          onClose={() => setPreviewOpen(false)}
+        />
+      )}
+    </>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Document — compact chip, click-to-open in a new tab
+// ---------------------------------------------------------------------------
+
+/**
+ * The compact treatment for documents (and the degraded arm for images
+ * whose URL failed): file glyph, filename, size. A click mints a FRESH
+ * URL — presigned URLs expire, so the stable item address is the thing
+ * to hold, not a URL (the `useArtifactDownload` rationale) — and opens
+ * it in a new tab: the media contract presigns inline disposition only,
+ * so the browser previews what it can (PDFs) and downloads the rest.
+ * A failed mint reports below the chip in the surface's own error
+ * grammar (DD-006 — never a silent dead click).
+ */
+function MediaDocumentChip({
+  media,
+  address,
+  className,
+}: {
+  readonly media: ConversationMediaRef;
+  readonly address: ConversationMediaAddress;
+  readonly className?: string;
+}) {
+  const { open, isOpening, error } = useOpenConversationMedia(address);
+  const name = displayName(media);
+  const size = media.sizeBytes > BigInt(0)
+    ? // WhatsApp caps media far below 2^53 bytes, so the narrowing is exact.
+      formatFileSize(Number(media.sizeBytes))
+    : null;
+
+  return (
+    <div className={className}>
+      <span
+        title={name}
+        className="stg:inline-flex stg:max-w-[240px] stg:items-center stg:rounded-md stg:bg-muted-subtle stg:px-2 stg:py-1 stg:text-xs stg:text-foreground"
+      >
+        <button
+          type="button"
+          onClick={() => void open()}
+          disabled={isOpening}
+          aria-label={`Open ${name}`}
+          className={cn(
+            UNSTYLED_BUTTON,
+            "stg:flex stg:min-w-0 stg:items-center stg:gap-1.5 stg:rounded-sm stg:hover:text-accent-foreground stg:focus-visible:outline-none stg:focus-visible:ring-2 stg:focus-visible:ring-ring",
+            isOpening && "stg:opacity-70",
+          )}
+        >
+          <FileGlyph />
+          <span className="stg:min-w-0 stg:truncate">{name}</span>
+          {size !== null && (
+            <span className="stg:shrink-0 stg:text-muted-foreground">{size}</span>
+          )}
+        </button>
+      </span>
+      {error !== null && (
+        <p className="stg:mt-1 stg:break-words stg:text-xs stg:text-destructive">
+          {getUserMessage(error)}
+        </p>
+      )}
+    </div>
+  );
+}
+
+/**
+ * Click → mint fresh URL → open in a new tab. Kept local to this file:
+ * unlike {@link useConversationMediaUrl} (render data), an open is a
+ * user action — and it must complete within the browser's
+ * user-activation window, which the single fast unary mint does.
+ */
+function useOpenConversationMedia(address: ConversationMediaAddress): {
+  readonly open: () => Promise<void>;
+  readonly isOpening: boolean;
+  readonly error: Error | null;
+} {
+  const stigmer = useStigmer();
+  const [isOpening, setIsOpening] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const open = useCallback(async () => {
+    if (isOpening) return;
+    setIsOpening(true);
+    setError(null);
+    try {
+      const result = await stigmer.agentChannel.getMediaDownloadUrl(
+        create(GetConversationMediaDownloadUrlInputSchema, {
+          agentChannelId: address.agentChannelId,
+          conversationKey: address.conversationKey,
+          itemId: address.itemId,
+        }),
+      );
+      if (result.url) {
+        openInNewTab(result.url);
+      }
+    } catch (err) {
+      setError(toError(err));
+    } finally {
+      setIsOpening(false);
+    }
+  }, [stigmer, address.agentChannelId, address.conversationKey, address.itemId, isOpening]);
+
+  return useMemo(() => ({ open, isOpening, error }), [open, isOpening, error]);
+}
+
+/**
+ * Open a URL in a new tab via a transient anchor click (the
+ * `triggerBrowserDownload` shape, minus the `download` hint — the URL's
+ * disposition is inline and cross-origin anchors ignore the attribute
+ * anyway). Falls back to `window.open` in non-DOM environments.
+ */
+function openInNewTab(url: string): void {
+  if (typeof document === "undefined") {
+    if (typeof window !== "undefined") {
+      window.open(url, "_blank", "noopener,noreferrer");
+    }
+    return;
+  }
+  const anchor = document.createElement("a");
+  anchor.href = url;
+  anchor.rel = "noopener noreferrer";
+  anchor.target = "_blank";
+  document.body.appendChild(anchor);
+  anchor.click();
+  document.body.removeChild(anchor);
+}
+
+/**
+ * Generic document glyph — the same geometry as the attachment chips'
+ * icon so the surfaces read as one family.
+ */
+function FileGlyph() {
+  return (
+    <svg
+      width="10"
+      height="10"
+      viewBox="0 0 14 14"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className="stg:shrink-0 stg:text-muted-foreground"
+      aria-hidden="true"
+    >
+      <path d="M8 1H4C3.45 1 3 1.45 3 2V12C3 12.55 3.45 13 4 13H10C10.55 13 11 12.55 11 12V4L8 1Z" />
+      <path d="M8 1V4H11" />
+    </svg>
+  );
+}