From 96d266109b7d94c7a70a52efa15f07d7baeeb2c8 Mon Sep 17 00:00:00 2001
From: Dotta <bippadotta@protonmail.com>
Date: Sat, 30 May 2026 19:06:15 +0000
Subject: [PATCH] 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>
---
 .../issue-output/IssueOutputSection.test.tsx  | 137 +++++++++++++++
 .../issue-output/IssueOutputSection.tsx       |  49 ++++++
 .../issue-output/OutputFileTile.tsx           |  35 ++++
 .../issue-output/OutputPrimaryCard.tsx        |  96 +++++++++++
 ui/src/components/issue-output/OutputRow.tsx  |  57 +++++++
 .../issue-output/OutputVideoPlayer.tsx        |  33 ++++
 ui/src/lib/issue-output.test.ts               | 154 +++++++++++++++++
 ui/src/lib/issue-output.ts                    | 158 ++++++++++++++++++
 ui/src/pages/DesignGuide.tsx                  |  85 ++++++++++
 ui/src/pages/IssueDetail.tsx                  |  14 +-
 10 files changed, 817 insertions(+), 1 deletion(-)
 create mode 100644 ui/src/components/issue-output/IssueOutputSection.test.tsx
 create mode 100644 ui/src/components/issue-output/IssueOutputSection.tsx
 create mode 100644 ui/src/components/issue-output/OutputFileTile.tsx
 create mode 100644 ui/src/components/issue-output/OutputPrimaryCard.tsx
 create mode 100644 ui/src/components/issue-output/OutputRow.tsx
 create mode 100644 ui/src/components/issue-output/OutputVideoPlayer.tsx
 create mode 100644 ui/src/lib/issue-output.test.ts
 create mode 100644 ui/src/lib/issue-output.ts

diff --git a/ui/src/components/issue-output/IssueOutputSection.test.tsx b/ui/src/components/issue-output/IssueOutputSection.test.tsx
new file mode 100644
index 00000000..94c8fc60
--- /dev/null
+++ b/ui/src/components/issue-output/IssueOutputSection.test.tsx
@@ -0,0 +1,137 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import type { IssueWorkProduct } from "@paperclipai/shared";
+import { IssueOutputSection } from "./IssueOutputSection";
+
+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: "output",
+    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;
+}
+
+const UUIDS: Record<string, string> = {
+  "att-1": "11111111-1111-4111-8111-111111111111",
+  "att-vid": "22222222-2222-4222-8222-222222222222",
+  "att-pdf": "33333333-3333-4333-8333-333333333333",
+};
+
+function metadata(key: string, contentType: string, filename: string) {
+  const attachmentId = UUIDS[key] ?? key;
+  return {
+    attachmentId,
+    contentType,
+    byteSize: 19_293_798,
+    contentPath: `/api/attachments/${attachmentId}/content`,
+    openPath: `/api/attachments/${attachmentId}/content`,
+    downloadPath: `/api/attachments/${attachmentId}/content?download=1`,
+    originalFilename: filename,
+  };
+}
+
+describe("IssueOutputSection", () => {
+  it("renders a playable, downloadable video as the primary output", () => {
+    const markup = renderToStaticMarkup(
+      <IssueOutputSection
+        workProducts={[
+          makeWorkProduct({
+            id: "wp-1",
+            title: "Demo walkthrough",
+            isPrimary: true,
+            metadata: metadata("att-1", "video/mp4", "demo.mp4"),
+          }),
+        ]}
+      />,
+    );
+
+    // Native video player present
+    expect(markup).toContain("<video");
+    expect(markup).toContain("controls");
+    expect(markup).toContain(`/api/attachments/${UUIDS["att-1"]}/content`);
+    // Filename surfaced and download/open wired
+    expect(markup).toContain("demo.mp4");
+    expect(markup).toContain(`/api/attachments/${UUIDS["att-1"]}/content?download=1`);
+    expect(markup).toContain("Download");
+    expect(markup).toContain("Open");
+    // Section header + size formatting
+    expect(markup).toContain("Output");
+    expect(markup).toContain("18.4 MB");
+  });
+
+  it("renders nothing when the issue has no artifact outputs (empty state)", () => {
+    const markup = renderToStaticMarkup(
+      <IssueOutputSection
+        workProducts={[
+          makeWorkProduct({ id: "pr-1", type: "pull_request" }),
+        ]}
+      />,
+    );
+    expect(markup).toBe("");
+  });
+
+  it("renders the primary card plus an Also produced list for multiple outputs", () => {
+    const markup = renderToStaticMarkup(
+      <IssueOutputSection
+        workProducts={[
+          makeWorkProduct({
+            id: "wp-primary",
+            isPrimary: true,
+            createdAt: new Date("2026-05-30T12:00:00Z"),
+            metadata: metadata("att-vid", "video/mp4", "summary.mp4"),
+          }),
+          makeWorkProduct({
+            id: "wp-pdf",
+            createdAt: new Date("2026-05-30T11:00:00Z"),
+            metadata: metadata("att-pdf", "application/pdf", "talking-points.pdf"),
+          }),
+        ]}
+      />,
+    );
+
+    expect(markup).toContain("Also produced");
+    expect(markup).toContain("summary.mp4");
+    expect(markup).toContain("talking-points.pdf");
+    // PDF glyph tile label appears for the secondary row
+    expect(markup).toContain("PDF");
+  });
+
+  it("surfaces an output with failed/invalid attachment metadata without crashing", () => {
+    const markup = renderToStaticMarkup(
+      <IssueOutputSection
+        workProducts={[
+          makeWorkProduct({
+            id: "wp-broken",
+            title: "broken-output.mp4",
+            isPrimary: true,
+            // Missing required path fields → fails the shared metadata schema
+            metadata: { attachmentId: "att-x", contentType: "video/mp4" } as Record<string, unknown>,
+          }),
+        ]}
+      />,
+    );
+
+    expect(markup).toContain("broken-output.mp4");
+    expect(markup).toContain("metadata is unavailable");
+    // No video element and no download link can be built from invalid metadata
+    expect(markup).not.toContain("<video");
+    expect(markup).not.toContain("download=1");
+  });
+});
diff --git a/ui/src/components/issue-output/IssueOutputSection.tsx b/ui/src/components/issue-output/IssueOutputSection.tsx
new file mode 100644
index 00000000..5b7faa0f
--- /dev/null
+++ b/ui/src/components/issue-output/IssueOutputSection.tsx
@@ -0,0 +1,49 @@
+import { Play } from "lucide-react";
+import type { IssueWorkProduct } from "@paperclipai/shared";
+import { getIssueOutputs, type IssueOutputItem } from "@/lib/issue-output";
+import { OutputPrimaryCard } from "./OutputPrimaryCard";
+import { OutputRow } from "./OutputRow";
+
+interface IssueOutputSectionProps {
+  workProducts: IssueWorkProduct[] | null | undefined;
+  /** Optional resolver for the artifact creator's display name. */
+  resolveCreatorName?: (item: IssueOutputItem) => string | null;
+}
+
+/**
+ * Issue Output surface (PAP-10162 Phase 3).
+ *
+ * Renders attachment-backed artifact work products as first-class issue
+ * outputs: a full-width primary card (video player / image / generic file) with
+ * Open + Download, plus compact rows for any additional outputs. The section is
+ * omitted entirely when the issue has produced no outputs — we never show a
+ * permanent empty card.
+ */
+export function IssueOutputSection({ workProducts, resolveCreatorName }: IssueOutputSectionProps) {
+  const { primary, rest, count } = getIssueOutputs(workProducts);
+
+  if (!primary) return null;
+
+  const creatorFor = (item: IssueOutputItem) => resolveCreatorName?.(item) ?? null;
+
+  return (
+    <section className="space-y-3" aria-label="Issue outputs">
+      <div className="flex items-center gap-2">
+        <Play className="h-3.5 w-3.5 text-muted-foreground" aria-hidden="true" />
+        <h3 className="text-sm font-medium text-muted-foreground">Output</h3>
+        <span className="text-xs text-muted-foreground">{count}</span>
+      </div>
+
+      <OutputPrimaryCard item={primary} creatorName={creatorFor(primary)} />
+
+      {rest.length > 0 && (
+        <div className="space-y-2">
+          <p className="text-[11px] font-medium uppercase tracking-wide text-muted-foreground">Also produced</p>
+          {rest.map((item) => (
+            <OutputRow key={item.id} item={item} creatorName={creatorFor(item)} />
+          ))}
+        </div>
+      )}
+    </section>
+  );
+}
diff --git a/ui/src/components/issue-output/OutputFileTile.tsx b/ui/src/components/issue-output/OutputFileTile.tsx
new file mode 100644
index 00000000..13ad442f
--- /dev/null
+++ b/ui/src/components/issue-output/OutputFileTile.tsx
@@ -0,0 +1,35 @@
+import { cn } from "@/lib/utils";
+import { getOutputFileGlyph, type OutputFileTone } from "@/lib/issue-output";
+
+const TONE_CLASSES: Record<OutputFileTone, string> = {
+  video: "bg-indigo-500/15 text-indigo-300",
+  pdf: "bg-red-500/15 text-red-300",
+  zip: "bg-amber-500/15 text-amber-300",
+  image: "bg-emerald-500/15 text-emerald-300",
+  bin: "bg-muted text-muted-foreground",
+};
+
+interface OutputFileTileProps {
+  contentType: string | null | undefined;
+  className?: string;
+  /** Tailwind size classes for the square tile. Defaults to a 32×32 tile. */
+  sizeClassName?: string;
+}
+
+/** Square file-type tile showing a short MIME-derived label, colorised by tone. */
+export function OutputFileTile({ contentType, className, sizeClassName = "h-8 w-8" }: OutputFileTileProps) {
+  const glyph = getOutputFileGlyph(contentType);
+  return (
+    <span
+      className={cn(
+        "flex shrink-0 items-center justify-center rounded-md text-[10px] font-semibold tabular-nums",
+        sizeClassName,
+        TONE_CLASSES[glyph.tone],
+        className,
+      )}
+      aria-hidden="true"
+    >
+      {glyph.label}
+    </span>
+  );
+}
diff --git a/ui/src/components/issue-output/OutputPrimaryCard.tsx b/ui/src/components/issue-output/OutputPrimaryCard.tsx
new file mode 100644
index 00000000..c0a6ca79
--- /dev/null
+++ b/ui/src/components/issue-output/OutputPrimaryCard.tsx
@@ -0,0 +1,96 @@
+import { Download, ExternalLink } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { Badge } from "@/components/ui/badge";
+import { cn, relativeTime } from "@/lib/utils";
+import {
+  formatBytes,
+  isImageContentType,
+  isVideoContentType,
+  outputFilename,
+  type IssueOutputItem,
+} from "@/lib/issue-output";
+import { OutputVideoPlayer } from "./OutputVideoPlayer";
+import { OutputFileTile } from "./OutputFileTile";
+
+interface OutputPrimaryCardProps {
+  item: IssueOutputItem;
+  creatorName?: string | null;
+}
+
+/**
+ * Full-width primary output card: media region (video / image / generic file)
+ * over a metadata strip with Open + Download actions. The layout stacks on
+ * mobile and uses a single horizontal meta row on desktop.
+ */
+export function OutputPrimaryCard({ item, creatorName }: OutputPrimaryCardProps) {
+  const meta = item.metadata;
+  const filename = outputFilename(item);
+  const contentType = meta?.contentType;
+
+  return (
+    <div className="overflow-hidden rounded-md border border-border bg-card">
+      {/* Media region */}
+      {meta && isVideoContentType(contentType) ? (
+        <OutputVideoPlayer src={meta.contentPath} title={filename} />
+      ) : meta && isImageContentType(contentType) ? (
+        <a
+          href={meta.openPath}
+          target="_blank"
+          rel="noreferrer"
+          className="block aspect-video w-full overflow-hidden bg-black"
+          aria-label={`Open ${filename}`}
+        >
+          <img src={meta.contentPath} alt={filename} className="h-full w-full object-contain" />
+        </a>
+      ) : (
+        <div className="flex aspect-video w-full items-center justify-center bg-muted/30">
+          <OutputFileTile contentType={contentType} sizeClassName="h-16 w-16 text-base" />
+        </div>
+      )}
+
+      {/* Metadata strip */}
+      <div className="flex flex-col gap-2 p-3 md:flex-row md:items-center md:justify-between">
+        <div className="min-w-0 flex-1">
+          <p className="break-words text-sm font-semibold text-foreground">{filename}</p>
+          {item.degraded ? (
+            <p className="mt-0.5 text-[11px] text-destructive">
+              Output metadata is unavailable — this file can’t be played or downloaded here.
+            </p>
+          ) : (
+            <div className="mt-0.5 flex flex-wrap items-center gap-x-1.5 gap-y-0.5 text-[11px] text-muted-foreground">
+              {item.isPrimary && (
+                <Badge variant="secondary" className="px-1.5 py-0 text-[10px]">
+                  Primary
+                </Badge>
+              )}
+              {meta && <span>{meta.contentType}</span>}
+              {meta && <span aria-hidden="true">·</span>}
+              {meta && <span>{formatBytes(meta.byteSize)}</span>}
+              {creatorName && <span aria-hidden="true">·</span>}
+              {creatorName && <span>{creatorName}</span>}
+              <span aria-hidden="true">·</span>
+              <span>{relativeTime(item.createdAt)}</span>
+            </div>
+          )}
+        </div>
+
+        {meta ? (
+          <div className={cn("flex shrink-0 items-center gap-2", "max-md:w-full")}>
+            <Button asChild variant="outline" size="sm" className="max-md:flex-1">
+              <a href={meta.openPath} target="_blank" rel="noreferrer">
+                <ExternalLink className="h-4 w-4" />
+                Open
+              </a>
+            </Button>
+            <Button asChild size="sm" className="max-md:flex-1">
+              <a href={meta.downloadPath} aria-label={`Download ${filename}`}>
+                <Download className="h-4 w-4" />
+                Download
+              </a>
+            </Button>
+          </div>
+        ) : null}
+      </div>
+    </div>
+  );
+}
diff --git a/ui/src/components/issue-output/OutputRow.tsx b/ui/src/components/issue-output/OutputRow.tsx
new file mode 100644
index 00000000..dc4687eb
--- /dev/null
+++ b/ui/src/components/issue-output/OutputRow.tsx
@@ -0,0 +1,57 @@
+import { Download, ExternalLink } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { cn, relativeTime } from "@/lib/utils";
+import { formatBytes, outputFilename, type IssueOutputItem } from "@/lib/issue-output";
+import { OutputFileTile } from "./OutputFileTile";
+
+interface OutputRowProps {
+  item: IssueOutputItem;
+  creatorName?: string | null;
+}
+
+/** Compact row for a non-primary output ("ALSO PRODUCED"). */
+export function OutputRow({ item, creatorName }: OutputRowProps) {
+  const filename = outputFilename(item);
+  const meta = item.metadata;
+
+  const metaBits: string[] = [];
+  if (meta) {
+    metaBits.push(meta.contentType);
+    metaBits.push(formatBytes(meta.byteSize));
+  }
+  if (creatorName) metaBits.push(creatorName);
+  metaBits.push(relativeTime(item.createdAt));
+
+  return (
+    <div className="flex items-center gap-2.5 rounded-md border border-border bg-card p-2">
+      <OutputFileTile contentType={meta?.contentType} />
+      <div className="min-w-0 flex-1">
+        <p className="truncate text-sm font-medium text-foreground" title={filename}>
+          {filename}
+        </p>
+        <p
+          className={cn(
+            "truncate text-[11px]",
+            item.degraded ? "text-destructive" : "text-muted-foreground",
+          )}
+        >
+          {item.degraded ? "File details unavailable" : metaBits.join(" · ")}
+        </p>
+      </div>
+      {meta ? (
+        <div className="flex shrink-0 items-center gap-1">
+          <Button asChild variant="ghost" size="icon-sm" title="Open in new tab">
+            <a href={meta.openPath} target="_blank" rel="noreferrer" aria-label={`Open ${filename}`}>
+              <ExternalLink className="h-4 w-4" />
+            </a>
+          </Button>
+          <Button asChild variant="ghost" size="icon-sm" title="Download">
+            <a href={meta.downloadPath} aria-label={`Download ${filename}`}>
+              <Download className="h-4 w-4" />
+            </a>
+          </Button>
+        </div>
+      ) : null}
+    </div>
+  );
+}
diff --git a/ui/src/components/issue-output/OutputVideoPlayer.tsx b/ui/src/components/issue-output/OutputVideoPlayer.tsx
new file mode 100644
index 00000000..ec286dc6
--- /dev/null
+++ b/ui/src/components/issue-output/OutputVideoPlayer.tsx
@@ -0,0 +1,33 @@
+import { cn } from "@/lib/utils";
+
+interface OutputVideoPlayerProps {
+  src: string;
+  poster?: string | null;
+  className?: string;
+  /** Accessible label, typically the filename. */
+  title?: string;
+}
+
+/**
+ * Thin wrapper around the native HTML5 `<video>` element with sensible
+ * defaults for issue outputs. We deliberately rely on the browser's native
+ * controls (play/pause/scrub/fullscreen/PiP) rather than building a custom
+ * scrubber — the backend serves byte ranges so seeking works.
+ *
+ * A fixed 16:9 box reserves height before metadata loads to avoid layout jump.
+ */
+export function OutputVideoPlayer({ src, poster, className, title }: OutputVideoPlayerProps) {
+  return (
+    <div className={cn("relative w-full overflow-hidden rounded-md bg-black aspect-video", className)}>
+      <video
+        src={src}
+        poster={poster ?? undefined}
+        controls
+        preload="metadata"
+        playsInline
+        aria-label={title ? `Video output: ${title}` : "Video output"}
+        className="absolute inset-0 h-full w-full"
+      />
+    </div>
+  );
+}
diff --git a/ui/src/lib/issue-output.test.ts b/ui/src/lib/issue-output.test.ts
new file mode 100644
index 00000000..15bb3508
--- /dev/null
+++ b/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();
+  });
+});
diff --git a/ui/src/lib/issue-output.ts b/ui/src/lib/issue-output.ts
new file mode 100644
index 00000000..9e396ab6
--- /dev/null
+++ b/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";
+}
diff --git a/ui/src/pages/DesignGuide.tsx b/ui/src/pages/DesignGuide.tsx
index 4b4a903f..0d2f0c59 100644
--- a/ui/src/pages/DesignGuide.tsx
+++ b/ui/src/pages/DesignGuide.tsx
@@ -125,6 +125,76 @@ import { PageSkeleton } from "@/components/PageSkeleton";
 import { Identity } from "@/components/Identity";
 import { IssueReferencePill } from "@/components/IssueReferencePill";
 import { MembershipAction } from "@/components/MembershipAction";
+import { IssueOutputSection } from "@/components/issue-output/IssueOutputSection";
+import type { IssueWorkProduct } from "@paperclipai/shared";
+
+/* ------------------------------------------------------------------ */
+/*  Sample data for the Issue Output surface showcase                  */
+/* ------------------------------------------------------------------ */
+
+function sampleOutput(
+  id: string,
+  attachmentId: string,
+  contentType: string,
+  filename: string,
+  opts: { byteSize: number; isPrimary?: boolean; createdAt: string },
+): IssueWorkProduct {
+  const contentPath = `/api/attachments/${attachmentId}/content`;
+  return {
+    id,
+    companyId: "demo-company",
+    projectId: null,
+    issueId: "demo-issue",
+    executionWorkspaceId: null,
+    runtimeServiceId: null,
+    type: "artifact",
+    provider: "paperclip",
+    externalId: null,
+    title: filename,
+    url: null,
+    status: "active",
+    reviewState: "none",
+    isPrimary: Boolean(opts.isPrimary),
+    healthStatus: "unknown",
+    summary: null,
+    createdByRunId: null,
+    createdAt: new Date(opts.createdAt),
+    updatedAt: new Date(opts.createdAt),
+    metadata: {
+      attachmentId,
+      contentType,
+      byteSize: opts.byteSize,
+      contentPath,
+      openPath: contentPath,
+      downloadPath: `${contentPath}?download=1`,
+      originalFilename: filename,
+    },
+  } as IssueWorkProduct;
+}
+
+const DESIGN_GUIDE_OUTPUTS: IssueWorkProduct[] = [
+  sampleOutput("wp-vid", "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "video/mp4", "q3-summary.mp4", {
+    byteSize: 19_293_798,
+    isPrimary: true,
+    createdAt: "2026-05-30T12:00:00Z",
+  }),
+  sampleOutput("wp-pdf", "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb", "application/pdf", "talking-points.pdf", {
+    byteSize: 421_888,
+    createdAt: "2026-05-30T11:52:00Z",
+  }),
+];
+
+const DESIGN_GUIDE_DEGRADED_OUTPUTS: IssueWorkProduct[] = [
+  {
+    ...sampleOutput("wp-broken", "cccccccc-cccc-4ccc-8ccc-cccccccccccc", "video/mp4", "corrupt-output.mp4", {
+      byteSize: 0,
+      isPrimary: true,
+      createdAt: "2026-05-30T12:01:00Z",
+    }),
+    // Strip the path metadata so it fails the shared artifact schema.
+    metadata: { attachmentId: "cccccccc-cccc-4ccc-8ccc-cccccccccccc", contentType: "video/mp4" },
+  } as IssueWorkProduct,
+];
 
 /* ------------------------------------------------------------------ */
 /*  Section wrapper                                                    */
@@ -1402,6 +1472,21 @@ export function DesignGuide() {
           ))}
         </div>
       </Section>
+
+      <Section title="Issue Output Surface">
+        <SubSection title="Multiple outputs (primary video + 'Also produced')">
+          <IssueOutputSection workProducts={DESIGN_GUIDE_OUTPUTS} />
+        </SubSection>
+        <SubSection title="Degraded output (invalid / failed attachment metadata)">
+          <IssueOutputSection workProducts={DESIGN_GUIDE_DEGRADED_OUTPUTS} />
+        </SubSection>
+        <SubSection title="Empty state">
+          <p className="text-xs text-muted-foreground">
+            When an issue has produced no artifact work products, the Output section renders nothing
+            at all (no placeholder card).
+          </p>
+        </SubSection>
+      </Section>
     </div>
   );
 }
diff --git a/ui/src/pages/IssueDetail.tsx b/ui/src/pages/IssueDetail.tsx
index 9ee3c69b..5c7d4607 100644
--- a/ui/src/pages/IssueDetail.tsx
+++ b/ui/src/pages/IssueDetail.tsx
@@ -67,6 +67,8 @@ import { IssueChatThread, type IssueChatComposerHandle } from "../components/Iss
 import { IssueContinuationHandoff } from "../components/IssueContinuationHandoff";
 import { IssueDocumentsSection } from "../components/IssueDocumentsSection";
 import { IssuePlanDecompositionsSection } from "../components/IssuePlanDecompositionsSection";
+import { IssueOutputSection } from "../components/issue-output/IssueOutputSection";
+import { formatBytes } from "../lib/issue-output";
 import { IssueSiblingNavigation } from "../components/IssueSiblingNavigation";
 import { IssuesList } from "../components/IssuesList";
 import { AgentIcon } from "../components/AgentIconPicker";
@@ -150,6 +152,7 @@ import {
   type Issue,
   type IssueAttachment,
   type IssueComment,
+  type IssueWorkProduct,
   type IssueWorkMode,
   type IssueThreadInteraction,
   type RequestConfirmationInteraction,
@@ -1339,6 +1342,13 @@ export function IssueDetail() {
     placeholderData: keepPreviousDataForSameQueryTail<IssueAttachment[]>(issueId ?? "pending"),
   });
 
+  const { data: workProducts } = useQuery({
+    queryKey: queryKeys.issues.workProducts(issueId!),
+    queryFn: () => issuesApi.listWorkProducts(issueId!),
+    enabled: !!issueId,
+    placeholderData: keepPreviousDataForSameQueryTail<IssueWorkProduct[]>(issueId ?? "pending"),
+  });
+
   const { data: liveRunCount = 0 } = useQuery<LiveRunForIssue[], Error, number>({
     queryKey: queryKeys.issues.liveRuns(issueId!),
     queryFn: () => heartbeatsApi.liveRunsForIssue(issueId!),
@@ -3757,6 +3767,8 @@ export function IssueDetail() {
         userProfileMap={userProfileMap}
       />
 
+      <IssueOutputSection workProducts={workProducts} />
+
       {attachmentsInitialLoading ? (
         <IssueSectionSkeleton titleWidth="w-24" rows={2} />
       ) : hasAttachments ? (
@@ -3880,7 +3892,7 @@ export function IssueDetail() {
                   </button>
                 </div>
                 <p className="text-[11px] text-muted-foreground">
-                  {attachment.contentType} · {(attachment.byteSize / 1024).toFixed(1)} KB
+                  {attachment.contentType} · {formatBytes(attachment.byteSize)}
                 </p>
               </div>
             ))}