@stigmer/react 3.9.0 → 3.10.0

package/src/attachment/__tests__/AttachmentChipList.test.tsx

@@ -1,6 +1,13 @@
-import { describe, it, expect, vi, afterEach } from "vitest";
-import { render, cleanup, waitFor } from "@testing-library/react";
+import { describe, it, expect, vi, beforeAll, afterEach } from "vitest";
+import {
+  render,
+  cleanup,
+  waitFor,
+  fireEvent,
+  screen,
+} from "@testing-library/react";
 import { AttachmentChipList } from "../AttachmentChipList.js";
+import type { AttachmentChipListProps } from "../AttachmentChipList.js";
 import type { AttachmentEntry } from "../useAttachments.js";
 
 // ---------------------------------------------------------------------------
@@ -22,30 +29,52 @@ function entry(overrides: Partial<AttachmentEntry> = {}): AttachmentEntry {
   };
 }
 
-function renderChips(entries: AttachmentEntry[]) {
+function renderChips(
+  entries: AttachmentEntry[],
+  props: Partial<AttachmentChipListProps> = {},
+) {
   return render(
-    <AttachmentChipList entries={entries} onRemove={vi.fn()} onRetry={vi.fn()} />,
+    <AttachmentChipList
+      entries={entries}
+      onRemove={vi.fn()}
+      onRetry={vi.fn()}
+      {...props}
+    />,
   );
 }
 
+/** The chip's miniature `<img>` (decorative, `aria-hidden`) — never the lightbox image. */
+function chipImage(container: HTMLElement): HTMLImageElement | null {
+  return container.querySelector('img[aria-hidden="true"]');
+}
+
+// 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();
   vi.restoreAllMocks();
 });
 
 // ---------------------------------------------------------------------------
-// Tests
+// Image miniature — visible in every phase (#371 gap 2)
 // ---------------------------------------------------------------------------
 
-describe("AttachmentChipList — image thumbnails", () => {
-  it("renders an object-URL thumbnail for a ready image entry", async () => {
+describe("AttachmentChipList — image miniature", () => {
+  it("renders an object-URL miniature for a ready image entry", async () => {
     const { container } = renderChips([entry()]);
 
     await waitFor(() => {
-      const img = container.querySelector("img");
+      const img = chipImage(container);
       expect(img).toBeTruthy();
       expect(img!.getAttribute("src")).toContain("blob:");
-      expect(img!.getAttribute("aria-hidden")).toBe("true");
       expect(img!.getAttribute("alt")).toBe("");
     });
   });
@@ -62,21 +91,63 @@ describe("AttachmentChipList — image thumbnails", () => {
     expect(container.querySelector("svg")).toBeTruthy();
   });
 
-  it("shows no thumbnail while uploading or errored (spinner / error dot own the slot)", () => {
+  it("keeps the miniature visible while uploading — the spinner overlays it, never replaces it", async () => {
     const uploading = entry({ id: "up", phase: "uploading", storageKey: null });
-    const errored = entry({ id: "err", phase: "error", error: "boom", storageKey: null });
 
-    const { container } = renderChips([uploading, errored]);
+    const { container } = renderChips([uploading]);
 
-    expect(container.querySelector("img")).toBeNull();
+    await waitFor(() => expect(chipImage(container)).toBeTruthy());
+    // Spinner present alongside the image, not instead of it.
+    expect(container.querySelector("svg.animate-spin")).toBeTruthy();
+  });
+
+  it("renders image chips preview-only: no visible filename or size text", async () => {
+    const { container } = renderChips([entry()]);
+
+    await waitFor(() => expect(chipImage(container)).toBeTruthy());
+
+    // The tile is the chip — the name lives in the tooltip and accessible
+    // label, never as a text node (file chips, by contrast, keep theirs).
+    expect(screen.queryByText("shot.png")).toBeNull();
+    const tile = screen.getByRole("listitem", { name: /^shot\.png/ });
+    expect(tile.getAttribute("title")).toBe("shot.png");
+    // Remove is an always-visible corner badge, not hover-revealed.
+    expect(screen.getByRole("button", { name: "Remove shot.png" })).toBeTruthy();
+  });
+
+  it("keeps visible filename and size text on non-image chips", () => {
+    const md = entry({
+      file: new File(["# notes"], "notes.md", { type: "text/markdown" }),
+      contentType: "text/markdown",
+    });
+
+    renderChips([md]);
+
+    expect(screen.getByText("notes.md")).toBeTruthy();
+  });
+
+  it("keeps the miniature visible on upload error, alongside the retry action", async () => {
+    const errored = entry({
+      id: "err",
+      phase: "error",
+      error: "boom",
+      storageKey: null,
+    });
+
+    const { container } = renderChips([errored]);
+
+    await waitFor(() => expect(chipImage(container)).toBeTruthy());
+    expect(
+      screen.getByRole("button", { name: "Retry uploading shot.png" }),
+    ).toBeTruthy();
   });
 
   it("revokes the object URL on unmount", async () => {
     const revokeSpy = vi.spyOn(URL, "revokeObjectURL");
     const { container, unmount } = renderChips([entry()]);
 
-    await waitFor(() => expect(container.querySelector("img")).toBeTruthy());
-    const src = container.querySelector("img")!.getAttribute("src")!;
+    await waitFor(() => expect(chipImage(container)).toBeTruthy());
+    const src = chipImage(container)!.getAttribute("src")!;
 
     unmount();
 
@@ -90,8 +161,8 @@ describe("AttachmentChipList — image thumbnails", () => {
       <AttachmentChipList entries={[image]} onRemove={vi.fn()} onRetry={vi.fn()} />,
     );
 
-    await waitFor(() => expect(container.querySelector("img")).toBeTruthy());
-    const src = container.querySelector("img")!.getAttribute("src")!;
+    await waitFor(() => expect(chipImage(container)).toBeTruthy());
+    const src = chipImage(container)!.getAttribute("src")!;
 
     rerender(
       <AttachmentChipList entries={[]} onRemove={vi.fn()} onRetry={vi.fn()} />,
@@ -100,4 +171,156 @@ describe("AttachmentChipList — image thumbnails", () => {
     expect(container.querySelector("img")).toBeNull();
     expect(revokeSpy).toHaveBeenCalledWith(src);
   });
+
+  it("degrades to the compact file chip when the image fails to decode", async () => {
+    const { container } = renderChips([entry()]);
+
+    await waitFor(() => expect(chipImage(container)).toBeTruthy());
+    fireEvent.error(chipImage(container)!);
+
+    // No broken-image glyph, no preview affordance — just the file treatment.
+    expect(container.querySelector("img")).toBeNull();
+    expect(screen.queryByRole("button", { name: "Preview shot.png" })).toBeNull();
+    expect(container.querySelector("svg")).toBeTruthy();
+    expect(
+      screen.getByRole("button", { name: "Remove shot.png" }),
+    ).toBeTruthy();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Click-to-open — built-in lightbox and the onPreview seam (#371 gap 3)
+// ---------------------------------------------------------------------------
+
+describe("AttachmentChipList — preview", () => {
+  it("opens the built-in lightbox with the full image when the chip body is clicked", async () => {
+    renderChips([entry()]);
+
+    expect(document.querySelector("dialog")).toBeNull();
+
+    fireEvent.click(screen.getByRole("button", { name: "Preview shot.png" }));
+
+    const dialog = document.querySelector("dialog");
+    expect(dialog).toBeTruthy();
+    expect(dialog!.getAttribute("aria-label")).toBe("Preview shot.png");
+    // The lightbox derives its own object URL; the full image carries the
+    // filename as meaningful alt text (unlike the decorative miniature).
+    await waitFor(() => {
+      const full = dialog!.querySelector("img");
+      expect(full).toBeTruthy();
+      expect(full!.getAttribute("src")).toContain("blob:");
+      expect(full!.getAttribute("alt")).toBe("shot.png");
+    });
+  });
+
+  it("closes the lightbox on Escape (the dialog's cancel event)", () => {
+    renderChips([entry()]);
+
+    fireEvent.click(screen.getByRole("button", { name: "Preview shot.png" }));
+    const dialog = document.querySelector("dialog")!;
+
+    fireEvent(dialog, new Event("cancel"));
+
+    expect(document.querySelector("dialog")).toBeNull();
+  });
+
+  it("closes the lightbox on backdrop click, but not on content clicks", async () => {
+    renderChips([entry()]);
+
+    fireEvent.click(screen.getByRole("button", { name: "Preview shot.png" }));
+    const dialog = document.querySelector("dialog")!;
+    await waitFor(() => expect(dialog.querySelector("img")).toBeTruthy());
+
+    // A click landing on content (the image) must not close.
+    fireEvent.click(dialog.querySelector("img")!);
+    expect(document.querySelector("dialog")).toBeTruthy();
+
+    // A click landing on the dialog element itself is the backdrop.
+    fireEvent.click(dialog);
+    expect(document.querySelector("dialog")).toBeNull();
+  });
+
+  it("closes the lightbox via its close button", () => {
+    renderChips([entry()]);
+
+    fireEvent.click(screen.getByRole("button", { name: "Preview shot.png" }));
+    fireEvent.click(
+      screen.getByRole("button", { name: "Close image preview" }),
+    );
+
+    expect(document.querySelector("dialog")).toBeNull();
+  });
+
+  it("closes the lightbox when the previewed entry is removed from the list", () => {
+    const image = entry();
+    const { rerender } = renderChips([image]);
+
+    fireEvent.click(screen.getByRole("button", { name: "Preview shot.png" }));
+    expect(document.querySelector("dialog")).toBeTruthy();
+
+    rerender(
+      <AttachmentChipList entries={[]} onRemove={vi.fn()} onRetry={vi.fn()} />,
+    );
+
+    expect(document.querySelector("dialog")).toBeNull();
+  });
+
+  it("routes the click to onPreview instead of opening the built-in lightbox", () => {
+    const onPreview = vi.fn();
+    const image = entry();
+    renderChips([image], { onPreview });
+
+    fireEvent.click(screen.getByRole("button", { name: "Preview shot.png" }));
+
+    expect(onPreview).toHaveBeenCalledTimes(1);
+    expect(onPreview).toHaveBeenCalledWith(image);
+    expect(document.querySelector("dialog")).toBeNull();
+  });
+
+  it("offers no preview affordance on non-image entries", () => {
+    const md = entry({
+      file: new File(["# notes"], "notes.md", { type: "text/markdown" }),
+      contentType: "text/markdown",
+    });
+
+    renderChips([md]);
+
+    expect(screen.queryByRole("button", { name: /^Preview/ })).toBeNull();
+  });
+
+  it("keeps preview clickable while remove/retry are disabled (preview is read-only)", async () => {
+    const { container } = renderChips([entry()], { disabled: true });
+
+    await waitFor(() => expect(chipImage(container)).toBeTruthy());
+
+    const preview = screen.getByRole("button", {
+      name: "Preview shot.png",
+    }) as HTMLButtonElement;
+    const remove = screen.getByRole("button", {
+      name: "Remove shot.png",
+    }) as HTMLButtonElement;
+
+    expect(preview.disabled).toBe(false);
+    expect(remove.disabled).toBe(true);
+
+    fireEvent.click(preview);
+    expect(document.querySelector("dialog")).toBeTruthy();
+  });
+
+  it("handles unicode filenames across the chip, preview target, and lightbox", () => {
+    const name = "スクリーンショット 2026-08-10.png";
+    const unicode = entry({
+      file: new File([new Uint8Array([0x89, 0x50, 0x4e, 0x47])], name, {
+        type: "image/png",
+      }),
+    });
+
+    renderChips([unicode]);
+
+    fireEvent.click(screen.getByRole("button", { name: `Preview ${name}` }));
+
+    const dialog = document.querySelector("dialog");
+    expect(dialog).toBeTruthy();
+    expect(dialog!.getAttribute("aria-label")).toBe(`Preview ${name}`);
+  });
 });

package/src/attachment/useObjectUrl.ts

@@ -0,0 +1,28 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+/**
+ * Object URL over a locally-held `Blob` (or `File`), alive for the lifetime
+ * of the mounted component (no fetch — the bytes are already in memory).
+ *
+ * The URL is created in an effect, not a memo: StrictMode double-invokes
+ * memos and would leak the first URL without a revoke. The effect cleanup
+ * revokes on unmount and on blob change. Returns `null` until the effect
+ * runs (first paint) — callers render a fallback for that frame.
+ *
+ * Deliberately display-oriented: the SDK's other `createObjectURL` calls
+ * (`useExportResource`, `useExportCSV`) are fire-and-forget download
+ * helpers with an immediate revoke, a different lifecycle from this one.
+ */
+export function useObjectUrl(blob: Blob): string | null {
+  const [url, setUrl] = useState<string | null>(null);
+
+  useEffect(() => {
+    const objectUrl = URL.createObjectURL(blob);
+    setUrl(objectUrl);
+    return () => URL.revokeObjectURL(objectUrl);
+  }, [blob]);
+
+  return url;
+}

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 is load-bearing: without it the thumbnail shows
+          the UA's default button box in preflight-less hosts. */}
+      <button
+        type="button"
+        onClick={() => setPreviewOpen(true)}
+        aria-label={`Preview ${name}`}
+        className={cn(
+          UNSTYLED_BUTTON,
+          "block rounded-md focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+          className,
+        )}
+      >
+        <span className="relative block h-40 w-56 max-w-full overflow-hidden rounded-md">
+          {url ? (
+            <img
+              src={url}
+              alt=""
+              aria-hidden="true"
+              loading="lazy"
+              className="h-full w-full object-cover"
+            />
+          ) : (
+            // Pulse placeholder while the presigned URL is minted; same
+            // footprint as the image, so no layout shift.
+            <span
+              className="block h-full w-full animate-pulse 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="inline-flex max-w-[240px] items-center rounded-md bg-muted-subtle px-2 py-1 text-xs text-foreground"
+      >
+        <button
+          type="button"
+          onClick={() => void open()}
+          disabled={isOpening}
+          aria-label={`Open ${name}`}
+          className={cn(
+            UNSTYLED_BUTTON,
+            "flex min-w-0 items-center gap-1.5 rounded-sm text-inherit [font:inherit] hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+            isOpening && "opacity-70",
+          )}
+        >
+          <FileGlyph />
+          <span className="min-w-0 truncate">{name}</span>
+          {size !== null && (
+            <span className="shrink-0 text-muted-foreground">{size}</span>
+          )}
+        </button>
+      </span>
+      {error !== null && (
+        <p className="mt-1 break-words text-xs 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="shrink-0 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>
+  );
+}