The design language that makes your AI harness better at design.
JavaScript
DELTAS and contract: surfaces off the ancestor chain
Paul Bakaus75032980d53f
diff --git a/docs/CLI-CONTRACT.md b/docs/CLI-CONTRACT.mdindex 7c500753d..4d553295b 100644--- a/docs/CLI-CONTRACT.md+++ b/docs/CLI-CONTRACT.md@@ -339,6 +339,8 @@ Optional keys added later by engines (appended after the above): `ignoreValue` (- **Scan order.** The reveal sweep runs *before* anything is measured, and one post-reveal capture serves every pass: the rule pass, `content-hidden-at-rest`, and the visual-contrast pass all read that capture, so a hit test any of them answers is answered for all three. The JS ran the rule pass over a capture taken right after load, when a scroll-reveal section is still at opacity 0 and the element checks skip it; the rules now measure the page as a visitor who scrolls it sees it, which reports the faults inside revealed sections and no longer reports a fade-in as `buried-raster`. `content-hidden-at-rest` still measures what stays hidden after the reveal handlers ran. Phase names, profile events, and the order findings are emitted in are unchanged.- **Covered text and unread surfaces.** The element pass asks `elementsFromPoint` over a failing `low-contrast` run, at the points the `text-occlusion` grid asks for the same box, in the same hit-test rounds. Where every deciding point has an image, video, canvas, or opaque fill at full opacity above the text (not the element, a descendant or an ancestor), the text is covered at capture: no verdict, and the visual-contrast collector skips it too. Where every deciding point has paint beneath the text that is nobody's ancestor, lies above the surface the background walk used, and could change what the text sits on, no element-pass verdict is printed; a visual-contrast candidate is still measured. That paint is a picture (an image, video, canvas or SVG `image`, or a `url()` background drawn `no-repeat`, `cover`, `contain`, at a percentage or larger than 256px), a gradient or fill that moves the named colour by more than 24 summed over the channels once composited over it, or, where the walk named no single colour or only reached the page ground (`html`, `body`, the canvas), a gradient, fill or SVG shape it cannot compare. Texture is read past and the verdict stands: a gradient drawn in cells of at most 64px on both axes, a `repeating-*` gradient, a gradient whose stops are mostly transparent or that pairs a transparent stop with a stop within 3px, a `url()` repeated at a drawn size of at most 256px, anything with a `mask-image`, and a picture, gradient or shape at an effective opacity of 0.3 or less. Paint at alpha times opacity of 0.1 or less is a wash and is read past too. A layer that cannot be placed (a remote image tiled at its own size, an `image-set`) keeps the verdict. The snapshot records `maskImage` and `webkitMaskImage` for this. The run must lie wholly inside the viewport, every point must be answered, and at least half must find the text; otherwise, and for a run only partly under a layer, the verdict stands. The SAFE_TAGS path asks before the page claims a colour pair. `text-occlusion` counts a decorated box only where its captured rect holds the probe point, so an answer from a page that moved after the capture names no occluder.- **What is not painted at capture reports nothing.** The URL engine's element pass drops findings on an element the painted-at-capture predicate (`crates/core/src/browser/painted.rs`) says a visitor cannot see: `display: none` or `content-visibility: hidden` above it, `visibility: hidden` or `checkVisibility()` false, an effective opacity of 0.02 or less, a clipping ancestor with no area or no overlap, a box wholly outside the document, a 1px visually hidden box. The text measurements and `italic-serif-display` also need text and area; `layout-transition`, `bounce-easing`, `dark-glow` and `ai-color-palette` need area. `blinking-cursor` needs area, and its own opacity and a `visibility: hidden` its parent does not share do not hide it, so a cursor caught between blinks still reports. `kicker-above-heading` asks the same about the heading and the label above it. The page-level forms of `bounce-easing`, `dark-glow` and `pulsing-dot` report only when their selector matches at least one painted element (no area test, since the selector may name a pseudo-element); a form without a selector is unchanged. `text-occlusion` asks it about the covered text, every hit-test answer that covers it, each card a headline overhangs and each inline leak host, in addition to its own ancestor test; it also skips text under a `filter: blur()` of 4px or more on the element or an ancestor and text with fewer than two characters on screen (a lone emoji), and names what covers the text: `overlapping text`, `an SVG graphic` (an SVG element other than `text`, `tspan` or `textPath`), `an opaque element` (a box with an opaque fill), or `a bordered element` (a box counted through its borders alone). `content-hidden-at-rest` is not gated. The static HTML engine measures no boxes and is unchanged.+ - **Surfaces off the ancestor chain.** Every `low-contrast` verdict, not only the SAFE_TAGS path's, also asks the structural layer climb (`impeccable_core::browser::visual::layer_under_text`), which answers below the fold and through layers with `pointer-events: none`, which `elementsFromPoint` never lists. Besides pictures and fills, the climb reads a gradient that paints a surface on a box that is nobody's ancestor (not a dot grid, hairline, small cell, mask, a wash at alpha times opacity of 0.1 or less, or a box at opacity 0.3 or less) and an SVG shape drawn around the text (at most three times the text box plus 16px on each axis) as paint the walk never read; an ancestor painting an opaque gradient ends the climb as its fill does. Outside the SAFE_TAGS path the climb's own finding counts where the stacks cannot answer (below the fold, a replay that never asked), already see unread paint, or confirm the walk only because the layer ignores pointer events or is an SVG shape. That paint is read for the surfaces it can make over the ground the walk read (`unread_verdict`): the climb is asked again past each translucent layer, up to four, until it reaches paint that hides what is beneath or the walk's ground; the walk's own translucent layers are placed over or under that paint by the box each hangs from. A verdict that fails on every surface in that span stands, also where the stacks see unread paint, and prints `N:1 (need T:1) — text #ink on #surface (layer on <box>)` against the surface it reads best on when the walk named a flat colour more than 24 away from the span and the span's colours are known (fills and gradients); a verdict that passes on every one is dropped; one that depends on what the paint shows (a photo, unknown SVG fill) stands outside the SAFE_TAGS path, and the SAFE_TAGS path waives it as before. Outlined text (a `-webkit-text-stroke` wider than 0 in a colour of its own, or two or more opaque text-shadow layers blurred at most 2px and offset in opposing directions) keeps its element verdict. The snapshot records `webkitTextStrokeColor` and `webkitTextStrokeWidth`. `dark-glow`'s "on dark background" form reads an opaque detached fill or gradient under the element's box as its surface; a picture or translucent layer leaves the claim as the walk made it.+ - **Text the element pass hands over.** `collect_visual_contrast_candidates` takes `maxRoutedCandidates` (0 unless given; the URL engine passes 12, after its 12 `maxCandidates`, whose candidates are unchanged): text over unread paint whose verdict depends on the paint, ink in exactly the walk's surface colour over unread paint, links and spans with no fill among them, and outlined text, in document order. They carry `routed` (`unread layer` or `text outline`) and those reasons, which the sampled pass refuses; a first-budget candidate the element pass hands over carries `routed` only (and `preferRenderedForeground: true` for an outline). The URL engine takes a routed candidate to the screenshot pass even where the element pass reported on its selector, and where the pixels give a verdict, pass or fail, drops the element pass's `low-contrast` finding on that selector. Those extra reads stop after 4 seconds or 4 slow reads in a row with no verdict. The screenshot flow's hide style also clears `-webkit-text-stroke-color`, and `fill` and `stroke` on SVG `text` and `tspan`. In the stack walk a picture faded by its own box or a wrapper (below the nearest box that also holds the text) is composited at that opacity, and a picture that cannot be read (a tainted image, a refused video frame) ends the walk. `overlaps_page_width` measures against the root's scroll width when the document is wider than the window.- **Element identity.** A finding from the rule pass or the visual-contrast pass carries `selector` (after `ignoreValue`): the flagged group's generated selector (`body` / `html` for page-level groups), or the visual-contrast candidate's selector. `content-hidden-at-rest` and `script-error` findings have none.- **Where a script error was thrown.** A `script-error` snippet is the message followed by ` (at <source>)`: `<function>, <url>:<line>:<column>` from the top stack frame, or `<url>:<line>:<column>` for an anonymous frame or a script with no stack (a syntax error carries only the script position). A frame in a script with no URL (code from `eval` or `new Function`, a script element given text rather than a `src`) prints V8's name for it, `<anonymous>`, in the URL's place: `(at eval, <anonymous>:3:1)`. Line and column are 1-based (CDP's are 0-based); a URL past 160 characters is cut to 160 plus `...`; a throw with neither a named script nor a frame gets no suffix. The suffix is added after deduping, from the first occurrence. The JSON shape is unchanged: the source travels in `snippet`.- **One message shape.** Every script-error message reads the way the console prints it, `Uncaught <Type>: <message>`, whatever path the throw took, where the JS printed puppeteer's `err.message` with the type stripped on one path and CDP's typed text on another. CDP's marker comes first: `Uncaught`, or `Uncaught (in promise)` for an unhandled rejection. An `Error` reads the first line of its description, which names its type (`TypeError: ...`, or the name a library gave it, `ChunkLoadError: ...`); a description that names no type gets the class in front, and an empty message is the type alone (`Uncaught AbortError`). A thrown value that is not an `Error` (CDP `type: object` with no `subtype`: a plain object, a class instance, a rejected object) reads its class and V8's property preview, `Uncaught Object {code: "E_CONFIG", message: "config missing"}` (strings JSON-quoted, other values as previewed, `...` when the preview overflowed). A primitive reads as `String(value)`, `Uncaught boom`. A throw that arrives with no exception object (a cross-origin script) keeps CDP's text, which is typed already (`Uncaught TypeError: ...`, or `Uncaught [object Object]`). The body after the marker is its first line, trimmed, and the message after its type (`TypeError: `) is cut at 160 characters, the cut the JS applied to the untyped message, so naming the type costs the message nothing it showed before; a throw whose body is empty reports nothing.diff --git a/tests/oracle/DELTAS.md b/tests/oracle/DELTAS.mdindex 151b5453d..d203a6b63 100644--- a/tests/oracle/DELTAS.md+++ b/tests/oracle/DELTAS.md@@ -4716,3 +4716,207 @@ From the review, checked against the merged code:(`a_right_to_left_page_records_where_its_screenshot_starts`, browserlaunch under load); the next full run and three runs of that filepassed.++## Recorded 2026-09-18: surfaces off the ancestor chain (corpus/round7-surfaces)++Corpus run 28, `observations-28.md` section 6 branch 1: rows 1 (sibling+layers), 3 (scrims over photos), 10 (text-shadow outlines), the sampled-pass+washes and SVG initials of row 27, and row 21's "on dark background" read off+a dark root; plus the walkthrough misses in `walkthroughs-28.md` issue 1 that+belong here (a link or span with no fill over a picture, the hit test's blind+spots below the fold and through `pointer-events: none`, and the page width+measured against the window).++- **Every contrast path asks the structural climb.** The SAFE_TAGS path asked+ `layer_under_text`; every other element relied on the hit-test stacks,+ which answer only in the viewport and never list a layer that ignores+ pointer events. Now every failing `low-contrast` verdict asks the climb.+ Outside the SAFE_TAGS path its own finding counts where the stacks cannot+ answer, already see unread paint, or confirm the walk only because the+ layer ignores pointer events or is an SVG shape.+- **A covering gradient beside the text is unread paint.** `own_paint` read a+ gradient only when drawn larger than its box, so an `absolute inset-0+ bg-gradient-to-br` sibling painted nothing to the climb. A gradient that+ paints a surface on a box that is nobody's ancestor is now+ `LayerUnder::Gradient` (opaque stops, as the channel-wise least and greatest)+ or `Unmodelled` (a translucent stop). It uses the stacks' own texture tests+ (`text_layers::gradient_surface_stops`). An ancestor painting an opaque+ gradient ends the climb, as its fill does, since the walk scores its stops.+ An SVG shape drawn around the text (at most three times the text box plus+ 16px) is unmodelled paint; one behind a whole section is decoration.+- **Unread paint is read for what it can make of the surface**+ (`visual::unread_verdict`). The climb is asked again past each translucent+ layer, up to four, until it reaches paint that hides what is beneath or the+ walk's own ground. The walk's translucent layers are put over or under that+ paint by the box each hangs from. Over that span of surfaces:+ - a verdict that **fails everywhere** stands, also where the stacks see+ unread paint. Where the walk named a flat colour more than 24 away from+ the span, and the span's colours are known (fills and gradients), it is+ printed against the surface it reads best on: `3.2:1 (need 4.5:1) — text+ #5b6c7f on #0a1f0e (layer on div.absolute)`.+ - a verdict that **passes everywhere** is dropped. Examples: light copy on+ a dark hero gradient, and white card copy on a dark panel, where the walk+ read the white page.+ - a verdict that **depends on what the paint shows** (a photo, an SVG+ shape's unknown fill) stands outside the SAFE_TAGS path, as it did (fail+ safe). The SAFE_TAGS path waives it, as it did.+- **The pixel pass reads what the element pass hands over.** A second+ candidate budget, `maxRoutedCandidates`, takes text over unread paint whose+ verdict depends on the paint, ink in exactly the walk's surface colour over+ it, links and spans with no fill among them, and outlined text.+ - **The first budget is unchanged.** Its 12 candidates are selected exactly+ as before; the URL engine passes 12 routed slots after them, and the+ in-page bundle passes none.+ - **Routed candidates go to the screenshot pass.** They carry `routed` and+ the reason `unread layer` or `text outline`, which the sampled pass+ refuses. A first-budget candidate the element pass hands over carries+ `routed` only, and the sampled pass reads it as before.+ - **The pixels' verdict replaces the element pass's.** Where the pixel+ pass gives a verdict, pass or fail, on a routed selector, the URL engine+ drops the element pass's `low-contrast` finding on it. Where it gives+ none, the element verdict stays.+ - **The extra reads are capped.** Reads the first budget would not have+ made stop after 4 seconds, or after 4 slow reads in a row that gave no+ verdict (lpga.or.jp's carousels, about a second a read).+- **Outlines.** `-webkit-text-stroke` (width and colour, now in the capture)+ in a colour of its own, or two or more opaque text-shadow layers blurred at+ most 2px and offset in opposing directions, is an outline. The element+ pass keeps its verdict. The pixel pass reads the rendered colours+ (`preferRenderedForeground`), and its hide style now also clears+ `-webkit-text-stroke-color`, and `fill` and `stroke` on SVG `text` and+ `tspan`, so an initial's glyphs can be diffed.+- **The sampled pass reads a faded picture faded.** A picture whose own box+ or wrapper is faded (below the nearest box that also holds the text) is+ composited at that opacity, not read raw. Examples: phillips66.com's card+ photos at 0.16, thairath.co.th's 0.1 slide wrapper. A picture that cannot+ be read (a tainted image, a refused video frame) ends the walk rather than+ letting the page white under a hero video answer. Both walks share this+ (`visual::media_sample`, `vc_media_sample`).+- **dark-glow's dark claim reads the surface under the element.** Where+ that form fired, an opaque detached fill or gradient under the element's box is+ its surface; a light panel laid over a dark section is not dark. A picture+ or a translucent layer leaves the claim as the walk made it.+- **The page's width is the document's** (`overlaps_page_width`): on a page+ laid out wider than the phone, the right column's links and spans are+ scored (inven.co.kr's 14 pairs at 390px).+- **Pixel budget.** The pixel pass's candidate budget goes from 12 to 24 per+ scan (the second 12 for handed-over text only). Measured live, a read costs+ about 80 to 190ms on the pages checked, so the second budget costs under+ two seconds there. lpga.or.jp, where every read takes about a second and+ none resolves, is bounded by the four-miss cap.++Goldens re-recorded from the binary and read finding by finding:++- `detect-fixture-json-unread-surface-contrast-html`,+ `detect-fixture-text-unread-surface-contrast-html`: new, 6 findings. The+ static engine has no layout: it scores the dim copy, the emerald copy and+ the outlined sticker against the page, both glows as on dark, and its+ page-level dark glow.+- `detect-fixture-json-wide-page-contrast-html`,+ `detect-fixture-text-wide-page-contrast-html`: new, 2 findings, the right+ column label and the parked drawer's label (no layout).+- `detect-dir-json-all-fixtures`, `detect-no-advisory-json`: exactly the new+ fixtures' 8 added, none removed (810 to 818, 686 to 694);+ `detect-dir-text-all-fixtures`, `detect-dir-quiet-all-fixtures`,+ `detect-no-advisory-text` the same.++The URL behavior is pinned by `crates/browser/tests/unread_surfaces.rs`.+Scanned with the base binary (156c3150), the fixture misses the dim copy, the+grain link, the cream copy on the pointer-events-none photo and the faint+link below the fold. It reports the outlined sticker (`1.2:1`), the faded card+photo (`browser contrast 1.9:1 via canvas-img-underlay`) and the glow on the+light panel. `a_title_cut_by_the_viewport_edge_is_answered_from_what_is_visible`+now ends its photo at the viewport's edge, since the climb reads a photo under+the whole run. `paint_under_the_text_that_the_walk_never_read_leaves_no_verdict`+now expects the 40% violet tint to report, since the near-white ink fails+over every surface it can make; a 90% dark scrim still prints nothing.++Corpus (`reports/ratchet/round7-surfaces-28-ratchet-28.json`, all three+cohorts, 801 captures):++- **low-contrast 6,471 to 6,419.** 158 removed, 106 added, 0 violations, no+ severity moves.+ - **By label:** pattern-absent 152, real-harmless 1, unjudged 5.+ - **By cohort:** cohort 3 removed 153 (pattern-absent 152, real-harmless 1)+ and added 72; cohort 1 removed 4 unjudged (sapo.vn's dark cards,+ becomeautonomous.com's dark tab) and added 27; cohort 2 removed 1 (fabadda.com, a+ 4.4:1 advisory) and added 7.+ - **The removals by site:** arbiproseller-app.vercel.app 136 (its whole row 1 set: the+ emerald nav, the tinted icon tiles, the `#cecece` cards, the white strong;+ 2 of them are the dim paragraph re-scored against its dark gradient), aisdr.com 6+ (row 3's glow-framed prices), pool-web-eight.vercel.app 8 (outlined brand letters over+ blurred blobs, a pair move to the next copy), zettabrasil.com.br 2, vestra.ai 1.+ - **The additions:** 62 are the page width on wide mobile pages+ (inven.co.kr 45, yahoo.co.jp 6, drom.ru 5, news.cn 5, people.com.cn 1). The rest are+ verdicts the unread paint decides as failing (ktb.gov.tr's search button+ on its white panel, bt.cn's white tab on the green slider, visiby.net's+ grey unit on its orange card, vestra.ai's calendar over a faded painting),+ rescores (arbiproseller-app.vercel.app 4, vestra.ai) and SAFE_TAGS pair moves+ (pool-web-eight.vercel.app 8).+ - **Crops opened:** 14 removed findings (sapo.vn, becomeautonomous.com,+ fabadda.com, arbiproseller-app.vercel.app x7, zettabrasil.com.br, aisdr.com x2, and+ the clipto.com chips of an earlier revision). Every kept removal shows+ readable light text on a dark surface. fabadda.com's is borderline: grey+ on pink, a 4.4:1 advisory.+ - **Revised during the ratchet:** an earlier revision removed clipto.com's 12+ pastel chips (real 3:1 fails) under a blurred blob. The walk had ended on+ a gradient and named no ground. The ground under that gradient is now+ read, and the chips report.+- **Live** (branch against 156c3150, the same moment, home pages):+ - arbiproseller-app.vercel.app: low-contrast 80 to 14.+ - myrecomy.com: 4 to 3. The cream hero's h1 and subline go; "Join today"+ (miss 317) reports from pixels at 2.5:1.+ - vestra.ai: 14 to 14. The hero kicker is re-measured from pixels at+ 2.4:1, and "The autonomous loop" (miss 319) reports at 2.6:1.+ - phillips66.com: 11 to 4. The scrim eyebrows and the sampled washes go;+ 3 pixel findings arrive, 2 of them nav links over the hero video.+ - zettabrasil.com.br: 14 to 11.+ - aisdr.com: 27 to 25.+ - pool-web-eight.vercel.app: 10 to 7 (outlines read from pixels).+ - lpga.or.jp: 21 to 21, at the same scan time once capped.+ - walla.co.il: an earlier live pair read 24 to 10. Its 14 scrim headlines+ were measured at 13 to 20:1 and replaced, and 8 unreadable ones kept+ their verdict.+ - hp.com and a later walla.co.il pair returned no findings to either binary.++### Known limits at merge++1. **The ratchet cannot see the pixel pass.** Replays keep every verdict the+ pixels would replace, so row 3's scrims over photos (walla.co.il, lpga.or.jp),+ the hero-video and pointer-events-none cases, and outlined text show no+ change there. Their live effect is above, and it depends on the page+ letting the two screenshots agree.+2. **A new hit test in a replay goes unanswered.** The climb's hit-test+ fallback asks points the capture never recorded; in a replay they fail+ safe (the verdict stands) where a live scan may answer.+3. **A picture's colours stay unknown.** Text over a photo prints the walk's+ numbers until the pixels replace them, and myrecomy.com's "on dark+ background" glow (139432, 139515) stands: its cream hero is a `url()`+ photo, which no surface span describes.+4. **Rescores print the best case.** A verdict re-scored over known paint+ prints the ratio the text reaches on its best surface in the span.+ Rescoring applies only where the walk named a flat colour.+5. **The SAFE_TAGS path waives more.** It waives a verdict that depends on+ paint it never read. That paint now includes translucent gradients and+ SVG shapes, so a colour pair can move to a later copy+ (pool-web-eight.vercel.app).+6. **The in-page bundle has no second budget.** The extension and the live+ overlay pass no routed slots. Their verdicts over unread paint stand+ unless the paint decides them.+7. **The pixel budget is bounded, not unlimited.** Beyond 12 handed-over+ candidates, or once the time or miss cap is hit, the element verdict+ stands. The time cap makes a slow page's output depend on its speed.+8. **Not changed from row 27:** yna.co.kr's icon sprite (125322), sapo.vn's+ straddling gradient panel (127441) and microsoft.com's shadow-host ink+ (130007) read as before.+9. **Stroke needs a new capture.** `webkitTextStrokeColor` and+ `webkitTextStrokeWidth` are recorded from this capture on; older+ snapshots read no stroke.+10. **API.** `LayerUnder` gains `Gradient`. `visual` gains+ `layer_under_text_found`, `layer_under_rect`, `layer_matches_surface`,+ `surface_unread`, `unread_verdict`, `unread_reading`, `UnreadVerdict`,+ `UnreadReading`, `Rescore`, `opaque_detached_span`, `contrast_threshold`,+ `routed_reason`, `text_outlined`, `layer_fade` and `media_sample`.+ `snapshot_engine::analyze_visual_contrast` takes the routed budget.+ `screenshot_contrast` gains `measure_visual_contrast_candidate` and+ `PixelMeasure`. The wasm module exports `vc_media_sample`.