app

adom-pdf-viewer

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 Versions Dependencies Discussions Activity
app / adom-pdf-viewer
!

Not installable via adompkg

This app has no published release. adompkg install kyle/adom-pdf-viewer will not work until a maintainer publishes a tarball with install.sh and uninstall.sh.

See the publishing docs for the package.json schema and tarball layout required to ship this app.

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.