composing-evidence

Composing Evidence

You name page elements and write words. Fast Browser measures them, crops to the card that holds them, and lays out every mark and label. On a live page you never place anything by pixel.

The pipeline

1. Choose selectors. On a large page a full browser_snapshot can run to tens of thousands of tokens; use browser_find, or a snapshot scoped to the section you need, instead. Choose one for each thing the brief names and one for each personal detail the frame will hold, named in the brief or not, all in the first capture (see redact).
2. Capture. Call browser_capture_evidence with { targets: { <key>: "<selector>" }, frame: "auto", out: "<board>.c1" }. out is a plain file name. The tool screenshots the viewport at 2x, measures each target, and writes <board>.c1.png and <board>.c1.capture.json (the sidecar) into ~/.fast-browser/screenshots/. If the tool is not in your tool list, run fast-browser setup, ask the human to restart the Fast Browser session, and capture once it is back.
3. Check the return. Never edit the sidecar. A return is finished only when missed is empty, frameSnap is not union and there is no failedStep, and a thin strip the tool chose has had its retry or was left for the hiding budget (below); until then fix the cause, capture again, and write no spec. Remove a key the board does not need from targets. If the same key misses on the second capture, report it and stop that board; other boards in the same job continue. Do not compose around it.
   • It has failedStep: read error, then fix what that step names (args, resolve, frame, measure).
   • failedStep: "frame" with frameSnap: "too-large": the targets cannot share one viewport-sized frame. Enlarge the viewport with browser_resize, or split them into separate boards.
   • failedStep: "frame" saying the frame selector is larger than the viewport: pick a smaller element, or enlarge the viewport with browser_resize.
   • failedStep: "frame" saying the frame selector does not contain every target: the frame is too tight. Pass, once, the next ancestor that holds each target's whole box (for a tab or link in a strip, the header region that holds the strip and the page title). Another selector for the same element is not a fix. If that fails too, report it and stop that board.
   • A key is in missed as no-match or ambiguous: the selector is wrong. Fix it, scoping to a unique container. For ambiguous, count says how many elements matched; read the structure of that region (browser_find, or a browser_snapshot scoped to it) before the second capture, then scope to the smallest element that holds the wanted match and none of the others. Changing the words inside the same kind of selector is not a fix.
   • A key is in missed as not-visible (zero-size box): the element is collapsed or hidden. Open, expand or reveal it first.
   • A key is in missed as out-of-view: it fell outside the viewport once the frame was centred, so the targets are too far apart for one view. Pass a tighter frame, enlarge the viewport with browser_resize, or split into separate boards.
   • failedStep: "resolve" or "frame" saying the element is inside a shadow root or an iframe: it cannot be a target. Name the element that hosts it (the custom element, or the iframe) instead.
   • frameSnap is union: pass frame: "<selector>" for the element that holds the targets and capture again. The frame from that capture is final, thin strip or not; if it is a thin strip, say so in the report. If that capture fails at frame saying the frame selector is larger than the viewport, try once more with a smaller element inside it that still holds every target: for a section heading, the heading's own header block with what sits beside it, not the whole section. Pick one that is not a thin strip; if the only one that fits is a thin strip, pass it, and its frame is final as above. Stop that board, and say so in the report, when that capture fails too, at any step (do not go one ancestor up from it), or when the budget is spent.
   • frame is a thin strip (far wider than it is tall, or cutting through the card) when the tool chose the frame, that is frameSnap is neither union nor selector: try once with frame: "<selector>" for the element that holds the targets. If that capture succeeds and is no better, capture once more with frame: "auto" to get the tool's frame back, and say so in the report. If it fails, the earlier files are untouched: keep them and say so in the report. This retry is required, not optional, unless the budget went to hiding personal details (see the hiding rule): a report that names a thin strip names its retry, or says the retry was skipped for budget.
   • The capture PNG shows a value the board compares wrapped onto two lines: widen the viewport with browser_resize until it sits on one line, and capture again. If a wider viewport leaves it wrapped, the page wraps it: write the value on one line in the mark's note and say there that the page wraps it.
   • The call fails with an error instead of a return (it timed out, the page moved while it was captured, the page lays out differently at 2x, the page is pinch-zoomed): do what the message says, then capture again once. If it fails the same way, report it and stop that board; other boards in the same job continue.
4. Keep the sidecar. The return carries its path as sidecar; carry that path forward. Compose refuses a sidecar whose image, frame, boxes or scale were changed afterwards.
5. Write the spec beside the sidecar, in ~/.fast-browser/screenshots/. capture names the sidecar by its file name only.
6. Render. fast-browser compose <spec.json>. If it lists problems, fix every one and run it again. Read any warnings it prints. Each warning names something compose could not lay out well; a tighter frame or a different mark usually clears it. The warning a panel is drawn small; frame the card that holds its marks means a panel shows too much to read at the size it is drawn. In a pair, capture that panel again with a tighter frame selector (in a pair of one region, capture both panels again on the same tighter region, with one selector where one names it on both pages; for a ticket image, shrink the panel's frame rectangle instead). A steps panel is already cropped to its marks, so there mark fewer things in the panel, or things closer together. The warning a crop edge cuts through content means a steps panel was cut at its marks' margin on a busy page: check that the cut hides nothing the step needs, and if it does, mark the element it cuts as well. If it says the renderer is not installed, run fast-browser setup.