@stigmer/react 3.9.0 → 3.11.0

package/src/conversation/ConversationTimelineView.tsx

@@ -17,6 +17,7 @@ import {
   TooltipTrigger,
 } from "../internal/tooltip.js";
 import { useAutoScroll } from "../internal/useAutoScroll.js";
+import { ConversationMediaAttachment } from "./ConversationMediaAttachment.js";
 import {
   authorKindOf,
   inboundPlaceholderOf,
@@ -30,6 +31,23 @@ import {
 export interface ConversationTimelineViewProps {
   /** Timeline items in chronological order (from `useConversationTimeline`). */
   readonly items: readonly ConversationTimelineItem[];
+  /**
+   * AgentChannel the conversation belongs to. Together with
+   * `conversationKey`, this is the opt-in for media rendering: items
+   * carrying `media` render an inline thumbnail or document chip whose
+   * bytes are fetched via `getMediaDownloadUrl` — which is addressed by
+   * (channel, conversation, item), so the view cannot fetch media
+   * without the address.
+   *
+   * When either identity prop is absent, media items keep the typed
+   * placeholder ("Photo", "Document") — and, load-bearing for
+   * provider-less hosts (documentation fixtures, visual tests): nothing
+   * that needs a `StigmerProvider` mounts, so the view stays purely
+   * presentational exactly as before these props existed.
+   */
+  readonly agentChannelId?: string;
+  /** Conversation key within the channel (see `agentChannelId`). */
+  readonly conversationKey?: string;
   /** `true` only during the first load. */
   readonly isLoading: boolean;
   /** Error from the timeline read, or `null`. */
@@ -71,6 +89,8 @@ export interface ConversationTimelineViewProps {
  */
 export function ConversationTimelineView({
   items,
+  agentChannelId,
+  conversationKey,
   isLoading,
   error,
   hasOlder,
@@ -93,15 +113,15 @@ export function ConversationTimelineView({
     <TooltipProvider>
       <div
         aria-label="Conversation timeline"
-        className={cn("relative flex min-h-0 flex-1 flex-col", className)}
+        className={cn("stg:relative stg:flex stg:min-h-0 stg:flex-1 stg:flex-col", className)}
       >
         <div
           ref={scrollRef}
-          className="min-h-0 flex-1 overflow-y-auto [overflow-anchor:none] px-4 py-3"
+          className="stg:min-h-0 stg:flex-1 stg:overflow-y-auto stg:[overflow-anchor:none] stg:px-4 stg:py-3"
         >
           {!showsCustomerMessages && descriptor && (
-            <div className="mb-3 flex items-start gap-2 rounded-md border border-border bg-muted-faint px-3 py-2 text-xs text-muted-foreground">
-              <Info aria-hidden="true" className="mt-0.5 size-3.5 shrink-0" />
+            <div className="stg:mb-3 stg:flex stg:items-start stg:gap-2 stg:rounded-md stg:border stg:border-border stg:bg-muted-faint stg:px-3 stg:py-2 stg:text-xs stg:text-muted-foreground">
+              <Info aria-hidden="true" className="stg:mt-0.5 stg:size-3.5 stg:shrink-0" />
               <p>
                 Customer messages on {descriptor.label} channels aren&apos;t shown
                 here yet — this thread has replies, sends, and internal events only.
@@ -112,20 +132,20 @@ export function ConversationTimelineView({
           {isLoading ? (
             <TimelineSkeleton />
           ) : 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>
           ) : items.length === 0 ? (
             <EmptyState
               variant="first-use"
-              icon={<MessageSquare className="size-8" />}
+              icon={<MessageSquare className="stg:size-8" />}
               title="No messages yet"
               description="The conversation's messages appear here as they happen."
             />
           ) : (
             <div ref={contentRef}>
               {hasOlder && (
-                <div className="flex justify-center pb-2">
+                <div className="stg:flex stg:justify-center stg:pb-2">
                   <Button
                     variant="ghost"
                     size="xs"
@@ -139,14 +159,19 @@ export function ConversationTimelineView({
               {days.map((day) => (
                 <div key={day.label}>
                   <div
-                    className="my-2 text-center text-xs text-muted-foreground-faint"
+                    className="stg:my-2 stg:text-center stg:text-xs stg:text-muted-foreground-faint"
                     role="separator"
                   >
                     {day.label}
                   </div>
-                  <ul className="space-y-1.5">
+                  <ul className="stg:space-y-1.5">
                     {day.items.map((item) => (
-                      <TimelineItemRow key={item.itemId} item={item} />
+                      <TimelineItemRow
+                        key={item.itemId}
+                        item={item}
+                        agentChannelId={agentChannelId}
+                        conversationKey={conversationKey}
+                      />
                     ))}
                   </ul>
                 </div>
@@ -170,8 +195,12 @@ const BUSINESS_CAPTION: Record<Exclude<ConversationAuthorKind, "customer">, stri
 
 const TimelineItemRow = memo(function TimelineItemRow({
   item,
+  agentChannelId,
+  conversationKey,
 }: {
   readonly item: ConversationTimelineItem;
+  readonly agentChannelId?: string;
+  readonly conversationKey?: string;
 }) {
   if (isInternalItem(item)) {
     return <InternalEventRow item={item} />;
@@ -179,7 +208,17 @@ const TimelineItemRow = memo(function TimelineItemRow({
 
   const author = authorKindOf(item);
   const isCustomer = author === "customer";
-  const body = item.text || inboundPlaceholderOf(item);
+
+  // Ingested media renders as the real thing — an inline thumbnail or
+  // document chip — ONLY when the view holds the conversation address
+  // (getMediaDownloadUrl's addressing; see the identity props' contract).
+  // Without the address, and on media the platform declined to ingest,
+  // the typed placeholder keeps telling staff what arrived.
+  const mediaAddress =
+    item.media !== undefined && agentChannelId && conversationKey
+      ? { agentChannelId, conversationKey, itemId: item.itemId }
+      : null;
+  const body = item.text || (mediaAddress !== null ? "" : inboundPlaceholderOf(item));
 
   // DD-014 D-c (amended at the Sitting 2 gate, R-1): the provider's
   // failure explanation is decision-bearing — window closed vs bad
@@ -199,28 +238,39 @@ const TimelineItemRow = memo(function TimelineItemRow({
       : null;
 
   return (
-    <li className={cn("flex", isCustomer ? "justify-start" : "justify-end")}>
+    <li className={cn("stg:flex", isCustomer ? "stg:justify-start" : "stg:justify-end")}>
       <div
         className={cn(
-          "max-w-[80%] rounded-lg px-3 py-2",
-          isCustomer ? "bg-muted-subtle" : "bg-primary-subtle",
+          "stg:max-w-[80%] stg:rounded-lg stg:px-3 stg:py-2",
+          isCustomer ? "stg:bg-muted-subtle" : "stg:bg-primary-subtle",
         )}
       >
         {!isCustomer && (
-          <p className="text-xs font-medium text-muted-foreground">
+          <p className="stg:text-xs stg:font-medium stg:text-muted-foreground">
             {BUSINESS_CAPTION[author]}
           </p>
         )}
-        <p
-          className={cn(
-            "whitespace-pre-wrap break-words text-sm text-foreground",
-            !item.text && "italic text-muted-foreground",
-          )}
-        >
-          {body || "Message content unavailable"}
-        </p>
+        {mediaAddress !== null && item.media !== undefined && (
+          <ConversationMediaAttachment
+            media={item.media}
+            address={mediaAddress}
+            className={item.text ? "stg:mb-1.5" : undefined}
+          />
+        )}
+        {/* A media item without a caption is complete as its media —
+            no body, and no "unavailable" apology under the thumbnail. */}
+        {(body || mediaAddress === null) && (
+          <p
+            className={cn(
+              "stg:whitespace-pre-wrap stg:break-words stg:text-sm stg:text-foreground",
+              !item.text && "stg:italic stg:text-muted-foreground",
+            )}
+          >
+            {body || "Message content unavailable"}
+          </p>
+        )}
         {receiptExplanation !== null && (
-          <p className="mt-1 break-words text-xs text-destructive">
+          <p className="stg:mt-1 stg:break-words stg:text-xs stg:text-destructive">
             {receiptExplanation}
           </p>
         )}
@@ -273,30 +323,30 @@ function ItemFooter({ item }: { readonly item: ConversationTimelineItem }) {
     : "";
 
   return (
-    <p className="mt-1 flex items-center justify-end gap-1 text-xs text-muted-foreground-faint">
+    <p className="stg:mt-1 stg:flex stg:items-center stg:justify-end stg:gap-1 stg:text-xs stg:text-muted-foreground-faint">
       <span>{time}</span>
       {attempt === "failed" && (
         <StatusHint
           hint="The platform could not deliver this message"
-          className="flex items-center gap-0.5 text-destructive"
+          className="stg:flex stg:items-center stg:gap-0.5 stg:text-destructive"
         >
-          <TriangleAlert aria-hidden="true" className="size-3" />
+          <TriangleAlert aria-hidden="true" className="stg:size-3" />
           Not delivered
         </StatusHint>
       )}
       {attempt === "suppressed" && (
         <StatusHint
           hint="Withheld because a human had the conversation when it came due"
-          className="flex items-center gap-0.5"
+          className="stg:flex stg:items-center stg:gap-0.5"
         >
-          <Ban aria-hidden="true" className="size-3" />
+          <Ban aria-hidden="true" className="stg:size-3" />
           Held
         </StatusHint>
       )}
       {(attempt === "pending" || attempt === "delivering") && (
-        <StatusHint hint="Sending" className="flex items-center gap-0.5">
-          <Clock aria-hidden="true" className="size-3" />
-          <span className="sr-only">Sending</span>
+        <StatusHint hint="Sending" className="stg:flex stg:items-center stg:gap-0.5">
+          <Clock aria-hidden="true" className="stg:size-3" />
+          <span className="stg:sr-only">Sending</span>
         </StatusHint>
       )}
       {attempt === "delivered" && <ReceiptTicks item={item} />}
@@ -316,34 +366,34 @@ function ReceiptTicks({ item }: { readonly item: ConversationTimelineItem }) {
     return (
       <StatusHint
         hint="The provider accepted this message but could not deliver it"
-        className="flex items-center gap-0.5 text-destructive"
+        className="stg:flex stg:items-center stg:gap-0.5 stg:text-destructive"
       >
-        <TriangleAlert aria-hidden="true" className="size-3" />
+        <TriangleAlert aria-hidden="true" className="stg:size-3" />
         Delivery failed
       </StatusHint>
     );
   }
   if (receipt === "read") {
     return (
-      <StatusHint hint="Read by the customer" className="text-primary">
-        <CheckCheck aria-hidden="true" className="size-3.5" />
-        <span className="sr-only">Read</span>
+      <StatusHint hint="Read by the customer" className="stg:text-primary">
+        <CheckCheck aria-hidden="true" className="stg:size-3.5" />
+        <span className="stg:sr-only">Read</span>
       </StatusHint>
     );
   }
   if (receipt === "delivered") {
     return (
       <StatusHint hint="Delivered to the customer's device">
-        <CheckCheck aria-hidden="true" className="size-3.5" />
-        <span className="sr-only">Delivered</span>
+        <CheckCheck aria-hidden="true" className="stg:size-3.5" />
+        <span className="stg:sr-only">Delivered</span>
       </StatusHint>
     );
   }
   // Handed to the provider; no (further) receipt yet.
   return (
     <StatusHint hint="Sent">
-      <Check aria-hidden="true" className="size-3.5" />
-      <span className="sr-only">Sent</span>
+      <Check aria-hidden="true" className="stg:size-3.5" />
+      <span className="stg:sr-only">Sent</span>
     </StatusHint>
   );
 }
@@ -359,25 +409,25 @@ function InternalEventRow({ item }: { readonly item: ConversationTimelineItem })
   const isEscalation = author === "agent" && item.text !== "";
 
   return (
-    <li className="flex justify-center">
+    <li className="stg:flex stg:justify-center">
       <div
         className={cn(
-          "flex max-w-[90%] items-start gap-1.5 rounded-md px-3 py-1.5 text-center text-xs",
+          "stg:flex stg:max-w-[90%] stg:items-start stg:gap-1.5 stg:rounded-md stg:px-3 stg:py-1.5 stg:text-center stg:text-xs",
           isEscalation
-            ? "bg-destructive-subtle text-destructive"
-            : "bg-muted-faint text-muted-foreground",
+            ? "stg:bg-destructive-subtle stg:text-destructive"
+            : "stg:bg-muted-faint stg:text-muted-foreground",
         )}
       >
         {isEscalation ? (
           <>
-            <TriangleAlert aria-hidden="true" className="mt-0.5 size-3.5 shrink-0" />
-            <span className="min-w-0 break-words">
+            <TriangleAlert aria-hidden="true" className="stg:mt-0.5 stg:size-3.5 stg:shrink-0" />
+            <span className="stg:min-w-0 stg:break-words">
               Agent escalated to a human — “{item.text}”
             </span>
           </>
         ) : item.text !== "" ? (
           // A future internal note flows through with zero code change.
-          <span className="min-w-0 break-words">{item.text}</span>
+          <span className="stg:min-w-0 stg:break-words">{item.text}</span>
         ) : (
           <span>A teammate resolved the attention flag</span>
         )}
@@ -388,10 +438,10 @@ function InternalEventRow({ item }: { readonly item: ConversationTimelineItem })
 
 function TimelineSkeleton() {
   return (
-    <div className="space-y-2" aria-hidden="true">
-      <div className="h-10 w-3/5 animate-pulse rounded-lg bg-muted-faint" />
-      <div className="ml-auto h-10 w-3/5 animate-pulse rounded-lg bg-muted-faint" />
-      <div className="h-10 w-2/5 animate-pulse rounded-lg bg-muted-faint" />
+    <div className="stg:space-y-2" aria-hidden="true">
+      <div className="stg:h-10 stg:w-3/5 stg:animate-pulse stg:rounded-lg stg:bg-muted-faint" />
+      <div className="stg:ml-auto stg:h-10 stg:w-3/5 stg:animate-pulse stg:rounded-lg stg:bg-muted-faint" />
+      <div className="stg:h-10 stg:w-2/5 stg:animate-pulse stg:rounded-lg stg:bg-muted-faint" />
     </div>
   );
 }

package/src/conversation/ConversationsWorkbench.tsx

@@ -265,10 +265,10 @@ export function ConversationsWorkbench({
   return (
     <div
       aria-label="Conversations workbench"
-      className={cn("flex min-h-0 flex-1", className)}
+      className={cn("stg:flex stg:min-h-0 stg:flex-1", className)}
     >
       <ConversationListPane
-        className="w-80 shrink-0 border-r border-border"
+        className="stg:w-80 stg:shrink-0 stg:border-r stg:border-border"
         conversations={list.conversations}
         isLoading={list.isLoading}
         error={list.error}
@@ -286,10 +286,10 @@ export function ConversationsWorkbench({
       />
 
       {selected === null ? (
-        <div className="flex min-w-0 flex-1 items-center justify-center p-6">
+        <div className="stg:flex stg:min-w-0 stg:flex-1 stg:items-center stg:justify-center stg:p-6">
           <EmptyState
             variant="first-use"
-            icon={<MessagesSquare className="size-8" />}
+            icon={<MessagesSquare className="stg:size-8" />}
             title="Select a conversation"
             description="Pick a conversation to read its thread, reply as your business, or take over from the agent."
           />
@@ -305,15 +305,15 @@ export function ConversationsWorkbench({
         // Channel ids never contain ":", so the joined key is unambiguous.
         <div
           key={`${selected.agentChannelId}:${selected.conversationKey}`}
-          className="flex min-w-0 flex-1 flex-col"
+          className="stg:flex stg:min-w-0 stg:flex-1 stg:flex-col"
         >
-          <div className="flex items-center justify-between gap-2 border-b border-border px-4 py-2.5">
-            <div className="min-w-0">
-              <h2 className="truncate text-sm font-semibold text-foreground">
+          <div className="stg:flex stg:items-center stg:justify-between stg:gap-2 stg:border-b stg:border-border stg:px-4 stg:py-2.5">
+            <div className="stg:min-w-0">
+              <h2 className="stg:truncate stg:text-sm stg:font-semibold stg:text-foreground">
                 {detailLabel}
               </h2>
               {(detailContact !== null || channelName) && (
-                <p className="truncate text-xs text-muted-foreground">
+                <p className="stg:truncate stg:text-xs stg:text-muted-foreground">
                   {detailContact}
                   {detailContact !== null && channelName && " · "}
                   {channelName &&
@@ -323,7 +323,7 @@ export function ConversationsWorkbench({
                     (selectedChannelHref ? (
                       <a
                         href={selectedChannelHref}
-                        className="hover:text-foreground hover:underline"
+                        className="stg:hover:text-foreground stg:hover:underline"
                       >
                         {channelName}
                       </a>
@@ -354,6 +354,8 @@ export function ConversationsWorkbench({
 
           <ConversationTimelineView
             items={timeline.items}
+            agentChannelId={selected.agentChannelId}
+            conversationKey={selected.conversationKey}
             isLoading={timeline.isLoading}
             error={timeline.error}
             hasOlder={timeline.hasOlder}

package/src/conversation/__tests__/ConversationComposer.test.tsx

@@ -85,7 +85,7 @@ describe("ConversationComposer", () => {
     expect(button.textContent).toContain("Sending…");
     // The house in-flight glyph (the session composer's pattern): the
     // static Send icon must not render while the reply is in flight.
-    expect(button.querySelector("svg.animate-spin")).not.toBeNull();
+    expect(button.querySelector("svg.stg\\:animate-spin")).not.toBeNull();
     expect(
       (screen.getByLabelText("Reply to the customer") as HTMLTextAreaElement).disabled,
     ).toBe(true);

package/src/conversation/__tests__/ConversationTimelineView.test.tsx

@@ -1,8 +1,10 @@
-import { describe, it, expect, vi, afterEach } from "vitest";
-import { cleanup, render, screen } from "@testing-library/react";
+import { describe, it, expect, vi, beforeAll, afterEach } from "vitest";
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
+import type { ReactElement } from "react";
 import { create } from "@bufbuild/protobuf";
 import { timestampFromDate } from "@bufbuild/protobuf/wkt";
+import type { Stigmer } from "@stigmer/sdk";
 import {
   ConversationItemAuthor,
   ConversationLane,
@@ -10,6 +12,7 @@ import {
 } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/conversation_io_pb";
 import { ChannelDeliveryStatus } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/delivery_pb";
 import { ChannelReceiptState } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/outbound_pb";
+import { StigmerContext } from "../../context";
 import { ConversationTimelineView } from "../ConversationTimelineView";
 
 const NOW = new Date("2026-08-07T12:00:00Z");
@@ -308,10 +311,14 @@ describe("ConversationTimelineView", () => {
     expect(screen.getByText("Held")).toBeDefined();
     expect(screen.getByText("Delivery failed")).toBeDefined();
     // Zero new tab stops: seven focusable glyphs per screen of messages
-    // would be an accessibility regression dressed as a fix. Nothing
-    // inside a message row may be focusable — the Jump-to-latest
-    // affordance (which manages its own tabIndex) lives outside the
-    // rows and stays the surface's only interactive element.
+    // would be an accessibility regression dressed as a fix. No status
+    // or metadata element inside a message row may be focusable — the
+    // Jump-to-latest affordance (which manages its own tabIndex) lives
+    // outside the rows. Media affordances (thumbnail preview, document
+    // open) are the one deliberate exception: they are the row's
+    // CONTENT action, which keyboard users must reach — covered in the
+    // "inbound media" suite below. These fixtures carry none, so the
+    // row-wide assertion holds here.
     expect(container.querySelectorAll("li [tabindex]")).toHaveLength(0);
     expect(container.querySelectorAll("li button")).toHaveLength(0);
   });
@@ -403,3 +410,223 @@ describe("ConversationTimelineView", () => {
     expect(screen.getByText("stitch failed")).toBeDefined();
   });
 });
+
+// ---------------------------------------------------------------------------
+// Inbound media (stigmer/stigmer#367): items carrying ingested media render
+// the real thing — an inline thumbnail or a document chip whose bytes are
+// fetched through getMediaDownloadUrl — instead of the typed placeholder.
+// The real hook runs against a mocked Stigmer client, so these cover the
+// full wiring: the item address on the RPC, the presigned URL on the
+// <img>, and the click-time mint on documents.
+// ---------------------------------------------------------------------------
+
+describe("ConversationTimelineView inbound media", () => {
+  // happy-dom does not implement the native dialog show/close methods.
+  beforeAll(() => {
+    HTMLDialogElement.prototype.showModal = function showModal() {
+      this.open = true;
+    };
+    HTMLDialogElement.prototype.close = function close() {
+      this.open = false;
+    };
+  });
+
+  afterEach(() => cleanup());
+
+  const identityProps = {
+    agentChannelId: "ach-1",
+    conversationKey: "15551234567",
+  };
+
+  const photoMedia = {
+    filename: "kitchen-leak.jpg",
+    contentType: "image/jpeg",
+    sizeBytes: BigInt(204800),
+  };
+
+  const documentMedia = {
+    filename: "lease-agreement.pdf",
+    contentType: "application/pdf",
+    sizeBytes: BigInt(1048576),
+  };
+
+  function renderWithClient(ui: ReactElement, getMediaDownloadUrl: ReturnType<typeof vi.fn>) {
+    const stigmer = { agentChannel: { getMediaDownloadUrl } } as unknown as Stigmer;
+    return render(
+      <StigmerContext.Provider value={stigmer}>{ui}</StigmerContext.Provider>,
+    );
+  }
+
+  it("renders an inbound photo as a thumbnail with click-to-open lightbox", async () => {
+    const mint = vi.fn().mockResolvedValue({ url: "https://r2.example/presigned/photo" });
+    const { container } = renderWithClient(
+      <ConversationTimelineView
+        {...baseProps()}
+        {...identityProps}
+        items={[
+          item("wa:1", {
+            author: ConversationItemAuthor.author_customer,
+            providerMessageType: "image",
+            media: photoMedia,
+          }),
+        ]}
+      />,
+      mint,
+    );
+
+    // The URL is minted from the item's full conversation address —
+    // never a storage key (whatsapp-media DD-001 D4).
+    await waitFor(() => {
+      const img = container.querySelector("img[aria-hidden='true']");
+      expect(img?.getAttribute("src")).toBe("https://r2.example/presigned/photo");
+    });
+    const req = mint.mock.calls[0][0];
+    expect(req.agentChannelId).toBe("ach-1");
+    expect(req.conversationKey).toBe("15551234567");
+    expect(req.itemId).toBe("wa:1");
+
+    // The placeholder gave way to the real thing.
+    expect(screen.queryByText("Photo")).toBeNull();
+
+    // Click-to-open: the shared lightbox mounts with the full image.
+    fireEvent.click(screen.getByRole("button", { name: "Preview kitchen-leak.jpg" }));
+    const dialog = container.querySelector("dialog");
+    expect(dialog).toBeTruthy();
+    expect(dialog!.getAttribute("aria-label")).toBe("Preview kitchen-leak.jpg");
+  });
+
+  it("renders a photo's caption beside it, and no apology when there is none", async () => {
+    const mint = vi.fn().mockResolvedValue({ url: "https://r2.example/presigned/photo" });
+    renderWithClient(
+      <ConversationTimelineView
+        {...baseProps()}
+        {...identityProps}
+        items={[
+          item("wa:1", {
+            author: ConversationItemAuthor.author_customer,
+            providerMessageType: "image",
+            text: "here's the leak under the sink",
+            media: photoMedia,
+          }),
+        ]}
+      />,
+      mint,
+    );
+
+    expect(screen.getByText("here's the leak under the sink")).toBeDefined();
+    // A caption-less media item is complete as its media — never the
+    // "Message content unavailable" apology (that copy is for items
+    // with neither text nor media nor a typed placeholder).
+    expect(screen.queryByText("Message content unavailable")).toBeNull();
+  });
+
+  it("renders an inbound document as a chip; a click mints a fresh URL and opens it", async () => {
+    const mint = vi.fn().mockResolvedValue({ url: "https://r2.example/presigned/doc" });
+    const anchorClick = vi
+      .spyOn(HTMLAnchorElement.prototype, "click")
+      .mockImplementation(() => {});
+    renderWithClient(
+      <ConversationTimelineView
+        {...baseProps()}
+        {...identityProps}
+        items={[
+          item("wa:2", {
+            author: ConversationItemAuthor.author_customer,
+            providerMessageType: "document",
+            media: documentMedia,
+          }),
+        ]}
+      />,
+      mint,
+    );
+
+    // The chip carries the operator's decision facts: name and size.
+    expect(screen.getByText("lease-agreement.pdf")).toBeDefined();
+    expect(screen.getByText("1.0 MB")).toBeDefined();
+    // No render-time mint for documents — the URL is minted fresh at
+    // click time (presigned URLs expire; the item address does not).
+    expect(mint).not.toHaveBeenCalled();
+
+    fireEvent.click(screen.getByRole("button", { name: "Open lease-agreement.pdf" }));
+    await waitFor(() => expect(anchorClick).toHaveBeenCalled());
+    const req = mint.mock.calls[0][0];
+    expect(req.agentChannelId).toBe("ach-1");
+    expect(req.conversationKey).toBe("15551234567");
+    expect(req.itemId).toBe("wa:2");
+    anchorClick.mockRestore();
+  });
+
+  it("degrades a photo whose URL cannot be minted to the document treatment", async () => {
+    const mint = vi
+      .fn()
+      .mockRejectedValue(new Error("no downloadable media at this timeline item"));
+    const { container } = renderWithClient(
+      <ConversationTimelineView
+        {...baseProps()}
+        {...identityProps}
+        items={[
+          item("wa:1", {
+            author: ConversationItemAuthor.author_customer,
+            providerMessageType: "image",
+            media: photoMedia,
+          }),
+        ]}
+      />,
+      mint,
+    );
+
+    // Never a broken-image glyph — the file stays reachable as a chip.
+    await waitFor(() =>
+      expect(screen.getByRole("button", { name: "Open kitchen-leak.jpg" })).toBeDefined(),
+    );
+    expect(container.querySelector("img")).toBeNull();
+  });
+
+  it("reports a failed document open under the chip, never a silent dead click", async () => {
+    const mint = vi
+      .fn()
+      .mockRejectedValue(new Error("no downloadable media at this timeline item"));
+    renderWithClient(
+      <ConversationTimelineView
+        {...baseProps()}
+        {...identityProps}
+        items={[
+          item("wa:2", {
+            author: ConversationItemAuthor.author_customer,
+            providerMessageType: "document",
+            media: documentMedia,
+          }),
+        ]}
+      />,
+      mint,
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: "Open lease-agreement.pdf" }));
+    await waitFor(() =>
+      expect(screen.getByText(/no downloadable media/)).toBeDefined(),
+    );
+  });
+
+  it("keeps the typed placeholder without the conversation address — and stays provider-free", () => {
+    // Deliberately NO StigmerProvider: without the identity props the
+    // media arm must not mount anything that needs one — the view's
+    // presentational contract for fixture-driven hosts (documentation
+    // tours, visual tests) predates media and must survive it.
+    const { container } = render(
+      <ConversationTimelineView
+        {...baseProps()}
+        items={[
+          item("wa:1", {
+            author: ConversationItemAuthor.author_customer,
+            providerMessageType: "image",
+            media: photoMedia,
+          }),
+        ]}
+      />,
+    );
+
+    expect(screen.getByText("Photo")).toBeDefined();
+    expect(container.querySelector("img")).toBeNull();
+    expect(container.querySelectorAll("li button")).toHaveLength(0);
+  });
+});