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.
| Tool | pdf-viewer-install |
| IRI | https://litlfred.github.io/folio-assistant/cat-harness/tools/pdf-viewer-install.jsonld |
| part of | https://litlfred.github.io/folio-assistant/cat-harness/cat-harness.jsonld |
| type | https://litlfred.github.io/cat-harness/v0/ns/Tool |
| declared by | cat-harness |
| invoked | shell |
| qa | qa-reports |
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.
| port | type | required | description | constraint | |
|---|---|---|---|---|---|
| in | site | RepoPath | yes | The 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. |
| in | allow | Url | yes | 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. | string · format uri · An absolute http(s) URL |
| in | zip | RepoPath | A 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. | |
| out | summary | Text | 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. | 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:viewerrunsbun run cat-harness-tools/scripts/pdf-viewer.ts(declared incat-harness-tools/package.json). - GitHub Actions. 2 workflow line(s) run its command:
| workflow | line | |
|---|---|---|
.github/workflows/docs-site.yml | 640 | bun run cat-harness-tools/scripts/pdf-viewer.ts --site ./_site |
.github/workflows/feature-staging.yml | 1267 | bun 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.
| install | none |
| runtime | bun, unzip |
| network | yes |
When a host it reaches is refused:
| host / error | remedy |
|---|---|
github.com | none: pdf.js is fetched from its GitHub release and no copy is vendored; the site builds without the viewer. |
| when to choose it | |
|---|---|
| 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. |
What it is made of
| role | file | |
|---|---|---|
| script | cat-harness-tools/scripts/pdf-viewer.ts |
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."
}
}