@tamsensedev/runner 0.13.0 → 0.18.0

package/library/skills/design-review/references/critique-passes.md

@@ -1,101 +1,101 @@
-# Critique passes
-
-Read this when judging screenshots. Make each pass on its own; do not blend them. Write the answers down: a critique you only think through drifts toward approving your own work.
-
-Judge the pictures. If a problem shows in a screenshot, it is real, whatever the code says. Judge against the product's own design language (step 2 of the main skill), not a generic ideal.
-
-## The whole screen first
-
-Open the desktop first screen, then the full page, then the phone.
-
-1. **One second, then five.** Glance and look away: what did you see? There should be one answer (a word, a number, an object). If the answer is "a screen", there is no focal point. Then give it five seconds as a stranger: can you say what this is, who it is for and what to do next?
-2. **Squint.** Blur your attention until text becomes grey bars. The screen should reduce to two or three masses with clear size differences, in the right order. Many similar masses mean everything is medium and nothing leads.
-3. **Cover the name.** Could this screen belong to a competitor or another industry? If swapping the product name and one noun gives an equally valid screen, the free choices were defaulted.
-4. **Edges.** Follow the left edge of every text block down the screen. Count the distinct x positions: two or three, reused on purpose, is composed; six means things were placed one at a time. Check right edges of rows of cards too.
-5. **Space and frame.** Related things close, unrelated far. Gaps between sections clearly larger than gaps inside them. Any hole (empty by accident, beside a short column or under a removed element) rather than a rest (empty by decision)? Equal outer margins? A section using half the width with the other half empty?
-6. **Type.** Is the jump from body to title decisive? More than five or six sizes? Weights doing hierarchy work, or size alone? A heading with one orphan word on its last line? Paragraphs wider than about 75 characters? Text in a grey too light to read?
-7. **Colour.** Name the proportions: what holds most of the surface, what supports, where the accent is. An accent in ten places means nothing; on the one action and one detail it means "here". Is colour carrying meaning (status, selection, data) or decorating?
-8. **Sameness.** Write one word for each block's layout (split, list, table, grid, statement). The same word three times in a row is the template showing, unless the blocks really are peers.
-9. **Phone.** Is the phone layout a composition of its own (navigation folded, its own line breaks, the first screen still one clear thing), or the desktop squeezed? Anything running off the edge, a row scrolling sideways, a tap target smaller than 44px?
-10. **Collisions.** Anything overlapping a heading, a label or a button at any width? Text clipped by its container? A sticky header covering focused content?
-11. **Substance.** Does every block deliver its information completely and at a readable size? Is the primary action a real button on the first screen? Is any content invented (metrics, customers, quotes) or placeholder text left in?
-
-## The lenses
-
-Then one lens at a time, asking each time: was this decided, or defaulted?
-
-- **Hierarchy.** Name the focal element. Does it win through size, weight, contrast or space? Is everything else demoted (secondary actions quieter, metadata muted)? Can you tell primary, secondary and metadata apart without reading?
-- **Typography and colour.** A real scale or near-equal sizes? A text-colour ramp (primary, secondary, muted) or just "text" and "grey text"? Tabular figures on numbers that update or align? One accent with a job?
-- **Surfaces and depth.** One depth strategy (borders, tone steps or shadows), held everywhere? Borders findable but not loud? Nested radii concentric? Shadows only on floating layers?
-- **Layout and rhythm.** Tight inside groups, generous between them? Shared edges? A grid that fits the item count, no orphan cells, no stretched cards with blank bands?
-- **States and polish.** Hover, focus, active, disabled on every control? Loading, empty, error, long content on every data block? Hit areas? Press feedback? Motion short and purposeful?
-- **Content and honesty.** Every visible string read as a user would: do the title, body and numbers tell one coherent story? Do numbers add up and agree where shown twice? Copy in the product's voice, sentence case unless the product does otherwise?
-- **System fit.** Uses the project's components, tokens and patterns? Looks like it shipped with its sibling screens? No hand-rolled control where the project has one?
-
-## Extra questions for app screens
-
-From `app-screens`:
-
-1. Is the screen's one question answered by the biggest thing on it, and is that read first?
-2. Do all blocks share the screen's edges, with no dead strip, orphan cell or stretched card?
-3. Is colour only on data, status and the one primary action?
-4. Do numbers add up, line up digit for digit, and name their baseline?
-5. Is every zero a zero and every missing value a dash?
-6. Does every legend swatch match its mark, with no colliding labels?
-7. On the phone, is navigation folded and does each block still answer its question?
-8. Is the most frequent job one click from the first screen?
-
-## Extra questions for marketing pages
-
-- Does the first screen carry a clear title in the page's `h1`, a sentence saying what this is, and one primary action?
-- Does every section have a heading that names it, and a composition different from its neighbours?
-- Is each screen of the desktop page full (one dominant thing and its content), not a narrow column of small text with dead ground either side?
-- Is every image doing a job (showing the product, proving a claim), with consistent crops? Any grey boxes or fake dashboards?
-- Does the idea carry past the first screen into pricing, FAQ and footer, or do they become stock blocks?
-
-## Cognitive load
-
-Count the failures; two or three mean the screen needs simplifying, four or more is a blocker for a task screen:
-
-- **Single focus**: the main task can be done without competing elements pulling attention.
-- **Chunking**: information comes in groups of about four or fewer.
-- **Grouping**: related items are visibly together.
-- **Visible priority**: it is immediately clear what matters most.
-- **One decision at a time**: the person is not asked to read, decide and navigate at once.
-- **Few choices**: about four or fewer options at a decision point (one primary action, one or two secondary, the rest in a menu).
-- **No memory bridge**: nothing from a previous screen has to be remembered to act here.
-- **Progressive disclosure**: rare detail is revealed when needed, not shown upfront.
-
-## Writing it down
-
-```
-Round n
-Seen in one second: ...
-Focal element: ... (wins / does not win, because ...)
-Layout words by block: header=... / list=... / ...
-Problems (most visible first), each with screenshot and fix:
-1. ...
-2. ...
-3. ...
-```
-
-Name problems the way a designer would to a colleague: "the supporting text starts 24px left of the title's edge", "the empty state is the third bordered box in a row", "on the phone the Save button sits under the fold". "Could be more polished" is not a finding.
-
-## What to fix first
-
-Later items cannot rescue earlier ones:
-
-1. The focal point and hierarchy: make the big thing bigger and the small things fewer.
-2. Layout: shared edges, spacing between and within groups, holes, grid fit.
-3. Typography: scale contrast, line breaks, measure.
-4. Colour: proportions and accent discipline.
-5. States and details: focus, hover, empty, error, small alignments, phone refinements.
-6. Motion, last.
-
-When removing something leaves a gap, close the gap or enlarge what remains; do not refill it with an ornament.
-
-## When to stop
-
-At most three rounds of critique, fix the top three, re-render, critique. Stop early when a round finds nothing a stranger would notice. If problems remain after round three, list them plainly in the report; do not round up.
-
-Sources: adapted from Leonxlnx/taste-skill references/critique.md and app-screens.md (MIT, changed: scoring and caps tied to its inspector removed, product-screen questions added), Dammyjay93/interface-design design-review lenses (MIT) and the cognitive load checklist in pbakaus/impeccable critique reference (Apache-2.0, changed: rewritten).
+# Critique passes
+
+Read this when judging screenshots. Make each pass on its own; do not blend them. Write the answers down: a critique you only think through drifts toward approving your own work.
+
+Judge the pictures. If a problem shows in a screenshot, it is real, whatever the code says. Judge against the product's own design language (step 2 of the main skill), not a generic ideal.
+
+## The whole screen first
+
+Open the desktop first screen, then the full page, then the phone.
+
+1. **One second, then five.** Glance and look away: what did you see? There should be one answer (a word, a number, an object). If the answer is "a screen", there is no focal point. Then give it five seconds as a stranger: can you say what this is, who it is for and what to do next?
+2. **Squint.** Blur your attention until text becomes grey bars. The screen should reduce to two or three masses with clear size differences, in the right order. Many similar masses mean everything is medium and nothing leads.
+3. **Cover the name.** Could this screen belong to a competitor or another industry? If swapping the product name and one noun gives an equally valid screen, the free choices were defaulted.
+4. **Edges.** Follow the left edge of every text block down the screen. Count the distinct x positions: two or three, reused on purpose, is composed; six means things were placed one at a time. Check right edges of rows of cards too.
+5. **Space and frame.** Related things close, unrelated far. Gaps between sections clearly larger than gaps inside them. Any hole (empty by accident, beside a short column or under a removed element) rather than a rest (empty by decision)? Equal outer margins? A section using half the width with the other half empty?
+6. **Type.** Is the jump from body to title decisive? More than five or six sizes? Weights doing hierarchy work, or size alone? A heading with one orphan word on its last line? Paragraphs wider than about 75 characters? Text in a grey too light to read?
+7. **Colour.** Name the proportions: what holds most of the surface, what supports, where the accent is. An accent in ten places means nothing; on the one action and one detail it means "here". Is colour carrying meaning (status, selection, data) or decorating?
+8. **Sameness.** Write one word for each block's layout (split, list, table, grid, statement). The same word three times in a row is the template showing, unless the blocks really are peers.
+9. **Phone.** Is the phone layout a composition of its own (navigation folded, its own line breaks, the first screen still one clear thing), or the desktop squeezed? Anything running off the edge, a row scrolling sideways, a tap target smaller than 44px?
+10. **Collisions.** Anything overlapping a heading, a label or a button at any width? Text clipped by its container? A sticky header covering focused content?
+11. **Substance.** Does every block deliver its information completely and at a readable size? Is the primary action a real button on the first screen? Is any content invented (metrics, customers, quotes) or placeholder text left in?
+
+## The lenses
+
+Then one lens at a time, asking each time: was this decided, or defaulted?
+
+- **Hierarchy.** Name the focal element. Does it win through size, weight, contrast or space? Is everything else demoted (secondary actions quieter, metadata muted)? Can you tell primary, secondary and metadata apart without reading?
+- **Typography and colour.** A real scale or near-equal sizes? A text-colour ramp (primary, secondary, muted) or just "text" and "grey text"? Tabular figures on numbers that update or align? One accent with a job?
+- **Surfaces and depth.** One depth strategy (borders, tone steps or shadows), held everywhere? Borders findable but not loud? Nested radii concentric? Shadows only on floating layers?
+- **Layout and rhythm.** Tight inside groups, generous between them? Shared edges? A grid that fits the item count, no orphan cells, no stretched cards with blank bands?
+- **States and polish.** Hover, focus, active, disabled on every control? Loading, empty, error, long content on every data block? Hit areas? Press feedback? Motion short and purposeful?
+- **Content and honesty.** Every visible string read as a user would: do the title, body and numbers tell one coherent story? Do numbers add up and agree where shown twice? Copy in the product's voice, sentence case unless the product does otherwise?
+- **System fit.** Uses the project's components, tokens and patterns? Looks like it shipped with its sibling screens? No hand-rolled control where the project has one?
+
+## Extra questions for app screens
+
+From `app-screens`:
+
+1. Is the screen's one question answered by the biggest thing on it, and is that read first?
+2. Do all blocks share the screen's edges, with no dead strip, orphan cell or stretched card?
+3. Is colour only on data, status and the one primary action?
+4. Do numbers add up, line up digit for digit, and name their baseline?
+5. Is every zero a zero and every missing value a dash?
+6. Does every legend swatch match its mark, with no colliding labels?
+7. On the phone, is navigation folded and does each block still answer its question?
+8. Is the most frequent job one click from the first screen?
+
+## Extra questions for marketing pages
+
+- Does the first screen carry a clear title in the page's `h1`, a sentence saying what this is, and one primary action?
+- Does every section have a heading that names it, and a composition different from its neighbours?
+- Is each screen of the desktop page full (one dominant thing and its content), not a narrow column of small text with dead ground either side?
+- Is every image doing a job (showing the product, proving a claim), with consistent crops? Any grey boxes or fake dashboards?
+- Does the idea carry past the first screen into pricing, FAQ and footer, or do they become stock blocks?
+
+## Cognitive load
+
+Count the failures; two or three mean the screen needs simplifying, four or more is a blocker for a task screen:
+
+- **Single focus**: the main task can be done without competing elements pulling attention.
+- **Chunking**: information comes in groups of about four or fewer.
+- **Grouping**: related items are visibly together.
+- **Visible priority**: it is immediately clear what matters most.
+- **One decision at a time**: the person is not asked to read, decide and navigate at once.
+- **Few choices**: about four or fewer options at a decision point (one primary action, one or two secondary, the rest in a menu).
+- **No memory bridge**: nothing from a previous screen has to be remembered to act here.
+- **Progressive disclosure**: rare detail is revealed when needed, not shown upfront.
+
+## Writing it down
+
+```
+Round n
+Seen in one second: ...
+Focal element: ... (wins / does not win, because ...)
+Layout words by block: header=... / list=... / ...
+Problems (most visible first), each with screenshot and fix:
+1. ...
+2. ...
+3. ...
+```
+
+Name problems the way a designer would to a colleague: "the supporting text starts 24px left of the title's edge", "the empty state is the third bordered box in a row", "on the phone the Save button sits under the fold". "Could be more polished" is not a finding.
+
+## What to fix first
+
+Later items cannot rescue earlier ones:
+
+1. The focal point and hierarchy: make the big thing bigger and the small things fewer.
+2. Layout: shared edges, spacing between and within groups, holes, grid fit.
+3. Typography: scale contrast, line breaks, measure.
+4. Colour: proportions and accent discipline.
+5. States and details: focus, hover, empty, error, small alignments, phone refinements.
+6. Motion, last.
+
+When removing something leaves a gap, close the gap or enlarge what remains; do not refill it with an ornament.
+
+## When to stop
+
+At most three rounds of critique, fix the top three, re-render, critique. Stop early when a round finds nothing a stranger would notice. If problems remain after round three, list them plainly in the report; do not round up.
+
+Sources: adapted from Leonxlnx/taste-skill references/critique.md and app-screens.md (MIT, changed: scoring and caps tied to its inspector removed, product-screen questions added), Dammyjay93/interface-design design-review lenses (MIT) and the cognitive load checklist in pbakaus/impeccable critique reference (Apache-2.0, changed: rewritten).

package/library/skills/design-review/references/screenshot-procedure.md

@@ -1,121 +1,121 @@
-# Rendering screens for a design check
-
-Read this when you need screenshots of changed screens at desktop, tablet and phone widths, and their key states. The output is pictures you open with the Read tool and judge.
-
-## Ground rules
-
-Everything about running the app comes from the `ui-testing` skill and holds here too: headless only, the project's own start command on a free port, no new dependencies or browser downloads (if the project has no Playwright but `TAMSENSE_PLAYWRIGHT` is set, the headless check uses the `playwright-core` and browser the TAMsense runner installed outside the project), outputs only in a new folder under the OS temp directory, nothing written to shared systems, the server stopped at the end by its process id (never kill processes by name: other programs on the computer may be using the same runtime), `git status` clean. In a review step, also change nothing in the repository (no fixtures, seed edits or config): states come from intercepting responses in the browser.
-
-If the project uses Storybook for the changed components, story URLs (`/iframe.html?id=<story-id>`) are often the quickest way to see each state; render them the same way.
-
-In a TAMsense run the browser is recorded for the task too: open contexts through the recorder with a title and a purpose, as [the ui-testing recording reference](../../ui-testing/references/recording.md) shows. For a design check the title names the variant and the purpose names the question, for example "Design option 2" and "Denser table for the invoices list, compared with option 1". Mark each state as you reach it (`mark('Empty state')`, `mark('Error state')`), and add `video: true` when the screen draws on a canvas, shows a map or a video, or embeds another site.
-
-## What to capture
-
-For each changed screen:
-
-| Width | Name |
-|---|---|
-| 1440 | desktop |
-| 768 | tablet |
-| 390 | phone |
-
-At each width: the first screen (what is visible without scrolling) and the full page. For pages taller than about four screens, also capture screen-height slices, because one very tall image is hard to judge.
-
-Then the states the change affects, at desktop and phone at least:
-
-- **Empty**: the endpoint returns no items.
-- **Loading**: the endpoint does not answer while the screenshot is taken.
-- **Error**: the endpoint returns a 500 (and a 403 if permissions matter).
-- **Long content**: the real response with worst-case values swapped in (long names, unbreakable emails, big numbers, missing optional fields; see `interface-polish`).
-- **Interaction**: hover on the primary action, keyboard focus on the first controls (press Tab), an open menu or dialog if the change adds one.
-- **Theme**: dark mode if the product supports it; reduced motion if the change adds motion.
-
-## Using the ui-testing headless check
-
-Use the script in the `ui-testing` skill's `references/headless-check.md`, written to your temp folder, with these settings:
-
-- `CONFIG.widths`: `[1440, 768, 390]`.
-- `CONFIG.paths`: the routes of the changed screens.
-- `CONFIG.title` and `CONFIG.purpose`: the variant and the question this render answers ("Design option 1", "Checking the billing page after the redesign").
-- If the screens need a signed-in user, follow the auth section of `ui-testing` (a storage state saved in the temp folder, passed to `browser.newContext`).
-- If `CHROME_PATH` is set, add `executablePath: process.env.CHROME_PATH` to the launch options.
-- For dark mode, add `colorScheme: 'dark'` to `browser.newContext`; for reduced motion, `reducedMotion: 'reduce'`.
-
-Its own screenshot is the full page in the final state of `steps`. Capture the first screen and the states inside `steps`, and leave the page in its normal state at the end:
-
-```js
-async function steps(page, { path, width, mark }) {
-    const slug = path.replace(/[^a-z0-9]+/gi, '-').replace(/^-+|-+$/g, '') || 'home'
-    const shot = async (state) => {
-        await mark(`${state} state`)
-        await page.screenshot({
-            path: join(CONFIG.outDir, `${slug}-${width}-${state}.png`),
-            animations: 'disabled',
-        })
-    }
-
-    await page.evaluate(async () => { await document.fonts.ready })
-    await shot('fold')
-    if (path !== '/billing') return
-
-    await page.getByRole('button', { name: 'Create invoice' }).hover()
-    await shot('hover')
-    await page.keyboard.press('Tab')
-    await page.keyboard.press('Tab')
-    await shot('focus')
-
-    const api = '**/api/invoices**'
-
-    await page.route(api, (route) => route.fulfill({ json: { items: [], total: 0 } }))
-    await page.reload()
-    await page.getByText('No invoices').waitFor()
-    await shot('empty')
-    await page.unroute(api)
-
-    await page.route(api, (route) => route.fulfill({
-        status: 500, contentType: 'application/json', body: '{"error":"Internal error"}',
-    }))
-    await page.reload()
-    await page.getByRole('button', { name: 'Try again' }).waitFor()
-    await shot('error')
-    await page.unroute(api)
-
-    await page.route(api, () => {})
-    await page.reload({ waitUntil: 'domcontentloaded' })
-    await page.locator('[aria-busy="true"]').first().waitFor()
-    await shot('loading')
-    await page.unroute(api)
-
-    await page.route(api, async (route) => {
-        const response = await route.fetch()
-        const json = await response.json()
-        json.items[0].customer = 'Aleksandra Wiśniewska-Kowalczyk Consulting GmbH'
-        json.items[1].email = 'bartholomew.fitzgerald@northwind-industries-holdings.example.com'
-        json.items[2].amount = 12345678.9
-        await route.fulfill({ response, json })
-    })
-    await page.reload()
-    await page.getByText('Aleksandra').waitFor()
-    await shot('long')
-    await page.unroute(api)
-
-    await page.reload()
-}
-```
-
-Adapt the endpoint pattern, the response shape and the readiness checks (`waitFor` on the element that proves each state) to the real screen; find the endpoint in the code or the failed-request list of a first run. The loading route never answers on purpose, so the following `reload` discards it.
-
-If the data is rendered on the server and cannot be intercepted in the browser, use the states the project's stories, fixtures or seed data already provide. In a code step you may add a fixture where the project keeps fixtures; in a review step, list the states you could not render.
-
-## Naming and reporting
-
-Files are named `<screen>-<width>-<state>.png` (for example `billing-390-error.png`) so findings can cite them. Put the temp folder path in the report, describe what each cited screenshot shows, and delete the folder when the step ends unless the task asks to keep artifacts.
-
-When you attach screenshots to the task with `attach_screenshot`, give each a title and a purpose that say what it shows and why: "Design option 1" with "Billing page at 1440, the denser table", not "billing-1440-fold". The replays of the render are attached by themselves.
-
-## When rendering is impossible
-
-If the app needs services that are not available, the build fails, Playwright is not installed (neither in the project nor through `TAMSENSE_PLAYWRIGHT`), or no browser can run: say exactly that in the report, review from the code, and mark every visual finding as inferred rather than seen.
-
-Sources: written for this library on top of the `ui-testing` headless check; the three widths and the screenshot-first critique follow Leonxlnx/taste-skill (MIT) inspect and critique references, described in words instead of shipping its inspector.
+# Rendering screens for a design check
+
+Read this when you need screenshots of changed screens at desktop, tablet and phone widths, and their key states. The output is pictures you open with the Read tool and judge.
+
+## Ground rules
+
+Everything about running the app comes from the `ui-testing` skill and holds here too: headless only, the project's own start command on a free port, no new dependencies or browser downloads (if the project has no Playwright but `TAMSENSE_PLAYWRIGHT` is set, the headless check uses the `playwright-core` and browser the TAMsense runner installed outside the project), outputs only in a new folder under the OS temp directory, nothing written to shared systems, the server stopped at the end by its process id (never kill processes by name: other programs on the computer may be using the same runtime), `git status` clean. In a review step, also change nothing in the repository (no fixtures, seed edits or config): states come from intercepting responses in the browser.
+
+If the project uses Storybook for the changed components, story URLs (`/iframe.html?id=<story-id>`) are often the quickest way to see each state; render them the same way.
+
+In a TAMsense run the browser is recorded for the task too: open contexts through the recorder with a title and a purpose, as [the ui-testing recording reference](../../ui-testing/references/recording.md) shows. For a design check the title names the variant and the purpose names the question, for example "Design option 2" and "Denser table for the invoices list, compared with option 1". Mark each state as you reach it (`mark('Empty state')`, `mark('Error state')`), and add `video: true` when the screen draws on a canvas, shows a map or a video, or embeds another site.
+
+## What to capture
+
+For each changed screen:
+
+| Width | Name |
+|---|---|
+| 1440 | desktop |
+| 768 | tablet |
+| 390 | phone |
+
+At each width: the first screen (what is visible without scrolling) and the full page. For pages taller than about four screens, also capture screen-height slices, because one very tall image is hard to judge.
+
+Then the states the change affects, at desktop and phone at least:
+
+- **Empty**: the endpoint returns no items.
+- **Loading**: the endpoint does not answer while the screenshot is taken.
+- **Error**: the endpoint returns a 500 (and a 403 if permissions matter).
+- **Long content**: the real response with worst-case values swapped in (long names, unbreakable emails, big numbers, missing optional fields; see `interface-polish`).
+- **Interaction**: hover on the primary action, keyboard focus on the first controls (press Tab), an open menu or dialog if the change adds one.
+- **Theme**: dark mode if the product supports it; reduced motion if the change adds motion.
+
+## Using the ui-testing headless check
+
+Use the script in the `ui-testing` skill's `references/headless-check.md`, written to your temp folder, with these settings:
+
+- `CONFIG.widths`: `[1440, 768, 390]`.
+- `CONFIG.paths`: the routes of the changed screens.
+- `CONFIG.title` and `CONFIG.purpose`: the variant and the question this render answers ("Design option 1", "Checking the billing page after the redesign").
+- If the screens need a signed-in user, follow the auth section of `ui-testing` (a storage state saved in the temp folder, passed to `browser.newContext`).
+- If `CHROME_PATH` is set, add `executablePath: process.env.CHROME_PATH` to the launch options.
+- For dark mode, add `colorScheme: 'dark'` to `browser.newContext`; for reduced motion, `reducedMotion: 'reduce'`.
+
+Its own screenshot is the full page in the final state of `steps`. Capture the first screen and the states inside `steps`, and leave the page in its normal state at the end:
+
+```js
+async function steps(page, { path, width, mark }) {
+    const slug = path.replace(/[^a-z0-9]+/gi, '-').replace(/^-+|-+$/g, '') || 'home'
+    const shot = async (state) => {
+        await mark(`${state} state`)
+        await page.screenshot({
+            path: join(CONFIG.outDir, `${slug}-${width}-${state}.png`),
+            animations: 'disabled',
+        })
+    }
+
+    await page.evaluate(async () => { await document.fonts.ready })
+    await shot('fold')
+    if (path !== '/billing') return
+
+    await page.getByRole('button', { name: 'Create invoice' }).hover()
+    await shot('hover')
+    await page.keyboard.press('Tab')
+    await page.keyboard.press('Tab')
+    await shot('focus')
+
+    const api = '**/api/invoices**'
+
+    await page.route(api, (route) => route.fulfill({ json: { items: [], total: 0 } }))
+    await page.reload()
+    await page.getByText('No invoices').waitFor()
+    await shot('empty')
+    await page.unroute(api)
+
+    await page.route(api, (route) => route.fulfill({
+        status: 500, contentType: 'application/json', body: '{"error":"Internal error"}',
+    }))
+    await page.reload()
+    await page.getByRole('button', { name: 'Try again' }).waitFor()
+    await shot('error')
+    await page.unroute(api)
+
+    await page.route(api, () => {})
+    await page.reload({ waitUntil: 'domcontentloaded' })
+    await page.locator('[aria-busy="true"]').first().waitFor()
+    await shot('loading')
+    await page.unroute(api)
+
+    await page.route(api, async (route) => {
+        const response = await route.fetch()
+        const json = await response.json()
+        json.items[0].customer = 'Aleksandra Wiśniewska-Kowalczyk Consulting GmbH'
+        json.items[1].email = 'bartholomew.fitzgerald@northwind-industries-holdings.example.com'
+        json.items[2].amount = 12345678.9
+        await route.fulfill({ response, json })
+    })
+    await page.reload()
+    await page.getByText('Aleksandra').waitFor()
+    await shot('long')
+    await page.unroute(api)
+
+    await page.reload()
+}
+```
+
+Adapt the endpoint pattern, the response shape and the readiness checks (`waitFor` on the element that proves each state) to the real screen; find the endpoint in the code or the failed-request list of a first run. The loading route never answers on purpose, so the following `reload` discards it.
+
+If the data is rendered on the server and cannot be intercepted in the browser, use the states the project's stories, fixtures or seed data already provide. In a code step you may add a fixture where the project keeps fixtures; in a review step, list the states you could not render.
+
+## Naming and reporting
+
+Files are named `<screen>-<width>-<state>.png` (for example `billing-390-error.png`) so findings can cite them. Put the temp folder path in the report, describe what each cited screenshot shows, and delete the folder when the step ends unless the task asks to keep artifacts.
+
+When you attach screenshots to the task with `attach_screenshot`, give each a title and a purpose that say what it shows and why: "Design option 1" with "Billing page at 1440, the denser table", not "billing-1440-fold". The replays of the render are attached by themselves.
+
+## When rendering is impossible
+
+If the app needs services that are not available, the build fails, Playwright is not installed (neither in the project nor through `TAMSENSE_PLAYWRIGHT`), or no browser can run: say exactly that in the report, review from the code, and mark every visual finding as inferred rather than seen.
+
+Sources: written for this library on top of the `ui-testing` headless check; the three widths and the screenshot-first critique follow Leonxlnx/taste-skill (MIT) inspect and critique references, described in words instead of shipping its inspector.