@tangle-network/ui 11.25.0 → 11.27.0

package/dist/index.js

@@ -82,7 +82,11 @@ import { LiveDuration } from "./run/run-item-primitives.js";
 import { ToolCallFeed, parseToolEvent } from "./run/tool-call-feed.js";
 import { FileTree, filterFileTree } from "./files/file-tree.js";
 import { RichFileTree } from "./files/rich-file-tree.js";
+import { FileCard } from "./files/file-card.js";
+import { configurePdfViewer } from "./files/pdf-loader.js";
+import { PdfViewer } from "./files/pdf-viewer.js";
 import { CSV_PREVIEW_ROW_LIMIT, FilePreview, parseCsv } from "./files/file-preview.js";
+import { FileList } from "./files/file-list.js";
 import { FileTabs } from "./files/file-tabs.js";
 import { FileArtifactPane } from "./files/file-artifact-pane.js";
 import { AuthHeader, GitHubLoginButton, UserMenu } from "./auth/auth.js";
@@ -99,4 +103,4 @@ import { addMessage, addParts, clearChat, isStreamingAtom, messagesAtom, partMap
 import { copyText } from "./utils/copy-text.js";
 import { timeAgo } from "./utils/time-ago.js";
 import { RedactedDocument } from "./redaction/redacted-document.js";
-export { AgentTimeline, Alert, AlertDescription, AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, AlertTitle, ArtifactPane, AuthHeader, Avatar, AvatarFallback, AvatarImage, Badge, Button, CATEGORY_TONES, CSV_PREVIEW_ROW_LIMIT, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, ChatContainer, ChatMessage, Checkbox, Chip, CodeBlock, Collapsible, CollapsibleContent, CollapsibleTrigger, CommandPreview, ContextMenu, ContextMenuCheckboxItem, ContextMenuContent, ContextMenuGroup, ContextMenuItem, ContextMenuLabel, ContextMenuPortal, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuSeparator, ContextMenuShortcut, ContextMenuSub, ContextMenuSubContent, ContextMenuSubTrigger, ContextMenuTrigger, CopyButton, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DiffPreview, DropZone, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, EmptyState, ExpandedToolDetail, FileArtifactPane, FilePreview, FileTabs, FileTree, FilterField, GitHubLoginButton, GlobResultsPreview, GrepResultsPreview, Heading, IconTile, InlineCode, InlineThinkingItem, InlineToolItem, Input, Label, LiveDuration, LoginLayout, Logo, Markdown, MessageAuthor, MessageList, Metric, MetricStrip, OPENUI_NODE_JSON_SCHEMA, OPENUI_NODE_TYPES, OpenUIArtifactRenderer, PageHeader, PageShell, Pagination, Popover, PopoverAnchor, PopoverClose, PopoverContent, PopoverTrigger, Progress, QuestionPreview, RealtimeSessionRegistry, RedactedDocument, RichFileTree, RunGroup, RunRowShell, RunRowStatusDot, SegmentedControl, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger, SidebarDropZone, Skeleton, SkeletonCard, SkeletonTable, Slider, StatCard, StatusPill, Switch, TONE_CLASSES, TOOL_CATEGORY_ICONS, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, Tag, TangleKnot, TerminalCursor, TerminalDisplay, TerminalInput, TerminalLine, TextShimmer, Textarea, ThemeToggle, ThinkingIndicator, ToastContainer, ToastProvider, ToolCallFeed, Toolbar, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, UploadProgress, UserMenu, UserMessage, WebSearchPreview, WriteFilePreview, activeSessionsAtom, addMessage, addParts, badgeVariants, bumpActiveSessionActivity, buttonVariants, clearChat, cn, copyText, createAuthFetcher, detectFileFormat, fileExtension, filterFileTree, findUnsupportedOpenUINode, focusField, focusFieldInvalid, focusFieldWithin, focusRing, focusRingInset, formatBytes, formatDuration, formatUptime, getActiveSession, getAllActiveSessions, getAllProjectActivity, getCodeLanguage, getFormatLabel, getSanitizedMarkdownHeadingIdFromRawFragment, getSessionsByActivity, getSessionsForNavbar, getSessionsForProject, getSyntaxLanguage, getToolCategory, getToolDisplayMetadata, getToolErrorText, getTotalRunningSessionCount, hasBackgroundRunningSessions, initialsOf, isStreamingAtom, isViewerMessage, messagesAtom, parseCsv, parseToolEvent, partMapAtom, registerActiveSession, resetActiveSessions, resolveFilePreviewKind, setActiveSessionAttention, setActiveSessionConnection, setActiveSessionError, setActiveSessionRunning, setForegroundActiveSession, timeAgo, toneFor, truncateText, unregisterActiveSession, updateActiveSessionMeta, updatePart, useActiveSession, useActiveSessions, useActiveSessionsState, useApiKey, useAuth, useAutoScroll, useDropdownMenu, useHasBackgroundRunningSessions, useLiveTime, useNavbarSessions, useProjectActivity, useProjectSessions, useRealtimeSession, useRunCollapseState, useRunGroups, useSSEStream, useSdkSession, useSessionsByActivity, useTheme, useToast, useToolCallStream, useTotalRunningSessions, validateOpenUIJsonArtifact, validateOpenUIJsonNode };
+export { AgentTimeline, Alert, AlertDescription, AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, AlertTitle, ArtifactPane, AuthHeader, Avatar, AvatarFallback, AvatarImage, Badge, Button, CATEGORY_TONES, CSV_PREVIEW_ROW_LIMIT, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, ChatContainer, ChatMessage, Checkbox, Chip, CodeBlock, Collapsible, CollapsibleContent, CollapsibleTrigger, CommandPreview, ContextMenu, ContextMenuCheckboxItem, ContextMenuContent, ContextMenuGroup, ContextMenuItem, ContextMenuLabel, ContextMenuPortal, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuSeparator, ContextMenuShortcut, ContextMenuSub, ContextMenuSubContent, ContextMenuSubTrigger, ContextMenuTrigger, CopyButton, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DiffPreview, DropZone, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, EmptyState, ExpandedToolDetail, FileArtifactPane, FileCard, FileList, FilePreview, FileTabs, FileTree, FilterField, GitHubLoginButton, GlobResultsPreview, GrepResultsPreview, Heading, IconTile, InlineCode, InlineThinkingItem, InlineToolItem, Input, Label, LiveDuration, LoginLayout, Logo, Markdown, MessageAuthor, MessageList, Metric, MetricStrip, OPENUI_NODE_JSON_SCHEMA, OPENUI_NODE_TYPES, OpenUIArtifactRenderer, PageHeader, PageShell, Pagination, PdfViewer, Popover, PopoverAnchor, PopoverClose, PopoverContent, PopoverTrigger, Progress, QuestionPreview, RealtimeSessionRegistry, RedactedDocument, RichFileTree, RunGroup, RunRowShell, RunRowStatusDot, SegmentedControl, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger, SidebarDropZone, Skeleton, SkeletonCard, SkeletonTable, Slider, StatCard, StatusPill, Switch, TONE_CLASSES, TOOL_CATEGORY_ICONS, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, Tag, TangleKnot, TerminalCursor, TerminalDisplay, TerminalInput, TerminalLine, TextShimmer, Textarea, ThemeToggle, ThinkingIndicator, ToastContainer, ToastProvider, ToolCallFeed, Toolbar, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, UploadProgress, UserMenu, UserMessage, WebSearchPreview, WriteFilePreview, activeSessionsAtom, addMessage, addParts, badgeVariants, bumpActiveSessionActivity, buttonVariants, clearChat, cn, configurePdfViewer, copyText, createAuthFetcher, detectFileFormat, fileExtension, filterFileTree, findUnsupportedOpenUINode, focusField, focusFieldInvalid, focusFieldWithin, focusRing, focusRingInset, formatBytes, formatDuration, formatUptime, getActiveSession, getAllActiveSessions, getAllProjectActivity, getCodeLanguage, getFormatLabel, getSanitizedMarkdownHeadingIdFromRawFragment, getSessionsByActivity, getSessionsForNavbar, getSessionsForProject, getSyntaxLanguage, getToolCategory, getToolDisplayMetadata, getToolErrorText, getTotalRunningSessionCount, hasBackgroundRunningSessions, initialsOf, isStreamingAtom, isViewerMessage, messagesAtom, parseCsv, parseToolEvent, partMapAtom, registerActiveSession, resetActiveSessions, resolveFilePreviewKind, setActiveSessionAttention, setActiveSessionConnection, setActiveSessionError, setActiveSessionRunning, setForegroundActiveSession, timeAgo, toneFor, truncateText, unregisterActiveSession, updateActiveSessionMeta, updatePart, useActiveSession, useActiveSessions, useActiveSessionsState, useApiKey, useAuth, useAutoScroll, useDropdownMenu, useHasBackgroundRunningSessions, useLiveTime, useNavbarSessions, useProjectActivity, useProjectSessions, useRealtimeSession, useRunCollapseState, useRunGroups, useSSEStream, useSdkSession, useSessionsByActivity, useTheme, useToast, useToolCallStream, useTotalRunningSessions, validateOpenUIJsonArtifact, validateOpenUIJsonNode };

package/dist/lib/optional-peer.js

@@ -0,0 +1,29 @@
+//#region src/lib/optional-peer.ts
+/**
+* Shared handling for optional peers that an entry reaches through a dynamic
+* `import()`: `./editor` for tiptap, yjs and Hocuspocus, `./files` for
+* pdfjs-dist. `scripts/validate-dist.mjs` holds the rules these helpers serve.
+*/
+/** The messages a bundler or a runtime gives for a module it cannot resolve. */
+const RESOLUTION_FAILURE = /could not resolve|cannot find (?:module|package)|can't resolve|failed to resolve|module not found/i;
+/**
+* True when the rejection says the package is not installed. Only such an
+* error gets the install list: a transient chunk-fetch failure that reads as
+* "install the peers" sends the reader to the wrong fix. An error this
+* predicate does not match keeps its own message, so it can only
+* under-report.
+*/
+function isMissingPeerError(error) {
+	return error instanceof Error && RESOLUTION_FAILURE.test(error.message);
+}
+/**
+* Hands an `import()` rejection on unchanged. esbuild reports an unresolvable
+* literal `import()` as a build error and defers it to run time only when the
+* call carries a `.catch()`, so every peer import attaches this handler. It
+* changes nothing at run time.
+*/
+function rethrow(error) {
+	throw error;
+}
+//#endregion
+export { isMissingPeerError, rethrow };

package/dist/markdown/markdown.d.ts

@@ -9,8 +9,9 @@ export interface MarkdownProps {
   urlTransform?: UrlTransform;
 }
 /**
- * Renders Markdown content with GFM support, XSS sanitisation, and
- * custom code block rendering via our CodeBlock component.
+ * Renders Markdown content with GFM support, XSS sanitisation, custom code
+ * block rendering via our CodeBlock component, and images that open full size
+ * or show a labelled placeholder when unavailable.
  */
 export declare const Markdown: import("react").MemoExoticComponent<({ children, className, urlTransform }: MarkdownProps) => import("react").JSX.Element>;
 //#endregion

package/dist/markdown/markdown.js

@@ -1,7 +1,8 @@
 import { cn } from "../lib/utils.js";
 import { CodeBlock, CopyButton } from "./code-block.js";
-import { memo } from "react";
-import { Fragment as Fragment$1, jsx } from "react/jsx-runtime";
+import { createContext, memo, useContext, useEffect, useRef, useState } from "react";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+import { ImageOff } from "lucide-react";
 import ReactMarkdown, { defaultUrlTransform } from "react-markdown";
 import remarkGfm from "remark-gfm";
 import rehypeSanitize from "rehype-sanitize";
@@ -27,9 +28,72 @@ function transformMarkdownUrl(url, key, node, urlTransform) {
 	if (key === "href" && transformed === url && url.startsWith("#")) return safeUrl("#" + getSanitizedMarkdownHeadingIdFromRawFragment(url.slice(1)));
 	return safeUrl(transformed);
 }
+const MarkdownLinkContext = createContext(false);
+function MarkdownLink({ node: _node, ...props }) {
+	return /* @__PURE__ */ jsx(MarkdownLinkContext.Provider, {
+		value: true,
+		children: /* @__PURE__ */ jsx("a", { ...props })
+	});
+}
+/**
+* Renders a Markdown image that opens full size in a new tab, or a labelled
+* placeholder when its URL is unsafe or fails to load, instead of the
+* browser's broken-image icon.
+*/
+function MarkdownImage({ node: _node, src, alt, className, ...props }) {
+	const insideLink = useContext(MarkdownLinkContext);
+	const imageRef = useRef(null);
+	const url = typeof src === "string" && src ? src : void 0;
+	const [failedUrl, setFailedUrl] = useState();
+	useEffect(() => {
+		const image = imageRef.current;
+		if (!url || !image?.complete || typeof image.decode !== "function") return;
+		let current = true;
+		image.decode().catch(() => {
+			if (current) setFailedUrl(url);
+		});
+		return () => {
+			current = false;
+		};
+	}, [url]);
+	if (!url || failedUrl === url) {
+		const label = alt ? `Image unavailable: ${alt}` : "Image unavailable";
+		return /* @__PURE__ */ jsxs("span", {
+			role: "img",
+			"aria-label": label,
+			className: "inline-flex max-w-full items-center gap-2 rounded-md border border-dashed border-border bg-muted px-3 py-2 text-sm text-muted-foreground",
+			children: [/* @__PURE__ */ jsx(ImageOff, {
+				"aria-hidden": true,
+				className: "size-4 shrink-0"
+			}), /* @__PURE__ */ jsx("span", {
+				className: "min-w-0 truncate",
+				children: label
+			})]
+		});
+	}
+	const image = /* @__PURE__ */ jsx("img", {
+		...props,
+		ref: imageRef,
+		src: url,
+		alt: alt ?? "",
+		loading: "lazy",
+		decoding: "async",
+		onError: () => setFailedUrl(url),
+		className: cn("h-auto max-w-full rounded-md", className)
+	});
+	if (insideLink) return image;
+	return /* @__PURE__ */ jsx("a", {
+		href: url,
+		target: "_blank",
+		rel: "noopener noreferrer",
+		className: "inline-block max-w-full",
+		children: image
+	});
+}
 /**
-* Renders Markdown content with GFM support, XSS sanitisation, and
-* custom code block rendering via our CodeBlock component.
+* Renders Markdown content with GFM support, XSS sanitisation, custom code
+* block rendering via our CodeBlock component, and images that open full size
+* or show a labelled placeholder when unavailable.
 */
 const Markdown = memo(({ children, className, urlTransform }) => {
 	return /* @__PURE__ */ jsx("div", {
@@ -39,6 +103,8 @@ const Markdown = memo(({ children, className, urlTransform }) => {
 			rehypePlugins: [rehypeSlug, rehypeSanitize],
 			urlTransform: (url, key, node) => transformMarkdownUrl(url, key, node, urlTransform),
 			components: {
+				a: MarkdownLink,
+				img: MarkdownImage,
 				pre({ children: preChildren }) {
 					return /* @__PURE__ */ jsx(Fragment$1, { children: preChildren });
 				},

package/dist/primitives.d.ts

@@ -1,5 +1,7 @@
 import { Button, ButtonProps, buttonVariants } from "./primitives/button.js";
 import { ArtifactPane, ArtifactPaneProps } from "./primitives/artifact-pane.js";
+import { CATEGORY_TONES, CategoryTone, TONE_CLASSES, Tone, ToneClasses, toneFor } from "./primitives/tone.js";
+import { IconTile, IconTileProps, initialsOf } from "./primitives/icon-tile.js";
 import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, CardTitleProps } from "./primitives/card.js";
 import { Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger } from "./primitives/dialog.js";
 import { AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger } from "./primitives/alert-dialog.js";
@@ -40,10 +42,8 @@ import { PageHeader, PageHeaderProps } from "./primitives/page-header.js";
 import { StatusPill, StatusPillProps, StatusTone } from "./primitives/status-pill.js";
 import { Alert, AlertDescription, AlertProps, AlertTitle, AlertTone } from "./primitives/alert.js";
 import { Pagination, PaginationProps } from "./primitives/pagination.js";
-import { CATEGORY_TONES, CategoryTone, TONE_CLASSES, Tone, ToneClasses, toneFor } from "./primitives/tone.js";
 import { Tag, TagProps } from "./primitives/tag.js";
 import { Chip, ChipProps } from "./primitives/chip.js";
-import { IconTile, IconTileProps, initialsOf } from "./primitives/icon-tile.js";
 import { Metric, MetricProps, MetricStrip, MetricStripProps } from "./primitives/metric-strip.js";
 import { FilterField, FilterFieldProps, Toolbar, ToolbarProps } from "./primitives/toolbar.js";
 import { Logo, LogoProps, TangleKnot } from "@tangle-network/brand";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/ui",
-  "version": "11.25.0",
+  "version": "11.27.0",
   "description": "Generic React UI components for Tangle products — primitives, chat, run, files, editor, markdown.",
   "type": "module",
   "license": "MIT",
@@ -149,13 +149,14 @@
   "peerDependencies": {
     "@hocuspocus/provider": ">=2.15.0 <5.0.0",
     "@nanostores/react": ">=0.8.4 <3.0.0",
-    "@tangle-network/brand": "^1.17.0",
+    "@tangle-network/brand": "^1.17.1",
     "@tiptap/core": ">=3.20.4 <4.0.0",
     "@tiptap/extension-collaboration": ">=3.20.4 <4.0.0",
     "@tiptap/extension-collaboration-caret": ">=3.7.0 <4.0.0",
     "@tiptap/react": ">=3.20.4 <4.0.0",
     "@tiptap/starter-kit": ">=3.20.4 <4.0.0",
     "nanostores": ">=0.11.3 <2.0.0",
+    "pdfjs-dist": ">=6.0.0 <7.0.0",
     "react": "^18 || ^19",
     "react-dom": "^18 || ^19",
     "react-router": "^7 || ^8",
@@ -191,6 +192,9 @@
     },
     "react-router": {
       "optional": true
+    },
+    "pdfjs-dist": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -208,6 +212,7 @@
     "@types/turndown": "^5.0.6",
     "ajv": "8.17.1",
     "nanostores": "^1.5.4",
+    "pdfjs-dist": "^6.4.299",
     "react": "^19.3.0",
     "react-dom": "^19.3.0",
     "react-router": "^8.4.0",

package/src/editor/editor-peers.ts

@@ -32,6 +32,9 @@ import type * as TiptapCollaborationCaret from "@tiptap/extension-collaboration-
 import type * as TiptapReact from "@tiptap/react";
 import type * as TiptapStarterKit from "@tiptap/starter-kit";
 import type * as Yjs from "yjs";
+import { isMissingPeerError, rethrow } from "../lib/optional-peer";
+
+export { isMissingPeerError };
 
 /** Namespaces the local markdown editor needs. */
 export interface DocumentEditorPeers {
@@ -89,31 +92,6 @@ export function isMissingEditorPeersError(error: unknown): boolean {
   return error instanceof Error && error.name === "MissingEditorPeersError";
 }
 
-/** The messages a bundler or a runtime gives for a module it cannot resolve. */
-const RESOLUTION_FAILURE =
-  /could not resolve|cannot find (?:module|package)|can't resolve|failed to resolve|module not found/i;
-
-/**
- * True when the rejection says the package is not installed. Only such an
- * error gets the install list: a transient chunk-fetch failure that reads as
- * "install the peers" sends the reader to the wrong fix. An error this
- * predicate does not match keeps its own message, so it can only
- * under-report.
- */
-export function isMissingPeerError(error: unknown): boolean {
-  return error instanceof Error && RESOLUTION_FAILURE.test(error.message);
-}
-
-/**
- * Hands an `import()` rejection on unchanged. esbuild reports an unresolvable
- * literal `import()` as a build error and defers it to run time only when the
- * call carries a `.catch()`, so every peer import attaches this handler. It
- * changes nothing at run time.
- */
-function rethrow(error: unknown): never {
-  throw error;
-}
-
 /**
  * Every optional peer the `./editor` entry needs at run time. The loaders
  * import all but `@tiptap/core`, which the tiptap packages need in turn: a

package/src/files/file-artifact-pane.test.tsx

@@ -2,6 +2,12 @@ import { describe, expect, it, vi } from "vitest";
 import { fireEvent, render, screen } from "@testing-library/react";
 import { FileArtifactPane } from "./file-artifact-pane";
 import { CSV_PREVIEW_ROW_LIMIT, parseCsv } from "./file-preview";
+import { MissingPdfjsError, loadPdfjs } from "./pdf-loader";
+
+vi.mock("./pdf-loader", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("./pdf-loader")>()),
+  loadPdfjs: vi.fn(),
+}));
 
 const BLOB_URL = "blob:https://app.tangle.tools/1f2e3d4c";
 
@@ -32,16 +38,20 @@ describe("FileArtifactPane previews", () => {
     expect(container.querySelector("img")).toHaveClass("max-w-none");
   });
 
-  it("renders a PDF as an <object> of the blobUrl", () => {
+  it("renders a PDF in PdfViewer, and in an <object> of the blobUrl without pdfjs-dist", async () => {
+    vi.mocked(loadPdfjs).mockRejectedValue(new MissingPdfjsError());
+    const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
     const { container } = render(
       <FileArtifactPane filename="report.pdf" blobUrl={BLOB_URL} mimeType="application/pdf" />,
     );
 
+    expect(screen.getByRole("status")).toHaveTextContent("Loading report.pdf");
+    expect(await screen.findByText(/does not include the page viewer/)).toBeInTheDocument();
     const viewer = container.querySelector("object");
-    expect(viewer).not.toBeNull();
     expect(viewer).toHaveAttribute("data", BLOB_URL);
     expect(viewer).toHaveAttribute("type", "application/pdf");
     expect(viewer).toHaveAttribute("title", "report.pdf");
+    consoleError.mockRestore();
   });
 
   it("renders video and audio with native controls", () => {

package/src/files/file-card.test.tsx

@@ -0,0 +1,62 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { FileCard } from "./file-card";
+
+const UPLOADED = new Date("2026-10-06T15:30:00Z");
+
+describe("FileCard", () => {
+  it("names the file with its size, date and uploader", () => {
+    const { container } = render(
+      <FileCard
+        filename="Engagement letter.pdf"
+        size={2_516_582}
+        date={UPLOADED}
+        uploader={{ name: "Dana Ruiz", role: "Client" }}
+      />,
+    );
+
+    expect(screen.getByText("Engagement letter.pdf")).toBeInTheDocument();
+    expect(screen.getByText("2.4 MB")).toBeInTheDocument();
+    expect(container.querySelector("time")).toHaveAttribute("datetime", UPLOADED.toISOString());
+    expect(screen.getByText("Uploaded by Dana Ruiz (Client)")).toBeInTheDocument();
+  });
+
+  it("leaves out what it does not know", () => {
+    const { container } = render(<FileCard filename="notes.txt" date="not a date" />);
+    expect(container.querySelector("time")).toBeNull();
+    expect(screen.queryByText(/Uploaded by/)).toBeNull();
+    expect(screen.queryByRole("button")).toBeNull();
+  });
+
+  it("takes its icon tone from the file kind, with the MIME type outranking the name", () => {
+    const pdf = render(<FileCard filename="brief.pdf" />);
+    expect(pdf.container.querySelector("[aria-hidden='true']")?.className).toContain(
+      "--tone-orange-bg",
+    );
+    pdf.unmount();
+
+    const sheet = render(<FileCard filename="export" mimeType="text/csv" />);
+    expect(sheet.container.querySelector("[aria-hidden='true']")?.className).toContain(
+      "--tone-lime-bg",
+    );
+  });
+
+  it("offers Download and the host's own actions", () => {
+    const onDownload = vi.fn();
+    render(
+      <FileCard
+        filename="book.xlsx"
+        description="Download to open this workbook in a spreadsheet app."
+        onDownload={onDownload}
+        actions={<button type="button">Open</button>}
+      />,
+    );
+
+    expect(
+      screen.getByText("Download to open this workbook in a spreadsheet app."),
+    ).toBeInTheDocument();
+    fireEvent.click(screen.getByRole("button", { name: "Download" }));
+    expect(onDownload).toHaveBeenCalledTimes(1);
+    expect(screen.getByRole("button", { name: "Open" })).toBeInTheDocument();
+  });
+});

package/src/files/file-card.tsx

@@ -0,0 +1,210 @@
+/**
+ * FileCard — one file, described: its kind, name, size, date and uploader,
+ * with Download and any actions the host adds. FilePreview shows it for a file
+ * it cannot render inline; a host can show it anywhere a file stands on its own.
+ */
+
+import * as React from "react";
+import {
+  Download,
+  File,
+  FileAudio,
+  FileCode,
+  FileImage,
+  FileJson,
+  FileSpreadsheet,
+  FileText,
+  FileVideo,
+  type LucideIcon,
+} from "lucide-react";
+import { cn } from "../lib/utils";
+import { Button } from "../primitives/button";
+import { IconTile, type IconTileProps } from "../primitives/icon-tile";
+import type { CategoryTone } from "../primitives/tone";
+import { formatBytes } from "../utils/format";
+import { getFormatLabel, resolveFilePreviewKind, type FilePreviewKind } from "./file-format";
+
+/** Who added a file, as a reader of the list should see them. */
+export interface FileUploader {
+  name: string;
+  /** Their relationship to the work, e.g. "Client" or "Attorney". */
+  role?: string;
+}
+
+/** What FileCard and FileList show about one file. */
+export interface FileDetails {
+  filename: string;
+  /** Wins over the extension when choosing the kind, as in FilePreview. */
+  mimeType?: string;
+  /** Size in bytes. */
+  size?: number;
+  /** When the file was added or last changed. */
+  date?: Date | string | number;
+  uploader?: FileUploader;
+}
+
+// File kinds are categories, so each takes a categorical tone and never a
+// status colour: a PDF is not an error. See "Color Roles" in the brand guide.
+const KIND_ICON: Record<FilePreviewKind, { icon: LucideIcon; tone: CategoryTone }> = {
+  pdf: { icon: FileText, tone: "orange" },
+  image: { icon: FileImage, tone: "pink" },
+  video: { icon: FileVideo, tone: "violet" },
+  audio: { icon: FileAudio, tone: "cyan" },
+  csv: { icon: FileSpreadsheet, tone: "lime" },
+  spreadsheet: { icon: FileSpreadsheet, tone: "lime" },
+  code: { icon: FileCode, tone: "blue" },
+  json: { icon: FileJson, tone: "blue" },
+  yaml: { icon: FileCode, tone: "blue" },
+  markdown: { icon: FileText, tone: "teal" },
+  text: { icon: FileText, tone: "teal" },
+  binary: { icon: File, tone: "brown" },
+};
+
+/** The kind's icon on its category tone. Decorative: the filename names the file. */
+export function FileKindTile({
+  filename,
+  mimeType,
+  size = "md",
+  className,
+}: {
+  filename: string;
+  mimeType?: string;
+  size?: IconTileProps["size"];
+  className?: string;
+}) {
+  const { icon: Icon, tone } = KIND_ICON[resolveFilePreviewKind(filename, mimeType)];
+  return <IconTile tone={tone} size={size} icon={<Icon />} className={className} />;
+}
+
+function toDate(value: FileDetails["date"]): Date | undefined {
+  if (value === undefined) return undefined;
+  const date = value instanceof Date ? value : new Date(value);
+  return Number.isNaN(date.getTime()) ? undefined : date;
+}
+
+const DATE_FORMAT = new Intl.DateTimeFormat(undefined, { dateStyle: "medium" });
+
+/**
+ * A dot between facts for the eye, a comma for a screen reader, which would
+ * otherwise read the facts as one run-on word or announce "middle dot".
+ */
+export function FactSeparator() {
+  return (
+    <>
+      <span aria-hidden="true"> · </span>
+      <span className="sr-only">, </span>
+    </>
+  );
+}
+
+/**
+ * The kind, size and date as one muted line, each part only when known.
+ * The date follows the reader's locale, which a server render may not share,
+ * so the element tolerates a hydration difference.
+ */
+export function FileFacts({
+  filename,
+  mimeType,
+  size,
+  date,
+  showKind = false,
+  className,
+}: Pick<FileDetails, "filename" | "mimeType" | "size" | "date"> & {
+  showKind?: boolean;
+  className?: string;
+}) {
+  const parsed = toDate(date);
+  const parts: React.ReactNode[] = [];
+  if (showKind) parts.push(getFormatLabel(resolveFilePreviewKind(filename, mimeType)));
+  if (size !== undefined) parts.push(formatBytes(size));
+  if (parsed) {
+    parts.push(
+      <time key="date" dateTime={parsed.toISOString()} suppressHydrationWarning>
+        {DATE_FORMAT.format(parsed)}
+      </time>,
+    );
+  }
+  if (parts.length === 0) return null;
+  return (
+    <span className={cn("text-xs text-muted-foreground", className)}>
+      {parts.map((part, index) => (
+        <React.Fragment key={index}>
+          {index > 0 && <FactSeparator />}
+          {part}
+        </React.Fragment>
+      ))}
+    </span>
+  );
+}
+
+/** "Dana Ruiz (Client)", or the name alone. */
+export function uploaderLabel(uploader: FileUploader): string {
+  return uploader.role ? `${uploader.name} (${uploader.role})` : uploader.name;
+}
+
+export interface FileCardProps
+  extends FileDetails,
+    Omit<React.HTMLAttributes<HTMLDivElement>, "children"> {
+  /** One sentence under the details, such as why there is no preview. */
+  description?: React.ReactNode;
+  /** Adds a Download button. */
+  onDownload?: () => void;
+  /** Further buttons after Download, such as Open or Delete. */
+  actions?: React.ReactNode;
+}
+
+export const FileCard = React.forwardRef<HTMLDivElement, FileCardProps>(
+  (
+    {
+      filename,
+      mimeType,
+      size,
+      date,
+      uploader,
+      description,
+      onDownload,
+      actions,
+      className,
+      ...props
+    },
+    ref,
+  ) => (
+    <div
+      ref={ref}
+      className={cn(
+        "flex min-w-0 flex-col items-center justify-center rounded-[var(--radius-md)] border border-border bg-card px-6 py-12 text-center",
+        className,
+      )}
+      {...props}
+    >
+      <FileKindTile filename={filename} mimeType={mimeType} size="lg" />
+      <p
+        className="mt-3 line-clamp-2 max-w-full text-sm font-medium text-foreground [overflow-wrap:anywhere]"
+        title={filename}
+      >
+        {filename}
+      </p>
+      <FileFacts filename={filename} size={size} date={date} className="mt-1" />
+      {uploader && (
+        <p className="mt-0.5 max-w-full truncate text-xs text-muted-foreground">
+          Uploaded by {uploaderLabel(uploader)}
+        </p>
+      )}
+      {description && (
+        <div className="mt-3 max-w-md text-sm text-muted-foreground">{description}</div>
+      )}
+      {(onDownload || actions) && (
+        <div className="mt-5 flex flex-wrap items-center justify-center gap-2">
+          {onDownload && (
+            <Button type="button" variant="outline" size="sm" onClick={onDownload}>
+              <Download />
+              Download
+            </Button>
+          )}
+          {actions}
+        </div>
+      )}
+    </div>
+  ),
+);
+FileCard.displayName = "FileCard";