docs: screenshots of the running SPA in the README

[mforce]

Closes #549.

What and why

The README describes a shipped product and shows none of it. Three images now do, and they are generated, not hand-captured — the capture is a Playwright spec driving the real built SPA over the same seed --profile simulation fixture the smoke suite and k6 use.

Image	Claim it evidences
daily-entry.png (hero)	The core loop: counts → grading → sellable
sales.png	Orders across their lifecycle, with per-row provenance
reports.png	"the numbers that matter" — hen-day %, by-grade, money

How it was verified

npm run screenshots against a freshly reset.sh-seeded stack: 3 passed. npm run typecheck clean. Every frame was reviewed before commit — no auth screen, no token, no .sim-cast.json value; the visible identifiers are the fixture's synthetic @sim.local personas and Sim Customer N.

Decisions worth reviewing

A third Playwright config, not a spec in specs/. This run writes files into the repo. Folding it into npm test would rewrite committed images on every unrelated smoke run and turn a green run into a dirty working tree.

No CI job, no byte-diff gate. Rendering is not deterministic across fonts, antialiasing and GPU paths, so a gate shaped like the #417 schema-docs check would flake — and a flaky gate gets disabled, which is worse than an honest "no gate". The staleness contract is stated in the spec header: refresh when a captured screen changes, and at each release.

The Dashboard is deliberately absent, though #549 listed it. Its Today panel is empty in every fixture capture — the simulation seeds history up to a few days back, so both flocks read no entry and eggs collected today is 0. True of the fixture, misleading as a product's front page, and unfixable without the capture writing today's entries into the shared database. Same reason Daily entry captures yesterday and Reports sets an explicit window ending three days back: the most recent seeded days are drafts, which a report does not count, so both default views are trailing zeroes. Say the word and I will put a Dashboard shot back with its emptiness accepted.

Scale 1, measured not assumed. 382 KB for the three at scale 1 against 910 KB at scale 2; GitHub renders a README image into roughly 890 CSS pixels, so a 1280-wide capture still carries ~1.4x the pixels of its slot. Every regeneration adds its bytes to history permanently, which is what makes the 2.4x worth avoiding.

Four selector traps hit while writing this, each fixed with the reason in a comment — they are the kind that pass wrongly rather than fail loudly:

• getByText("Eggs available") is ambiguous with the Stock panel's "{{count}} eggs available."
• getByLabel("To") on Reports matches the theme toggle's "Switch to night mode".
• allGradedShort is present but CSS-hidden on the captured day — a wait on it times out claiming the data never arrived, when it had.
• A field this spec typed into keeps its focus ring and text selection, so the first daily-entry capture showed half a date highlighted. The capture helper blurs first.

Checklist

• The PR title is a conventional commit, and is the release note I want.
• Docs updated in this PR (tools/simulation/ui/README.md gains the third mode).
• No hardcoded credential — personas come from the git-ignored .sim-cast.json.
• No hardcoded English — every selector resolves through the SPA's own catalogs.
• Farm clock respected — farmToday(farm.timeZoneId), not a UTC date.
• No new Action, no dependency change, no migration.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 64986d8805

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Assert that sales rows loaded before capturing

If the initial /sales request fails, usePagedList converts rows to an empty array, clears reloading, and renders an error plus the empty-state message; both assertions here still pass because the Orders heading remains visible and the Loading text disappears. The suite then overwrites the committed image with an error/empty screen while reporting success, so assert that the orders table contains the expected populated lifecycle rows before calling capture.

Useful? React with 👍 / 👎.

[mforce]

Confirmed and fixed in 25cfb5b — and verified by mutation rather than asserted.

The capture now checks that the empty state is absent and that the table holds rows in both lifecycle states:

await expect(page.getByText(tEn("sales:noOrdersMatch"))).toHaveCount(0);
const orders = page.getByRole("table").first();
await expect(orders.getByRole("row").filter({ hasText: tEn("enums:status.Confirmed") })).not.toHaveCount(0);
await expect(orders.getByRole("row").filter({ hasText: tEn("enums:status.Draft") })).not.toHaveCount(0);

Mutation check, with the endpoint aborted (page.route("**/api/v1/sales**", r => r.abort())):

Error: expect(locator).toHaveCount(expected) failed
Locator:  getByText('No orders match.')
Expected: 0
Received: 1

The old assertions passed under that same mutation, exactly as you described. Restored, and all three captures are green again.

One thing your finding surfaced indirectly: the empty state on this page is sales:noOrdersMatch, not dashboard:noOrdersMessage — two namespaces, two different strings. src/i18n.ts throws on an absent key rather than falling back to English, which is what caught the wrong one on the first run.

[chatgpt-codex-connector]

Include the screenshot suite in TypeScript checks

The new config points at specs-screenshots, but this project’s tsconfig.json includes only specs/**/*.ts, specs-canary/**/*.ts, and the two existing config files. Consequently, npm run typecheck does not examine either this config or the new screenshot spec, so TypeScript-only regressions in the documented capture command can land while the advertised validation remains green; add both paths to the TypeScript project.

Useful? React with 👍 / 👎.

[mforce]

Confirmed and fixed in 25cfb5b. specs-screenshots/**/*.ts and playwright.screenshots.config.ts are both in the project now.

You were right that the advertised validation was green while proving nothing about the new files — and the fix immediately proved it, twice:

1. Coverage check. A deliberate const __mutant: number = "not a number" in the spec now fails the typecheck (TS2322 at that line); removing it restores green. Before the tsconfig change the same mutant compiled clean.
2. A real defect the vacuous check had hidden. The same run reported TS6133: 'prefixOf' is declared but its value is never read — a leftover import from an assertion I refuted while writing the spec. It would have shipped.

"npm run typecheck clean" in the PR body was therefore a claim about files the compiler never opened. Corrected.

[mforce]

@codex round 1 addressed in 25cfb5b — both findings confirmed real.

• Assert that sales rows loaded before capturing (P2). Fixed and mutation-checked: with the sales endpoint aborted, the run now fails on getByText('No orders match.') expecting 0, received 1. The previous assertions passed under that same mutation, exactly as described.
• Include the screenshot suite in TypeScript checks (P2). Fixed. Proven by mutant: a deliberate type error in the new spec now fails npm run typecheck and compiled clean before. It also surfaced a real leftover — an unused prefixOf import — that the vacuous check had hidden, so the PR body's "typecheck clean" was a claim about files the compiler never opened.

Fixing the first one also caught a wrong namespace: the page's empty state is sales:noOrdersMatch, not dashboard:noOrdersMessage.

Images regenerated against a reseeded fixture so all three come from one run. Please re-review.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 25cfb5b214

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Wait for sales setup data before capturing

Fresh evidence beyond the earlier order-loading fix is that SalesPage loads the order list independently from its customer/product/grade setup request. When /sales returns first, these row assertions pass while customer cells still show ID prefixes and the New order control is absent; if setup subsequently fails, the page can even switch to its setup-error screen before capture while the test remains green. Wait for a setup-derived signal such as the localized New order button before writing the image.

AGENTS.md reference: AGENTS.md:L188-L191

Useful? React with 👍 / 👎.

[mforce]

Confirmed and fixed in 151d4ed. Verified in SalesPage.tsx: customerName is customers.find(...)?.name ?? id.slice(0, 8) (line 175), and setupError replaces the entire screen (line 572) — so both halves of what you describe are real.

The capture now waits for the New order button, which renders only past the setup gate.

Mutation-checked in both directions, and they do not both land on the new line — worth stating rather than claiming the one assertion covers everything:

• Setup delayed past the expect timeout (page.route on /customers with a 20s delay): the rows render, every earlier assertion passes, and the run fails on getByRole('button', { name: 'New order' }) — the new guard, by name. This is the mid-load GUID-column case.
• Setup failing outright (r.abort()): the page becomes the setupError screen, and the run fails on the Orders heading — the first assertion, not the new one. Already covered, just not by the line you asked for.

Both restored; all three captures green.

[mforce]

@codex round 2 addressed in 151d4ed — confirmed real, and specific.

Wait for sales setup data before capturing (P2). Verified in SalesPage.tsx: customerName falls back to id.slice(0, 8) and setupError replaces the whole screen, so a capture between the two loads publishes GUID fragments in the customer column. The capture now waits for the New order button.

Mutation-checked in both directions: with /customers delayed past the expect timeout the run fails on the New order button by name (the mid-load case, which is the new guard); with /customers aborted it fails on the Orders heading instead (the setup-error case, already covered by the first assertion). Said plainly on the thread rather than claiming one line catches both.

Running total on this PR: 3 confirmed defects across 2 rounds, 0 rejected. Please re-review.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Keep it up!

Reviewed commit: 151d4ed158

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".