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/revealwhich shellsadom-vscode reveal <path>, with the workspace-boundary precheck pergallia/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
adom-pdf-viewer --port 8981
Then open the viewer in any Hydrogen webview tab:
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
.../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:
- text link →
/v?src=…&page=N&cites=…(in-page viewer) - ↗ icon → native browser tab (uses the user's PDF handler)
- ⬇ 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.