From b4dc94c973b28c1dfc3483328164b17889d364bd Mon Sep 17 00:00:00 2001 From: Leo Monti <61606076+leomontigatti@users.noreply.github.com> Date: Tue, 27 Oct 2026 19:57:16 -0300 Subject: [PATCH] docs(implement): drive T3 preview past hidden-tab, viewport and blur faults Rubens' PRD #16 verification on 2026-10-27 found clicks stalling in a tab that draws no frames, preview_resize reporting a width the page did not get, and blurred captures. PREVIEW.md now targets refs or CSS selectors, tells the two click-timeout causes apart, checks innerWidth, falls back to the browser CLI for blurred captures, and reads state with preview_evaluate. The trial entry in t3-dependencies.md records the faults. Co-Authored-By: Claude Opus 5.5 --- skills/implement/PREVIEW.md | 36 +++++++++++++++++++++++------------- t3-dependencies.md | 9 ++++++++- 2 files changed, 31 insertions(+), 14 deletions(-) diff --git a/skills/implement/PREVIEW.md b/skills/implement/PREVIEW.md index cf34117..7e9b1d2 100644 --- a/skills/implement/PREVIEW.md +++ b/skills/implement/PREVIEW.md @@ -24,25 +24,35 @@ and open the final report with the refusal's exact text. user should watch. Keep the returned `tabId` and pass it on every call; parallel subagents each open their own tab (`reuseExistingTab: false`) and finish driving before they report: a subagent resumed later by its own background task has lost the preview tools. -2. **Size** the viewport the screen is designed for with `preview_resize`, once: it holds across - navigations and sign-ins. Check a dense screen (a table, a long row) at the narrower width the - project names too. +2. **Size** the viewport the screen is designed for with `preview_resize`, once: it is meant to hold + across navigations and sign-ins. Read the width the page laid out at with `preview_evaluate` + (`innerWidth`), before each capture too: the response's `viewport` can say 1280x800 whatever + the page got, and the page sometimes lays out at 1280 after a resize to 1440. Check a dense + screen (a table, a long row) at the narrower width the project names too. 3. **Capture the before**, before the first edit: `preview_snapshot` with `save: true`, its `screenshotPath` the evidence file, or the browser CLI when `docs/agents/verification.md` § Evidence names it. The preview saves every capture at most 1280 px wide, scaling a wider - viewport down. + viewport down. When a capture comes out blurred, take the before and the after both with the + fallback § Drive names for outside T3: the two sides of a comparison come from one tool. 4. **Drive** the flow with `preview_act` (`action`: `click`, `type`, `select`, `press`) and - `preview_navigate`, targeting elements by the `aria-ref` refs of the latest `preview_snapshot`. - Refresh the snapshot after a navigation. Before every capture or assertion, `preview_wait_for` - the text, locator or URL the step should produce, one only the main content shows (a - navigation label matches before the page loads). Click a menu item by a ref from a snapshot - taken while the menu is open, or by a role locator: the snapshot's tree stops at 10 000 + `preview_navigate`, targeting elements by the `aria-ref` refs of the latest `preview_snapshot` + or by CSS selectors (`#email`, `main button[type=submit]`); role locators + (`role=button[name=…]`) are the ones that time out. Refresh the snapshot after a navigation. + Before every capture or assertion, `preview_wait_for` the text, locator or URL the step should + produce, one only the main content shows (a navigation label matches before the page loads). Click a menu item by a ref from a snapshot + taken while the menu is open, or by a CSS selector: the snapshot's tree stops at 10 000 characters, so a long page leaves a popover without refs. A menu that closed in between fails - as a bare click timeout: reopen it and click again. A role locator can time out on a visible - button too; click it by its ref. + as a bare click timeout: reopen it and click again. + A click that times out on `locator.scrollIntoViewIfNeeded` has two causes that look the same. + The target is not there as named (a wrong name, another user than you assumed): check it in a + snapshot. Or the tab draws no frames: a tab the preview pane does not show runs no + `requestAnimationFrame`, `open: true` included, and a click waits for frames. Take a snapshot, + which paints one, and click again by ref or CSS selector. 5. **Diagnose from the page**: the snapshot's diagnostics for console errors, `preview_evaluate` - for anything the snapshot omits. Its console entries cover the tab's whole life: read their - timestamps to tell which screen logged what. Done when the touched screens show no error. + for page state (a text, a value, the URL): it costs a fraction of a snapshot, which carries up + to ~160 network entries and the console, so keep snapshots for refs and captures. The + snapshot's console entries cover the tab's whole life: read their timestamps to tell which + screen logged what. Done when the touched screens show no error. 6. **Capture the after**, same screen, data, account, size and tool as the before. A change to motion or interaction is a recording instead: `preview_recording_start` before the interaction, `preview_recording_stop` after. 7. **Close** the tab with `t3_preview_close`, then stop what § Launch started (§ Cleanup). diff --git a/t3-dependencies.md b/t3-dependencies.md index 4c08060..966ca41 100644 --- a/t3-dependencies.md +++ b/t3-dependencies.md @@ -441,11 +441,18 @@ T3 source paths below are in pingdotgg/t3code. system `ffmpeg`; Playwright's bundled one reads no MP4) and is lossy, so the browser CLI stays. The tools need "Agent browser access" on in Settings and, on Ubuntu 23.10+, a one-time `sudo t3 browser setup`; both were missing until 2026-10-16, so no thread used them before. + Rubens' PRD #16 run on 2026-10-27 (desktop 0.1.4-nightly.20261027.3783) met three faults, + each worked around in `PREVIEW.md`: a tab the preview pane does not show runs no + `requestAnimationFrame`, so clicks time out waiting for stable frames (with `open: true` too); + after `preview_resize` to 1440×900 the response always said 1280x800 and the page laid out at + either width; and mid-session captures came out blurred on a page with no CSS filters, where + `playwright-cli` took the same screens sharp at 1440×900. - **Used by:** `skills/implement/PREVIEW.md`; `skills/implement/SKILL.md` § 4; `contract.md` (the `verification.md` row) - **Would improve if:** both hold, in the installed T3: a snapshot renders `backdrop-filter` correctly at a desktop viewport (pingdotgg/t3code#20899), and it saves at the viewport's size - or the user accepts images 1280 px wide. A fix to #20899 alone leaves this entry + or the user accepts images 1280 px wide; and Rubens' three faults are gone (a hidden tab draws + frames, `preview_resize` holds and reports the width the page gets, captures stay sharp). A fix to #20899 alone leaves this entry **watching** while the cap stands; ask the user about the 1280 px images. **Ready** only once en-escena's dialog probe passes (`/administracion/resultados`, Acciones → Descargar, 1440×900). Adoption is then two steps: first each project's § Evidence