Embed a PDF inline in a page
Print the HTML fragment that shows a PDF in the installed viewer: a lazily loaded frame whose address is derived from the page’s own location (so one page works at the site root, under a project base and under a staging preview), plus plain open and download links that work without it.
| Tool | pdf-viewer-embed |
| IRI | https://litlfred.github.io/folio-assistant/cat-harness/tools/pdf-viewer-embed.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-install.
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 | spec | Text | yes | One JSON object: src (the PDF’s URL, which must fall under a prefix pdf-viewer-install was given, or the viewer refuses it on screen), title (what the document is; the frame’s accessible name), route (a regular expression over the page’s pathname whose group 1 is the site root — the folio-mount.ts convention) and optionally page (open at this 1-based page). On stdin because a title and a regular expression are free text. | string · A short single-line human string. Not admissible as a command-line argument. |
| out | fragment | Text | The HTML fragment on stdout. TypeScript callers import embed from the module that implements this Tool instead. | 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 --embed.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 |
| network | no |
| when to choose it | |
|---|---|
| when | A generated page should let a reader search, page through, print or download a PDF without leaving it. Only for a document whose publication gates permit linking it: an embed is a link that also renders. |
| limits | It renders PDFs only. It cannot tell whether the site it lands on had the viewer installed; when it did not, or the page is off the route, the frame says so and the plain links still work. |
| cost | Nothing until the reader scrolls to it; then the viewer and worker (~3 MB, cached after the first) and the PDF itself. |
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-embed.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-embed.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-embed",
"title": "Embed a PDF inline in a page",
"description": "Print the HTML fragment that shows a PDF in the installed viewer: a lazily loaded frame whose address is derived from the page's own location (so one page works at the site root, under a project base and under a staging preview), plus plain open and download links that work without it.",
"install": {
"none": true
},
"invoke": {
"shell": "bun run cat pdf:viewer --embed"
},
"io": {
"inputs": [
{
"name": "spec",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Text",
"description": "One JSON object: `src` (the PDF's URL, which must fall under a prefix `pdf-viewer-install` was given, or the viewer refuses it on screen), `title` (what the document is; the frame's accessible name), `route` (a regular expression over the page's pathname whose group 1 is the site root — the `folio-mount.ts` convention) and optionally `page` (open at this 1-based page). On stdin because a title and a regular expression are free text.",
"required": true,
"arg": {
"stdin": true
}
}
],
"outputs": [
{
"name": "fragment",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Text",
"description": "The HTML fragment on stdout. TypeScript callers import `embed` from the module that implements this Tool instead."
}
]
},
"satisfies": [
"pdf-inline-viewer"
],
"requirements": {
"runtime": [
"bun"
],
"network": false
},
"selection": {
"when": "A generated page should let a reader search, page through, print or download a PDF without leaving it. Only for a document whose publication gates permit linking it: an embed is a link that also renders.",
"limits": "It renders PDFs only. It cannot tell whether the site it lands on had the viewer installed; when it did not, or the page is off the route, the frame says so and the plain links still work.",
"cost": "Nothing until the reader scrolls to it; then the viewer and worker (~3 MB, cached after the first) and the PDF itself."
}
}