Install the inline PDF viewer into a built site

Download the pinned pdf.js release (legacy build), verify its SHA-256, copy the parts a site needs into <site>/assets/vendor/pdfjs/, and add the shim that opens ?src= only for the allowlisted URL prefixes or the site’s own origin. Nothing is committed: the viewer exists only in the built site.

Skills it satisfies

A skill states the capability; this Tool is one way to exercise it. Each skill’s declared input and output contract follows, where it has one.

pdf-inline-viewer

Show a published PDF inside a generated page — search, scroll, jump to page, print and download — with the pinned pdf.js viewer the site build installs. Which two Tools do it, the publication-gate rule that decides whether a page may embed a document at all, why the viewer opens only allowlisted hosts, and the three pdf.js behaviours that were measured rather than assumed. Read before putting a PDF on a page, before bumping the pdf.js pin, and when an embedded viewer shows an empty frame.

Source: cat-harness/platform-ui/skills/platform-ui/pdf-inline-viewer.md.

Also satisfied by: pdf-viewer-embed.

The skill declares no I/O contract (schemas/skills/pdf-inline-viewer/{input,output}.schema.json).

Inputs and outputs

Each port names a shared type by IRI, so two Tools for one skill can be checked for interchangeability.

porttyperequireddescriptionconstraint
insiteRepoPathyesThe built site directory, _site in both site workflows.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
inallowUrlyesAn https URL prefix the viewer may open, ending in /. Repeat the flag for more than one. same-origin-only is the explicit way to allow none — an omitted flag is a usage error, because a viewer that refuses every CDN document would otherwise ship green.string · format uri · An absolute http(s) URL
inzipRepoPathA local copy of the release zip, for offline runs and tests. Its hash is checked exactly as a download’s would be.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
outsummaryTextOne line on stdout: version, destination, file count, and the prefixes it will open. Exit 2 on a usage error; a hash mismatch or a release missing a kept path throws, refusing the install.string · A short single-line human string. Not admissible as a command-line argument.

Processes and tasks

No process step names a skill this Tool satisfies.

How it is deployed and reached

  • Command line. From the repository root: bun run cat pdf:viewer. cat pdf:viewer runs bun run cat-harness-tools/scripts/pdf-viewer.ts (declared in cat-harness-tools/package.json).
  • GitHub Actions. 2 workflow line(s) run its command:
workflowline
.github/workflows/docs-site.yml640bun run cat-harness-tools/scripts/pdf-viewer.ts --site ./_site
.github/workflows/feature-staging.yml1267bun run cat-harness-tools/scripts/pdf-viewer.ts --site ./_site

As an API: its operation in the OpenAPI document and the MCP tool list of its layer.

installnone
runtimebun, unzip
networkyes

When a host it reaches is refused:

host / errorremedy
github.comnone: pdf.js is fetched from its GitHub release and no copy is vendored; the site builds without the viewer.
when to choose it
whenA site build that publishes pages carrying pdf-viewer-embed fragments. Run it after the site is assembled and before any pass that walks every page.
limitsIt installs one pinned version and nothing else: moving the pin is upstream-version-adoption, with the hash re-measured. It does not decide which PDFs may be shown — the allowlist bounds where the viewer will FETCH from, and a page’s publication gates decide whether a page embeds a document at all.
costOne ~7 MB download per build and ~12 MB (404 files) added to the built site. Not committed, so no clone cost.

What it is made of

Linked data

The Tool is published as its own JSON-LD document at its IRI, https://litlfred.github.io/folio-assistant/cat-harness/tools/pdf-viewer-install.jsonld, partOf its layer’s document. The node below is the definition this page was drawn from, and is embedded in the page as application/ld+json.

{
  "@context": "https://litlfred.github.io/folio-assistant/cat-harness/cat-harness.context.jsonld",
  "@id": "https://litlfred.github.io/folio-assistant/cat-harness/tools/pdf-viewer-install.jsonld",
  "@type": "https://litlfred.github.io/cat-harness/v0/ns/Tool",
  "partOf": "https://litlfred.github.io/folio-assistant/cat-harness/cat-harness.jsonld",
  "name": "pdf-viewer-install",
  "title": "Install the inline PDF viewer into a built site",
  "description": "Download the pinned pdf.js release (legacy build), verify its SHA-256, copy the parts a site needs into `<site>/assets/vendor/pdfjs/`, and add the shim that opens `?src=` only for the allowlisted URL prefixes or the site's own origin. Nothing is committed: the viewer exists only in the built site.",
  "install": {
    "none": true
  },
  "invoke": {
    "shell": "bun run cat pdf:viewer"
  },
  "io": {
    "inputs": [
      {
        "name": "site",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "The built site directory, `_site` in both site workflows.",
        "required": true,
        "arg": {
          "flag": "--site"
        }
      },
      {
        "name": "allow",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Url",
        "description": "An https URL prefix the viewer may open, ending in `/`. Repeat the flag for more than one. `same-origin-only` is the explicit way to allow none — an omitted flag is a usage error, because a viewer that refuses every CDN document would otherwise ship green.",
        "required": true,
        "arg": {
          "flag": "--allow"
        }
      },
      {
        "name": "zip",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "A local copy of the release zip, for offline runs and tests. Its hash is checked exactly as a download's would be.",
        "required": false,
        "arg": {
          "flag": "--zip"
        }
      }
    ],
    "outputs": [
      {
        "name": "summary",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Text",
        "description": "One line on stdout: version, destination, file count, and the prefixes it will open. Exit 2 on a usage error; a hash mismatch or a release missing a kept path throws, refusing the install."
      }
    ]
  },
  "satisfies": [
    "pdf-inline-viewer"
  ],
  "requirements": {
    "runtime": [
      "bun",
      "unzip"
    ],
    "network": true
  },
  "remedies": [
    {
      "host": "github.com",
      "none": "pdf.js is fetched from its GitHub release and no copy is vendored; the site builds without the viewer."
    }
  ],
  "selection": {
    "when": "A site build that publishes pages carrying `pdf-viewer-embed` fragments. Run it after the site is assembled and before any pass that walks every page.",
    "limits": "It installs one pinned version and nothing else: moving the pin is `upstream-version-adoption`, with the hash re-measured. It does not decide which PDFs may be shown — the allowlist bounds where the viewer will FETCH from, and a page's publication gates decide whether a page embeds a document at all.",
    "cost": "One ~7 MB download per build and ~12 MB (404 files) added to the built site. Not committed, so no clone cost."
  }
}

folio-assistant — code under the Apache License 2.0, documentation under CC BY 3.0. Generated schema and API references are rebuilt from source on every push to main.

deployed dev