screenshot-sync

screenshot-sync

Keep a repo's screenshots in lockstep with its UI. When the UX changes, the README shot, the web-demo Open Graph preview (og.png), and the gallery thumbnail all have to change with it — this skill re-captures them and the screenshot_sync_check.py gate fails a PR that forgot to.

Read the screenshot skill first for the raw capture mechanics (backends, the image-compositing trap, the content-floor oracle, vision-probe). This skill is the sync/consume orchestration on top of it.

When this applies

• A repo carrying .pulp/screenshots.toml had a UX-path change and the screenshot-sync gate (pre-push / CI) or PostToolUse hint fired, OR
• "update the screenshots / OG images / gallery thumbs", "backfill the WCLAP OG images", "the demo preview image is stale / links don't unfurl".

0. Confirm opt-in

Screenshots are a plugin-with-releases concern, not a core/tooling one. Check for .pulp/screenshots.toml at the repo root. Absent → the repo is not opted in; stop. Do not invent screenshots for a library/tool/core repo. Opt-in is per-repo by the file's presence — the same pattern ~/.config/pulp/daw-smoke.toml and .shipyard.local/config.toml use.

Default opt-in set: the packaged-demo and packaged-examples consumers (gpu-nam, bendr, superconvolver, spectral-lab, tempo-sampler, classic-effects, pulp-example-plugins). Everything else — pulp core included — stays off.

The manifest: .pulp/screenshots.toml

One file per opted-in repo, at its root. It lists the UX paths that should trigger a re-shoot and, for each screenshot target, its capture route and every place the image is consumed — so one re-shoot fans out to README + OG

• gallery and they cannot drift.

schema_version = 1

# UX paths whose change should trigger a re-shoot (repo-relative, gitignore-style
# globs — the same dialect skill_path_map.json uses). A design-token change
# reskins every widget, so a trigger hit invalidates ALL targets in the repo.
[trigger]
paths = [
  "src/**/*_editor.cpp",
  "ui/**/*.js",
  "assets/design-system/**/*.css",
  "assets/design-system/**/*.tokens.json",
]

# ── Native README / editor shot (capture route A) ──
[[target]]
id      = "mono-synth-editor"
route   = "native"                 # render_to_png / pulp-screenshot, Skia/gpu
tool    = "pulp-mono-synth-shot"   # per-editor dumper target (brew_shots.cpp pattern)
size    = "720x460"
scale   = 2.0                      # match the native editor baseline (test_editors.cpp)
backend = "skia"                   # or "gpu" for requires_gpu_host() views
consumes = [
  { kind = "readme", path = "docs/img/mono-synth.png" },
]

# ── Web demo OG + gallery (capture route B) ──
[[target]]
id                  = "mono-synth-web"
route               = "web"
url                 = "example-plugins/mono-synth/index.html"
device_scale_factor = 2
consumes = [
  { kind = "og",      path = "example-plugins/mono-synth/og.png" },
  { kind = "gallery", path = "docs/gallery/mono-synth.png" },
  { kind = "og_meta", html = "example-plugins/mono-synth/index.html", rel = "./og.png" },
]

[[target]]
id                  = "example-gallery-web"
route               = "web"
url                 = "example-plugins/index.html"
device_scale_factor = 2
# A target may narrow the global trigger to just the paths that affect IT:
trigger = [ "ui/**/*.js", "assets/design-system/**" ]
consumes = [
  { kind = "og",      path = "example-plugins/og.png" },
  { kind = "og_meta", html = "example-plugins/index.html", rel = "./og.png" },
]