Add issue Output UI for artifact playback (PAP-10168)

Surface attachment-backed artifact work products as a first-class
Output section on the issue detail page so cloud users can watch and
download agent-generated videos without host filesystem access.

- ui/src/lib/issue-output.ts: formatBytes/formatDuration/getOutputFileGlyph
  helpers + getIssueOutputs selector that validates the Phase-2 attachment
  artifact metadata contract and tolerates malformed metadata (degraded).
- issue-output components: IssueOutputSection, OutputPrimaryCard (native
  <video>/image/generic), OutputRow, OutputVideoPlayer, OutputFileTile.
- IssueDetail: fetch work products and render the Output section between
  Documents and Attachments; reuse formatBytes in the attachments list.
- DesignGuide: showcase multiple-output, degraded, and empty states.
- Focused tests for video output, empty state, multiple outputs, and
  failed attachment metadata (15 tests).

Co-Authored-By: Paperclip <noreply@paperclip.ing>

ui/src/lib/issue-output.test.ts

@@ -0,0 +1,154 @@
+import { describe, expect, it } from "vitest";
+import type { IssueWorkProduct } from "@paperclipai/shared";
+import {
+  formatBytes,
+  formatDuration,
+  getIssueOutputs,
+  getOutputFileGlyph,
+} from "./issue-output";
+
+function makeWorkProduct(overrides: Partial<IssueWorkProduct> & { id: string }): IssueWorkProduct {
+  return {
+    companyId: "company-1",
+    projectId: null,
+    issueId: "issue-1",
+    executionWorkspaceId: null,
+    runtimeServiceId: null,
+    type: "artifact",
+    provider: "paperclip",
+    externalId: null,
+    title: overrides.title ?? "output.mp4",
+    url: null,
+    status: "active",
+    reviewState: "none",
+    isPrimary: false,
+    healthStatus: "unknown",
+    summary: null,
+    metadata: null,
+    createdByRunId: null,
+    createdAt: new Date("2026-05-30T12:00:00Z"),
+    updatedAt: new Date("2026-05-30T12:00:00Z"),
+    ...overrides,
+  } as IssueWorkProduct;
+}
+
+let uuidCounter = 0;
+function uuid() {
+  uuidCounter += 1;
+  return `00000000-0000-4000-8000-${String(uuidCounter).padStart(12, "0")}`;
+}
+
+function videoMetadata(attachmentId = uuid()) {
+  return {
+    attachmentId,
+    contentType: "video/mp4",
+    byteSize: 19_293_798,
+    contentPath: `/api/attachments/${attachmentId}/content`,
+    openPath: `/api/attachments/${attachmentId}/content`,
+    downloadPath: `/api/attachments/${attachmentId}/content?download=1`,
+    originalFilename: "demo.mp4",
+  };
+}
+
+describe("formatBytes", () => {
+  it("renders bytes below 1KB as whole bytes", () => {
+    expect(formatBytes(0)).toBe("0 B");
+    expect(formatBytes(512)).toBe("512 B");
+  });
+
+  it("uses one trimmed decimal place from KB upward", () => {
+    expect(formatBytes(1024)).toBe("1 KB");
+    expect(formatBytes(412 * 1024)).toBe("412 KB");
+    expect(formatBytes(19_293_798)).toBe("18.4 MB");
+    expect(formatBytes(1.2 * 1024 * 1024 * 1024)).toBe("1.2 GB");
+  });
+
+  it("handles invalid input defensively", () => {
+    expect(formatBytes(Number.NaN)).toBe("0 B");
+    expect(formatBytes(-10)).toBe("0 B");
+  });
+});
+
+describe("formatDuration", () => {
+  it("formats sub-hour durations as m:ss", () => {
+    expect(formatDuration(58)).toBe("0:58");
+    expect(formatDuration(102)).toBe("1:42");
+  });
+
+  it("formats durations over an hour as h:mm:ss", () => {
+    expect(formatDuration(3600 + 42 * 60 + 9)).toBe("1:42:09");
+  });
+});
+
+describe("getOutputFileGlyph", () => {
+  it("maps known mime types to tone + label", () => {
+    expect(getOutputFileGlyph("video/mp4")).toEqual({ label: "MP4", tone: "video" });
+    expect(getOutputFileGlyph("video/quicktime")).toEqual({ label: "MOV", tone: "video" });
+    expect(getOutputFileGlyph("application/pdf")).toEqual({ label: "PDF", tone: "pdf" });
+    expect(getOutputFileGlyph("application/zip")).toEqual({ label: "ZIP", tone: "zip" });
+    expect(getOutputFileGlyph("image/png")).toEqual({ label: "IMG", tone: "image" });
+  });
+
+  it("falls back to BIN for unknown types", () => {
+    expect(getOutputFileGlyph("application/octet-stream")).toEqual({ label: "BIN", tone: "bin" });
+    expect(getOutputFileGlyph(undefined)).toEqual({ label: "BIN", tone: "bin" });
+  });
+});
+
+describe("getIssueOutputs", () => {
+  it("ignores non-artifact work products and returns empty for no outputs", () => {
+    const result = getIssueOutputs([
+      makeWorkProduct({ id: "pr-1", type: "pull_request" }),
+      makeWorkProduct({ id: "doc-1", type: "document" }),
+    ]);
+    expect(result.count).toBe(0);
+    expect(result.primary).toBeNull();
+    expect(result.rest).toEqual([]);
+  });
+
+  it("parses a single video artifact into a primary output", () => {
+    const result = getIssueOutputs([
+      makeWorkProduct({ id: "wp-1", metadata: videoMetadata(), isPrimary: true }),
+    ]);
+    expect(result.count).toBe(1);
+    expect(result.primary?.id).toBe("wp-1");
+    expect(result.primary?.degraded).toBe(false);
+    expect(result.primary?.metadata?.contentType).toBe("video/mp4");
+    expect(result.rest).toEqual([]);
+  });
+
+  it("orders the explicit primary first, then most recent", () => {
+    const result = getIssueOutputs([
+      makeWorkProduct({
+        id: "old",
+        createdAt: new Date("2026-05-29T10:00:00Z"),
+        metadata: videoMetadata(),
+      }),
+      makeWorkProduct({
+        id: "primary",
+        isPrimary: true,
+        createdAt: new Date("2026-05-28T10:00:00Z"),
+        metadata: videoMetadata(),
+      }),
+      makeWorkProduct({
+        id: "recent",
+        createdAt: new Date("2026-05-30T10:00:00Z"),
+        metadata: videoMetadata(),
+      }),
+    ]);
+    expect(result.primary?.id).toBe("primary");
+    expect(result.rest.map((r) => r.id)).toEqual(["recent", "old"]);
+  });
+
+  it("marks artifacts with invalid metadata as degraded without throwing", () => {
+    const result = getIssueOutputs([
+      makeWorkProduct({
+        id: "broken",
+        metadata: { attachmentId: "att-x", contentType: "video/mp4" } as Record<string, unknown>,
+      }),
+    ]);
+    expect(result.count).toBe(1);
+    expect(result.primary?.degraded).toBe(true);
+    expect(result.primary?.metadata).toBeNull();
+  });
+});

ui/src/lib/issue-output.ts

@@ -0,0 +1,158 @@
+import {
+  attachmentArtifactWorkProductMetadataSchema,
+  type AttachmentArtifactWorkProductMetadata,
+  type IssueWorkProduct,
+} from "@paperclipai/shared";
+
+/**
+ * Helpers + selectors for the issue Output surface (PAP-10162 Phase 3).
+ *
+ * The Output surface promotes attachment-backed artifact work products to a
+ * first-class slot on the issue page so cloud users can watch / download files
+ * an agent produced without digging through comments or the host filesystem.
+ */
+
+export type OutputFileTone = "video" | "pdf" | "zip" | "image" | "bin";
+
+export interface OutputFileGlyph {
+  /** Short (≤4 char) label for the file-type tile, e.g. "MP4". */
+  label: string;
+  tone: OutputFileTone;
+}
+
+/**
+ * Format a byte count for display.
+ *
+ * Examples: `0 B`, `512 B`, `412 KB`, `18.4 MB`, `1.2 GB`. One decimal place is
+ * used from KB upward, with a trailing `.0` trimmed so round values stay clean.
+ */
+export function formatBytes(bytes: number): string {
+  if (!Number.isFinite(bytes) || bytes < 0) return "0 B";
+  if (bytes < 1024) return `${Math.round(bytes)} B`;
+  const units = ["KB", "MB", "GB", "TB"];
+  let value = bytes / 1024;
+  let unitIndex = 0;
+  while (value >= 1024 && unitIndex < units.length - 1) {
+    value /= 1024;
+    unitIndex += 1;
+  }
+  const rounded = value.toFixed(1);
+  const trimmed = rounded.endsWith(".0") ? rounded.slice(0, -2) : rounded;
+  return `${trimmed} ${units[unitIndex]}`;
+}
+
+/**
+ * Format a duration in seconds as `m:ss` (under an hour) or `h:mm:ss`.
+ * Examples: `0:58`, `1:42:09`.
+ */
+export function formatDuration(seconds: number): string {
+  if (!Number.isFinite(seconds) || seconds < 0) return "0:00";
+  const total = Math.floor(seconds);
+  const hrs = Math.floor(total / 3600);
+  const mins = Math.floor((total % 3600) / 60);
+  const secs = total % 60;
+  const pad = (n: number) => String(n).padStart(2, "0");
+  if (hrs > 0) {
+    return `${hrs}:${pad(mins)}:${pad(secs)}`;
+  }
+  return `${mins}:${pad(secs)}`;
+}
+
+/**
+ * Map a MIME type to a short label + tone for the 32×32 file-type tile.
+ */
+export function getOutputFileGlyph(contentType: string | null | undefined): OutputFileGlyph {
+  const type = (contentType ?? "").toLowerCase();
+  if (type.startsWith("video/")) {
+    const subtype = type.slice("video/".length);
+    if (subtype === "quicktime") return { label: "MOV", tone: "video" };
+    return { label: (subtype || "vid").toUpperCase().slice(0, 4), tone: "video" };
+  }
+  if (type === "application/pdf") return { label: "PDF", tone: "pdf" };
+  if (type === "application/zip" || type === "application/x-zip-compressed" || type.endsWith("+zip")) {
+    return { label: "ZIP", tone: "zip" };
+  }
+  if (type.startsWith("image/")) return { label: "IMG", tone: "image" };
+  return { label: "BIN", tone: "bin" };
+}
+
+export function isVideoContentType(contentType: string | null | undefined): boolean {
+  return (contentType ?? "").toLowerCase().startsWith("video/");
+}
+
+export function isImageContentType(contentType: string | null | undefined): boolean {
+  return (contentType ?? "").toLowerCase().startsWith("image/");
+}
+
+/**
+ * A single rendered output. `metadata` is null when the work product's stored
+ * metadata fails validation — the row is still surfaced (degraded) so we never
+ * silently drop an artifact the agent reported producing.
+ */
+export interface IssueOutputItem {
+  id: string;
+  title: string;
+  status: string;
+  isPrimary: boolean;
+  createdAt: string | Date;
+  metadata: AttachmentArtifactWorkProductMetadata | null;
+  /** True when stored metadata could not be parsed into a usable artifact. */
+  degraded: boolean;
+  workProduct: IssueWorkProduct;
+}
+
+export interface IssueOutputs {
+  items: IssueOutputItem[];
+  primary: IssueOutputItem | null;
+  rest: IssueOutputItem[];
+  count: number;
+}
+
+function toTime(value: string | Date): number {
+  const t = new Date(value).getTime();
+  return Number.isNaN(t) ? 0 : t;
+}
+
+/**
+ * Parse attachment-backed artifact work products into renderable outputs.
+ *
+ * - Only `type: "artifact"` work products are considered outputs.
+ * - Metadata is validated against the shared contract; invalid metadata yields
+ *   a degraded item rather than an exception.
+ * - Ordering: the explicit primary (or the most-recent artifact when none is
+ *   marked primary) comes first, then remaining artifacts by most-recent.
+ */
+export function getIssueOutputs(workProducts: IssueWorkProduct[] | null | undefined): IssueOutputs {
+  const artifacts = (workProducts ?? []).filter((wp) => wp.type === "artifact");
+
+  const items: IssueOutputItem[] = artifacts.map((wp) => {
+    const parsed = attachmentArtifactWorkProductMetadataSchema.safeParse(wp.metadata);
+    return {
+      id: wp.id,
+      title: wp.title,
+      status: typeof wp.status === "string" ? wp.status : "active",
+      isPrimary: Boolean(wp.isPrimary),
+      createdAt: wp.createdAt,
+      metadata: parsed.success ? parsed.data : null,
+      degraded: !parsed.success,
+      workProduct: wp,
+    };
+  });
+
+  items.sort((a, b) => {
+    if (a.isPrimary !== b.isPrimary) return a.isPrimary ? -1 : 1;
+    return toTime(b.createdAt) - toTime(a.createdAt);
+  });
+
+  return {
+    items,
+    primary: items[0] ?? null,
+    rest: items.slice(1),
+    count: items.length,
+  };
+}
+
+/** Best display filename for an output, falling back to the work product title. */
+export function outputFilename(item: IssueOutputItem): string {
+  return item.metadata?.originalFilename || item.title || "output";
+}