---
name: adom-pdf-viewer
description: In-page PDF viewer for Adom Hydrogen webview tabs — PDF.js-rendered with thumbnail strip, deep-link to specific pages, citation-aware highlighting, "reveal in VS Code" and download affordances. Solves the Hydrogen-no-native-PDF problem so any tool can deep-link a datasheet page in-app instead of triggering a download to Acrobat. Trigger words — pdf viewer, in-page pdf, datasheet viewer, pdf.js, deep link pdf page, datasheet page jump, pdf thumbnails, cite pdf page, pdf in webview, pdf deep link, open datasheet at page, pdf viewer adom, pdfviewer.
---

# adom-pdf-viewer — in-page PDF viewer for Hydrogen webview tabs

The Hydrogen webview ships without a native PDF renderer. Loading a
.pdf URL directly (or via `<iframe>`/`<embed>`) shows a "blocked"
icon. Browsers configured to "always download PDFs" also lose the
`#page=N` fragment when the file jumps to Acrobat / Preview.

`adom-pdf-viewer` wraps the PDF in a **PDF.js-canvas** viewer with:

- thumbnail strip on the left (lazy-rendered, IntersectionObserver)
- prev/next + page-number input + ← / → keyboard shortcuts
- **citation-aware highlighting** — pass a JSON manifest of cited
  pages and the viewer highlights each thumb in brand-yellow with
  a snippet label inline ("footprint pad geometry", "GLB / package
  model", etc.). A summary chip strip at the top of the canvas
  lets the user click any cited page directly.
- **download** + **reveal in VS Code Explorer** affordances (the
  reveal button POSTs to `/api/reveal` which shells `adom-vscode
  reveal <path>`, with the workspace-boundary precheck per
  `gallia/skills/human-ui-patterns` §5b)

Brand-compliant: monochrome SVG icons, Satoshi/Familjen-Grotesk
fonts, dark steel-gradient page background, no color emoji.

## Run as a service

```bash
adom-pdf-viewer --port 8981
```

Then open the viewer in any Hydrogen webview tab:

```text
https://<container-proxy>/proxy/8981/v?src=<URL>&page=<N>
```

## Query parameters

| Param | Type | Description |
|---|---|---|
| `src` | URL (required) | PDF URL — same-origin or absolute. The viewer fetches it client-side via PDF.js. |
| `page` | int (default 1) | Initial page to render. |
| `cites` | JSON (optional) | Array `[{ page: int, label: string, section?: string }]` of cited pages to highlight. The same `page` can appear multiple times — labels are deduped per page. |
| `title` | string (optional) | Topbar title (e.g. "RP2040 datasheet"). |
| `reveal` | absolute path (optional) | If present, the topbar shows a `📁 reveal` button that opens VS Code's Explorer at that path. Subject to the workspace-boundary precheck. |

## Example

```text
.../proxy/8981/v?src=https://example.com/RP2040.pdf
   &page=608
   &title=RP2040+datasheet
   &reveal=/home/adom/project/.../RP2040.pdf
   &cites=[{"page":608,"label":"footprint pad geometry"},
           {"page":11,"label":"symbol pinout definition"}]
```

## How tools should cite

When a tool emits a provenance / citation string referencing a
datasheet page, it should ALSO surface a clickable chip that opens
the citation in `adom-pdf-viewer`. The viewer's thumbnail strip
makes the cited page obvious and the user can verify the AI's
claim in one click.

The `aci-provenance` MVP shows the canonical wiring — see its
`linkifyPages` helper which renders every "page N" / "pages N-M"
mention as a chip group with three click targets:

1. **text link** → `/v?src=…&page=N&cites=…` (in-page viewer)
2. **↗ icon**     → native browser tab (uses the user's PDF handler)
3. **⬇ icon**     → forced download

## API

`GET /v?src=…` — render the viewer page.
`GET /health`   — `{ ok: true, app: "adom-pdf-viewer" }`.
`POST /api/reveal` — body `{ path: "/abs/path" }` → shells
`adom-vscode reveal`. Workspace-boundary-precheck per the
human-ui-patterns skill.

## Why it's separate from the consumer apps

Every Adom tool that wants to deep-link a datasheet page hits the
same problem (no native PDF in webview, page jump lost on
download). Centralizing the viewer means:

- one PDF.js dependency, not N
- one citation manifest schema across every consumer
- one place to fix browser-blocked-PDF issues
- one consistent UX for all datasheet viewing

Consumers today: `aci-provenance`, `adom-chipfit`,
`aci component`'s live-build dashboard. Future: `aci library`,
`datasheet-parser` (each cropped figure deep-links back to the
page in the wrapper), `aci review`.