@stigmer/react 3.9.0 → 3.10.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,
@@ -146,7 +166,12 @@ export function ConversationTimelineView({
                   </div>
                   <ul className="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
@@ -211,14 +250,25 @@ const TimelineItemRow = memo(function TimelineItemRow({
             {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 ? "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(
+              "whitespace-pre-wrap break-words text-sm text-foreground",
+              !item.text && "italic text-muted-foreground",
+            )}
+          >
+            {body || "Message content unavailable"}
+          </p>
+        )}
         {receiptExplanation !== null && (
           <p className="mt-1 break-words text-xs text-destructive">
             {receiptExplanation}

package/src/conversation/ConversationsWorkbench.tsx

@@ -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__/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);
+  });
+});

package/src/conversation/__tests__/a11y/conversation-surfaces.a11y.test.tsx

@@ -9,9 +9,11 @@
 // states including the filtered one — each in light + dark against the
 // shipped stylesheet.
 
-import { describe, it, afterEach, vi } from "vitest";
+import { describe, it, afterEach, expect, vi } from "vitest";
+import { waitFor } from "@testing-library/react";
 import { create } from "@bufbuild/protobuf";
 import { timestampFromDate } from "@bufbuild/protobuf/wkt";
+import type { Stigmer } from "@stigmer/sdk";
 import { AgentChannelSchema } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/api_pb";
 import {
   ChannelConversationListFilter,
@@ -23,6 +25,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.js";
 import { ConversationComposer } from "../../ConversationComposer.js";
 import { ConversationListPane } from "../../ConversationListPane.js";
 import { ConversationTimelineView } from "../../ConversationTimelineView.js";
@@ -125,6 +128,49 @@ const timelineItems = [
   }),
 ];
 
+// Inbound-media fixtures (stigmer/stigmer#367): a captioned photo and a
+// document. Media rendering needs the conversation address AND a client
+// that answers getMediaDownloadUrl — the inner provider below overrides
+// the harness stub with one minting a data-URI image, so the audit sees
+// the loaded thumbnail, not just the pulse placeholder.
+const mediaTimelineItems = [
+  create(ConversationTimelineItemSchema, {
+    itemId: "wa:7",
+    lane: ConversationLane.lane_public,
+    author: ConversationItemAuthor.author_customer,
+    providerMessageType: "image",
+    text: "here's the leak under the sink",
+    media: {
+      filename: "kitchen-leak.jpg",
+      contentType: "image/jpeg",
+      sizeBytes: BigInt(204800),
+    },
+    at: timestampFromDate(new Date("2026-08-07T09:04:00Z")),
+  }),
+  create(ConversationTimelineItemSchema, {
+    itemId: "wa:8",
+    lane: ConversationLane.lane_public,
+    author: ConversationItemAuthor.author_customer,
+    providerMessageType: "document",
+    media: {
+      filename: "lease-agreement.pdf",
+      contentType: "application/pdf",
+      sizeBytes: BigInt(1048576),
+    },
+    at: timestampFromDate(new Date("2026-08-07T09:05:00Z")),
+  }),
+];
+
+// A 1×1 transparent PNG — enough for a real <img> load in the browser.
+const ONE_PX_PNG =
+  "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==";
+
+const mediaClient = {
+  agentChannel: {
+    getMediaDownloadUrl: () => Promise.resolve({ url: ONE_PX_PNG }),
+  },
+} as unknown as Stigmer;
+
 const listBaseProps = {
   isLoading: false,
   error: null,
@@ -207,6 +253,26 @@ describe("Conversation surfaces a11y", () => {
     await auditA11y(container, `conversation timeline · ${mode}`);
   });
 
+  it.each(COLOR_MODES)("timeline with inbound media: thumbnail and document chip (%s)", async (mode) => {
+    const container = renderAudited(
+      <StigmerContext.Provider value={mediaClient}>
+        <ConversationTimelineView
+          {...timelineBaseProps}
+          agentChannelId="ach_wa"
+          conversationKey="15550001111"
+          items={mediaTimelineItems}
+          hasOlder={false}
+          provider="whatsapp"
+        />
+      </StigmerContext.Provider>,
+      mode,
+    );
+    // Audit the LOADED thumbnail (the interactive state operators use),
+    // not just the pulse placeholder the first frame shows.
+    await waitFor(() => expect(container.querySelector("img")).toBeTruthy());
+    await auditA11y(container, `conversation timeline media · ${mode}`);
+  });
+
   it.each(COLOR_MODES)("composer with the closed-window advisory (%s)", async (mode) => {
     const container = renderAudited(
       <ConversationComposer

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

@@ -0,0 +1,66 @@
+import { describe, it, expect, vi } from "vitest";
+import { renderHook, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+import type { Stigmer } from "@stigmer/sdk";
+import { StigmerContext } from "../../context";
+import { useConversationMediaUrl } from "../useConversationMediaUrl";
+
+function wrapperFor(stigmer: Stigmer) {
+  return ({ children }: { children: ReactNode }) => (
+    <StigmerContext.Provider value={stigmer}>{children}</StigmerContext.Provider>
+  );
+}
+
+function makeStigmer(getMediaDownloadUrl = vi.fn()) {
+  return { agentChannel: { getMediaDownloadUrl } } as unknown as Stigmer;
+}
+
+describe("useConversationMediaUrl", () => {
+  it("mints a fresh URL from the item's conversation address", async () => {
+    const fn = vi.fn().mockResolvedValue({ url: "https://fresh/1" });
+    const { result } = renderHook(
+      () => useConversationMediaUrl("ach-1", "15551234567", "wa:abc"),
+      { wrapper: wrapperFor(makeStigmer(fn)) },
+    );
+
+    await waitFor(() => expect(result.current.url).toBe("https://fresh/1"));
+    expect(fn).toHaveBeenCalledTimes(1);
+    const req = fn.mock.calls[0][0];
+    expect(req.agentChannelId).toBe("ach-1");
+    expect(req.conversationKey).toBe("15551234567");
+    expect(req.itemId).toBe("wa:abc");
+  });
+
+  it("stays idle when disabled", () => {
+    const fn = vi.fn();
+    const { result } = renderHook(
+      () => useConversationMediaUrl("ach-1", "15551234567", "wa:abc", { enabled: false }),
+      { wrapper: wrapperFor(makeStigmer(fn)) },
+    );
+    expect(result.current.url).toBeNull();
+    expect(fn).not.toHaveBeenCalled();
+  });
+
+  it("skips fetching while any address part is empty", () => {
+    const fn = vi.fn();
+    const { result } = renderHook(
+      () => useConversationMediaUrl("ach-1", "", "wa:abc"),
+      { wrapper: wrapperFor(makeStigmer(fn)) },
+    );
+    expect(result.current.url).toBeNull();
+    expect(fn).not.toHaveBeenCalled();
+  });
+
+  it("reports a failed mint as an error, never a broken URL", async () => {
+    const fn = vi
+      .fn()
+      .mockRejectedValue(new Error("no downloadable media at this timeline item"));
+    const { result } = renderHook(
+      () => useConversationMediaUrl("ach-1", "15551234567", "wa:abc"),
+      { wrapper: wrapperFor(makeStigmer(fn)) },
+    );
+
+    await waitFor(() => expect(result.current.error).not.toBeNull());
+    expect(result.current.url).toBeNull();
+  });
+});

package/src/conversation/conversationPresentation.ts

@@ -108,9 +108,16 @@ export function receiptOf(item: ConversationTimelineItem): ReceiptKind | null {
 
 /**
  * Placeholder copy for inbound items whose body the platform cannot
- * render (`text` empty, `provider_message_type` names the kind). Media
- * retrieval is a named non-goal of this surface — the placeholder tells
- * staff something arrived and what shape it was.
+ * render (`text` empty, `provider_message_type` names the kind) — the
+ * placeholder tells staff something arrived and what shape it was.
+ *
+ * Since stigmer/stigmer#367 this is the FALLBACK arm of the media
+ * treatment, not the whole of it: items carrying ingested `media`
+ * render the real thing (thumbnail or document chip) when the timeline
+ * view holds the conversation address. The placeholder still covers
+ * media the platform declined to ingest (disallowed type, over the size
+ * cap — `media` unset by design) and renders without an address, where
+ * the bytes are unreachable.
  *
  * Returns `null` when the item needs no placeholder (it has text, or it
  * is not a provider-typed inbound item — e.g. an attention-clear event,

package/src/conversation/index.ts

@@ -40,6 +40,12 @@ export type {
   UseConversationTimelineReturn,
 } from "./useConversationTimeline.js";
 
+export { useConversationMediaUrl } from "./useConversationMediaUrl.js";
+export type {
+  UseConversationMediaUrlOptions,
+  UseConversationMediaUrlReturn,
+} from "./useConversationMediaUrl.js";
+
 export { useConversationParticipation } from "./useConversationParticipation.js";
 export type {
   ConversationCommand,