Skip to content

Every screenshot is taken by a spec - #418

Merged
VeryComplexAndLongName merged 3 commits into
mainfrom
every-screenshot-is-taken-by-a-spec
Sep 12, 2026
Merged

Every screenshot is taken by a spec#418
VeryComplexAndLongName merged 3 commits into
mainfrom
every-screenshot-is-taken-by-a-spec

Conversation

@VeryComplexAndLongName

Copy link
Copy Markdown
Owner

First of the six, implemented. Based on proposals-simpler-for-the-user
(#417), not on main
— the change it implements is proposed there.
Merge #417 first and this retargets itself.

openspec/specs/openspec-workbench/spec.md has required since it was
written that a documentation picture is captured from the running
product by a test. Twenty of twenty-six pictures predated the
requirement, most last touched on 22 August.

Seven pictures are now captured.
packages/server/e2e/documentation-screenshots.spec.ts drives one
fixture workspace and takes the command runner (with a real openspec show completed in it), the summary, the diff preview, the change
editor, the harness entry point, the template catalog, and the processes
view showing a journaled run. Every capture waits on the element that
makes the picture worth having, which is what makes a changed screen
fail here instead of producing a picture of the wrong thing — it did
exactly that twice while the spec was being written.

A check keeps it that way. scripts/check-screenshots.mjs fails on
any picture that neither a capture writes nor a dated entry accounts
for, and on an entry that outlives its picture. It reads the capture
sources rather than a list of pictures, so pipeline.spec.ts — added by
#414 while this was being written — is found without being named. Nine
tests, wired into lint and test.

Nine extension pictures are editor-native — tree views, context
menus and the editor itself — so they are listed with the date each was
actually taken (22 August), not with today's. A date claiming a retake
nobody performed would be the same defect this change removes. The
retake is a human-only item.

Three things worth a second opinion:

  • The four 0*.png files are not captured. They are assets for a
    post published elsewhere and no document here references them.
    Capturing them would mean building fixtures for a permission request,
    an observation record and a failing mechanical check to keep four
    pictures fresh that nothing shows. They are listed under a third
    reason, published-asset, and tasks 2.8-2.11 are left open: the
    question is delete them or reference them, and it is not a lint's to
    settle.
  • Three captures are not byte-stable between runs — they show the
    fixture's temporary path and a run timestamp. Measured, not assumed;
    recorded in the tasks rather than fixed by freezing fixtures every
    other spec shares.
  • No capture publishes the machine it was taken on. The first run
    put C:\Users\<account>\AppData\Local\Temp\... into two pictures;
    those fields are now masked with a flat grey rather than cropped, so a
    reader sees that something was covered.

Browser suite: 17 tests, 17 passed, 3.2m. npm run verify: exit 0, 1998
tests across 157 files. openspec validate --strict --changes: 7
passed, 0 failed.

🤖 Generated with Claude Code

@VeryComplexAndLongName
VeryComplexAndLongName force-pushed the every-screenshot-is-taken-by-a-spec branch from 8dcbdea to c350a45 Compare September 12, 2026 08:02
The requirement has been in openspec/specs/openspec-workbench/spec.md
since it was written: a documentation picture is captured from the
running product by a test, because "a hand-taken screenshot goes stale
silently: the screen changes, the picture does not, and nothing fails."
Twenty of twenty-six pictures predated it, most last touched on
22 August.

- `packages/server/e2e/documentation-screenshots.spec.ts` captures the
  seven standalone pictures the READMEs carry: the command runner with a
  real `openspec show` completed in it, the summary, the diff preview,
  the change editor, the harness entry point, the template catalog, and
  the processes view showing a journaled run.
- `scripts/check-screenshots.mjs` fails on any picture that neither a
  capture writes nor a dated entry accounts for, and on an entry that
  outlives its picture. It reads the capture sources rather than a list
  of pictures, so `pipeline.spec.ts` — added by another change while
  this was written — is found without being named.
- The nine extension pictures are editor-native: tree views, context
  menus and the editor itself. They are listed with the date each was
  actually taken, not with today's, and retaking them is left as a
  human-only item.

Two things this deliberately did not do. The four `0*.png` files are
assets for a post published elsewhere that no document here references;
they are listed under a third reason, `published-asset`, so the question
of deleting them stays visible rather than settled by a lint. And three
captures are not byte-stable between runs, because they show the
fixture's temporary path and a run timestamp — measured, recorded, and
left as a finding rather than fixed by freezing fixtures every other
spec shares.

Browser suite: 17 tests, 17 passed, 3.2m. npm run verify: exit 0, 1998
tests across 157 files.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The fixture workspace lives under a temporary directory whose path
carries the account name of whoever regenerates the pictures, and two of
the new captures published it: the command runner's two path fields, and
the summary's "Root:" line.

Both are masked with a flat grey rather than cropped. The field is part
of the screen, and a reader should be able to see that something was
covered instead of concluding the screen has no such field. In the
summary line only the path is masked — the change and spec counts beside
it are what the line is for.

The summary capture also now waits for its "Load summary" button to come
back from "Loading...", so the picture is of a loaded screen rather than
a loaded screen with a busy control on it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…d them

`docs/images/standalone/01-permission-request.png` and its three
siblings were assets for a post published elsewhere
(`2026-09-07-linkedin-teaser-assets`). No document in this repository
references any of them, and keeping them fresh would have meant fixtures
for a permission request, an observation record and a failing mechanical
check — to photograph screens nothing shows.

They were briefly listed under a third baseline reason,
`published-asset`. That reason is removed with them: listing them used
the exception surface to avoid a decision, and the decision was to
delete. What stays is the rule, in the code comment — a reason belongs
in that set when a picture genuinely cannot be captured, never when one
is merely inconvenient to delete.

The published post keeps its own copies, and git keeps these.

npm run verify: exit 0. "Screenshot check passed. 22 pictures: 13
captured, 9 listed as hand-taken."

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@VeryComplexAndLongName
VeryComplexAndLongName force-pushed the every-screenshot-is-taken-by-a-spec branch from c350a45 to a174666 Compare September 12, 2026 08:49
@VeryComplexAndLongName
VeryComplexAndLongName changed the base branch from proposals-simpler-for-the-user to main September 12, 2026 08:49
@VeryComplexAndLongName

Copy link
Copy Markdown
Owner Author

Reopening to trigger the workflow now the base is main.

@VeryComplexAndLongName
VeryComplexAndLongName merged commit ee31b4d into main Sep 12, 2026
9 checks passed
@VeryComplexAndLongName
VeryComplexAndLongName deleted the every-screenshot-is-taken-by-a-spec branch September 12, 2026 09:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant