@stigmer/react 3.8.0 → 3.10.0

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,

package/src/conversation/useConversationMediaUrl.ts

@@ -0,0 +1,121 @@
+"use client";
+
+import { useMemo } from "react";
+import { create } from "@bufbuild/protobuf";
+import { GetConversationMediaDownloadUrlInputSchema } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/conversation_io_pb";
+import { useStigmer } from "../hooks.js";
+import { useFetch } from "../internal/useFetch.js";
+
+/** Return value of {@link useConversationMediaUrl}. */
+export interface UseConversationMediaUrlReturn {
+  /**
+   * A freshly minted presigned download URL for the timeline item's media,
+   * or `null` when:
+   * - Fetching is skipped (`enabled` is `false`, or any address part is empty)
+   * - The request is in-flight
+   * - The request failed (including the server's uniform NOT_FOUND for
+   *   items without ingested media)
+   */
+  readonly url: string | null;
+
+  /** `true` while the URL request is in-flight (first load). */
+  readonly isLoading: boolean;
+
+  /** `true` while a background refetch is in flight. */
+  readonly isRefetching: boolean;
+
+  /** Error from the last failed attempt, or `null` when healthy. */
+  readonly error: Error | null;
+
+  /** Re-fetch the URL (e.g. to mint a fresh one after the previous expired). */
+  readonly refetch: () => void;
+}
+
+interface UrlData {
+  readonly url: string | null;
+}
+
+const EMPTY: UrlData = { url: null };
+
+/** Options for {@link useConversationMediaUrl}. */
+export interface UseConversationMediaUrlOptions {
+  /**
+   * Gate the request. When `false`, the hook stays idle and returns `null` —
+   * use this to defer minting a URL until it is actually needed.
+   * Defaults to `true`.
+   */
+  readonly enabled?: boolean;
+}
+
+/**
+ * Data hook that resolves a **fresh** presigned download URL for one
+ * timeline item's ingested media (an image or document the customer sent)
+ * via `stigmer.agentChannel.getMediaDownloadUrl()`.
+ *
+ * Addressed by `(channel, conversation, item_id)` — never a storage key:
+ * the server resolves the blob from its own row, so the read path stays
+ * conversation-viewer-scoped by construction and blob capabilities never
+ * ride the wire (whatsapp-media DD-001 D4). The URL expires (about an
+ * hour); minting at view time keeps it always valid, the
+ * `useArtifactDownloadUrl` rationale.
+ *
+ * The URL is cached cross-mount by the item's full address (DD-014), so
+ * the 5s timeline poll's re-renders and a lightbox opened from a
+ * thumbnail reuse the minted URL instead of re-hitting the API.
+ *
+ * Pass empty strings (or `enabled: false`) to skip fetching — the
+ * conversation surface's established skip convention.
+ *
+ * @param agentChannelId - AgentChannel the conversation belongs to, or `""` to skip.
+ * @param conversationKey - Conversation key within the channel, or `""` to skip.
+ * @param itemId - The timeline item whose media to fetch (e.g. `"wa:<wamid>"`), or `""` to skip.
+ * @param options - Optional gating (`enabled`).
+ *
+ * @example
+ * ```tsx
+ * // Render an inbound photo with an always-fresh URL.
+ * const { url, isLoading } = useConversationMediaUrl(channelId, key, item.itemId);
+ * if (isLoading) return <Skeleton />;
+ * return url ? <img src={url} alt={item.media?.filename} /> : null;
+ * ```
+ *
+ * @see useArtifactDownloadUrl — the execution-artifact counterpart this mirrors
+ */
+export function useConversationMediaUrl(
+  agentChannelId: string,
+  conversationKey: string,
+  itemId: string,
+  options?: UseConversationMediaUrlOptions,
+): UseConversationMediaUrlReturn {
+  const stigmer = useStigmer();
+  const enabled = options?.enabled ?? true;
+  const active =
+    enabled && agentChannelId !== "" && conversationKey !== "" && itemId !== "";
+
+  const { data, isLoading, isRefetching, error, refetch } = useFetch(
+    active
+      ? () =>
+          stigmer.agentChannel
+            .getMediaDownloadUrl(
+              create(GetConversationMediaDownloadUrlInputSchema, {
+                agentChannelId,
+                conversationKey,
+                itemId,
+              }),
+            )
+            .then((result): UrlData => ({ url: result.url || null }))
+      : null,
+    [agentChannelId, conversationKey, itemId, active, stigmer],
+    EMPTY,
+    {
+      cacheKey: active
+        ? `conversation-media-url:${agentChannelId}:${conversationKey}:${itemId}`
+        : undefined,
+    },
+  );
+
+  return useMemo(
+    () => ({ url: data.url, isLoading, isRefetching, error, refetch }),
+    [data.url, isLoading, isRefetching, error, refetch],
+  );
+}