Folio block screenshots
Picture each changed figure, diagram, table, equation or simulator block on the published main site and on a staging build, and compare the two pictures pixel by pixel in Chromium’s canvas. Writes visual-diff.json (folio-visual-diff/v1: per block, the share of pixels changed beyond anti-aliasing, and the before, after and diff pictures) and visual/*.png, which the review page’s visual renderer shows. A side that cannot be pictured (page or anchor missing) is recorded as missing, never drawn blank. Drives Chromium through Playwright.
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.
visual-diff
Pictures of a changed figure, diagram or table, before and after, and how much of it changed. Says when to use it, what the percentage means and must NOT be read as, what a missing picture means, and how the staging job and the review process call it. Use when a reviewer asks “what does this figure look like now”, when a table’s markup diff is unreadable, or when a staging preview’s pictures are missing.
Source: cat-harness/sdlc/skills/sdlc-core/visual-diff.md.
The skill declares no I/O contract (schemas/skills/visual-diff/{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 | changeset | RepoPath | yes | The preview’s changeset.json: which blocks changed, and their kind on each side. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. |
| in | base | RepoPath | The published main site, as a directory (the publish branch’s root). | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. | |
| in | head | RepoPath | The staging build’s site directory. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. | |
| in | out | RepoPath | Where to write visual-diff.json and visual/: the site root, so the review page finds them. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. | |
| in | count | Flag | Print how many changed blocks would be pictured, and stop, so a caller installs a browser only when there is work. | boolean · A boolean switch — projects to a bare flag, with no value word | |
| out | visual-diff | RepoPath | <out>/visual-diff.json and <out>/visual/*.png. A per-block summary goes to stderr. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. |
Processes and tasks
Steps this Tool can carry out, because each names a skill it satisfies:
| process | step | lane | via skill |
|---|---|---|---|
| Committee review of a content change | Compare main vs staging | Review Committee | visual-diff |
| SMART Guideline end to end | Review each L2 asset (before / after if adapted) | Human adjudicators | visual-diff |
| L2 component edit and review | Review the staged component | Component reviewer (person) | visual-diff |
How it is deployed and reached
- Command line. From the repository root:
bun run cat block:screenshots.cat block:screenshotsrunsbun run cat-harness-tools/scripts/block-screenshots.ts(declared incat-harness-tools/package.json). - GitHub Actions. 2 workflow line(s) run its command:
| workflow | line | |
|---|---|---|
.github/workflows/folio-staging.yml | 601 | N=$(bun run "$PLATFORM_DIR/cat-harness-tools/scripts/block-screenshots.ts" --changeset "$SITE_DIR/changeset.json" --count) |
.github/workflows/folio-staging.yml | 607 | bun run "$PLATFORM_DIR/cat-harness-tools/scripts/block-screenshots.ts" \\ |
As an API: its operation in the OpenAPI document and the MCP tool list of its layer.
| install | none |
| runtime | bun, chromium |
| network | no |
| when to choose it | |
|---|---|
| when | A staging build changed a figure, diagram, table, equation or simulator, whose markup diff says little, and the reviewer needs to see before and after. |
| limits | The number is how MUCH changed, never whether the change is right. A block’s picture is its anchor down to the next anchor, so a page whose anchors are missing or misplaced pictures the wrong region. Pictures are of the light theme. |
| cost | A Chromium launch and two page loads, one screenshot and one canvas compare per visual block. Nothing when no visual block changed. |
What it is made of
| role | file | |
|---|---|---|
| script | cat-harness-tools/scripts/block-screenshots.ts |
Linked data
The Tool is published as its own JSON-LD document at its IRI, https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/folio-block-screenshots.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/folio-assistant-core/folio-assistant-core.context.jsonld",
"@id": "https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/folio-block-screenshots.jsonld",
"@type": "https://litlfred.github.io/cat-harness/v0/ns/Tool",
"partOf": "https://litlfred.github.io/folio-assistant/folio-assistant-core/folio-assistant-core.jsonld",
"name": "folio-block-screenshots",
"title": "Folio block screenshots",
"description": "Picture each changed figure, diagram, table, equation or simulator block on the published main site and on a staging build, and compare the two pictures pixel by pixel in Chromium's canvas. Writes `visual-diff.json` (`folio-visual-diff/v1`: per block, the share of pixels changed beyond anti-aliasing, and the before, after and diff pictures) and `visual/*.png`, which the review page's visual renderer shows. A side that cannot be pictured (page or anchor missing) is recorded as missing, never drawn blank. Drives Chromium through Playwright.",
"install": {
"none": true
},
"invoke": {
"shell": "bun run cat block:screenshots"
},
"io": {
"inputs": [
{
"name": "changeset",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "The preview's `changeset.json`: which blocks changed, and their kind on each side.",
"required": true,
"arg": {
"flag": "--changeset"
}
},
{
"name": "base",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "The published main site, as a directory (the publish branch's root).",
"required": false,
"arg": {
"flag": "--base"
}
},
{
"name": "head",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "The staging build's site directory.",
"required": false,
"arg": {
"flag": "--head"
}
},
{
"name": "out",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "Where to write `visual-diff.json` and `visual/`: the site root, so the review page finds them.",
"required": false,
"arg": {
"flag": "--out"
}
},
{
"name": "count",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Flag",
"description": "Print how many changed blocks would be pictured, and stop, so a caller installs a browser only when there is work.",
"required": false,
"arg": {
"flag": "--count"
}
}
],
"outputs": [
{
"name": "visual-diff",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "`<out>/visual-diff.json` and `<out>/visual/*.png`. A per-block summary goes to stderr."
}
]
},
"satisfies": [
"visual-diff"
],
"requirements": {
"runtime": [
"bun",
"chromium"
],
"network": false
},
"selection": {
"when": "A staging build changed a figure, diagram, table, equation or simulator, whose markup diff says little, and the reviewer needs to see before and after.",
"limits": "The number is how MUCH changed, never whether the change is right. A block's picture is its anchor down to the next anchor, so a page whose anchors are missing or misplaced pictures the wrong region. Pictures are of the light theme.",
"cost": "A Chromium launch and two page loads, one screenshot and one canvas compare per visual block. Nothing when no visual block changed."
}
}