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.

porttyperequireddescriptionconstraint
inchangesetRepoPathyesThe 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.
inbaseRepoPathThe 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.
inheadRepoPathThe staging build’s site directory.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
inoutRepoPathWhere 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.
incountFlagPrint 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
outvisual-diffRepoPath<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:

processsteplanevia skill
Committee review of a content changeCompare main vs stagingReview Committeevisual-diff
SMART Guideline end to endReview each L2 asset (before / after if adapted)Human adjudicatorsvisual-diff
L2 component edit and reviewReview the staged componentComponent reviewer (person)visual-diff

How it is deployed and reached

  • Command line. From the repository root: bun run cat block:screenshots. cat block:screenshots runs bun run cat-harness-tools/scripts/block-screenshots.ts (declared in cat-harness-tools/package.json).
  • GitHub Actions. 2 workflow line(s) run its command:
workflowline
.github/workflows/folio-staging.yml601N=$(bun run "$PLATFORM_DIR/cat-harness-tools/scripts/block-screenshots.ts" --changeset "$SITE_DIR/changeset.json" --count)
.github/workflows/folio-staging.yml607bun 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.

installnone
runtimebun, chromium
networkno
when to choose it
whenA staging build changed a figure, diagram, table, equation or simulator, whose markup diff says little, and the reviewer needs to see before and after.
limitsThe 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.
costA 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

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."
  }
}

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