@asrunjs/asrun 0.2.0 → 0.5.2

package/.claude/skills/exploring-cases/references/open-questions.md

@@ -1,112 +1,116 @@
-# Open questions: write, resolve, report
-
-Shared by `exploring-cases` and `generating-specs`. The agent never waits for an answer in the chat: it may run
-without anybody present (a one-shot `claude -p` / `opencode run`). The case file is where the agent and the user
-talk to each other, so nothing is lost between runs, tools or sessions.
-
-## How a question is written in the case file
-Every marker starts with its emoji, which is part of the marker: `🚫 TODO [blocking]`, `❓ TODO [non-blocking]`, `✍️ Answer:`, `🔍 to be confirmed by QA` and `👁️ not observed`. The web UI colors the emoji with the marker and offers an X button that deletes it.
-Every question is a small block that hangs under a normal sentence. The sentence is the agent's suggestion, written
-exactly as it should read in the final case. The block holds the question and an empty answer slot:
-
-```
-- <the suggested statement, a complete sentence that can stand in the case as it is>
-  - ❓ TODO [non-blocking]: <the question, one sentence>? (<evidence, e.g. seen on example-staging>)
-    - ✍️ Answer:
-```
-
-The same shape is used under a step, under a bullet of "Expected", under the yaml block of "Values" and in "Data":
-
-```
-11. Delete the document with the "Delete" option of its "..." menu on the list page. [writes]
-    - 🚫 TODO [blocking]: How is the document deleted? (the same path was observed for drafts on example-staging)
-      - ✍️ Answer:
-```
-
-Rules for writing it:
-- **The suggestion is a statement, never a question or a half sentence.** "The logo is visible and not empty." is
-  right. "Suggested: visible." and "what is the logo?" are wrong. When no value is known, state the safest reading
-  (visible and not empty, the spec accepts both, no screenshot baseline is taken, ...). Never invent a concrete
-  value such as a text, a count or a color.
-- **The suggestion is always the parent line**, so deleting the TODO block leaves a finished case. Do not put the
-  suggestion inside the TODO line, and do not write `Suggested:`.
-- **Always leave the empty `Answer:` line** as the last line of the block, one level deeper than the `TODO` line.
-- The TODO line has the question and, when the page showed something, the evidence in parentheses. Nothing else.
-- `[blocking]`: the spec cannot be written correctly without the answer. `[non-blocking]`: the suggestion is safe;
-  QA should confirm it later but nothing waits for it.
-- One question per block; narrow broad questions down instead of copying them ("which profile elements?" becomes
-  "is the logo the only per-profile element in the left side bar?").
-- A value read from a page is not a question: write it as a statement marked `(observed, 🔍 to be confirmed by QA)`.
-  It needs no TODO block; the reviewer confirms it by deleting the marker.
-
-## How the user answers
-Two ways, and the agent must understand both on the next run:
-- **The suggestion is fine:** delete the whole TODO block (the `TODO` line and the `Answer:` line). The parent
-  sentence is now confirmed text.
-- **Own answer:** write it after `Answer:`. The answer replaces the parent sentence where they disagree. The user
-  may delete the rest of the block, or leave it.
-- An `Answer:` with no text is not an answer. A block that was left untouched stays open.
-- An old `TODO: ...` line without a tag or without a parent suggestion (written before this format) counts as
-  `[blocking]` until it is rewritten into the shape above.
-
-The agent folds an answer into plain text in the right place (the parent sentence, an expected bullet, an entry of
-`## Values`, a step) and removes the `TODO` line and the `Answer:` line. If an answer contradicts the page, it keeps the
-answer, adds `(page shows <x> on <profile-id>)` and reports it as a finding. It never overrides the user.
-
-## What an open block means for the agent
-- No TODO block under a sentence: the sentence is confirmed. Use it.
-- `[non-blocking]` block: use the parent sentence as the expectation; keep the block for QA.
-- `[blocking]` block: the parent sentence is only a guess. Do not generate a check from it: write
-  `test.fixme(true, '<the question>')` inside the step (or skip that profile).
-- Every run re-evaluates the blocks that are already in the file against the rules below, including their tag: a
-  `[blocking]` question that now has an observation or a safe default is downgraded or closed in the file, and the
-  edit is part of the report. Do not carry old tags over.
-
-## Resolution order (no question goes to the user while a better step exists)
-1. **The page answers it.** Facts such as exact labels, which controls exist, where the logo is, what a menu holds
-   are answered by exploration (`/explore-case`; needs an environment and a logged-in profile; the agent only reads, a person does the steps that write). Rewrite the parent sentence
-   with the fact, mark it `(observed, 🔍 to be confirmed by QA)` and remove the block.
-   - A check with no expected value ("check X", "can see Y") becomes: the observed behaviour, marked as observed.
-     A spec may be generated from it.
-   - Values that a check asserts (logo name, label, option list) are observed per profile and written into the case's
-     `## Values`, under the profile id (or `default` when they hold for every profile).
-2. **A default is safe.** Use the default of `gaps.md` in the `making-cases` skill (visible and not empty, all
-   environments, `suites: [regression]`, ...) as the parent sentence and keep the block as `[non-blocking]`.
-   Implementation questions are in this group: whether "visible" is enough, how long to wait, which of two equally
-   good locators for the SAME element to use. Pick the most robust option the page offers, state it, and do not
-   block on it. **Not in this group: which element a check looks at.** That is a target (`assertion-targets.md`):
-   one clear candidate becomes a card, anything else blocks.
-3. **Otherwise it blocks.** Keep the block as `[blocking]`, narrowed as far as the page allows, with the best guess
-   as the parent sentence.
-
-## What is always blocking (never guess, never generate around it)
-- A step that would write data or send email while the front matter has no `writes` list (or no `writes-note`), or for an environment that `writes` does not list.
-- A step that writes data or needs a choice, in a run that is not attended: no person can do it, so there is nothing to
-  record under `## Inputs`.
-- A step that cannot be performed after exploring: the path 404s, the control does not exist for any profile, or it
-  needs data that does not exist and the case does not create it.
-- Observed behaviour that contradicts what the case states, or a profile that deviates from the others where the case
-  says "same for every profile". This may be a product bug: record it (`(observed: <what>, on <profile-id>)`),
-  do not encode the deviating value as the expectation, and say it in the report.
-- **An assertion target that is in doubt** (`assertion-targets.md`): several candidates, only a position or a generic
-  locator to find it, dynamic data in its area, no stable identity, or the page differs from the case. The question
-  names the exact image, text, place or UI wanted and lists the candidates. Never a safe default, because a wrong
-  guess passes silently.
-- An intent question the page cannot answer ("should this also work for agents?").
-- No environment was given, or no profile is logged in, so a fact that needs the page cannot be observed.
-
-## Final report
-Report in the user's language. List every open block with its question and the parent sentence it would confirm, so
-the user can see what deleting it accepts. The last line of the final message is exactly one of:
-
-```
-RESULT: ready
-RESULT: needs-input
-```
-
-- `ready`: no `[blocking]` question remains. Non-blocking ones may remain; list them so QA can confirm them.
-- `needs-input`: at least one `[blocking]` question remains in the case file (list each with its parent sentence),
-  or the work could not be done (no environment, nobody logged in). Say what the user should edit in the case file,
-  then re-run.
-
-Do not write anything after the `RESULT:` line.
+# Open questions: write, resolve, report
+
+Shared by `exploring-cases` and `generating-specs`. The agent never waits for an answer in the chat: it may run
+without anybody present (a one-shot `claude -p` / `opencode run`). The case file is where the agent and the user
+talk to each other, so nothing is lost between runs, tools or sessions.
+
+## How a question is written in the case file
+Every marker starts with its emoji, which is part of the marker: `🚫 TODO [blocking]`, `❓ TODO [non-blocking]`, `✍️ Answer:`, `🔍 to be confirmed by QA` and `👁️ not observed`. The web UI colors the emoji with the marker and offers an X button that deletes it.
+Every question is a small block that hangs under a normal sentence. The sentence is the agent's suggestion, written
+exactly as it should read in the final case. The block holds the question and an empty answer slot:
+
+```
+- <the suggested statement, a complete sentence that can stand in the case as it is>
+  - ❓ TODO [non-blocking]: <the question, one sentence>? (<evidence, e.g. seen on example-staging>)
+    - ✍️ Answer:
+```
+
+The same shape is used under a step, under a bullet of "Expected" and under the yaml block of "Values":
+
+```
+11. Delete the document with the "Delete" option of its "..." menu on the list page. [writes]
+    - 🚫 TODO [blocking]: How is the document deleted? (the same path was observed for drafts on example-staging)
+      - ✍️ Answer:
+```
+
+Rules for writing it:
+- **The suggestion is a statement, never a question or a half sentence.** "The logo is visible and not empty." is
+  right. "Suggested: visible." and "what is the logo?" are wrong. When no value is known, state the safest reading
+  (visible and not empty, the spec accepts both, no screenshot baseline is taken, ...). Never invent a concrete
+  value such as a text, a count or a color.
+- **The suggestion is always the parent line**, so deleting the TODO block leaves a finished case. Do not put the
+  suggestion inside the TODO line, and do not write `Suggested:`.
+- **Always leave the empty `Answer:` line** as the last line of the block, one level deeper than the `TODO` line.
+  Nothing goes after it, and there is exactly one per block.
+- **Both the suggestion and the question may wrap.** A wrapped line is plain text (no bullet): the block ends at the
+  first blank line or at a line that is not indented deeper than the `TODO` line. Indent the block by 4 spaces under a
+  numbered step (2 under a `-` bullet) so Markdown renders it inside that step; `pnpm case:check` warns otherwise.
+- The TODO line has the question and, when the page showed something, the evidence in parentheses. Nothing else.
+- `[blocking]`: the spec cannot be written correctly without the answer. `[non-blocking]`: the suggestion is safe;
+  QA should confirm it later but nothing waits for it.
+- One question per block; narrow broad questions down instead of copying them ("which profile elements?" becomes
+  "is the logo the only per-profile element in the left side bar?").
+- A value read from a page is not a question: write it as a statement marked `(observed, 🔍 to be confirmed by QA)`.
+  It needs no TODO block; the reviewer confirms it by deleting the marker.
+
+## How the user answers
+Two ways, and the agent must understand both on the next run:
+- **The suggestion is fine:** delete the whole TODO block (the `TODO` line and the `Answer:` line). The parent
+  sentence is now confirmed text.
+- **Own answer:** write it after `Answer:`. The answer replaces the parent sentence where they disagree. The user
+  may delete the rest of the block, or leave it.
+- An `Answer:` with no text is not an answer. A block that was left untouched stays open.
+- An old `TODO: ...` line without a tag or without a parent suggestion (written before this format) counts as
+  `[blocking]` until it is rewritten into the shape above.
+
+The agent folds an answer into plain text in the right place (the parent sentence, an expected bullet, an entry of
+`## Values`, a step) and removes the `TODO` line and the `Answer:` line. If an answer contradicts the page, it keeps the
+answer, adds `(page shows <x> on <profile-id>)` and reports it as a finding. It never overrides the user.
+
+## What an open block means for the agent
+- No TODO block under a sentence: the sentence is confirmed. Use it.
+- `[non-blocking]` block: use the parent sentence as the expectation; keep the block for QA.
+- `[blocking]` block: the parent sentence is only a guess. Do not generate a check from it: write
+  `test.fixme(true, '<the question>')` inside the step (or skip that profile).
+- Every run re-evaluates the blocks that are already in the file against the rules below, including their tag: a
+  `[blocking]` question that now has an observation or a safe default is downgraded or closed in the file, and the
+  edit is part of the report. Do not carry old tags over.
+
+## Resolution order (no question goes to the user while a better step exists)
+1. **The page answers it.** Facts such as exact labels, which controls exist, where the logo is, what a menu holds
+   are answered by exploration (`/explore-case`; needs an environment and a logged-in profile; the agent only reads, a person does the steps that write). Rewrite the parent sentence
+   with the fact, mark it `(observed, 🔍 to be confirmed by QA)` and remove the block.
+   - A check with no expected value ("check X", "can see Y") becomes: the observed behaviour, marked as observed.
+     A spec may be generated from it.
+   - Values that a check asserts (logo name, label, option list) are observed per profile and written into the case's
+     `## Values`, under the profile id (or `default` when they hold for every profile).
+2. **A default is safe.** Use the default of `gaps.md` in the `making-cases` skill (visible and not empty, all
+   environments, `suites: [regression]`, ...) as the parent sentence and keep the block as `[non-blocking]`.
+   Implementation questions are in this group: whether "visible" is enough, how long to wait, which of two equally
+   good locators for the SAME element to use. Pick the most robust option the page offers, state it, and do not
+   block on it. **Not in this group: which element a check looks at.** That is a target (`assertion-targets.md`):
+   one clear candidate becomes a card, anything else blocks.
+3. **Otherwise it blocks.** Keep the block as `[blocking]`, narrowed as far as the page allows, with the best guess
+   as the parent sentence.
+
+## What is always blocking (never guess, never generate around it)
+- A step that would write data or send email while the front matter has no `writes` list (or no `writes-note`), or for an environment that `writes` does not list.
+- A step that writes data or needs a choice, in a run that is not attended: no person can do it, so there is nothing to
+  record as a `- Recipe:` line under it.
+- A step that cannot be performed after exploring: the path 404s, the control does not exist for any profile, or it
+  needs data that does not exist and the case does not create it.
+- Observed behaviour that contradicts what the case states, or a profile that deviates from the others where the case
+  says "same for every profile". This may be a product bug: record it (`(observed: <what>, on <profile-id>)`),
+  do not encode the deviating value as the expectation, and say it in the report.
+- **An assertion target that is in doubt** (`assertion-targets.md`): several candidates, only a position or a generic
+  locator to find it, dynamic data in its area, no stable identity, or the page differs from the case. The question
+  names the exact image, text, place or UI wanted and lists the candidates. Never a safe default, because a wrong
+  guess passes silently.
+- An intent question the page cannot answer ("should this also work for agents?").
+- No environment was given, or no profile is logged in, so a fact that needs the page cannot be observed.
+
+## Final report
+Report in the user's language. List every open block with its question and the parent sentence it would confirm, so
+the user can see what deleting it accepts. The last line of the final message is exactly one of:
+
+```
+RESULT: ready
+RESULT: needs-input
+```
+
+- `ready`: no `[blocking]` question remains. Non-blocking ones may remain; list them so QA can confirm them.
+- `needs-input`: at least one `[blocking]` question remains in the case file (list each with its parent sentence),
+  or the work could not be done (no environment, nobody logged in). Say what the user should edit in the case file,
+  then re-run.
+
+Do not write anything after the `RESULT:` line.

package/.claude/skills/exploring-cases/references/readiness.md

@@ -1,137 +1,146 @@
-# Readiness: look at the result only after the content is there
-
-Shared by `exploring-cases`, `generating-specs` and healing. It is binding in all three.
-
-A page that has just reacted is not ready. Dialogs, composers, previews, lists and PDFs show a frame first and fill
-in later. Reading it too early gives a false "missing", "empty" or "wrong", and exploration then writes the false fact
-into the case, the spec encodes it, and healing believes it.
-
-**The rule: after every action that loads something, wait for its key requests to finish and for the content itself
-to be visible, before reading, asserting or recording anything.**
-
-## What "ready" is
-All of these, in this order:
-1. **The key requests finished** with a success status. The key requests are the data calls the action starts
-   (the composer's content, the list query, the PDF render), not images, fonts or analytics.
-2. **Nothing says it is still loading**: no spinner, progress bar, skeleton, `aria-busy="true"`, "Loading..." text.
-3. **The content itself is visible**: a positive signal that only exists when the data is there (a field with its value, the
-   first row, an image whose `naturalWidth` is above 0), never "the frame is open".
-4. **Stable**: for exploration, two snapshots one second apart say the same.
-
-A check for something **missing, empty or hidden** is only valid after a positive ready signal. "The list has no X"
-means: the list finished loading and has rows, and none is X.
-
-## Exploring
-- Know the key requests: after the action, call `browser_network_requests`, pick the data calls (XHR/fetch to the
-  app's API, the ones that return the content). Wait until they are finished; use `browser_network_clear` before the
-  action so the list only holds what the action started.
-- Then wait for the content signal (`browser_wait_for` with text, or `browser_find` that the content is there), and
-  take the snapshot only then. A snapshot taken right after a click is a frame, not a fact.
-- Observations record the ready signal: `(observed after <signal>, ...)`. A fact with no signal is not recorded.
-- When the first read shows less than expected (empty, a missing field, a logo not there), do not record it yet and do
-  not raise a question yet. Wait for readiness, read again, and only then decide. Mention in the report that the first
-  read was too early, with what was missing.
-- Do it for every profile: loading time differs between profiles and environments.
-
-## In the case
-Steps and targets state their ready signal: `Ready when: <signal>` under the step, or the target card's `Ready when`.
-Example: `Ready when: the composer's "To" field is visible and the logo image has loaded.` It is what `/gen-spec` turns into
-`ready` and `responses`.
-
-## Generating (spec code)
-Use `actAndWait` and `expectNotBusy` from `@asrunjs/asrun/ready`, and `verifyDownload` from `@asrunjs/asrun/downloads`:
-
-```ts
-// ready: the composer shows its recipient field and the logo image has loaded
-const composer = page.getByRole('dialog', {name: 'Email PDF'});
-await actAndWait(page, () => option.click(), {
-  responses: [/\/api\/documents\/[^/]+\/email-preview/],
-  ready: [composer.getByRole('textbox', {name: 'To'}), logo],
-});
-await expectImageLoaded(logo);
-```
-
-- Register the response wait **before** the action (`actAndWait` does).
-- Every action that opens a dialog, a tab, a menu with data, a list or a preview waits for its key requests and its content
-  signal. The request URL patterns come from `browser_network_requests` during exploration, not from guesses; if none was
-  seen (the action was not run), say "not verified on the page" in the report.
-- Never `waitForTimeout`, never `networkidle`. They wait for time or for silence, not for the content. `pnpm spec:lint` fails both.
-- Never `if (await x.isVisible()) ...` to decide something that may not have loaded yet. Wait for a ready signal, then branch.
-  Where an element is genuinely optional, say what proves the page finished (`// ready: ...`) before looking for it.
-- `locator.isVisible()` and `isHidden()` answer for this instant only. Their `timeout` option is deprecated and ignored:
-  `isVisible({timeout: 3_000})` does not wait 3 seconds. Never write it, and never use `.catch(() => false)` to make it
-  look like a wait. `pnpm spec:lint` fails both.
-- An optional confirmation (see below) is handled with `clickOptionalUntilHidden`, not with `isVisible`.
-
-### Optional confirmations (a dialog that may or may not show up)
-Closing a composer, leaving an editor or deleting something can raise "Discard draft?", "Are you sure?" or nothing at all,
-and the dialog can show up a second or two after the click. A check made right after the click sees "no dialog" and skips
-it, then the next check (the composer is closed) races a dialog that appears later and fails.
-
-The click on the confirmation and the check that the action finished go into **one retry loop**:
-
-```ts
-await composer.getByRole('button', {name: 'close', exact: true}).click();
-await clickOptionalUntilHidden(page.getByRole('button', {name: 'Discard', exact: true}), composer, {
-  message: 'The email composer did not close',
-});
-```
-
-- Each round: click the confirmation if it is visible now, then check that the target is hidden. A late dialog is clicked
-  in a later round; no dialog passes in the first round.
-- Never decide "there is no dialog" from one look, and never wait a fixed time for it.
-- The same holds for any other optional modal (for example "Add to Business Tracker" after publishing): when the case says
-  it opens, assert it with a waiting `expect(...).toBeVisible({timeout})`; when it may or may not open, use a loop that
-  also checks the next page state, or wait for the signal that proves the action finished (URL, heading), then look.
-- A check for absence needs a positive ready signal in front of it (`// ready: <signal>`).
-- A new tab: wait for the page event first (`context.waitForEvent('page')`), then for its URL, then for its content signal.
-- A download is verified with `verifyDownload` (below), never with a bare `waitForEvent('download')`.
-
-## Downloads
-Any download (PDF, image, CSV, ZIP), in exploration and in the spec, is verified in five parts, and the verification
-step fails as a whole when any part fails or times out:
-1. wait for the download to start after the click;
-2. wait for the download to finish;
-3. check that the file exists and has content;
-4. check that the file is valid for its kind (an image has the right signature; a ZIP/CSV likewise; a PDF starts with `%PDF-`,
-   ends with `%%EOF` and **opens with at least one page**), and run the case's own validation if there is one;
-5. any failure or timeout of 1 to 4 fails the verification with a message that names the stage.
-
-`verifyDownload(page, trigger, {kind, fileName?, minBytes?, validate?})` does exactly this. Name the file type in the
-case (`kind`), and describe in a target card what the file must contain.
-
-### PDF content: read it like a person (rendered images and extracted text)
-A PDF check never stops at "it is a PDF". `verifyDownload(..., {kind: 'pdf'})` returns `file.pdf`, and
-`expectPdf(file.pdf!, {...})` from `@asrunjs/asrun/pdf` then:
-- **renders the pages to images** (scale 2, white background) and, for every region check, fails when the region is blank
-  and compares it with the profile's baseline image (2% tolerance; the first run with `--update-snapshots` creates the
-  baseline and a person looks at it, like any other baseline);
-- **extracts the text** of every page and checks `textContains` / `textNotContains` (the names of the other profiles, for
-  example).
-Regions are fractions of the page from the top-left corner; `corner('top-left')` is the usual logo corner.
-
-**Which pages are checked is the case's decision, case by case:**
-- The case says ONLY certain pages in strong words (a requirement: "only", "exactly", "must be on the first page", "the
-  logo is on the first and last page and nowhere else"): check just those (`pages: 'first' | 'last' | [1, 3]`), and put
-  `// pages: <the case's words>` above the check so a reviewer can see where the limit comes from.
-- The case names pages softly ("should", "always", "usually", "typically", "normally", "e.g.") or names no page: check
-  **every page** (`pages: 'all'`, the default). The named page is then only the place where the check was first seen.
-- A page limit that comes from the agent's own reading of the case is not allowed. When it is unclear whether a wording is
-  a strong requirement, check all pages and put the doubt in a `[non-blocking]` TODO.
-
-**While exploring, the agent looks at the PDF too:** save the downloaded file under `.explore/` (`download.saveAs(...)`
-in the same `browser_run_code_unsafe` call that waits for the download), run
-`pnpm pdf:render <file> --out .explore/targets/<case-id>/<name> --pages all --corner top-left`, then **open the page
-images** and say in the card where the logo really is on each page, which pages have it and which do not, and what the
-text shows. The rendered pages are the card's `Reference`. If the logo is not where the case says, that is a question.
-
-While exploring, do the same by hand: click, wait for the download event, see the file finish, read its size and its first
-bytes. Record "(observed: <file name>, <size>, valid <kind>)".
-
-## Healing
-A failure of the kind "missing", "empty", "not visible", "wrong count", "timeout waiting for X" is first a suspected
-readiness problem, then a suspected product problem:
-1. Read the failure screenshot and video: was the page still loading (a spinner, a skeleton, an empty frame)?
-2. Run the failing step by hand with the readiness protocol above and compare.
-3. Only when the content is complete and still not what the case says is it a test-expectation or product matter.
-4. A readiness fix goes into the spec as `actAndWait` / a ready signal, never as a longer timeout alone and never as a sleep.
+# Readiness: look at the result only after the content is there
+
+Shared by `exploring-cases`, `generating-specs` and healing. It is binding in all three.
+
+A page that has just reacted is not ready. Dialogs, composers, previews, lists and PDFs show a frame first and fill
+in later. Reading it too early gives a false "missing", "empty" or "wrong", and exploration then writes the false fact
+into the case, the spec encodes it, and healing believes it.
+
+**The rule: after every action that loads something, wait for its key requests to finish and for the content itself
+to be visible, before reading, asserting or recording anything.**
+
+## What "ready" is
+All of these, in this order:
+1. **The key requests finished** with a success status. The key requests are the data calls the action starts
+   (the composer's content, the list query, the PDF render), not images, fonts or analytics.
+2. **Nothing says it is still loading**: no spinner, progress bar, skeleton, `aria-busy="true"`, "Loading..." text.
+3. **The content itself is visible**: a positive signal that only exists when the data is there (a field with its value, the
+   first row, an image whose `naturalWidth` is above 0), never "the frame is open".
+4. **Stable**: for exploration, two snapshots one second apart say the same.
+
+A check for something **missing, empty or hidden** is only valid after a positive ready signal. "The list has no X"
+means: the list finished loading and has rows, and none is X.
+
+## Exploring
+- Know the key requests: after the action, call `browser_network_requests`, pick the data calls (XHR/fetch to the
+  app's API, the ones that return the content). Wait until they are finished; use `browser_network_clear` before the
+  action so the list only holds what the action started.
+- Then wait for the content signal (`browser_wait_for` with text, or `browser_find` that the content is there), and
+  take the snapshot only then. A snapshot taken right after a click is a frame, not a fact.
+- Observations record the ready signal: `(observed after <signal>, ...)`. A fact with no signal is not recorded.
+- When the first read shows less than expected (empty, a missing field, a logo not there), do not record it yet and do
+  not raise a question yet. Wait for readiness, read again, and only then decide. Mention in the report that the first
+  read was too early, with what was missing.
+- Do it for every profile: loading time differs between profiles and environments.
+
+## In the case
+Steps and targets state their ready signal: `Ready when: <signal>` under the step, or the target card's `Ready when`.
+Example: `Ready when: the composer's "To" field is visible and the logo image has loaded.` It is what `/gen-spec` turns into
+`ready` and `responses`.
+
+**A ready signal is when to look, `## Expected` is what must hold.** Write the shortest positive signal that proves the
+content arrived (one element, one image, one first row): no counts, no negatives, no "and everything else is right". The
+requirement itself lives in `## Expected`, and a check may repeat the same element the signal names — one is the wait,
+the other the assertion. A ready signal is never the only place where a required behaviour is written down.
+
+A step that loads something and has no `Ready when` is read too early by whoever replays it: `/gen-spec` then waits for
+the step's text alone, and a check on what only appears later fails or records a false "empty". Add one to every step
+whose action opens a page, a dialog, a tab, a list or a preview.
+
+## Generating (spec code)
+Use `actAndWait` and `expectNotBusy` from `@asrunjs/asrun/ready`, and `verifyDownload` from `@asrunjs/asrun/downloads`:
+
+```ts
+// ready: the composer shows its recipient field and the logo image has loaded
+const composer = page.getByRole('dialog', {name: 'Email PDF'});
+await actAndWait(page, () => option.click(), {
+  responses: [/\/api\/documents\/[^/]+\/email-preview/],
+  ready: [composer.getByRole('textbox', {name: 'To'}), logo],
+});
+await expectImageLoaded(logo);
+```
+
+- Register the response wait **before** the action (`actAndWait` does).
+- Every action that opens a dialog, a tab, a menu with data, a list or a preview waits for its key requests and its content
+  signal. The request URL patterns come from `browser_network_requests` during exploration, not from guesses; if none was
+  seen (the action was not run), say "not verified on the page" in the report.
+- Never `waitForTimeout`, never `networkidle`. They wait for time or for silence, not for the content. `pnpm spec:lint` fails both.
+- Never `if (await x.isVisible()) ...` to decide something that may not have loaded yet. Wait for a ready signal, then branch.
+  Where an element is genuinely optional, say what proves the page finished (`// ready: ...`) before looking for it.
+- `locator.isVisible()` and `isHidden()` answer for this instant only. Their `timeout` option is deprecated and ignored:
+  `isVisible({timeout: 3_000})` does not wait 3 seconds. Never write it, and never use `.catch(() => false)` to make it
+  look like a wait. `pnpm spec:lint` fails both.
+- An optional confirmation (see below) is handled with `clickOptionalUntilHidden`, not with `isVisible`.
+
+### Optional confirmations (a dialog that may or may not show up)
+Closing a composer, leaving an editor or deleting something can raise "Discard draft?", "Are you sure?" or nothing at all,
+and the dialog can show up a second or two after the click. A check made right after the click sees "no dialog" and skips
+it, then the next check (the composer is closed) races a dialog that appears later and fails.
+
+The click on the confirmation and the check that the action finished go into **one retry loop**:
+
+```ts
+await composer.getByRole('button', {name: 'close', exact: true}).click();
+await clickOptionalUntilHidden(page.getByRole('button', {name: 'Discard', exact: true}), composer, {
+  message: 'The email composer did not close',
+});
+```
+
+- Each round: click the confirmation if it is visible now, then check that the target is hidden. A late dialog is clicked
+  in a later round; no dialog passes in the first round.
+- Never decide "there is no dialog" from one look, and never wait a fixed time for it.
+- The same holds for any other optional modal (for example "Add to Business Tracker" after publishing): when the case says
+  it opens, assert it with a waiting `expect(...).toBeVisible({timeout})`; when it may or may not open, use a loop that
+  also checks the next page state, or wait for the signal that proves the action finished (URL, heading), then look.
+- A check for absence needs a positive ready signal in front of it (`// ready: <signal>`).
+- A new tab: wait for the page event first (`context.waitForEvent('page')`), then for its URL, then for its content signal.
+- A download is verified with `verifyDownload` (below), never with a bare `waitForEvent('download')`.
+
+## Downloads
+Any download (PDF, image, CSV, ZIP), in exploration and in the spec, is verified in five parts, and the verification
+step fails as a whole when any part fails or times out:
+1. wait for the download to start after the click;
+2. wait for the download to finish;
+3. check that the file exists and has content;
+4. check that the file is valid for its kind (an image has the right signature; a ZIP/CSV likewise; a PDF starts with `%PDF-`,
+   ends with `%%EOF` and **opens with at least one page**), and run the case's own validation if there is one;
+5. any failure or timeout of 1 to 4 fails the verification with a message that names the stage.
+
+`verifyDownload(page, trigger, {kind, fileName?, minBytes?, validate?})` does exactly this. Name the file type in the
+case (`kind`), and describe in a target card what the file must contain.
+
+### PDF content: read it like a person (rendered images and extracted text)
+A PDF check never stops at "it is a PDF". `verifyDownload(..., {kind: 'pdf'})` returns `file.pdf`, and
+`expectPdf(file.pdf!, {...})` from `@asrunjs/asrun/pdf` then:
+- **renders the pages to images** (scale 2, white background) and, for every region check, fails when the region is blank
+  and compares it with the profile's baseline image (2% tolerance; the first run with `--update-snapshots` creates the
+  baseline and a person looks at it, like any other baseline);
+- **extracts the text** of every page and checks `textContains` / `textNotContains` (the names of the other profiles, for
+  example).
+Regions are fractions of the page from the top-left corner; `corner('top-left')` is the usual logo corner.
+
+**Which pages are checked is the case's decision, case by case:**
+- The case says ONLY certain pages in strong words (a requirement: "only", "exactly", "must be on the first page", "the
+  logo is on the first and last page and nowhere else"): check just those (`pages: 'first' | 'last' | [1, 3]`), and put
+  `// pages: <the case's words>` above the check so a reviewer can see where the limit comes from.
+- The case names pages softly ("should", "always", "usually", "typically", "normally", "e.g.") or names no page: check
+  **every page** (`pages: 'all'`, the default). The named page is then only the place where the check was first seen.
+- A page limit that comes from the agent's own reading of the case is not allowed. When it is unclear whether a wording is
+  a strong requirement, check all pages and put the doubt in a `[non-blocking]` TODO.
+
+**While exploring, the agent looks at the PDF too:** save the downloaded file under `.explore/` (`download.saveAs(...)`
+in the same `browser_run_code_unsafe` call that waits for the download), run
+`pnpm pdf:render <file> --out .explore/targets/<case-id>/<name> --pages all --corner top-left`, then **open the page
+images** and say in the card where the logo really is on each page, which pages have it and which do not, and what the
+text shows. The rendered pages are the card's `Reference`. If the logo is not where the case says, that is a question.
+
+While exploring, do the same by hand: click, wait for the download event, see the file finish, read its size and its first
+bytes. Record "(observed: <file name>, <size>, valid <kind>)".
+
+## Healing
+A failure of the kind "missing", "empty", "not visible", "wrong count", "timeout waiting for X" is first a suspected
+readiness problem, then a suspected product problem:
+1. Read the failure screenshot and video: was the page still loading (a spinner, a skeleton, an empty frame)?
+2. Run the failing step by hand with the readiness protocol above and compare.
+3. Only when the content is complete and still not what the case says is it a test-expectation or product matter.
+4. A readiness fix goes into the spec as `actAndWait` / a ready signal, never as a longer timeout alone and never as a sleep.