app

adom-pdf-viewer

Public Unreviewed

by Kyle Bergstedt

In-page PDF viewer for Hydrogen webview tabs — PDF.js + thumbnail strip + citation-aware highlighting + reveal-in-VS-Code.

Overview Files Skills Packages Releases Dependencies Issues Breadcrumbs Pull Requests Activity
Propose a change
Name Last commit message Last updated
install.sh Add adompkg installer files 1mo ago
package.json Add adompkg installer files 1mo ago
page.json Remove internal identifiers from page.json 11d ago
README.md Initial commit: app/adom-pdf-viewer 1mo ago
SKILL.md Add adompkg installer files 1mo ago
uninstall.sh Add adompkg installer files 1mo ago

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

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:

  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.