@tangle-network/ui 11.25.0 → 11.26.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @tangle-network/ui
 
+## 11.26.0
+
+### Minor Changes
+
+- 950b7ca: `./files` gains document primitives. `PdfViewer` renders a PDF's pages to canvas with pdf.js, so a file reads the same on Android Chrome and iOS Safari as on a desktop: a scrolling column of pages with page navigation, zoom, fit-to-width and Download, one toolbar row at 360px, and only the pages near the screen holding a canvas. `FilePreview` and `FileArtifactPane` now show PDFs through it. `pdfjs-dist` (6.x) is a new optional peer, reached only through a caught dynamic import; without it, or when a file will not open, the viewer says why and falls back to the browser's `<object>` viewer and then a download card. `configurePdfViewer({ workerSrc, assetsUrl })` sets the page-wide worker and the decoder assets that scanned pages need; with neither, pdf.js runs on the main thread and no CDN is contacted. `FileCard` describes one file with its kind, size, date, uploader and actions, and replaces FilePreview's private download card. `FileList` is a flat document list whose rows open, download or delete a file and hand the host's own record back.
+
 ## 11.25.0
 
 ### Minor Changes

package/README.md

@@ -131,6 +131,28 @@ A TypeScript consumer resolves these entries through the emitted declarations, a
 
 Because the peers now resolve at first render rather than at build time, a missing one surfaces as a thrown error while React renders. Wrap the editors in an error boundary, so the install list reaches a surface you control instead of unmounting the tree.
 
+### PDF pages
+
+`pdfjs-dist` backs `PdfViewer` in `./files`, which `FilePreview` and `FileArtifactPane` use for PDFs. It follows the editor's rule: the entry reaches it only through a caught dynamic `import()`, so a consumer without it builds under Vite and esbuild. Without it, `PdfViewer` says so and shows the browser's own viewer through `<object>`, which Android Chrome does not have, so a reader there gets a download card instead of pages.
+
+```sh
+pnpm add pdfjs-dist
+```
+
+`PdfViewer` imports pdf.js's legacy build, which carries the polyfills that phone browsers a year or two old need. Two settings are page-wide, because pdf.js's own worker setting is. Set them once, before the first viewer renders:
+
+```ts
+import { configurePdfViewer } from "@tangle-network/ui/files";
+import workerSrc from "pdfjs-dist/legacy/build/pdf.worker.min.mjs?url"; // Vite
+
+configurePdfViewer({ workerSrc, assetsUrl: "/pdfjs/" });
+```
+
+- `workerSrc` moves parsing into a worker. Without it, the viewer runs pdf.js's worker code on the main thread, which needs no bundler setup and no CDN, at the cost of scrolling while a large file parses.
+- `assetsUrl` is where the app serves the installed pdfjs-dist's `wasm/`, `cmaps/`, `standard_fonts/` and `iccs/` directories. pdf.js 6 decodes JBIG2, CCITT fax and JPEG 2000 images with the wasm modules, and black-and-white scans use the first two, so without it a scanned page renders blank. The viewer warns once in the console when it is missing. Copy the directories at build time; they must come from the same pdfjs-dist version as the worker.
+
+An http(s) `src` on another origin needs CORS, as any `fetch` does. When it fails, the viewer falls back to `<object>`, which does not.
+
 `nanostores` and `@nanostores/react` back `./stores`, and `react-router` backs `./nav`.
 Those entries create values at module scope, so consumers must install their peers before importing them.
 The package root also re-exports `./stores`, so a root import requires both nanostores peers.

package/dist/editor/editor-peers.js

@@ -1,3 +1,4 @@
+import { isMissingPeerError, rethrow } from "../lib/optional-peer.js";
 //#region src/editor/editor-peers.ts
 const DOCUMENT_PEERS_MISSING = "@tangle-network/ui/editor needs its optional editor peers. Install @tiptap/react and @tiptap/starter-kit.";
 const PROVIDER_PEERS_MISSING = "@tangle-network/ui/editor needs its optional collaboration transport peers. Install @hocuspocus/provider and yjs.";
@@ -20,27 +21,6 @@ var MissingEditorPeersError = class extends Error {
 function isMissingEditorPeersError(error) {
 	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.
-*/
-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;
-}
 /**
 * 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/dist/files/file-card.d.ts

@@ -0,0 +1,30 @@
+import "../primitives/icon-tile.js";
+import * as React from "react";
+//#region src/files/file-card.d.ts
+/** 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;
+}
+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 declare const FileCard: React.ForwardRefExoticComponent<FileCardProps & React.RefAttributes<HTMLDivElement>>;
+//#endregion

package/dist/files/file-card.js

@@ -0,0 +1,162 @@
+import { cn } from "../lib/utils.js";
+import { Button } from "../primitives/button.js";
+import { IconTile } from "../primitives/icon-tile.js";
+import { formatBytes } from "../utils/format.js";
+import { getFormatLabel, resolveFilePreviewKind } from "./file-format.js";
+import * as React from "react";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+import { Download, File, FileAudio, FileCode, FileImage, FileJson, FileSpreadsheet, FileText, FileVideo } from "lucide-react";
+//#region src/files/file-card.tsx
+/**
+* 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.
+*/
+const KIND_ICON = {
+	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. */
+function FileKindTile({ filename, mimeType, size = "md", className }) {
+	const { icon: Icon, tone } = KIND_ICON[resolveFilePreviewKind(filename, mimeType)];
+	return /* @__PURE__ */ jsx(IconTile, {
+		tone,
+		size,
+		icon: /* @__PURE__ */ jsx(Icon, {}),
+		className
+	});
+}
+function toDate(value) {
+	if (value === void 0) return void 0;
+	const date = value instanceof Date ? value : new Date(value);
+	return Number.isNaN(date.getTime()) ? void 0 : date;
+}
+const DATE_FORMAT = new Intl.DateTimeFormat(void 0, { 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".
+*/
+function FactSeparator() {
+	return /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx("span", {
+		"aria-hidden": "true",
+		children: " · "
+	}), /* @__PURE__ */ jsx("span", {
+		className: "sr-only",
+		children: ", "
+	})] });
+}
+/**
+* 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.
+*/
+function FileFacts({ filename, mimeType, size, date, showKind = false, className }) {
+	const parsed = toDate(date);
+	const parts = [];
+	if (showKind) parts.push(getFormatLabel(resolveFilePreviewKind(filename, mimeType)));
+	if (size !== void 0) parts.push(formatBytes(size));
+	if (parsed) parts.push(/* @__PURE__ */ jsx("time", {
+		dateTime: parsed.toISOString(),
+		suppressHydrationWarning: true,
+		children: DATE_FORMAT.format(parsed)
+	}, "date"));
+	if (parts.length === 0) return null;
+	return /* @__PURE__ */ jsx("span", {
+		className: cn("text-xs text-muted-foreground", className),
+		children: parts.map((part, index) => /* @__PURE__ */ jsxs(React.Fragment, { children: [index > 0 && /* @__PURE__ */ jsx(FactSeparator, {}), part] }, index))
+	});
+}
+/** "Dana Ruiz (Client)", or the name alone. */
+function uploaderLabel(uploader) {
+	return uploader.role ? `${uploader.name} (${uploader.role})` : uploader.name;
+}
+const FileCard = React.forwardRef(({ filename, mimeType, size, date, uploader, description, onDownload, actions, className, ...props }, ref) => /* @__PURE__ */ jsxs("div", {
+	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,
+	children: [
+		/* @__PURE__ */ jsx(FileKindTile, {
+			filename,
+			mimeType,
+			size: "lg"
+		}),
+		/* @__PURE__ */ jsx("p", {
+			className: "mt-3 line-clamp-2 max-w-full text-sm font-medium text-foreground [overflow-wrap:anywhere]",
+			title: filename,
+			children: filename
+		}),
+		/* @__PURE__ */ jsx(FileFacts, {
+			filename,
+			size,
+			date,
+			className: "mt-1"
+		}),
+		uploader && /* @__PURE__ */ jsxs("p", {
+			className: "mt-0.5 max-w-full truncate text-xs text-muted-foreground",
+			children: ["Uploaded by ", uploaderLabel(uploader)]
+		}),
+		description && /* @__PURE__ */ jsx("div", {
+			className: "mt-3 max-w-md text-sm text-muted-foreground",
+			children: description
+		}),
+		(onDownload || actions) && /* @__PURE__ */ jsxs("div", {
+			className: "mt-5 flex flex-wrap items-center justify-center gap-2",
+			children: [onDownload && /* @__PURE__ */ jsxs(Button, {
+				type: "button",
+				variant: "outline",
+				size: "sm",
+				onClick: onDownload,
+				children: [/* @__PURE__ */ jsx(Download, {}), "Download"]
+			}), actions]
+		})
+	]
+}));
+FileCard.displayName = "FileCard";
+//#endregion
+export { FactSeparator, FileCard, FileFacts, FileKindTile, uploaderLabel };

package/dist/files/file-list.d.ts

@@ -0,0 +1,25 @@
+import { FileDetails } from "./file-card.js";
+import * as React from "react";
+//#region src/files/file-list.d.ts
+export interface FileListItem extends FileDetails {
+  /** Stable key, and what `activeId` matches. */
+  id: string;
+}
+export interface FileListProps<T extends FileListItem = FileListItem> extends Omit<React.HTMLAttributes<HTMLElement>, "children"> {
+  files: readonly T[];
+  /** Opens a file, usually in a preview. Makes each row a button. */
+  onOpen?: (file: T) => void;
+  /** Adds a Download button to each row. */
+  onDownload?: (file: T) => void;
+  /**
+   * Adds a Delete button to each row. It calls this at once, so a host that
+   * wants a confirmation asks for it here.
+   */
+  onDelete?: (file: T) => void;
+  /** The open file. Its row is marked as the current one. */
+  activeId?: string;
+  /** Shown in place of the list when `files` is empty. */
+  empty?: React.ReactNode;
+}
+export declare function FileList<T extends FileListItem>({ files, onOpen, onDownload, onDelete, activeId, empty, className, ...props }: FileListProps<T>): React.JSX.Element;
+//#endregion

package/dist/files/file-list.js

@@ -0,0 +1,88 @@
+import { focusRingInset } from "../lib/focus.js";
+import { cn } from "../lib/utils.js";
+import { Button } from "../primitives/button.js";
+import { FactSeparator, FileFacts, FileKindTile, uploaderLabel } from "./file-card.js";
+import "react";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+import { Download, Trash2 } from "lucide-react";
+//#region src/files/file-list.tsx
+function FileList({ files, onOpen, onDownload, onDelete, activeId, empty = "No files yet.", className, ...props }) {
+	if (files.length === 0) return /* @__PURE__ */ jsx("div", {
+		className: cn("rounded-[var(--radius-md)] border border-border bg-card px-4 py-10 text-center text-sm text-muted-foreground", className),
+		...props,
+		children: empty
+	});
+	return /* @__PURE__ */ jsx("ul", {
+		className: cn("divide-y divide-border overflow-hidden rounded-[var(--radius-md)] border border-border bg-card", className),
+		...props,
+		children: files.map((file) => {
+			const active = file.id === activeId;
+			const body = /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx(FileKindTile, {
+				filename: file.filename,
+				mimeType: file.mimeType
+			}), /* @__PURE__ */ jsxs("span", {
+				className: "grid min-w-0 flex-1",
+				children: [
+					/* @__PURE__ */ jsx("span", {
+						className: "line-clamp-2 text-sm font-medium text-foreground [overflow-wrap:anywhere] sm:line-clamp-1",
+						children: file.filename
+					}),
+					/* @__PURE__ */ jsxs("span", {
+						className: "truncate text-xs text-muted-foreground",
+						children: [/* @__PURE__ */ jsx(FileFacts, {
+							filename: file.filename,
+							mimeType: file.mimeType,
+							size: file.size,
+							date: file.date,
+							showKind: true
+						}), file.uploader && /* @__PURE__ */ jsxs("span", {
+							className: "hidden sm:inline",
+							children: [/* @__PURE__ */ jsx(FactSeparator, {}), uploaderLabel(file.uploader)]
+						})]
+					}),
+					file.uploader && /* @__PURE__ */ jsx("span", {
+						className: "truncate text-xs text-muted-foreground sm:hidden",
+						children: uploaderLabel(file.uploader)
+					})
+				]
+			})] });
+			return /* @__PURE__ */ jsxs("li", {
+				className: cn("flex items-center gap-1 pr-2", active ? "bg-primary/10" : onOpen && "hover:bg-[var(--bg-hover)]"),
+				children: [
+					onOpen ? /* @__PURE__ */ jsx("button", {
+						type: "button",
+						onClick: () => onOpen(file),
+						"aria-current": active ? "true" : void 0,
+						className: cn("flex min-w-0 flex-1 items-center gap-3 py-2.5 pl-3 text-left", focusRingInset),
+						children: body
+					}) : /* @__PURE__ */ jsx("div", {
+						"aria-current": active ? "true" : void 0,
+						className: "flex min-w-0 flex-1 items-center gap-3 py-2.5 pl-3",
+						children: body
+					}),
+					onDownload && /* @__PURE__ */ jsx(Button, {
+						type: "button",
+						variant: "ghost",
+						size: "icon",
+						"aria-label": `Download ${file.filename}`,
+						title: "Download",
+						onClick: () => onDownload(file),
+						children: /* @__PURE__ */ jsx(Download, {})
+					}),
+					onDelete && /* @__PURE__ */ jsx(Button, {
+						type: "button",
+						variant: "ghost",
+						size: "icon",
+						"aria-label": `Delete ${file.filename}`,
+						title: "Delete",
+						className: "hover:text-[var(--surface-danger-text)]",
+						onClick: () => onDelete(file),
+						children: /* @__PURE__ */ jsx(Trash2, {})
+					})
+				]
+			}, file.id);
+		})
+	});
+}
+//#endregion
+export { FileList };

package/dist/files/file-preview.js

@@ -1,19 +1,19 @@
 import { focusRingInset } from "../lib/focus.js";
 import { cn } from "../lib/utils.js";
-import { Button } from "../primitives/button.js";
 import { CodeBlock, CopyButton } from "../markdown/code-block.js";
-import { formatBytes } from "../utils/format.js";
 import { fileExtension, getCodeLanguage, getFormatLabel, resolveFilePreviewKind } from "./file-format.js";
 import { Markdown } from "../markdown/markdown.js";
+import { FileCard } from "./file-card.js";
+import { PdfViewer } from "./pdf-viewer.js";
 import { useState } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
-import { Download, FileSpreadsheet, FileText, Music, X } from "lucide-react";
+import { Download, Music, X } from "lucide-react";
 //#region src/files/file-preview.tsx
 /**
 * FilePreview — universal file renderer.
 *
 * Renders any file type:
-* - PDF: embedded viewer at full pane height
+* - PDF: PdfViewer's rendered pages at full pane height
 * - Images: fit to the pane on a checker ground; click toggles natural size
 * - Video / audio: native players
 * - CSV: sticky-header table, capped at CSV_PREVIEW_ROW_LIMIT rows
@@ -146,21 +146,6 @@ function ImagePreview({ src, filename }) {
 		})
 	});
 }
-function PdfPreview({ blobUrl, filename, size, onDownload }) {
-	return /* @__PURE__ */ jsx("object", {
-		data: blobUrl,
-		type: "application/pdf",
-		title: filename,
-		className: "min-h-[24rem] w-full flex-1 rounded-[var(--radius-md)]",
-		children: /* @__PURE__ */ jsx(DownloadCard, {
-			filename,
-			size,
-			sentence: "This browser does not show PDFs inline.",
-			onDownload,
-			className: "h-full"
-		})
-	});
-}
 function VideoPreview({ src, filename }) {
 	return /* @__PURE__ */ jsx("div", {
 		className: "flex min-h-[12rem] flex-1 items-center justify-center overflow-hidden rounded-[var(--radius-md)] border border-border bg-background",
@@ -207,55 +192,23 @@ function MarkdownPreview({ content, urlTransform }) {
 		})
 	});
 }
-/**
-* One muted sentence plus the filename, its size when known, and a Download
-* button when the host wires `onDownload`. Serves spreadsheets, binaries, and
-* every kind whose source (blob or text) is missing.
-*/
-function DownloadCard({ filename, size, sentence, icon: Icon = FileText, onDownload, className }) {
-	return /* @__PURE__ */ jsxs("div", {
-		className: cn("flex flex-col items-center justify-center rounded-[var(--radius-md)] border border-dashed border-border bg-background px-6 py-16 text-center", className),
-		children: [
-			/* @__PURE__ */ jsx(Icon, { className: "mb-3 h-12 w-12 text-muted-foreground opacity-40" }),
-			/* @__PURE__ */ jsx("p", {
-				className: "max-w-full truncate text-sm font-medium text-foreground",
-				children: filename
-			}),
-			size !== void 0 && /* @__PURE__ */ jsx("p", {
-				className: "mt-1 text-xs text-muted-foreground",
-				children: formatBytes(size)
-			}),
-			/* @__PURE__ */ jsx("p", {
-				className: "mt-3 max-w-md text-sm text-muted-foreground",
-				children: sentence
-			}),
-			onDownload && /* @__PURE__ */ jsxs(Button, {
-				type: "button",
-				variant: "outline",
-				size: "sm",
-				className: "mt-5",
-				onClick: onDownload,
-				children: [/* @__PURE__ */ jsx(Download, {}), "Download"]
-			})
-		]
-	});
-}
-function PreviewBody({ kind, filename, content, blobUrl, size, urlTransform, onDownload }) {
+function PreviewBody({ kind, filename, mimeType, content, blobUrl, size, urlTransform, onDownload }) {
 	const hasText = typeof content === "string";
-	const card = (sentence, icon) => /* @__PURE__ */ jsx(DownloadCard, {
+	const card = (sentence) => /* @__PURE__ */ jsx(FileCard, {
 		filename,
+		mimeType,
 		size,
-		sentence,
-		icon,
+		description: sentence,
 		onDownload
 	});
 	switch (kind) {
 		case "pdf":
-			if (blobUrl) return /* @__PURE__ */ jsx(PdfPreview, {
-				blobUrl,
+			if (blobUrl) return /* @__PURE__ */ jsx(PdfViewer, {
+				src: blobUrl,
 				filename,
 				size,
-				onDownload
+				onDownload,
+				className: "min-h-[24rem] flex-1"
 			});
 			return card(NEEDS_DOWNLOAD_LINK);
 		case "image":
@@ -280,10 +233,10 @@ function PreviewBody({ kind, filename, content, blobUrl, size, urlTransform, onD
 				src: blobUrl,
 				filename
 			});
-			return card(NEEDS_DOWNLOAD_LINK, Music);
+			return card(NEEDS_DOWNLOAD_LINK);
 		case "csv":
 			if (hasText) return /* @__PURE__ */ jsx(CsvPreview, { content });
-			return card(NO_INLINE_CONTENT, FileSpreadsheet);
+			return card(NO_INLINE_CONTENT);
 		case "code":
 		case "json":
 		case "yaml":
@@ -302,7 +255,7 @@ function PreviewBody({ kind, filename, content, blobUrl, size, urlTransform, onD
 		case "text":
 			if (hasText) return /* @__PURE__ */ jsx(TextPreview, { content });
 			return card(NO_INLINE_CONTENT);
-		case "spreadsheet": return card("Download to open this workbook in a spreadsheet app.", FileSpreadsheet);
+		case "spreadsheet": return card("Download to open this workbook in a spreadsheet app.");
 		case "binary":
 			if (hasText) return /* @__PURE__ */ jsx(TextPreview, { content });
 			return card(blobUrl ? NO_INLINE_PREVIEW : NEEDS_DOWNLOAD_LINK);
@@ -346,6 +299,7 @@ function FilePreview({ filename, content, blobUrl, mimeType, size, urlTransform,
 			children: /* @__PURE__ */ jsx(PreviewBody, {
 				kind,
 				filename,
+				mimeType,
 				content,
 				blobUrl,
 				size,

package/dist/files/pdf-loader.d.ts

@@ -0,0 +1,22 @@
+import "pdfjs-dist";
+//#region src/files/pdf-loader.d.ts
+export interface PdfViewerConfig {
+  /**
+   * URL of `pdfjs-dist/legacy/build/pdf.worker.min.mjs` from the installed
+   * pdfjs-dist, served by the app. Moves PDF parsing off the main thread.
+   */
+  workerSrc?: string;
+  /**
+   * Base URL, ending in `/`, under which the app serves the `wasm/`, `cmaps/`,
+   * `standard_fonts/` and `iccs/` directories of the installed pdfjs-dist.
+   * Needed for scanned pages, CJK text and non-embedded fonts.
+   */
+  assetsUrl?: string;
+}
+/**
+ * Sets the page-wide pdf.js worker and asset locations. Call it once, before
+ * the first `PdfViewer` renders; a worker set afterwards applies only when no
+ * document has loaded the main-thread worker yet.
+ */
+export declare function configurePdfViewer(next: PdfViewerConfig): void;
+//#endregion

package/dist/files/pdf-loader.js

@@ -0,0 +1,82 @@
+import { isMissingPeerError, rethrow } from "../lib/optional-peer.js";
+//#region src/files/pdf-loader.ts
+let config = {};
+/**
+* Sets the page-wide pdf.js worker and asset locations. Call it once, before
+* the first `PdfViewer` renders; a worker set afterwards applies only when no
+* document has loaded the main-thread worker yet.
+*/
+function configurePdfViewer(next) {
+	config = { ...next };
+}
+/**
+* The optional peer behind `PdfViewer`. `scripts/validate-dist.mjs` reads this
+* list and requires every import of it to be dynamic and caught.
+*/
+const DEFERRED_PEERS = ["pdfjs-dist"];
+/** pdfjs-dist is absent, or resolved to a stub with none of its API. */
+var MissingPdfjsError = class extends Error {
+	constructor(options) {
+		super("PdfViewer needs the optional peer pdfjs-dist. Install pdfjs-dist to render PDF pages.", options);
+		this.name = "MissingPdfjsError";
+	}
+};
+function isMissingPdfjsError(error) {
+	return error instanceof Error && error.name === "MissingPdfjsError";
+}
+/**
+* Turns a resolution failure that names pdfjs-dist into `MissingPdfjsError`.
+* Any other rejection, such as a chunk that did not download, passes through.
+*/
+function asMissingPdfjsError(error) {
+	if (!isMissingPeerError(error)) return error;
+	const message = error.message;
+	return DEFERRED_PEERS.some((name) => message.includes(name)) ? new MissingPdfjsError({ cause: error }) : error;
+}
+async function importPdfjs() {
+	let pdfjs;
+	try {
+		pdfjs = await import("pdfjs-dist/legacy/build/pdf.mjs").catch(rethrow);
+	} catch (error) {
+		throw asMissingPdfjsError(error);
+	}
+	if (typeof pdfjs.getDocument !== "function") throw new MissingPdfjsError();
+	return pdfjs;
+}
+let pending = null;
+let warnedAboutAssets = false;
+/**
+* Resolves pdf.js with its worker configured. A missing peer stays missing for
+* the session, so its rejection is kept; any other failure, such as a chunk
+* that did not download, is dropped so the next viewer tries again.
+*/
+function loadPdfjs() {
+	pending ??= importPdfjs().catch((error) => {
+		if (!isMissingPdfjsError(error)) pending = null;
+		throw error;
+	});
+	return pending.then(async (pdfjs) => {
+		const { GlobalWorkerOptions } = pdfjs;
+		if (config.workerSrc) GlobalWorkerOptions.workerSrc = config.workerSrc;
+		else if (!GlobalWorkerOptions.workerSrc && !GlobalWorkerOptions.workerPort) await import("pdfjs-dist/legacy/build/pdf.worker.min.mjs").catch(rethrow);
+		if (!config.assetsUrl && !warnedAboutAssets) {
+			warnedAboutAssets = true;
+			console.warn("PdfViewer: no assetsUrl is configured, so JBIG2, CCITT fax and JPEG 2000 images (most black-and-white scans) will not render. See configurePdfViewer.");
+		}
+		return pdfjs;
+	});
+}
+/** `getDocument` asset options for the configured `assetsUrl`, or none. */
+function pdfAssetParams() {
+	if (!config.assetsUrl) return {};
+	const base = new URL(config.assetsUrl, document.baseURI).href.replace(/\/?$/, "/");
+	return {
+		wasmUrl: `${base}wasm/`,
+		cMapUrl: `${base}cmaps/`,
+		cMapPacked: true,
+		standardFontDataUrl: `${base}standard_fonts/`,
+		iccUrl: `${base}iccs/`
+	};
+}
+//#endregion
+export { MissingPdfjsError, asMissingPdfjsError, configurePdfViewer, isMissingPdfjsError, loadPdfjs, pdfAssetParams };

package/dist/files/pdf-viewer.d.ts

@@ -0,0 +1,32 @@
+//#region src/files/pdf-viewer.d.ts
+/**
+ * PdfViewer — renders a PDF's pages to canvas with pdf.js, so a document reads
+ * the same in every browser, phones included. A continuous column of pages
+ * with page navigation, zoom and fit-to-width, and Download.
+ *
+ * Only pages within a screen of the visible area hold a canvas; the rest keep
+ * their size and release theirs, so a long document stays inside the canvas
+ * memory a phone allows.
+ *
+ * When pdf.js is not installed or cannot open the file, the viewer says so
+ * and falls back to the browser's own viewer through `<object>`, and from
+ * there to a FileCard where the browser has none (Android Chrome).
+ */
+export interface PdfViewerProps {
+  /**
+   * The PDF: an object URL, a data URL, or an http(s) URL. A URL on another
+   * origin must allow this one through CORS; when it does not, the viewer
+   * falls back to the browser's viewer.
+   */
+  src: string;
+  /** Names the document for assistive technology and the fallback card. */
+  filename?: string;
+  /** Size in bytes, shown on the fallback card. */
+  size?: number;
+  /** Adds a Download button to the toolbar and the fallback card. */
+  onDownload?: () => void;
+  /** Give the viewer a height; it scrolls its pages inside it. */
+  className?: string;
+}
+export declare function PdfViewer({ src, filename, size, onDownload, className }: PdfViewerProps): import("react").JSX.Element;
+//#endregion