Skip to content

docs(implement): drive T3 preview around hidden-tab, viewport and blur faults #55

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
leomontigatti merged 1 commit into from
Oct 27, 2026
Merged

docs(implement): drive T3 preview around hidden-tab, viewport and blur faults #55

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 23 additions & 13 deletions skills/implement/PREVIEW.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
9 changes: 8 additions & 1 deletion t3-dependencies.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading